From f11a8f68b74d20a5d35663149badadce024789f4 Mon Sep 17 00:00:00 2001 From: Liam Rohan Date: Fri, 1 May 2026 05:55:41 +0100 Subject: [PATCH] reorganise skills --- AGENTS.md | 16 ++ LICENSE | 2 +- README.md | 129 +++----------- deprecated/README.md | 8 + .../design-an-interface}/SKILL.md | 0 deprecated/qa/SKILL.md | 130 ++++++++++++++ .../request-refactor-plan}/SKILL.md | 4 +- .../ubiquitous-language}/SKILL.md | 39 ++-- docs/agents/domain.md | 13 ++ docs/agents/issue-tracker.md | 28 +++ docs/agents/triage-labels.md | 13 ++ engineering/README.md | 13 ++ engineering/diagnose/SKILL.md | 117 ++++++++++++ .../diagnose/scripts/hitl-loop.template.sh | 41 +++++ engineering/grill-with-docs/ADR-FORMAT.md | 47 +++++ engineering/grill-with-docs/CONTEXT-FORMAT.md | 77 ++++++++ engineering/grill-with-docs/SKILL.md | 88 +++++++++ .../DEEPENING.md | 37 ++++ .../INTERFACE-DESIGN.md | 44 +++++ .../improve-codebase-architecture/LANGUAGE.md | 53 ++++++ .../improve-codebase-architecture/SKILL.md | 71 ++++++++ engineering/setup-skills/SKILL.md | 123 +++++++++++++ engineering/setup-skills/domain.md | 51 ++++++ .../setup-skills/issue-tracker-forgejo.md | 29 +++ .../setup-skills/issue-tracker-github.md | 22 +++ .../setup-skills/issue-tracker-gitlab.md | 23 +++ .../setup-skills/issue-tracker-local.md | 19 ++ engineering/setup-skills/triage-labels.md | 15 ++ {tdd => engineering/tdd}/SKILL.md | 2 + {tdd => engineering/tdd}/deep-modules.md | 0 {tdd => engineering/tdd}/interface-design.md | 0 {tdd => engineering/tdd}/mocking.md | 0 {tdd => engineering/tdd}/refactoring.md | 0 {tdd => engineering/tdd}/tests.md | 0 engineering/to-issues/SKILL.md | 81 +++++++++ {write-a-prd => engineering/to-prd}/SKILL.md | 16 +- engineering/triage/AGENT-BRIEF.md | 168 ++++++++++++++++++ engineering/triage/OUT-OF-SCOPE.md | 101 +++++++++++ engineering/triage/SKILL.md | 103 +++++++++++ engineering/zoom-out/SKILL.md | 7 + improve-codebase-architecture/REFERENCE.md | 78 -------- improve-codebase-architecture/SKILL.md | 76 -------- misc/README.md | 8 + .../git-guardrails-claude-code}/SKILL.md | 0 .../scripts/block-dangerous-git.sh | 0 .../migrate-to-shoehorn}/SKILL.md | 0 .../scaffold-exercises}/SKILL.md | 0 .../setup-pre-commit}/SKILL.md | 0 personal/README.md | 6 + .../edit-article}/SKILL.md | 0 .../obsidian-vault}/SKILL.md | 0 prd-to-issues/SKILL.md | 88 --------- prd-to-plan/SKILL.md | 107 ----------- productivity/README.md | 7 + productivity/caveman/SKILL.md | 49 +++++ {grill-me => productivity/grill-me}/SKILL.md | 2 + .../write-a-skill}/SKILL.md | 0 software-design/SKILL.md | 57 ------ triage-issue/SKILL.md | 102 ----------- 59 files changed, 1675 insertions(+), 635 deletions(-) create mode 100644 AGENTS.md create mode 100644 deprecated/README.md rename {design-an-interface => deprecated/design-an-interface}/SKILL.md (100%) create mode 100644 deprecated/qa/SKILL.md rename {request-refactor-plan => deprecated/request-refactor-plan}/SKILL.md (90%) rename {ubiquitous-language => deprecated/ubiquitous-language}/SKILL.md (71%) create mode 100644 docs/agents/domain.md create mode 100644 docs/agents/issue-tracker.md create mode 100644 docs/agents/triage-labels.md create mode 100644 engineering/README.md create mode 100644 engineering/diagnose/SKILL.md create mode 100644 engineering/diagnose/scripts/hitl-loop.template.sh create mode 100644 engineering/grill-with-docs/ADR-FORMAT.md create mode 100644 engineering/grill-with-docs/CONTEXT-FORMAT.md create mode 100644 engineering/grill-with-docs/SKILL.md create mode 100644 engineering/improve-codebase-architecture/DEEPENING.md create mode 100644 engineering/improve-codebase-architecture/INTERFACE-DESIGN.md create mode 100644 engineering/improve-codebase-architecture/LANGUAGE.md create mode 100644 engineering/improve-codebase-architecture/SKILL.md create mode 100644 engineering/setup-skills/SKILL.md create mode 100644 engineering/setup-skills/domain.md create mode 100644 engineering/setup-skills/issue-tracker-forgejo.md create mode 100644 engineering/setup-skills/issue-tracker-github.md create mode 100644 engineering/setup-skills/issue-tracker-gitlab.md create mode 100644 engineering/setup-skills/issue-tracker-local.md create mode 100644 engineering/setup-skills/triage-labels.md rename {tdd => engineering/tdd}/SKILL.md (95%) rename {tdd => engineering/tdd}/deep-modules.md (100%) rename {tdd => engineering/tdd}/interface-design.md (100%) rename {tdd => engineering/tdd}/mocking.md (100%) rename {tdd => engineering/tdd}/refactoring.md (100%) rename {tdd => engineering/tdd}/tests.md (100%) create mode 100644 engineering/to-issues/SKILL.md rename {write-a-prd => engineering/to-prd}/SKILL.md (65%) create mode 100644 engineering/triage/AGENT-BRIEF.md create mode 100644 engineering/triage/OUT-OF-SCOPE.md create mode 100644 engineering/triage/SKILL.md create mode 100644 engineering/zoom-out/SKILL.md delete mode 100644 improve-codebase-architecture/REFERENCE.md delete mode 100644 improve-codebase-architecture/SKILL.md create mode 100644 misc/README.md rename {git-guardrails-claude-code => misc/git-guardrails-claude-code}/SKILL.md (100%) rename {git-guardrails-claude-code => misc/git-guardrails-claude-code}/scripts/block-dangerous-git.sh (100%) rename {migrate-to-shoehorn => misc/migrate-to-shoehorn}/SKILL.md (100%) rename {scaffold-exercises => misc/scaffold-exercises}/SKILL.md (100%) rename {setup-pre-commit => misc/setup-pre-commit}/SKILL.md (100%) create mode 100644 personal/README.md rename {edit-article => personal/edit-article}/SKILL.md (100%) rename {obsidian-vault => personal/obsidian-vault}/SKILL.md (100%) delete mode 100644 prd-to-issues/SKILL.md delete mode 100644 prd-to-plan/SKILL.md create mode 100644 productivity/README.md create mode 100644 productivity/caveman/SKILL.md rename {grill-me => productivity/grill-me}/SKILL.md (94%) rename {write-a-skill => productivity/write-a-skill}/SKILL.md (100%) delete mode 100644 software-design/SKILL.md delete mode 100644 triage-issue/SKILL.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..343a6d3 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,16 @@ +# Agent Skills + +## Agent skills + +### Issue tracker + +Issues for this repo live in Forgejo at `src.liamrohan.com/ldr/skills`. Use the +`fj` CLI, not `gh`. See `docs/agents/issue-tracker.md`. + +### Triage labels + +Use the canonical triage labels unchanged. See `docs/agents/triage-labels.md`. + +### Domain docs + +This repo is single-context. See `docs/agents/domain.md`. diff --git a/LICENSE b/LICENSE index efc78c2..14fac91 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2026 Liam Rohan +Copyright (c) 2026 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index 88bed7f..fbc2b0d 100644 --- a/README.md +++ b/README.md @@ -1,117 +1,44 @@ # Agent Skills -A collection of agent skills that extend capabilities across planning, development, and tooling. +This repository contains the local agent skills used by Codex. -## Planning & Design +Current imported source commit: -These skills help you think through problems before writing code. +`b843cb5ea74b1fe5e58a0fc23cddef9e66076fb8` -- **write-a-prd** — Create a PRD through an interactive interview, codebase exploration, and module design. Filed as a GitHub issue. +## Layout - ``` - npx skills@latest add mattpocock/skills/write-a-prd - ``` +- `engineering/` +- `productivity/` +- `misc/` +- `personal/` +- `deprecated/` -- **prd-to-plan** — Turn a PRD into a multi-phase implementation plan using tracer-bullet vertical slices. +Each category directory is copied from upstream with its own README and skill +subdirectories. - ``` - npx skills@latest add mattpocock/skills/prd-to-plan - ``` +## Active Codex Install -- **prd-to-issues** — Break a PRD into independently-grabbable GitHub issues using vertical slices. +`/home/ldr/.codex/skills` should stay flat. Do not symlink the category +directories into Codex. - ``` - npx skills@latest add mattpocock/skills/prd-to-issues - ``` +Instead, each skill directory under the categories here should be exposed as a +top-level symlink in `/home/ldr/.codex/skills`, for example: -- **grill-me** — Get relentlessly interviewed about a plan or design until every branch of the decision tree is resolved. +```sh +/home/ldr/.codex/skills/tdd -> ../../ldr/skills/engineering/tdd +``` - ``` - npx skills@latest add mattpocock/skills/grill-me - ``` +Keep `/home/ldr/.codex/skills/.system` config-only. -- **design-an-interface** — Generate multiple radically different interface designs for a module using parallel sub-agents. +## Refresh - ``` - npx skills@latest add mattpocock/skills/design-an-interface - ``` +From this repository root: -- **request-refactor-plan** — Create a detailed refactor plan with tiny commits via user interview, then file it as a GitHub issue. +```sh +curl -L -o /tmp/skills-main.tar.gz +tar -xzf /tmp/skills-main.tar.gz -C /tmp +cp -a /tmp/skills-main/skills/. . +``` - ``` - npx skills@latest add mattpocock/skills/request-refactor-plan - ``` - -## Development - -These skills help you write, refactor, and fix code. - -- **tdd** — Test-driven development with a red-green-refactor loop. Builds features or fixes bugs one vertical slice at a time. - - ``` - npx skills@latest add mattpocock/skills/tdd - ``` - -- **triage-issue** — Investigate a bug by exploring the codebase, identify the root cause, and file a GitHub issue with a TDD-based fix plan. - - ``` - npx skills@latest add mattpocock/skills/triage-issue - ``` - -- **improve-codebase-architecture** — Explore a codebase for architectural improvement opportunities, focusing on deepening shallow modules and improving testability. - - ``` - npx skills@latest add mattpocock/skills/improve-codebase-architecture - ``` - -- **migrate-to-shoehorn** — Migrate test files from `as` type assertions to @total-typescript/shoehorn. - - ``` - npx skills@latest add mattpocock/skills/migrate-to-shoehorn - ``` - -- **scaffold-exercises** — Create exercise directory structures with sections, problems, solutions, and explainers. - - ``` - npx skills@latest add mattpocock/skills/scaffold-exercises - ``` - -## Tooling & Setup - -- **setup-pre-commit** — Set up Husky pre-commit hooks with lint-staged, Prettier, type checking, and tests. - - ``` - npx skills@latest add mattpocock/skills/setup-pre-commit - ``` - -- **git-guardrails-claude-code** — Set up Claude Code hooks to block dangerous git commands (push, reset --hard, clean, etc.) before they execute. - - ``` - npx skills@latest add mattpocock/skills/git-guardrails-claude-code - ``` - -## Writing & Knowledge - -- **write-a-skill** — Create new skills with proper structure, progressive disclosure, and bundled resources. - - ``` - npx skills@latest add mattpocock/skills/write-a-skill - ``` - -- **edit-article** — Edit and improve articles by restructuring sections, improving clarity, and tightening prose. - - ``` - npx skills@latest add mattpocock/skills/edit-article - ``` - -- **ubiquitous-language** — Extract a DDD-style ubiquitous language glossary from the current conversation. - - ``` - npx skills@latest add mattpocock/skills/ubiquitous-language - ``` - -- **obsidian-vault** — Search, create, and manage notes in an Obsidian vault with wikilinks and index notes. - - ``` - npx skills@latest add mattpocock/skills/obsidian-vault - ``` +After refreshing, update the commit hash above from the source repository. diff --git a/deprecated/README.md b/deprecated/README.md new file mode 100644 index 0000000..939226a --- /dev/null +++ b/deprecated/README.md @@ -0,0 +1,8 @@ +# Deprecated + +Skills I no longer use. + +- **[design-an-interface](./design-an-interface/SKILL.md)** — Generate multiple radically different interface designs for a module using parallel sub-agents. +- **[qa](./qa/SKILL.md)** — Interactive QA session where user reports bugs conversationally and the agent files issues. +- **[request-refactor-plan](./request-refactor-plan/SKILL.md)** — Create a detailed refactor plan with tiny commits via user interview, then file it as an issue. +- **[ubiquitous-language](./ubiquitous-language/SKILL.md)** — Extract a DDD-style ubiquitous language glossary from the current conversation. diff --git a/design-an-interface/SKILL.md b/deprecated/design-an-interface/SKILL.md similarity index 100% rename from design-an-interface/SKILL.md rename to deprecated/design-an-interface/SKILL.md diff --git a/deprecated/qa/SKILL.md b/deprecated/qa/SKILL.md new file mode 100644 index 0000000..e685484 --- /dev/null +++ b/deprecated/qa/SKILL.md @@ -0,0 +1,130 @@ +--- +name: qa +description: Interactive QA session where user reports bugs or issues conversationally, and the agent files issues. Explores the codebase in the background for context and domain language. Use when user wants to report bugs, do QA, file issues conversationally, or mentions "QA session". +--- + +# QA Session + +Run an interactive QA session. The user describes problems they're encountering. You clarify, explore the codebase for context, and file issues that are durable, user-focused, and use the project's domain language. + +## For each issue the user raises + +### 1. Listen and lightly clarify + +Let the user describe the problem in their own words. Ask **at most 2-3 short clarifying questions** focused on: + +- What they expected vs what actually happened +- Steps to reproduce (if not obvious) +- Whether it's consistent or intermittent + +Do NOT over-interview. If the description is clear enough to file, move on. + +### 2. Explore the codebase in the background + +While talking to the user, kick off an Agent (subagent_type=Explore) in the background to understand the relevant area. The goal is NOT to find a fix — it's to: + +- Learn the domain language used in that area (check UBIQUITOUS_LANGUAGE.md) +- Understand what the feature is supposed to do +- Identify the user-facing behavior boundary + +This context helps you write a better issue — but the issue itself should NOT reference specific files, line numbers, or internal implementation details. + +### 3. Assess scope: single issue or breakdown? + +Before filing, decide whether this is a **single issue** or needs to be **broken down** into multiple issues. + +Break down when: + +- The fix spans multiple independent areas (e.g. "the form validation is wrong AND the success message is missing AND the redirect is broken") +- There are clearly separable concerns that different people could work on in parallel +- The user describes something that has multiple distinct failure modes or symptoms + +Keep as a single issue when: + +- It's one behavior that's wrong in one place +- The symptoms are all caused by the same root behavior + +### 4. File the issue(s) + +Create issues using the project issue tracker configured in `docs/agents/issue-tracker.md`. Do NOT ask the user to review first — just file and share URLs. + +Issues must be **durable** — they should still make sense after major refactors. Write from the user's perspective. + +#### For a single issue + +Use this template: + +``` +## What happened + +[Describe the actual behavior the user experienced, in plain language] + +## What I expected + +[Describe the expected behavior] + +## Steps to reproduce + +1. [Concrete, numbered steps a developer can follow] +2. [Use domain terms from the codebase, not internal module names] +3. [Include relevant inputs, flags, or configuration] + +## Additional context + +[Any extra observations from the user or from codebase exploration that help frame the issue — e.g. "this only happens when using the Docker layer, not the filesystem layer" — use domain language but don't cite files] +``` + +#### For a breakdown (multiple issues) + +Create issues in dependency order (blockers first) so you can reference real issue numbers. + +Use this template for each sub-issue: + +``` +## Parent issue + +# (if you created a tracking issue) or "Reported during QA session" + +## What's wrong + +[Describe this specific behavior problem — just this slice, not the whole report] + +## What I expected + +[Expected behavior for this specific slice] + +## Steps to reproduce + +1. [Steps specific to THIS issue] + +## Blocked by + +- # (if this issue can't be fixed until another is resolved) + +Or "None — can start immediately" if no blockers. + +## Additional context + +[Any extra observations relevant to this slice] +``` + +When creating a breakdown: + +- **Prefer many thin issues over few thick ones** — each should be independently fixable and verifiable +- **Mark blocking relationships honestly** — if issue B genuinely can't be tested until issue A is fixed, say so. If they're independent, mark both as "None — can start immediately" +- **Create issues in dependency order** so you can reference real issue numbers in "Blocked by" +- **Maximize parallelism** — the goal is that multiple people (or agents) can grab different issues simultaneously + +#### Rules for all issue bodies + +- **No file paths or line numbers** — these go stale +- **Use the project's domain language** (check UBIQUITOUS_LANGUAGE.md if it exists) +- **Describe behaviors, not code** — "the sync service fails to apply the patch" not "applyPatch() throws on line 42" +- **Reproduction steps are mandatory** — if you can't determine them, ask the user +- **Keep it concise** — a developer should be able to read the issue in 30 seconds + +After filing, print all issue URLs (with blocking relationships summarized) and ask: "Next issue, or are we done?" + +### 5. Continue the session + +Keep going until the user says they're done. Each issue is independent — don't batch them. diff --git a/request-refactor-plan/SKILL.md b/deprecated/request-refactor-plan/SKILL.md similarity index 90% rename from request-refactor-plan/SKILL.md rename to deprecated/request-refactor-plan/SKILL.md index 7e8b2e4..8ff8086 100644 --- a/request-refactor-plan/SKILL.md +++ b/deprecated/request-refactor-plan/SKILL.md @@ -1,6 +1,6 @@ --- name: request-refactor-plan -description: Create a detailed refactor plan with tiny commits via user interview, then file it as a GitHub issue. Use when user wants to plan a refactor, create a refactoring RFC, or break a refactor into safe incremental steps. +description: Create a detailed refactor plan with tiny commits via user interview, then file it as an issue. Use when user wants to plan a refactor, create a refactoring RFC, or break a refactor into safe incremental steps. --- This skill will be invoked when the user wants to create a refactor request. You should go through the steps below. You may skip steps if you don't consider them necessary. @@ -19,7 +19,7 @@ This skill will be invoked when the user wants to create a refactor request. You 7. Break the implementation into a plan of tiny commits. Remember Martin Fowler's advice to "make each refactoring step as small as possible, so that you can always see the program working." -8. Create a GitHub issue with the refactor plan. Use the following template for the issue description: +8. Create an issue with the refactor plan. Use the following template for the issue description: diff --git a/ubiquitous-language/SKILL.md b/deprecated/ubiquitous-language/SKILL.md similarity index 71% rename from ubiquitous-language/SKILL.md rename to deprecated/ubiquitous-language/SKILL.md index db4fbd6..35b649d 100644 --- a/ubiquitous-language/SKILL.md +++ b/deprecated/ubiquitous-language/SKILL.md @@ -1,6 +1,7 @@ --- name: ubiquitous-language description: Extract a DDD-style ubiquitous language glossary from the current conversation, flagging ambiguities and proposing canonical terms. Saves to UBIQUITOUS_LANGUAGE.md. Use when user wants to define domain terms, build a glossary, harden terminology, create a ubiquitous language, or mentions "domain model" or "DDD". +disable-model-invocation: true --- # Ubiquitous Language @@ -27,17 +28,17 @@ Write a `UBIQUITOUS_LANGUAGE.md` file with this structure: ## Order lifecycle -| Term | Definition | Aliases to avoid | -|------|-----------|-----------------| -| **Order** | A customer's request to purchase one or more items | Purchase, transaction | +| Term | Definition | Aliases to avoid | +| ----------- | ------------------------------------------------------- | --------------------- | +| **Order** | A customer's request to purchase one or more items | Purchase, transaction | | **Invoice** | A request for payment sent to a customer after delivery | Bill, payment request | ## People -| Term | Definition | Aliases to avoid | -|------|-----------|-----------------| +| Term | Definition | Aliases to avoid | +| ------------ | ------------------------------------------- | ---------------------- | | **Customer** | A person or organization that places orders | Client, buyer, account | -| **User** | An authentication identity in the system | Login, account | +| **User** | An authentication identity in the system | Login, account | ## Relationships @@ -60,12 +61,27 @@ Write a `UBIQUITOUS_LANGUAGE.md` file with this structure: - **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others as aliases to avoid. - **Flag conflicts explicitly.** If a term is used ambiguously in the conversation, call it out in the "Flagged ambiguities" section with a clear recommendation. +- **Only include terms relevant for domain experts.** Skip the names of modules or classes unless they have meaning in the domain language. - **Keep definitions tight.** One sentence max. Define what it IS, not what it does. - **Show relationships.** Use bold term names and express cardinality where obvious. - **Only include domain terms.** Skip generic programming concepts (array, function, endpoint) unless they have domain-specific meaning. - **Group terms into multiple tables** when natural clusters emerge (e.g. by subdomain, lifecycle, or actor). Each group gets its own heading and table. If all terms belong to a single cohesive domain, one table is fine — don't force groupings. - **Write an example dialogue.** A short conversation (3-5 exchanges) between a dev and a domain expert that demonstrates how the terms interact naturally. The dialogue should clarify boundaries between related concepts and show terms being used precisely. + + +## Example dialogue + +> **Dev:** "How do I test the **sync service** without Docker?" + +> **Domain expert:** "Provide the **filesystem layer** instead of the **Docker layer**. It implements the same **Sandbox service** interface but uses a local directory as the **sandbox**." + +> **Dev:** "So **sync-in** still creates a **bundle** and unpacks it?" + +> **Domain expert:** "Exactly. The **sync service** doesn't know which layer it's talking to. It calls `exec` and `copyIn` — the **filesystem layer** just runs those as local shell commands." + + + ## Re-running When invoked again in the same conversation: @@ -73,12 +89,5 @@ When invoked again in the same conversation: 1. Read the existing `UBIQUITOUS_LANGUAGE.md` 2. Incorporate any new terms from subsequent discussion 3. Update definitions if understanding has evolved -4. Mark changed entries with "(updated)" and new entries with "(new)" -5. Re-flag any new ambiguities -6. Rewrite the example dialogue to incorporate new terms - -## Post-output instruction - -After writing the file, state: - -> I've written/updated `UBIQUITOUS_LANGUAGE.md`. From this point forward I will use these terms consistently. If I drift from this language or you notice a term that should be added, let me know. +4. Re-flag any new ambiguities +5. Rewrite the example dialogue to incorporate new terms diff --git a/docs/agents/domain.md b/docs/agents/domain.md new file mode 100644 index 0000000..81b733e --- /dev/null +++ b/docs/agents/domain.md @@ -0,0 +1,13 @@ +# Domain Docs + +This repo is single-context. + +## Layout + +- Repository-level agent guidance lives in `AGENTS.md`. +- Skill source lives under the category directories in this repo. +- Active Codex skill entries are flat symlinks from `/home/ldr/.codex/skills` + into this repo. + +There is no separate `CONTEXT.md` yet. If one is added later, engineering skills +should read it before making broad changes. diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md new file mode 100644 index 0000000..a95b2f2 --- /dev/null +++ b/docs/agents/issue-tracker.md @@ -0,0 +1,28 @@ +# Issue tracker: Forgejo + +Issues for this repo live in Forgejo: + +`src.liamrohan.com/ldr/skills` + +Use the `fj` CLI for issue operations. Do not use `gh` for this repo. + +## Commands + +- Create an issue: `fj issue create "Title" --body-file ` +- Read an issue body: `fj issue view ` +- Read comments: `fj issue view comments` +- Search open issues: `fj issue search --state open` +- Search by label: `fj issue search --state open --labels "needs-triage"` +- Comment: `fj issue comment --body-file ` +- Add a label: `fj issue edit labels --add "