From 84b5ee5afd738b6a3484e62509b84b3b573c5be3 Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Fri, 21 Aug 2026 11:09:36 +0100 Subject: [PATCH] Add implement-spec skill (in-progress) with its bucket docs The skill itself takes a spec plus its tickets and drives them to one PR, reading the tickets as a task graph so implementer subagents can run concurrently across the ready frontier. Documentation duties for the in-progress bucket: - List it in skills/in-progress/README.md (flat list, name linked to its SKILL.md), the one entry every skill in a bucket must have. It stays out of the top-level README and .claude-plugin/plugin.json, and gets no docs page, as the bucket requires. - Add a changeset, so the release notes carry it. - Match the bucket's openai.yaml style in short_description: a short verb phrase, no closing period. Also ignore .claude, which holds settings.local.json and agent worktrees that should never be committed. Co-Authored-By: Claude Opus 5 (1M context) --- .changeset/add-implement-spec-skill.md | 5 +++ .gitignore | 1 + skills/in-progress/README.md | 1 + skills/in-progress/implement-spec/SKILL.md | 35 +++++++++++++++++++ .../implement-spec/agents/openai.yaml | 5 +++ 5 files changed, 47 insertions(+) create mode 100644 .changeset/add-implement-spec-skill.md create mode 100644 skills/in-progress/implement-spec/SKILL.md create mode 100644 skills/in-progress/implement-spec/agents/openai.yaml diff --git a/.changeset/add-implement-spec-skill.md b/.changeset/add-implement-spec-skill.md new file mode 100644 index 0000000..2128b7d --- /dev/null +++ b/.changeset/add-implement-spec-skill.md @@ -0,0 +1,5 @@ +--- +"mattpocock-skills": patch +--- + +Add the `implement-spec` skill (in-progress bucket, user-invoked). It takes a spec and its tickets and drives them to a single PR: the tickets are read as a task graph with blocking edges, so implementer subagents run in background worktrees across the ready frontier for concurrency, a merger subagent folds each one back into the PR branch, and the flow closes with `/code-review` before the PR is marked ready. diff --git a/.gitignore b/.gitignore index 3c3629e..98dd2d8 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ node_modules +.claude diff --git a/skills/in-progress/README.md b/skills/in-progress/README.md index 792ebaa..65b4524 100644 --- a/skills/in-progress/README.md +++ b/skills/in-progress/README.md @@ -14,3 +14,4 @@ npx skills@latest add mattpocock/skills --skill= - **[writing-shape](./writing-shape/SKILL.md)**: Take a markdown file of raw material and shape it into an article paragraph by paragraph, arguing format choices at each step. - **[claude-handoff](./claude-handoff/SKILL.md)**: Hand the current conversation off to a fresh background agent that picks up the work immediately, seeded with a handoff summary via `claude --bg`. User-invoked. - **[setup-ts-deep-modules](./setup-ts-deep-modules/SKILL.md)**: Wire dependency-cruiser into a TypeScript repo so each package is a deep module: implementation hidden in subfolders, reachable only through its entry-point files, tests exercising it through those. User-invoked. +- **[implement-spec](./implement-spec/SKILL.md)**: Implement a whole spec on one branch. Works the tickets as a task graph rather than a list, running implementer subagents across the ready frontier for maximum concurrency, and lands the result as a single PR. User-invoked. diff --git a/skills/in-progress/implement-spec/SKILL.md b/skills/in-progress/implement-spec/SKILL.md new file mode 100644 index 0000000..97e0346 --- /dev/null +++ b/skills/in-progress/implement-spec/SKILL.md @@ -0,0 +1,35 @@ +--- +name: implement-spec +description: "Implement a specification in code." +disable-model-invocation: true +--- + +You have been provided a spec. This spec should have tickets associated with it, describing how to implement the spec. + +The goal is a PR which implements the entire spec on a single branch. + +The tickets are not a list of steps. They are a **task graph** with blocking relationships between them. This means there is always a **frontier** of tickets which are ready to be grabbed. + +Communication to and from subagents should be sparse. Communicate primarily through **context pointers**: to the spec, tickets, research notes, and previous commits. Don't duplicate information already available via pointers. + +**Implementer subagents** should be run in the background where possible for **maximum concurrency**. + +## Steps + +1. Read the spec and tickets. Read enough to understand the task graph. + +2. (optional) Use an **exploration subagent** to conduct any exploration required by the tickets - relevant codebase files or external documentation. Ensure the exploration subagent can save files - it should save its markdown notes in a directory outside the repo, accessible by all future subagents. This lets **implementer subagents** focus on implementation rather than exploration. + +3. Create a branch, and a draft PR. The PR should be marked as 'closing' the spec issue and tickets. + +4. Use **implementer subagents** to implement each ticket. Each implementer subagent should work in its own worktree, on its own branch. + +5. Once an **implementer subagent** completes, merge its work to the PR branch with a **merger subagent**. + +6. If this changes the **frontier** of available tickets, kick off more **implementer subagents** to work on the new tickets. This allows for maximum concurrency. + +7. Once all tickets are complete, run /code-review on the PR branch. Fix all issues raised by the code review in an **implementer subagent**. + +8. Mark the PR as ready for review. + +9. Clean up all **implementer subagent** worktrees. diff --git a/skills/in-progress/implement-spec/agents/openai.yaml b/skills/in-progress/implement-spec/agents/openai.yaml new file mode 100644 index 0000000..043f27f --- /dev/null +++ b/skills/in-progress/implement-spec/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Implement Spec" + short_description: "Implement a whole spec as one PR" +policy: + allow_implicit_invocation: false