/plan-implementation

name: "plan-implementation"
description: >
  Builds a feature implementation plan from an existing feature specification (or equivalent context) through a
  facilitated team conversation. Use when the user wants to plan how to implement, build, deliver, or ship a
  feature that has already been specified. Does not specify what the feature should do — use plan-a-feature first. Does
  not design the contract for an interface — use design-an-api. Does not refine or stress-test an already-written plan —
  use iterative-plan-review. Runs its resolution rounds to completion and holds its questions until after they finish;
  to review each round as it lands, use pairing.
arguments: size
argument-hint: "[size: small | medium | large | dynamic] [feature specification path, optional: additional context]"
allowed-tools:
  Read, Write, Edit, Glob, Grep, Agent, Bash(find *), Bash(git *), Bash(mkdir *), Bash(cp *),
  Bash(bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh")

Project Context

• CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f`
• project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f`
• personal config directory: !`bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude"`
• project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""`

As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read that returns no file is no personal configuration: continue silently. When that file or the `project .han/config.md` probe supplies content, apply it per [config-rule.md](../../references/config-rule.md), which governs precedence between the two files, relative-path resolution, and what to do with a file that reads but cannot be used.

Operating Principles

• **The feature specification is the ground truth for _what_, but not for scope.** This skill plans _how_. Do not re-open

behavioral decisions the specification already settled; flag contradictions as Open Questions for the user. Scope is the exception, and it is narrow: a specification is an artifact, not a scope authority, so a commitment it carries for a subsystem, integration, or artifact the work item never asks for is cut with the citation rather than planned. The license reaches unrequested subsystems and nothing else. See [../../references/scope-justification-rule.md](../../references/scope-justification-rule.md).

• **The run stays inside the boundary it descends from.** Before locating the specification, the skill records the work

item's stated scope and exclusions, per [../../references/planning-boundary-rule.md](../../references/planning-boundary-rule.md). The scope gate at Step 7.5 then reads that record, including commitments the plan inherited from the specification.

• **Visual material the user supplies is kept, and reaches every reviewer.** Persist it beside the plan as it arrives,

never at document-write time, and pass its paths in every dispatched specialist's brief. The boundary rule owns the convention.

• **Questions to the user arrive one at a time, led by the consequence.** An escalation carries one question, opens with

what a person who will not read the code would describe, gives named candidate answers, and puts paths and identifiers below the question or leaves them out. Per [../../references/operator-escalation-rule.md](../../references/operator-escalation-rule.md). The opening confirmation turn is the one exception, and the one turn that carries more than one ask.

• **The han-core:plan-synthesizer reconciles the specialists, it does not author every section.** It reads what every

specialist produced, tracks claims and evidence, and commits the decisions the plan records. Specialists own their domains. This skill runs the rounds itself; the synthesizer is dispatched once, at the end.

• **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:plan-synthesizer says so.** The loop exits when the han-core:plan-synthesizer 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 — intention over prescription.** The plan is the reader's layer: it carries the

intention and goals of the work, the touch points (a module, a contract, a boundary), and the decision-bearing values (a flag default, a key name, a