Plan Implementation

Project Context

• CLAUDE.md: !find . -maxdepth 1 -name "CLAUDE.md" -type f
• project-discovery.md: !find . -maxdepth 3 -name "project-discovery.md" -type f

Operating Principles

• **The feature specification is the ground truth for what.** This skill plans how. Do not re-open behavioral decisions the specification already settled; flag contradictions as Open Questions for the user.
• The han-core:project-manager is the coordinator, not the author of every section. It facilitates rounds of discussion among specialists, tracks claims and evidence, and decides when the plan is ready. Specialists own their domains.
• Always include han-core:junior-developer on the team. When decisions lack strong evidence, the han-core:junior-developer reframes the issue in plain terms first — that frequently unlocks a resolution without needing the user.
• Escalate to the user only when evidence and reframing have both failed. Every escalation surfaces with a full description, the evidence considered, and a recommended answer.
• Done is when the han-core:project-manager says so. The loop exits when the han-core:project-manager reports the plan is ready to commit, or that only user-input items remain. The user is not asked to keep iterating past that point.
• **YAGNI is a first-class operating principle, applied to implementation choices.** The implementation plan inherits the spec's behavioral commitments but applies the evidence-based YAGNI rule from [../../references/yagni-rule.md](../../references/yagni-rule.md) independently to abstractions, configuration knobs, observability, runbooks, infrastructure, rollout machinery, test scaffolding, schema columns, indexes, and any other implementation artifact the plan recommends. Items that fail the evidence test get demoted to a ## Deferred (YAGNI) section in feature-implementation-plan.md with the reopening trigger named; items where a strictly simpler implementation satisfies the same evidence get the simpler implementation recorded as the decision and the larger version under Rejected alternatives:. The Sentry-runbook-on-staging-only-Sentry pattern is the named project precedent — operational machinery shipped before the system that drives it actually produces the data, traffic, or failures it covers is YAGNI by default. Every committed implementation item is ongoing maintenance and a pattern future agents will copy.
• Keep the plan at planning altitude. Name and reference config and code artifacts; do not inline their full contents. Inline only the specific values that are themselves decisions (a flag default, a key name, a threshold). A full file block — a complete plist, a whole config file, a multi-line XML or JSON document — belongs in the file it configures, not in the plan. YAGNI gates whether an item is included; this principle gates how verbose an included item is.
• The plan lives in three cross-referenced files. feature-implementation-plan.md is the primary plan and lives at the root of {folder}/; implementation-decision-log.md records every decision and implementation-iteration-history.md records each round of discussion — both companion artifacts live in {folder}/artifacts/ to keep the planning folder uncluttered. The main plan cites decisions with inline ([D-N](artifacts/implementation-decision-log.md#...)) links for non-obvious claims. The decision log and iteration history cross-link through Driven by rounds: / Decisions produced: fields (they sit as siblings inside artifacts/), and both link back into the plan through Referenced in plan: / Changed in plan: fields using ../feature-implementation-plan.md. Any edit to one file requires updating the matching fields in the others.

Plan an Implementation

Step 1: Locate the Feature Specification

Read the user's argument and conversation context to identify the source artifact. The expected input is a feature-specification.md produced by the plan-a-feature skill, but any document describing what the feature should do is acceptable (PRD, design doc, product brief).

Resolve the source path:

• If the user provided a file path, use it.
• Otherwise, search for a recent feature-specification.md under docs/features/, docs/plans/, or other documentation roots discovered via CLAUDE.md or project-discovery.md. If multiple candidates exist, ask the user which one.
• If no feature specification exists, tell the user this skill requires one and recommend running plan-a-feature first.

Three files will be written. The primary plan lives at the root of {same-folder-as-source}/; the two companion artifacts live in {same-folder-as-source}/artifacts/ (which may already exist if the source spec came from plan-a-feature — share the same subfolder rather than creating a second one):

• {same-folder-as-source}/feature-implementation-plan.md — the primary plan.
• {same-folder-as-source}/artifacts/implementation-decision-log.md — every committed implementation decision with rationale, evidence, and rejected alternatives.
• {same-folder-as-source}/artifacts/implementation-iteration-history.md — round-by-round record of specialists engaged, questions raised, and how each was resolved.

Create the artifacts/ subfolder before writing the companion files if it does not already exist.

The three files cross-reference each other. The main plan cites decisions with inline parenthetical links like ([D-3](artifacts/implementation-decision-log.md#d-3-rollout-strategy)); the decision log and iteration history cross-link through Driven by rounds: / Decisions produced: fields (siblings inside artifacts/), and both link back into the plan through Referenced in plan: / Changed in plan: fields via ../feature-implementation-plan.md.

If any of the three files already exist, ask the user whether to overwrite or append iteration notes before proceeding.

Read the full specification into context. If the specification is a feature-specification.md produced by plan-a-feature, also read its companion decision-log.md, team-findings.md, and feature-technical-notes.md if it exists — these live in {same-folder-as-source}/artifacts/ (the same subfolder this skill will write to). Fall back to reading them from {same-folder-as-source}/ directly for spec folders produced before the artifacts layout was introduced. The feature-technical-notes.md file is lazily created by plan-a-feature — its absence means no load-bearing mechanics were captured at spec time, not that the spec is incomplete. Note the decisions already settled, any open items the spec flagged, the review team findings, and any committed technical mechanics the plan must honor.

Detect tech-notes presence once, here. Record whether feature-technical-notes.md exists. If it does NOT exist, omit every T#-related sentence from agent briefs (Step 4), the spec-maturity tag set (Step 5), and the synthesis inputs (Step 8) — do not add boilerplate qualifiers like "if it exists" to those briefs. The T#-contradiction spec-maturity classification simply does not apply when there are no T# notes, so the spec-maturity gate reduces to the spec-level threshold alone.

Step 2: Discover Implementation Context

Before launching the team, gather the context specialists will need to produce evidence-backed recommendations. Use Glob and Grep to find:

• CLAUDE.md, AGENTS.md, and project-discovery.md — tech stack, languages, frameworks, build tools, test runners.
• ADRs in docs/adr/ or docs/architecture/decisions/ — architectural decisions the implementation must respect.
• Coding standards in docs/coding-standards/ or .github/CODING_STANDARDS.md — rules the implementation must follow.
• Code adjacent to the feature's touch points — existing modules, patterns, integration surfaces the feature will plug into.
• Existing implementation plans in the same documentation root — format precedent and level of detail the team expects.
• Recent activity — if git is available, run git log --since="90 days ago" --name-only --pretty=format:"" on the directories the feature will touch to surface churn and recent precedent.

Write the result to {same-folder-as-source}/artifacts/.discovery-notes.md as a structured summary: tech stack, ADRs found (paths + one-line summary each), coding standards found (paths + one-line summary each), code touch points (paths + one-line summary), recent-activity churn, and explicitly enumerated gaps (what was searched for and not found). Missing standards or ADRs are themselves findings the team should note.

The discovery notes file is the single source of truth for project context across the team. Specialists in Step 4 are instructed to read .discovery-notes.md first and not to re-grep for what has already been found — they may search further for what their domain specifically needs that the discovery notes do not cover, but they must not duplicate what is already there.

Step 3: Select the Team

Default to small. Start the classification at small and only escalate to medium or large when the signals below clearly require it. When a signal is borderline, stay at the smaller band. Use the spec's coordinations, T# count, security/PII surface, integration boundaries, and the user's framing:

• Small (default) — single subsystem, no cross-service integration, no auth/PII/secrets, no data migration. Team cap: 3 (han-core:project-manager + han-core:junior-developer + 1 chosen specialist). Round cap: 1.
• Medium — two to three subsystems, optional integration, may touch UX or rollout, may have a small auth surface. Team cap: 4 to 5 (han-core:project-manager + han-core:junior-developer + 2–3 chosen specialists). Round cap: 2.
• Large — cross-service, security-sensitive, data ownership shifts, multiple new coordinations, or the user explicitly requests full team. Team cap: 6 to 8 (han-core:project-manager + han-core:junior-developer + 4–6 chosen specialists). Round cap: 3.

Size override. If $size is non-empty (the user passed small, medium, or large as the first argument), use that value as the size and skip the signal-based classification above; the team cap and round cap still scale to the chosen size. State the chosen size, the recommended team, and the reason for the size choice to the user in one short message before launching agents (e.g., "Medium: two subsystems, small auth surface" or "Medium: passed via $size"). If the user disagrees, accept the override (size, specific specialists, or both) and proceed.

The team always includes:

• han-core:project-manager — coordinator and final synthesizer.
• han-core:junior-developer — generalist stress-tester and reframer.

Select additional specialists up to the team cap based on what the feature actually touches. Err toward including a specialist rather than discovering a gap late. Unless the user specified a team composition, draw from:

• han-core:user-experience-designer — any user-facing flow, UI, or interaction model.
• han-core:adversarial-security-analyst — authentication, authorization, PII, untrusted input, secrets, supply chain.
• han-core:devops-engineer — deployment, observability, rollout, feature flags, scale, SLO impact, cost.
• han-core:on-call-engineer — application-source resilience patterns the plan introduces: timeouts and deadline propagation, retry logic with backoff and jitter, idempotency-key wiring, queue and buffer handling, async / blocking-I/O patterns, bulkhead boundaries, correlation-id propagation, kill-switch wiring, observability-of-the-failure-path at the application source line. Hard boundary against han-core:devops-engineer: infrastructure, IaC, pipelines, and observability platform configuration stay there.
• han-core:structural-analyst — module boundaries, coupling, where the implementation fits in the system.
• han-core:behavioral-analyst — runtime behavior, data flow, error propagation, state transitions.
• han-core:concurrency-analyst — concurrent access, race conditions, async coordination, ordering.
• han-core:software-architect — intra-codebase architectural recommendations, module/class/interface sketches, SOLID-grounded refactoring paths. Include when the feature is mostly internal to one codebase or one bounded context.
• han-core:system-architect — cross-service / bounded-context topology, context-map relationships, integration patterns (sync vs. async, saga, ACL, OHS), data ownership across services, failure-domain containment. Include when the feature crosses a service boundary, introduces a new integration, changes a context-map relationship, or shifts data ownership. Include both when the feature does both.
• han-core:risk-analyst — prioritization of architectural and delivery risks.
• han-core:test-engineer — observable-behavior test planning and test doubles.
• han-core:edge-case-explorer — boundary values, input messiness, state-dependent failures.
• han-core:data-engineer — schema changes, migrations, data movement, analytics implications.

If the user specified which agents to include, honor that. Otherwise, state the proposed team composition to the user briefly before launching — one line per specialist with the reason they were selected — and proceed.

Step 4: Round 1 — Parallel Specialist Review

Launch every non-han-core:project-manager specialist in parallel in a single message. Use domain-scoped briefs — do not hand every agent the full set of artifacts. Pass each agent only the spec sections relevant to its domain plus pointers, and instruct it to read further on demand only if its domain needs it. Default mapping:

| Specialist | Spec sections to include in brief | |---|---| | han-core:user-experience-designer | Outcome, Primary Flow, User Interactions, Edge Cases (UX-relevant rows only) | | han-core:adversarial-security-analyst | Outcome, Coordinations, Edge Cases, sections touching auth/PII/secrets/supply-chain | | han-core:devops-engineer | Outcome, Coordinations, Out of Scope, Open Items | | han-core:on-call-engineer | Sections naming outbound calls, retry behavior, queue or buffer handling, async work, error handling on failure paths, schema migrations, idempotency, kill switches, and observability of new code paths | | han-core:structural-analyst | Sections naming module boundaries, coupling, dependency direction | | han-core:behavioral-analyst | Sections describing runtime behavior, data flow, error propagation, state | | han-core:concurrency-analyst | Sections touching concurrent access, race conditions, async coordination | | han-core:software-architect / han-core:system-architect | Architecture / topology / context-map sections | | han-core:risk-analyst | Architectural and delivery risks; depends on upstream specialist findings | | han-core:test-engineer / han-core:edge-case-explorer | Outcome, Primary Flow, Alternate Flows, Edge Cases | | han-core:data-engineer | Sections touching schema, migration, data movement, analytics | | han-core:junior-developer | Outcome + first paragraph of every section (plain-language overview) |

Give each agent:

• The full feature specification path (so it can read further) plus the relevant section excerpts inline in the brief. Also pass the spec's artifacts/decision-log.md, artifacts/team-findings.md, and artifacts/feature-technical-notes.md paths if they exist (fall back to the spec folder root for legacy layouts) — as paths only, not contents, so the agent can read on demand.
• The path to artifacts/.discovery-notes.md from Step 2, with a directive: read the discovery notes first; do not re-grep for what is already there. Search further only for what your domain specifically needs that the discovery notes do not cover.
• A specific question framed for their domain — not "any concerns?" but

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: testdouble
• Source: testdouble/han
• License: MIT

Install and usage instructions live in the source repository linked above.