diff --git a/CLAUDE.md b/CLAUDE.md index ae63624..5ab79b7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -27,7 +27,7 @@ Current version: **2.2.0** (see [CHANGELOG.md](./CHANGELOG.md)). │ ├── sizing.md │ ├── yagni.md │ ├── agents/ # Long-form docs for all 21 agents, plus README -│ ├── skills/ # Long-form docs for all 15 skills, plus README +│ ├── skills/ # Long-form docs for all 16 skills, plus README │ ├── guidance/ # Contributor-facing authoring guidance │ └── templates/ # Templates and coverage rule for long-form docs └── images/ # Banner and graphics for README @@ -56,7 +56,7 @@ The plugin is shipped from `plugin/`; documentation lives in `docs/`. Long-form ### Skill catalog (`docs/skills/`) -- **[docs/skills/README.md](./docs/skills/README.md).** Index of all 15 skills grouped by purpose (planning, investigation, review, discovery, conventions, reporting). Start here when looking for the right slash command. +- **[docs/skills/README.md](./docs/skills/README.md).** Index of all 16 skills grouped by purpose (planning, investigation, review, discovery, conventions, reporting). Start here when looking for the right slash command. - **[docs/skills/plan-a-feature.md](./docs/skills/plan-a-feature.md).** Spec a feature from scratch through an evidence-based interview that walks the design tree and dispatches specialist reviewers. - **[docs/skills/plan-implementation.md](./docs/skills/plan-implementation.md).** Turn a feature specification into an implementation plan through a project-manager-led team conversation. - **[docs/skills/plan-a-phased-build.md](./docs/skills/plan-a-phased-build.md).** Split a body of context (gap analysis, PRD, design doc) into a numbered sequence of vertical-slice phases, each independently demoable. @@ -123,4 +123,4 @@ Subdirectories: - **Every long-form doc links up.** The first bullet of the "Related Documentation" section always points back to the README at the repo root. - **Voice is uniform.** Every doc follows [docs/writing-voice.md](./docs/writing-voice.md). No em-dashes, direct second person, no flattery or hype. - **YAGNI applies to docs too.** Don't add speculative sections, for-future-flexibility warnings, or examples for behavior the skill doesn't have. The same evidence rule that gates plan steps gates docs. -- **Counts to verify when editing indexes.** 21 agents in `plugin/agents/`; 15 skills in `plugin/skills/`; 21 long-form agent docs in `docs/agents/`; 15 long-form skill docs in `docs/skills/`. +- **Counts to verify when editing indexes.** 21 agents in `plugin/agents/`; 16 skills in `plugin/skills/`; 21 long-form agent docs in `docs/agents/`; 16 long-form skill docs in `docs/skills/`. diff --git a/README.md b/README.md index 1deec46..da8ac85 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ Read [Concepts](./docs/concepts.md) for the skill-and-agent model that runs thro ## Which path are you on? - **New to han?** → Start with [Concepts](./docs/concepts.md), then the [Quickstart](./docs/quickstart.md). -- **Looking for a specific skill?** → [Skills Index](./docs/skills/README.md). 15 skills grouped by purpose. +- **Looking for a specific skill?** → [Skills Index](./docs/skills/README.md). 16 skills grouped by purpose. - **Looking for a specific agent?** → [Agents Index](./docs/agents/README.md). 21 agents grouped by role. - **Wondering how the agent swarms scale?** → [Sizing](./docs/sizing.md). The small / medium / large dispatch model used by `/code-review`, `/gap-analysis`, `/iterative-plan-review`, `/plan-a-feature`, and `/plan-implementation`. - **Wondering why a skill said "YAGNI"?** → [YAGNI](./docs/yagni.md). The evidence-based rule every planning, review, and architecture skill applies before committing items to an artifact. @@ -33,6 +33,7 @@ Spec what to build, plan how to build it, sequence it into phases, and stress-te - **[`/plan-implementation`](./docs/skills/plan-implementation.md).** Turn a feature specification into an implementation plan through a project-manager-led team conversation. - **[`/plan-a-phased-build`](./docs/skills/plan-a-phased-build.md).** Split a body of work into a numbered sequence of vertical-slice phases, each independently demoable. - **[`/iterative-plan-review`](./docs/skills/iterative-plan-review.md).** Stress-test an existing plan through multiple codebase-grounded review passes. +- **[`/implementation-plan-to-issues`](./docs/skills/implementation-plan-to-issues.md).** Divide up the implementation plan into atomic units of work. ### Investigation & root cause @@ -85,7 +86,7 @@ Add the Test Double skills marketplace to Claude Code, then install the plugin: - [Concepts](./docs/concepts.md). Skill vs. agent, and how they compose. Read once before using the plugin. - [Quickstart](./docs/quickstart.md). Four paths for four common situations. Each path is a short sequence of skills. -- [Skills Index](./docs/skills/README.md). All 15 skills, grouped by purpose. +- [Skills Index](./docs/skills/README.md). All 16 skills, grouped by purpose. - [Agents Index](./docs/agents/README.md). All 21 agents, grouped by role. - [Sizing](./docs/sizing.md). The small / medium / large model that decides how many agents the swarming skills dispatch. - [YAGNI](./docs/yagni.md). The evidence-based "You Aren't Gonna Need It" rule every planning, review, and architecture skill applies. diff --git a/docs/concepts.md b/docs/concepts.md index efef3c1..7bbc4d7 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -92,7 +92,7 @@ Direct invocation uses the `Agent` tool with `subagent_type: han:{agent-name}` ( ## What does the plugin include? -- **15 skills.** The [skills index](./skills/README.md) groups them by purpose (planning, investigation, review, discovery, conventions, reporting). +- **16 skills.** The [skills index](./skills/README.md) groups them by purpose (planning, investigation, review, discovery, conventions, reporting). - **21 agents.** The [agents index](./agents/README.md) groups them by role (planning and facilitation, adversarial reviewers, investigation, architecture, testing, gap and content). Skim the indexes after you read this page. Pick the one skill you need right now. Come back later to learn the rest. diff --git a/docs/quickstart.md b/docs/quickstart.md index d71b5dc..c4d7c8c 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -23,6 +23,7 @@ You have a feature idea and want a specification grounded in evidence, then a pl 2. **[`/plan-a-phased-build`](./skills/plan-a-phased-build.md)** *(optional).* When the feature is large enough to ship in slices rather than all at once, split the spec into a numbered sequence of vertical-slice phases, each independently demoable to a real person. 3. **[`/plan-implementation`](./skills/plan-implementation.md).** Turn the specification (or a single phase from the phased build) into an implementation plan through a project-manager-led team conversation. 4. **[`/iterative-plan-review`](./skills/iterative-plan-review.md)** *(optional).* Stress-test either plan through multiple codebase-grounded review passes before committing to it. +5. **[`/implementation-plan-to-issues`](./skills/implementation-plan-to-issues.md)** *(optional).* Divide an implementation plan up into individual, atomic units of work. **You are done when:** you have a `feature-specification.md` and a `feature-implementation-plan.md` in the same folder, each with a cross-referenced decision log and review findings. If the feature was large enough to phase, you also have a `build-phase-outline.md` that orders the work into demoable vertical slices. @@ -77,8 +78,8 @@ You can reference multiple skills in one prompt and Claude runs them in sequence - *"Scan this repo, document the auth system, and create a coding standard for how we handle tokens."* → [`/project-discovery`](./skills/project-discovery.md) → [`/project-documentation`](./skills/project-documentation.md) → [`/coding-standard`](./skills/coding-standard.md). - *"Review my branch, then create an ADR for any architectural decisions in the diff."* → [`/code-review`](./skills/code-review.md) → [`/architectural-decision-record`](./skills/architectural-decision-record.md). - *"Plan the retry feature, then plan the implementation, then create a test plan for it."* → [`/plan-a-feature`](./skills/plan-a-feature.md) → [`/plan-implementation`](./skills/plan-implementation.md) → [`/test-planning`](./skills/test-planning.md). -- *"Compare the auth implementation to the auth spec, then plan how to close the gaps."* → [`/gap-analysis`](./skills/gap-analysis.md) → [`/plan-implementation`](./skills/plan-implementation.md). -- *"Compare the share v1 implementation to the share v2 spec, split the gaps into a phased rollout, then plan implementation for the first phase."* → [`/gap-analysis`](./skills/gap-analysis.md) → [`/plan-a-phased-build`](./skills/plan-a-phased-build.md) → [`/plan-implementation`](./skills/plan-implementation.md). +- *"Compare the auth implementation to the auth spec, then plan how to close the gaps, finishing with splitting that work up into task-sized units."* → [`/gap-analysis`](./skills/gap-analysis.md) → [`/plan-implementation`](./skills/plan-implementation.md) → [`/implementation-plan-to-issues`](./skills/implementation-plan-to-issues.md). +- *"Compare the share v1 implementation to the share v2 spec, split the gaps into a phased rollout, then plan implementation for the first phase, finally laying out individual tasks based on that plan."* → [`/gap-analysis`](./skills/gap-analysis.md) → [`/plan-a-phased-build`](./skills/plan-a-phased-build.md) → [`/plan-implementation`](./skills/plan-implementation.md) → [`/implementation-plan-to-issues`](/skills/implementation-plan-to-issues.md). ## A note on sizing diff --git a/docs/skills/README.md b/docs/skills/README.md index 5427b19..024b38d 100644 --- a/docs/skills/README.md +++ b/docs/skills/README.md @@ -16,6 +16,8 @@ Skills for specifying *what* a feature does, planning *how* to build it, and str - **[`/plan-implementation`](./plan-implementation.md).** Turn a feature specification into an implementation plan through a project-manager-led team conversation. - **[`/plan-a-phased-build`](./plan-a-phased-build.md).** Split a body of context (gap analysis, PRD, design doc, feature spec, requirements list) into a numbered sequence of vertical-slice build phases, each independently demoable to a real person and each building on the prior. Dispatches `information-architect` against the rendered outline to verify findability, EPPO standalone-ness of phase entries, and progressive comprehension. - **[`/iterative-plan-review`](./iterative-plan-review.md).** Stress-test an already-written plan through multiple codebase-grounded review passes. +- **[`/implementation-plan-to-issues`](./implementation-plan-to-issues.md).** Divide up the implementation plan into atomic units of work. + ## Investigation & root cause @@ -76,7 +78,8 @@ Most han skills dispatch agents to do their judgment-heavy work. The [Concepts]( A few common compositions: -- **Plan → implement → iterate.** `/plan-a-feature` → `/plan-implementation` → `/iterative-plan-review`. +- **Create specs → plan implementation → iterate → create issues.** `/plan-a-feature` → `/plan-implementation` → `/iterative-plan-review` → `/implementation-plan-to-issues`. +- **Plan implementation → create issues.** `/plan-implementation` → `/implementation-plan-to-issues`. - **Discover → document → standardize.** `/project-discovery` → `/project-documentation` → `/coding-standard`. - **Review locally → post to PR.** `/code-review` → `/gh-pr-review`. - **Investigate → iterate on the fix.** `/investigate` → `/iterative-plan-review`. diff --git a/docs/skills/architectural-analysis.md b/docs/skills/architectural-analysis.md index c0f0e3e..cbf9e7c 100644 --- a/docs/skills/architectural-analysis.md +++ b/docs/skills/architectural-analysis.md @@ -130,7 +130,7 @@ URL: https://www.domainlanguage.com/ddd/ ## Related documentation - [Plugin landing page](../../README.md). The front door. Start here if you arrived from outside the docs tree. -- [Skills Index](./README.md). All 15 skills, grouped by purpose. +- [Skills Index](./README.md). All 16 skills, grouped by purpose. - [`structural-analyst`](../agents/structural-analyst.md), [`behavioral-analyst`](../agents/behavioral-analyst.md), [`concurrency-analyst`](../agents/concurrency-analyst.md). The three parallel analysts. - [`risk-analyst`](../agents/risk-analyst.md). The agent that scores the analysts' findings by likelihood, severity, blast radius, and reversibility. - [`software-architect`](../agents/software-architect.md). The adversarial synthesis agent that produces intra-codebase recommendations and pseudocode sketches (dispatched by this skill). diff --git a/docs/skills/architectural-decision-record.md b/docs/skills/architectural-decision-record.md index 39c9698..1f904db 100644 --- a/docs/skills/architectural-decision-record.md +++ b/docs/skills/architectural-decision-record.md @@ -120,7 +120,7 @@ URL: https://www.thoughtworks.com/radar/techniques/lightweight-architecture-deci - [Plugin landing page](../../README.md). The front door. Start here if you arrived from outside the docs tree. - [YAGNI](../yagni.md). The evidence-based "You Aren't Gonna Need It" rule this skill applies before committing items. The two gates, the acceptable-evidence list, the named anti-patterns, and the deferral format. -- [Skills Index](./README.md). All 15 skills, grouped by purpose. +- [Skills Index](./README.md). All 16 skills, grouped by purpose. - [`/coding-standard`](./coding-standard.md). For rules that come out of a decision. Link the standard to the ADR. - [`/architectural-analysis`](./architectural-analysis.md). Often produces decisions worth recording as ADRs. - [`/project-documentation`](./project-documentation.md). For feature docs that reference the ADR. diff --git a/docs/skills/code-review.md b/docs/skills/code-review.md index fafb250..34db7b9 100644 --- a/docs/skills/code-review.md +++ b/docs/skills/code-review.md @@ -162,7 +162,7 @@ URL: https://itrevolution.com/product/accelerate/ - [Plugin landing page](../../README.md). The front door. Start here if you arrived from outside the docs tree. - [YAGNI](../yagni.md). The evidence-based "You Aren't Gonna Need It" rule this skill applies before committing items. The two gates, the acceptable-evidence list, the named anti-patterns, and the deferral format. -- [Skills Index](./README.md). All 15 skills, grouped by purpose. +- [Skills Index](./README.md). All 16 skills, grouped by purpose. - [`/gh-pr-review`](./gh-pr-review.md). Wraps this skill and posts the review to a GitHub PR. - [`/investigate`](./investigate.md). Next step when a CRIT finding hides a bug whose root cause needs deeper analysis. - [`/architectural-analysis`](./architectural-analysis.md). Run alongside when the change touches module boundaries. diff --git a/docs/skills/coding-standard.md b/docs/skills/coding-standard.md index 7dd4c94..007c164 100644 --- a/docs/skills/coding-standard.md +++ b/docs/skills/coding-standard.md @@ -118,7 +118,7 @@ URL: https://sre.google/sre-book/ - [Plugin landing page](../../README.md). The front door. Start here if you arrived from outside the docs tree. - [YAGNI](../yagni.md). The evidence-based "You Aren't Gonna Need It" rule this skill applies before committing items. The two gates, the acceptable-evidence list, the named anti-patterns, and the deferral format. -- [Skills Index](./README.md). All 15 skills, grouped by purpose. +- [Skills Index](./README.md). All 16 skills, grouped by purpose. - [`/architectural-decision-record`](./architectural-decision-record.md). For decisions rather than rules. Link the standard to the ADR when the rule embeds a choice. - [`/project-documentation`](./project-documentation.md). For system and feature documentation that is not a rule. - [`/code-review`](./code-review.md). Reads standards during every review. Violations become findings. diff --git a/docs/skills/gap-analysis.md b/docs/skills/gap-analysis.md index 0c29555..727e933 100644 --- a/docs/skills/gap-analysis.md +++ b/docs/skills/gap-analysis.md @@ -200,7 +200,7 @@ URLs: https://hbr.org/2007/09/performing-a-project-premortem and https://en.wiki ## Related documentation - [Plugin landing page](../../README.md). The front door. Start here if you arrived from outside the docs tree. -- [Skills Index](./README.md). All 15 skills, grouped by purpose. +- [Skills Index](./README.md). All 16 skills, grouped by purpose. - [Sizing](../sizing.md). The cross-skill sizing model. Explains the small / medium / large bands, the default-to-small rule, and the `$size` override. - [`gap-analyzer`](../agents/gap-analyzer.md). The agent that performs the underlying gap analysis. The skill always dispatches it once and reads its full output. - [`adversarial-validator`](../agents/adversarial-validator.md). Required swarm role at every size. Attacks each gap with counter-evidence to produce per-gap `confirmed` / `contradicted` / `inconclusive` verdicts. diff --git a/docs/skills/gh-pr-review.md b/docs/skills/gh-pr-review.md index 7090364..94f9311 100644 --- a/docs/skills/gh-pr-review.md +++ b/docs/skills/gh-pr-review.md @@ -97,7 +97,7 @@ URL: https://google.github.io/eng-practices/review/reviewer/ ## Related documentation - [Plugin landing page](../../README.md). The front door. Start here if you arrived from outside the docs tree. -- [Skills Index](./README.md). All 15 skills, grouped by purpose. +- [Skills Index](./README.md). All 16 skills, grouped by purpose. - [`/code-review`](./code-review.md). The skill this one wraps. Use directly for local review without GitHub posting. - [`/update-pr-description`](./update-pr-description.md). For writing the PR description. - [`/investigate`](./investigate.md). Next step when a Critical finding hides a bug. diff --git a/docs/skills/implementation-plan-to-issues.md b/docs/skills/implementation-plan-to-issues.md new file mode 100644 index 0000000..5af1be4 --- /dev/null +++ b/docs/skills/implementation-plan-to-issues.md @@ -0,0 +1,79 @@ +# /implementation-plan-to-issues + +Operator documentation for the `/implementation-plan-to-issues` skill in the han plugin. This document helps you decide *when* and *how* to use the skill. For what the skill does internally, read the skill definition at [`plugin/skills/implementation-plan-to-issues/SKILL.md`](../../plugin/skills/implementation-plan-to-issues/SKILL.md). + +> See also: [Plugin landing page](../../README.md) · [All skills](./README.md) · [All agents](../agents/README.md) · [YAGNI](../yagni.md) + +## TL;DR + +- **What it does.** Takes an implementation plan and divides it up into individual, focused units of work, which we will call issues. +- **When to use it.** You have an implementation plan and now you need to divide it up into issues and determine dependencies (e.g., which issues can and can't be worked on in parallel). These issues will be ready to be assigned to an implementor. +- **What you get back.** `.work-items.md`, a list of the work items generated for the targeted repo. + +## Key concepts + +- **Vertical slice.** Each unit of work is a narrow but complete path through the relevant layers (schema, API, UI, tests) for a single repo. A completed slice is demoable or verifiable on its own: not a layer, not a stub. +- **HITL and AFK.** Every slice is classified as HITL (requires a human sync: architectural decision, design review) or AFK (can be implemented and merged without one). The skill prefers AFK and prefers many thin slices over few thick ones. +- **Symbolic ID.** Each slice gets a per-repo identifier (`SYM-N`) assigned before GitHub issue numbers exist. Symbolic IDs are for cross-referencing slices within and across work-items files. They are replaced by actual issue numbers (`#NNN`) when issues are created. +- **Work-items file.** The primary output is one `.work-items.md` file per affected repo, written alongside the plan. It contains a preamble (cross-repo integration table, shared artifacts) followed by one section per slice. +- **Cross-repo vs. within-repo dependencies.** Slices in the same repo use native `Depends on` ordering. Dependencies that cross repo boundaries are never native blockers. They live in the preamble integration table as integration contracts, and the table's Precedence rule wins over per-ticket ordering hints. + +## When to use it + +**Invoke when:** + +- You have a high degree of confidence in a plan and you're ready to start implementing it. + +**Do not invoke for:** + +- **Thinking about a feature.** Use [`/plan-a-feature`](./plan-a-feature.md) to start a feature from scratch, developing specifications through asking questions. +- **Turning feature specs into an implementation plan.** Use [`/plan-implementation`](./plan-implementation.md) to turn a feature specification into an implementation plan through a project-manager-led team conversation. +- **Reviewing a plan.** Use [`/iterative-plan-review`](./iterative-plan-review.md) to stress-test an existing plan through multiple codebase-grounded review passes. +- **Any work where there isn't an existing implementation plan.** If there isn't an implementation plan yet, use one of the above entry points to create one before trying to divide it into issues. + +## How to invoke it + +Run `/implementation-plan-to-issues` in Claude Code. + +Give it: + +1. **The feature name or implementation plan, optional.** The default is to look for the plan within the project. + +Example prompts that work well: + +- `/implementation-plan-to-issues docs/features/my-feature/feature-implementation-plan.md`. Divides the plan described in `feature-implementation-plan.md` up into issues. +- `/implementation-plan-to-issues my-feature`. Looks for a plan implementation under `docs/features/my-feature` to divide up into issues. + +## What you get back + +One file on disk per affected repo plus an in-channel summary: + +- The **`.work-items.md`**. The stakeholder-readable artifact. Each section is a work item. +- An **in-channel summary** with the work item list path and any open recommendations. + +## How to get the most out of it + +- **Be explicit about the feature.** The default direction is to make a best guess, based on which feature (with an implementation plan) was most currently worked on. Give the feature name explicitly to help guide the agent to the desired result. +- **Pair with `/plan-implementation` upstream.** This skill is highly-dependent on there being a plan in place. +- **Pair with `/iterative-plan-review` upstream.** A highly-trusted, reviewed-and-battle-tested plan makes the work of divvying up issues much easier. + +## Cost and latency + +One sub-agent dispatch: `project-manager` on `sonnet` for slice drafting (Step 4). All other work runs in-process: locating and reading the plan, inventorying reference artifacts, assigning symbolic IDs, presenting the breakdown for confirmation, and writing the work-items files. The project-manager dispatch is the most expensive step. For a typical feature plan, expect a single dispatch plus a few minutes of in-process work. The skill is designed for a once-per-plan cadence after planning is complete. Re-run it only after the plan has materially changed. For iterating on the plan itself, use `/iterative-plan-review`. + +## YAGNI (when applicable) + +YAGNI does not gate this skill's output. The work-items file is a structural decomposition of an already-committed implementation plan: the slice boundaries, HITL/AFK classification, and reference artifact links derive from what the plan already decided. This skill does not introduce new behavioral commitments or speculative infrastructure. YAGNI enforcement belongs upstream, in `/plan-implementation` and `/iterative-plan-review`, before the plan reaches this stage. + +If the plan you are decomposing has not yet been through a YAGNI sweep, run `/iterative-plan-review` first. + +See [YAGNI](../yagni.md) for the two gates, the acceptable-evidence list, and the named anti-patterns. + +## Related documentation + +- [Plugin landing page](../../README.md). The front door. Start here if you arrived from outside the docs tree. +- [Skills Index](./README.md). All 16 skills, grouped by purpose. +- [`project-manager`](../agents/project-manager.md). Dispatched in Step 4 to draft the vertical slice breakdown. +- [`/iterative-plan-review`](./iterative-plan-review.md). Pair upstream when splitting up an implementation plan you do not yet trust. Hardening the desired state makes breaking down into issues easier. +- [`/plan-implementation`](./plan-implementation.md). Pair upstream when splitting up a simpler or more trusted implementation plan. +- [Report template](../../plugin/skills/implementation-plan-to-issues/references/issue-template.md). The template the skill renders for each issue. diff --git a/docs/skills/investigate.md b/docs/skills/investigate.md index eb2f986..1390c59 100644 --- a/docs/skills/investigate.md +++ b/docs/skills/investigate.md @@ -121,7 +121,7 @@ URL: https://pragprog.com/titles/tpp20/the-pragmatic-programmer-20th-anniversary ## Related documentation - [Plugin landing page](../../README.md). The front door. Start here if you arrived from outside the docs tree. -- [Skills Index](./README.md). All 15 skills, grouped by purpose. +- [Skills Index](./README.md). All 16 skills, grouped by purpose. - [`evidence-based-investigator`](../agents/evidence-based-investigator.md). The agent the skill dispatches in parallel for multi-angle evidence gathering. - [`adversarial-validator`](../agents/adversarial-validator.md). The agent that challenges evidence and fix after the plan is drafted. - [`concurrency-analyst`](../agents/concurrency-analyst.md), [`behavioral-analyst`](../agents/behavioral-analyst.md), [`data-engineer`](../agents/data-engineer.md). Specialist analysts dispatched alongside the investigators when the symptom classification calls for them. diff --git a/docs/skills/iterative-plan-review.md b/docs/skills/iterative-plan-review.md index 850d75a..4e69df5 100644 --- a/docs/skills/iterative-plan-review.md +++ b/docs/skills/iterative-plan-review.md @@ -191,7 +191,7 @@ URLs: https://asana.com/resources/raid-log and https://projectmanagementcompass. - [Plugin landing page](../../README.md). The front door. Start here if you arrived from outside the docs tree. - [YAGNI](../yagni.md). The evidence-based "You Aren't Gonna Need It" rule this skill applies before committing items. The two gates, the acceptable-evidence list, the named anti-patterns, and the deferral format. -- [Skills Index](./README.md). All 15 skills, grouped by purpose. +- [Skills Index](./README.md). All 16 skills, grouped by purpose. - [Sizing](../sizing.md). The cross-skill sizing model. Explains the small / medium / large bands, the default-to-small rule, and the `$size` override. - [`/plan-a-feature`](./plan-a-feature.md). The upstream skill for producing a feature specification from scratch. This skill can iterate on that spec, but the typical handoff is spec → `/plan-implementation` → this skill. - [`/plan-implementation`](./plan-implementation.md). The upstream skill for producing a committable implementation plan. This skill is the natural next step when the team wants the implementation plan stress-tested across multiple review passes. diff --git a/docs/skills/plan-a-feature.md b/docs/skills/plan-a-feature.md index f2ed802..15e7a26 100644 --- a/docs/skills/plan-a-feature.md +++ b/docs/skills/plan-a-feature.md @@ -183,7 +183,7 @@ URLs: https://asana.com/resources/raid-log and https://projectmanagementcompass. - [Plugin landing page](../../README.md). The front door. Start here if you arrived from outside the docs tree. - [YAGNI](../yagni.md). The evidence-based "You Aren't Gonna Need It" rule this skill applies before committing items. The two gates, the acceptable-evidence list, the named anti-patterns, and the deferral format. -- [Skills Index](./README.md). All 15 skills, grouped by purpose. +- [Skills Index](./README.md). All 16 skills, grouped by purpose. - [Sizing](../sizing.md). The cross-skill sizing model. Explains the small / medium / large bands, the default-to-small rule, and the `$size` override. - [`/plan-implementation`](./plan-implementation.md). The next step after this skill. Takes the `feature-specification.md` produced here and turns it into a feature-implementation-plan through an iterative, project-manager-led team conversation. - [`/iterative-plan-review`](./iterative-plan-review.md). The complement for plans that already exist. Use this when an implementation plan or spec has been drafted and needs multiple review passes to challenge assumptions and refine. diff --git a/docs/skills/plan-a-phased-build.md b/docs/skills/plan-a-phased-build.md index 341acec..e176bc5 100644 --- a/docs/skills/plan-a-phased-build.md +++ b/docs/skills/plan-a-phased-build.md @@ -195,7 +195,7 @@ URL: see [`information-architect` agent definition](../../plugin/agents/informat - [Plugin landing page](../../README.md). The front door. Start here if you arrived from outside the docs tree. - [YAGNI](../yagni.md). The evidence-based "You Aren't Gonna Need It" rule this skill applies before committing items. The two gates, the acceptable-evidence list, the named anti-patterns, and the deferral format. -- [Skills Index](./README.md). All 15 skills, grouped by purpose. +- [Skills Index](./README.md). All 16 skills, grouped by purpose. - [`information-architect`](../agents/information-architect.md). The agent the skill dispatches at runtime to review the rendered outline. Also the agent that reviewed the output template before the skill shipped. - [`/gap-analysis`](./gap-analysis.md). Pair upstream when the source artifact is a comparison between current and desired state. Run `/gap-analysis` first to produce the gap report, then point this skill at the report. `G-NNN` gap IDs become source citations on the phase entries that close them. - [`/plan-a-feature`](./plan-a-feature.md). Pair upstream when the source artifact is a single feature that needs a phased rollout. Run `/plan-a-feature` first to produce the spec, then point this skill at the spec when the feature is large enough to ship in slices rather than all at once. diff --git a/docs/skills/plan-implementation.md b/docs/skills/plan-implementation.md index e288e08..72d135a 100644 --- a/docs/skills/plan-implementation.md +++ b/docs/skills/plan-implementation.md @@ -200,7 +200,7 @@ URL: https://ieeexplore.ieee.org/document/1204375 - [Plugin landing page](../../README.md). The front door. Start here if you arrived from outside the docs tree. - [YAGNI](../yagni.md). The evidence-based "You Aren't Gonna Need It" rule this skill applies before committing items. The two gates, the acceptable-evidence list, the named anti-patterns, and the deferral format. -- [Skills Index](./README.md). All 15 skills, grouped by purpose. +- [Skills Index](./README.md). All 16 skills, grouped by purpose. - [Sizing](../sizing.md). The cross-skill sizing model. Explains the small / medium / large bands, the default-to-small rule, and the `$size` override. - [`/plan-a-feature`](./plan-a-feature.md). The prior step. Produces the `feature-specification.md` this skill consumes. Running the two in sequence is the intended flow: *what* first, *how* second. - [`/iterative-plan-review`](./iterative-plan-review.md). The complement for stress-testing the plan after it lands. This skill produces the committable plan. `/iterative-plan-review` iterates on it. diff --git a/docs/skills/project-discovery.md b/docs/skills/project-discovery.md index 2bc0054..33de9c9 100644 --- a/docs/skills/project-discovery.md +++ b/docs/skills/project-discovery.md @@ -98,7 +98,7 @@ URL: https://research.google/pubs/why-google-stores-billions-of-lines-of-code-in ## Related documentation - [Plugin landing page](../../README.md). The front door. Start here if you arrived from outside the docs tree. -- [Skills Index](./README.md). All 15 skills, grouped by purpose. +- [Skills Index](./README.md). All 16 skills, grouped by purpose. - [`/project-documentation`](./project-documentation.md). For feature and system docs. Reads the discovery reference to find the right directory and language. - [`/coding-standard`](./coding-standard.md). For coding rules. Reads the discovery reference to find the standards directory. - [`/architectural-decision-record`](./architectural-decision-record.md). For architectural decisions. Reads the discovery reference to find the ADR directory. diff --git a/docs/skills/project-documentation.md b/docs/skills/project-documentation.md index 215704b..9e6443d 100644 --- a/docs/skills/project-documentation.md +++ b/docs/skills/project-documentation.md @@ -115,7 +115,7 @@ URL: https://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture ## Related documentation - [Plugin landing page](../../README.md). The front door. Start here if you arrived from outside the docs tree. -- [Skills Index](./README.md). All 15 skills, grouped by purpose. +- [Skills Index](./README.md). All 16 skills, grouped by purpose. - [`/project-discovery`](./project-discovery.md). Run first. The documentation skill reads the discovery reference to find the docs directory and stack language. - [`/architectural-decision-record`](./architectural-decision-record.md). Use for decisions rather than system documentation. - [`/coding-standard`](./coding-standard.md). Use for rules rather than descriptions. diff --git a/docs/skills/test-planning.md b/docs/skills/test-planning.md index f33b87f..f07f6f8 100644 --- a/docs/skills/test-planning.md +++ b/docs/skills/test-planning.md @@ -115,7 +115,7 @@ URL: https://www.wiley.com/en-us/Testing+Computer+Software%2C+2nd+Edition-p-9780 - [Plugin landing page](../../README.md). The front door. Start here if you arrived from outside the docs tree. - [YAGNI](../yagni.md). The evidence-based "You Aren't Gonna Need It" rule this skill applies before committing items. The two gates, the acceptable-evidence list, the named anti-patterns, and the deferral format. -- [Skills Index](./README.md). All 15 skills, grouped by purpose. +- [Skills Index](./README.md). All 16 skills, grouped by purpose. - [`/code-review`](./code-review.md). Dispatches the same agents plus `adversarial-security-analyst`. Use when you want correctness findings too. - [`/architectural-analysis`](./architectural-analysis.md). For structural testability concerns. - [`/iterative-plan-review`](./iterative-plan-review.md). Use to stress-test an already-written test plan. diff --git a/docs/skills/update-pr-description.md b/docs/skills/update-pr-description.md index fe132a1..13ad230 100644 --- a/docs/skills/update-pr-description.md +++ b/docs/skills/update-pr-description.md @@ -99,7 +99,7 @@ URL: https://martinfowler.com/articles/feature-toggles.html ## Related documentation - [Plugin landing page](../../README.md). The front door. Start here if you arrived from outside the docs tree. -- [Skills Index](./README.md). All 15 skills, grouped by purpose. +- [Skills Index](./README.md). All 16 skills, grouped by purpose. - [`/gh-pr-review`](./gh-pr-review.md). Post a code review to the same PR. - [`/code-review`](./code-review.md). Local code review without touching GitHub. - [`junior-developer`](../agents/junior-developer.md). Runs the reviewer context check against the drafted description. diff --git a/plugin/skills/implementation-plan-to-issues/SKILL.md b/plugin/skills/implementation-plan-to-issues/SKILL.md new file mode 100644 index 0000000..4c43796 --- /dev/null +++ b/plugin/skills/implementation-plan-to-issues/SKILL.md @@ -0,0 +1,91 @@ +--- +name: implementation-plan-to-issues +description: > + Break an implementation plan into independently-grabbable issues. Use when + user wants to convert a plan to issues, create implementation tickets, or + break down the plan into work items. Do not use when there isn't an + implementation plan yet, or when the plan isn't yet trusted. Pair with + `/plan-implementation` or `/iterative-plan-review` upstream to create or + harden the plan before breaking it into issues. +allowed-tools: Read, Write, Edit, Glob, Grep, Agent, Bash(find *), Bash(gh *) +--- + +## Pre-requisites + +- gh CLI: !`which gh` + +If `gh CLI` is not found and the user has provided a `github.com` URL as the plan source, inform the user that the gh CLI must be installed and configured to fetch issue content, and ask them to provide the plan as a file path instead. If the plan is a file path, proceed regardless of gh CLI availability. + +## Project Context + +- CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f` +- project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f` +- feature-implementation-plan.md: !`find . -maxdepth 5 -name "feature-implementation-plan.md" -type f` + +# Implementation Plan to Issues + +Break an implementation plan into vertical slices (tracer bullets), write a work-item file per repo. + +This skill (Steps 1–7) largely coordinates: locating the plan, getting confirmation, writing the work-items file. Step 4 is where the judgement comes into play, in dividing up the plan. + +## Rules + +- Do NOT close, edit, or comment on the parent implementation plan issue. +- Each slice lives in exactly one repo. Cross-repo integration is documented in the preamble integration table, never as a native blocker. +- Native `blocked_by` relationships are **within-repo only**. Cross-repo dependencies stay in the preamble integration table. +- Every slice issue body MUST link the reference artifacts an implementer needs: API/event contracts, design frames, schema docs, runbooks, ADRs, coding standards. Issues that consume an HTTP endpoint or event payload MUST link the contract section that defines it. +- UI slices, when the plan folder has a `ui-designs/` subfolder, MUST embed the relevant screenshots inline using same-target-repo raw URLs. See [references/screenshot-embed-rules.md](references/screenshot-embed-rules.md). +- NEVER include process artifacts in issue bodies or the work-items preamble. Excluded categories: iteration histories, decision logs, review findings, team findings, facilitation summaries, gap analyses, and anything under an `artifacts/` subfolder of the plan that is not a contract or design reference. Restate plan-level decisions inline in the slice with `See plan: D-N` as the breadcrumb. Full include/exclude list in [references/reference-artifact-inventory.md](references/reference-artifact-inventory.md). + +## Process + +### 1. Locate the implementation plan + +If the plan is not provided, check to see if there are any existing features with plans, e.g., `docs/features//feature-implementation-plan.md`. If there is only one, use that as the plan. If there are multiple, use the most recently-updated file as the plan. If there are none, ask for the plan file path or an issue URL. If the plan is a file and not already in context, read it. If the plan is a `github.com` URL, use the `gh` CLI tool to fetch the issue. Otherwise, try to use WebFetch to retrieve the issue body and all comments. If the issue body references a file, read that file too. The plan content is the union of all these sources. If WebFetch fails, e.g., due to authentication errors, ask the user to paste the content directly. + +### 2. Explore the codebase when needed + +If the plan references existing code or repo boundaries that aren't in your context, explore the affected repos. Skip exploration if the plan is self-contained and the boundaries are already clear. + +### 3. Inventory reference artifacts + +Before drafting slices, list every artifact an implementer of those slices will need. See [references/reference-artifact-inventory.md](references/reference-artifact-inventory.md) for the include list, exclude list, and screenshot-to-slice mapping rules. + +If an expected artifact is missing (e.g., the plan touches an HTTP boundary but no contract file exists), surface it to the user before Step 4. Slices that consume an undefined contract are not draftable. + +### 4. Draft vertical slices + +Launch `project-manager` (`subagent_type: "han:project-manager"`, `model: "sonnet"`) with: + +- The full plan content from Step 1. +- The artifact inventory from Step 3. +- The Rules section of this skill verbatim. +- A directive to draft vertical slices: each slice is a narrow but complete path through the appropriate layers (schema, API, UI, tests) for a single repo, demoable or verifiable on its own. Classify each slice as **HITL** (requires human interaction: architectural decision, design review) or **AFK** (can be implemented and merged without sync). Prefer AFK over HITL. Prefer many thin slices over few thick ones. +- A directive to return the proposed slice breakdown as a numbered list. Do not write any files. + +Return the project-manager's output verbatim. Proceed to Step 5. + +### 5. Assign symbolic IDs and titles + +Give each slice a per-repo symbolic ID: a short prefix + sequential number within that file. + +Propose a 1–3 letter prefix based on the repo name and surface it to the user in Step 6 for confirmation before writing files. + +Issue title format: ` — ` (em-dash separator). + +### 6. Show the breakdown and get confirmation + +Present a numbered list. For each slice show: + +- **Title**: ` — ` +- **Type**: HITL or AFK +- **Depends on**: other slices in the **same repo** that must complete first, or `None` +- **Work items addressed**: user stories or work-unit numbers from the parent plan that this slice satisfies +- **Reference artifacts**: contract sections, design frame IDs, ADRs, and other references from Step 3 +- **Screenshots**: when `ui-designs/` exists and the slice is UI-bearing, list the screenshot filenames that will be embedded in the issue body + +Wait for the user's confirmation before writing files or creating issues. + +### 7. Write work-item files + +**Plan is a file:** write one `.work-items.md` file per affected repo, in the same folder as the plan file. File layout (title line, intro, preamble structure) is specified in [references/work-items-file-format.md](references/work-items-file-format.md). Slice template is [references/issue-template.md](references/issue-template.md). diff --git a/plugin/skills/implementation-plan-to-issues/references/issue-template.md b/plugin/skills/implementation-plan-to-issues/references/issue-template.md new file mode 100644 index 0000000..33a5a49 --- /dev/null +++ b/plugin/skills/implementation-plan-to-issues/references/issue-template.md @@ -0,0 +1,45 @@ +# Slice issue template + +Each slice in a `.work-items.md` file uses this template. Required fields appear in the order shown. The `**References.**` block is required whenever the slice consumes any artifact identified in Step 3 of the skill — omit it only when no external artifact applies. Additional `**Bold paragraph.**` context blocks are allowed between required fields when a slice needs them — common ones: `**Note on scope boundary with .**` for ticket-boundary clarifications, `**Note on capability.**` for SDK or platform caveats that affect acceptance. + +``` +## — + +**Summary.** One paragraph describing what this slice delivers. Include a plan reference inline (e.g., `See plan: [D-6](feature-implementation-plan.md#d-6-...)` or `See plan: D-3, D-7, and Work Unit 2`). The plan reference replaces a standalone "Work items addressed" field — do not add one. + +**Description.** +1. Numbered steps describing the full behavior to build. +2. Reference implementation details by file path where helpful (`db/ent/schema/jot.go`), but do not prescribe implementation code. +3. Duplicate content from the parent plan into this description when clarity requires it. + +*(Insert additional `**Bold paragraph.**` blocks here when needed — e.g., `**Note on scope boundary.**`.)* + +**Screenshots.** *(Required for UI-bearing slices when the plan folder contains a `ui-designs/` subfolder. Embed each screenshot inline using a same-target-repo raw URL of the form `https://github.com///raw//.github/issue-assets//.png`. Cross-repo URLs are forbidden — the automated implementation tooling cannot resolve them. Wrap each embed in a link to the same URL so readers can open the full-size image in a new tab. One image per bullet, with a short caption naming the depicted state. Omit the entire block when the slice has no UI surface or no `ui-designs/` folder exists.)* + +- ** — `[![](https://github.com///raw//.github/issue-assets//.png)](https://github.com///raw//.github/issue-assets//.png)` + +**References.** +- **API contract** — `[#]()` (e.g., `[api-contracts.md#post-v1-parent_kind-id-comments-create](api-contracts.md#post-v1parent_kindidcomments--create)`). Required when the slice produces or consumes an HTTP endpoint. +- **Event contract** — `[#]()`. Required when the slice produces or consumes an event payload. +- **Design (Pencil)** — ``, frames `` (purpose), `` (purpose). Required for UI slices. +- **Spec section** — `[feature-specification.md#](feature-specification.md#)` for the behavior this slice realizes. +- **ADR / standard / repo doc** — link any architectural decision, coding standard, or feature doc the implementer must honor. +- Omit any bullet that does not apply. Do not link iteration histories, decision logs, review findings, team findings, facilitation summaries, or any other process artifact. + +**Tests.** +- Bullet list of tests required for the behavior above. Be concrete: name the test type (unit, integration, migration, visual, etc.) and the assertion. + +**Acceptance criteria.** +- [ ] Criterion 1 +- [ ] Criterion 2 + +**Depends on.** `` (within this repo), comma-separated for multiple, or `None.` +``` + +## Format invariants the scripts depend on + +- Heading line begins with `## ` followed by `` (uppercase letters, dash, digits), then ` — ` (em-dash with surrounding spaces), then the title. +- After issue creation, the heading is rewritten in place to `## (#NNN) — `. The `(#NNN)` annotation is how `link-blockers.sh` resolves symbolic IDs to GitHub issue numbers, and how `create-issues.sh` knows to skip already-created slices on re-run. +- A slice body ends at the next `## ` heading or end of file. +- Screenshot URLs use the exact path scheme `.github/issue-assets/<SYM-N>/<file>.png`. The upload script extracts this path verbatim from the work-items file. +- The `**Depends on.**` line uses the literal bold marker, comma-separates blockers, and ends with `.` (the trailing period is part of the format, not a sentence terminator). diff --git a/plugin/skills/implementation-plan-to-issues/references/reference-artifact-inventory.md b/plugin/skills/implementation-plan-to-issues/references/reference-artifact-inventory.md new file mode 100644 index 0000000..8e2c6e3 --- /dev/null +++ b/plugin/skills/implementation-plan-to-issues/references/reference-artifact-inventory.md @@ -0,0 +1,33 @@ +# Reference artifact inventory + +Before drafting slices, list every artifact an implementer of those slices will need to reach for. Pull from the same folder as the plan, the plan's links, and the cross-repo rule in `.claude/rules/cross-repository-work.md`. + +## Include (link these from slices and/or the preamble) + +- **HTTP API contract files** (e.g., `api-contracts.md`) and the specific endpoint sections that slices in this breakdown produce or consume. +- **Event payload contract files** and the specific event sections. +- **Feature specification** (`feature-specification.md`) — sections that define behavior the slice must realize. +- **Design assets** — Pencil document file paths plus specific frame IDs (when the plan or a sibling doc maps frames to UI), screenshot files, Figma URLs, mockup PDFs. +- **Screenshots from `ui-designs/`**, when present. Inventory every PNG in that folder and map each one to the slices that realize the behavior it depicts. Use the feature spec as the mapping source: the spec's "Visual Reference" table (or equivalent) lists every screenshot, and the spec's inline `![…](ui-designs/…png)` embeds appear next to the prose that describes the depicted state — that prose tells you which slice owns the screenshot. A single slice may need multiple screenshots when it implements multiple states (e.g., a list-page slice may embed both the manager and viewer states); a single screenshot may apply to multiple slices when distinct slices share a screen — in that case the file is copied once into each owning slice's `.github/issue-assets/<SYM-N>/` folder by the upload script. The planning-repo location is the *source*; it is never the URL embedded in the issue. See [screenshot-embed-rules.md](screenshot-embed-rules.md) for the full URL rule. +- **Schema/migration references** in the target repo when a slice depends on a not-yet-shipped schema. +- **ADRs** (`docs/adr/...` in target repos), coding standards, and feature documentation that constrain the slice's implementation. +- **Runbook skeletons or observability notes** only when a slice's acceptance criteria require them. + +## Exclude (these never belong in tickets) + +- Iteration histories (`*-iteration-history.md`, `.evidence-roundN.md`, `.junior-developer-roundN.md`, `.adversarial-roundN.md`, etc.) +- Decision logs (`decision-log.md`, `implementation-decision-log.md`) +- Review findings (`review-findings.md`, `implementation-review-findings.md`) +- Team findings, facilitation summaries, gap analyses, security/UX round notes +- Anything under an `artifacts/` subfolder of the plan **unless** it is a contract or design reference (e.g., a `design-frame-verification.md` may be cited; a `team-findings.md` may not). + +These exist to record how the plan was reached, not what the implementer needs to build. Plan-level decisions that survive into the slice are restated inline in the slice description, with `See plan: D-N` as the breadcrumb — never a link to the decision log itself. + +## Where to cite each artifact + +- When a single artifact applies to **many slices in one repo**, cite it once in that repo's preamble (under "Shared reference artifacts" or equivalent) and let slices reference the section by anchor. +- When an artifact applies to a **single slice**, cite it inline in that slice's `**References.**` block. + +## Missing-artifact handling + +If an expected artifact is missing — for example, the plan touches an HTTP boundary but no contract file exists — surface it to the user **before drafting slices**. Slices that consume an undefined contract are not draftable. diff --git a/plugin/skills/implementation-plan-to-issues/references/screenshot-embed-rules.md b/plugin/skills/implementation-plan-to-issues/references/screenshot-embed-rules.md new file mode 100644 index 0000000..2b6673b --- /dev/null +++ b/plugin/skills/implementation-plan-to-issues/references/screenshot-embed-rules.md @@ -0,0 +1,45 @@ +# Screenshot embed rules + +When the plan folder contains a `ui-designs/` subfolder with screenshot files (typically produced by the `ui-design-from-feature-spec` skill), every UI-bearing slice MUST embed the relevant screenshots **inline in the issue body** — not as plain links. + +## Why cross-repo URLs are forbidden + +The automated implementation tooling (Ralph) runs against the **target code repo** and cannot resolve URLs that point into a different repository. An issue body with cross-repo image URLs renders blank in that environment, and the implementer can't see the design. + +Solution: **copy each PNG into the target repo first**, then embed it via a same-repo URL. + +## Required URL form + +``` +https://github.com/<organization>/<target-repo>/raw/<branch>/.github/issue-assets/<SYM-N>/<file>.png +``` + +- `<organization>` is the GitHub organization that contains the code repo, usually a username or business name (e.g., `testdouble`). +- `<target-repo>` is the code repo the issue is being created in (e.g., `han`). +- `<branch>` is the target repo's default branch, fetched at upload time via `gh repo view <organization>/<repo> --json defaultBranchRef --jq .defaultBranchRef.name` (typically `main`). +- `<SYM-N>` is the slice's symbolic ID (e.g., `W-3`). +- `<file>.png` matches the source filename in `<plan-folder>/ui-designs/<file>.png`. + +## Embed format inside the issue body + +Wrap each embed in a link to the same URL so readers can open the full-size image in a new tab: + +``` +- *<state-or-scenario name>* — [![<alt text>](<URL>)](<URL>) +``` + +One image per bullet, with a short caption naming the depicted state. + +## Mapping screenshots to slices + +Map screenshots to slices via the feature spec's own embeds: the section in the spec that describes the behavior a slice implements is where the canonical screenshot for that slice is referenced. + +## Duplication over sharing + +When a screenshot applies to multiple slices, copy it once **per slice** so each `<SYM-N>` folder is self-contained. The upload script handles this automatically — every URL it sees in the work-items file produces an upload, even if the source file is shared. + +## What never to do + +- Never embed any cross-repo URL in an issue body. +- Never use a shared `.github/issue-assets/shared/` path. Each slice owns its own folder. +- Never link to a screenshot without embedding the image — implementers should see the design without clicking out. diff --git a/plugin/skills/implementation-plan-to-issues/references/work-items-file-format.md b/plugin/skills/implementation-plan-to-issues/references/work-items-file-format.md new file mode 100644 index 0000000..1ed55de --- /dev/null +++ b/plugin/skills/implementation-plan-to-issues/references/work-items-file-format.md @@ -0,0 +1,30 @@ +# Work-items file format + +One file per affected repo, in the same folder as the plan, named `<repo-name>.work-items.md` (e.g., `my-repo.work-items.md`). + +## Title and intro + +``` +# <repo-name> Work Items — <feature-name> +``` + +Followed by one intro paragraph linking the parent plan and noting: + +> Issues are numbered `<SYM>-N` for cross-reference only; actual issue numbers come from the issue tracker on creation. Dependencies listed are within this repo only. + +Link the parent plan once here. Do not relink it inside every slice. + +## Preamble (only when the plan touches more than one repo) + +In order: + +1. **Prerequisites** *(required when this repo depends on external PRs or other-repo deliverables)* — external PRs or cross-repo deliverables whose state must be verified before picking up any slice in this file. +2. **Cross-repo integration points** *(required)* — a table of what this repo emits/exposes, which other-repo component consumes it, and the downstream slice that does the consuming. Immediately after the table, include a one-paragraph **Precedence rule**: + > If a per-ticket `Depends on` line conflicts with this table, this table wins for upstream-vs-downstream ownership. Per-ticket `Depends on` is a within-repo ordering hint only. +3. **Shared reference artifacts** *(required when any artifact applies to more than one slice in this file)* — API response envelopes, event payload shapes, shared-stylesheet notices, design-frame-to-component mappings (Pencil document path + frame IDs), ADR pointers. Each entry is a relative link plus the anchor an implementer should jump to. + +## Slices + +Every slice uses the template at [issue-template.md](issue-template.md). + +The preamble (Prerequisites, Cross-repo integration points + Precedence rule, Shared reference artifacts) stays in the work-items file and is **not** duplicated into each issue body. Each issue body still carries its own `**References.**` block — slice references can point into the preamble's shared-artifacts entries by anchor when the artifact is shared, but the bullets in the slice itself are what the implementer reads on the issue. diff --git a/plugin/skills/iterative-plan-review/SKILL.md b/plugin/skills/iterative-plan-review/SKILL.md index 551706f..c3214d3 100644 --- a/plugin/skills/iterative-plan-review/SKILL.md +++ b/plugin/skills/iterative-plan-review/SKILL.md @@ -15,6 +15,8 @@ description: > (round-by-round record of specialists engaged and plan changes applied). Do NOT use for implementing plan steps, generating new plans from scratch, writing test plans, code review, or bug investigation. + Can be paired with implementation-plan-to-issues downstream to break the plan + into issues after the plan has been refined. arguments: size argument-hint: "[size: small | medium | large] [context or path to plan file]" allowed-tools: Read, Write, Edit, Glob, Grep, Agent, Bash(find *) diff --git a/plugin/skills/plan-implementation/SKILL.md b/plugin/skills/plan-implementation/SKILL.md index 0a788d1..46c09f5 100644 --- a/plugin/skills/plan-implementation/SKILL.md +++ b/plugin/skills/plan-implementation/SKILL.md @@ -19,6 +19,8 @@ description: > stress-test an already-written plan — use iterative-plan-review. Does not investigate bugs or failures — use investigate. Does not perform file-level code review — use code-review. Does not record architectural decisions — use architectural-decision-record. + Typically paired with implementation-plan-to-issues downstream to break the + plan into issues after it's complete. arguments: size argument-hint: "[size: small | medium | large] [feature specification path, optional: additional context]" allowed-tools: Read, Write, Edit, Glob, Grep, Agent, Bash(find *), Bash(git *)