gwt-plan-spec

name	gwt-plan-spec
description	Use when a SPEC exists and the next task is to generate or refresh implementation planning artifacts such as plan.md and tasks.md.

gwt-plan-spec

Unified planning skill that translates a clarified spec.md into implementation-ready artifacts through four sequential phases: technical context, architecture design, task decomposition, and quality gate.

Covers planning, task decomposition, and pre-implementation quality-gate work behind the visible gwt-plan-spec entrypoint.

gwtd resolution

Before executing any gwtd ... command from this skill or its references, resolve GWT_BIN first: executable GWT_BIN_PATH, then command -v gwtd, then $GWT_PROJECT_ROOT/target/debug/gwtd or ./target/debug/gwtd. Run the command as "$GWT_BIN" ...; if none exists, stop with an actionable gwtd not found error.

Invocation

• With SPEC: gwt-plan-spec SPEC-<id> — full pipeline from spec.md to quality gate
• Lightweight: gwt-plan-spec without a SPEC — produce a plan.md and tasks.md in the current working context (no spec.md required, skip traceability checks)
• Standalone: works independently of the visible SPEC flow owner

Exit CLI (Stop-block contract)

SPEC-1935 FR-014q routes Stop through skill-plan-spec-stop-check, which reads .gwt/skill-state/plan-spec.json and blocks Stop while the skill is active. Register the skill lifecycle explicitly with the exit CLI:

• JSON operation plan.start with params.spec:<n> at the beginning of the skill invocation (params.spec:0 for lightweight mode)
• JSON operation plan.phase with params.spec:<n> (or params.spec:0 for lightweight mode) and params.label:"plan-draft"|"tasks-draft"|"quality-gate" at each internal milestone (logging only; does not affect blocking)
• JSON operation plan.complete with params.spec:<n> (or params.spec:0 for lightweight mode) once the quality gate verdict is CLEAR and planning artifacts are written
• JSON operation plan.abort with params.spec:<n> (or params.spec:0 for lightweight mode) and params.reason when planning cannot proceed (e.g. spec gap discovered mid-planning)

The Stop-block handler honours Claude Code / Codex's built-in stop_hook_active flag, so forced continuation is capped at one per Stop cycle and the skill will never infinitely loop even if the exit CLI is skipped.

Prerequisites

• If spec.md has critical [NEEDS CLARIFICATION] markers, use gwt-discussion first.
• If the target SPEC does not exist, use gwt-discussion to create it first.
• If planning artifacts already exist but are stale, update them — do not recreate blindly.

Required inputs

• spec.md from the target SPEC directory (or a user-provided description in lightweight mode)
• .gwt/memory/constitution.md

Required outputs

All artifacts are written to the SPEC's GitHub Issue sections:

• plan.md — architecture, phases, constitution check
• research.md — unknowns, tradeoff decisions, external findings
• data-model.md — entities, shapes, lifecycle, invariants
• quickstart.md — minimum validation flow for reviewers and implementers
• contracts/* — interface or schema contracts (only when needed)
• tasks.md — executable work items with test-first ordering

Use the current user's language for generated artifact text, quality-gate reports, and any user-facing planning summaries unless the artifact already has an established language that must be preserved.

Phase 1: Technical Context

Establish the implementation landscape before designing.

1. Load source artifacts. Read spec.md and .gwt/memory/constitution.md. Refuse to continue only when spec.md is missing or a user decision still blocks planning.

2. Run Board active-claim preflight. Once the target SPEC number is known, read the current Board with JSON operation board.show.

   • Look for active claim entries from another session that mention the same owner (#<N> or SPEC-<N>) or the planning phase being refreshed.
   • If a matching claim exists, pause before changing artifacts and present the conflict: join that session with a Board handoff request, discuss a disjoint planning split, or continue only after the user explicitly accepts duplicate risk.
   • Intentional parallel planning is allowed only when artifact ownership is disjoint. Post a fresh Board claim with a Boundary: line naming the sections/files owned by this session before editing.
   • Acceptance scenario: Given another session has an active Board claim for SPEC-1935 plan refresh, when gwt-plan-spec starts for SPEC-1935, then the preflight reports the claim and requires user confirmation before plan, tasks, or related artifacts are edited.

3. Identify affected scope. List files, modules, services, and external constraints that the work touches. Record assumptions explicitly.

4. Run the constitution check. Evaluate the work against every rule in .gwt/memory/constitution.md. If a rule is violated, either redesign or record the justification in Complexity Tracking.

5. Answer the Required Plan Gates from the constitution:

   • What files/modules are affected?
   • What constitution constraints apply?
   • Which risks or complexity additions are accepted, and why?
   • How will the acceptance scenarios be verified?

Phase 2: Architecture Design (SDD)

Design the solution using Software Design Document methodology before decomposing tasks.

See references/sdd-design.md for full methodology.

1. Component design. Identify new and modified components, their responsibilities, and ownership boundaries. Keep the design minimal — no unnecessary abstractions.

2. Interface contracts. Define public APIs, message formats, and protocol boundaries between components. Write stable contracts to contracts/* when interfaces cross module or crate boundaries.

3. Data model. Document entities, their shapes, lifecycle states, and invariants. Write to data-model.md.

4. Sequence descriptions. Describe key interaction flows in plain text — which component calls what, in what order, with what data. No diagram syntax required; clarity and completeness matter.

5. Produce supporting artifacts.

   • research.md: unknowns, tradeoff decisions, external findings
   • quickstart.md: minimum validation flow for reviewers and implementers

6. Write plan.md. Structure:

   • Summary
   • Technical Context (from Phase 1)
   • Constitution Check
   • Architecture Design (component, interface, data model, sequences)
   • Project Structure
   • Complexity Tracking
   • Phased Implementation

Phase 3: Task Decomposition

Turn the architecture and plan into executable work items.

See references/task-decomposition.md for full rules.

1. Lay out phase order. Canonical ordering:

   • Setup — tooling, configuration, scaffolding
   • Foundational — shared infrastructure, core types
   • User Story phases (US1, US2, ...) — story-specific implementation
   • Polish / Cross-Cutting — cleanup, documentation, integration tests

2. Generate test-first tasks. For each user story:

   • Add test/verification tasks before or alongside implementation tasks
   • Include contract, integration, and e2e coverage when the spec implies it

3. Add implementation tasks. Each task must include:

   • Task ID in T-NNN format
   • [P] marker when parallelizable (only when write scopes do not overlap)
   • Linked user story ID where applicable
   • Exact file path or module
   • Concrete action — no vague descriptions

4. Validate traceability.

   • Every user story has implementation and verification tasks
   • Every acceptance scenario has verification coverage
   • Every declared contract/data-model change has matching tasks

5. Write tasks.md.

Phase 4: Quality Gate

Final readiness check before implementation. This is a pre-implementation gate only — it does not certify that implementation is complete.

See references/quality-gate.md for full check definitions.

Mandatory checks

1. Clarification completeness — no critical [NEEDS CLARIFICATION] markers remain
2. Spec completeness — User Stories, Acceptance Scenarios, Edge Cases, Requirements, and Success Criteria exist
3. Plan completeness — Constitution Check exists, Technical Context and Phased Implementation are concrete
4. Task traceability — every user story has tasks, every acceptance scenario has verification coverage, every contract/data-model change has matching tasks
5. Constitution alignment — violations are either removed or explicitly tracked in Complexity Tracking

Verdict

## <Analysis Report in the current user's language>: SPEC-<id>

Status: CLEAR | AUTO-FIXABLE | NEEDS-DECISION

Blocking items:
- A1. <artifact gap>
- A2. <traceability gap>

Next:
- gwt-build-spec (on CLEAR)
- self-repair and rerun (on AUTO-FIXABLE)
- ask user for decision (on NEEDS-DECISION)

Decision rule:

• CLEAR — implementation may proceed through gwt-build-spec
• AUTO-FIXABLE — repair the artifact set in-place and rerun the quality gate
• NEEDS-DECISION — report points to the exact user decision or unresolved ambiguity

Boundary: CLEAR means artifacts are ready for execution. It does not mean the SPEC is complete — completion requires post-implementation reconciliation in gwt-build-spec.

Chain suggestion

On CLEAR verdict, suggest proceeding to gwt-build-spec for implementation.

Lightweight mode

When invoked without a SPEC:

• Skip traceability checks (Phase 4 check 4)
• Skip constitution check if .gwt/memory/constitution.md is not found
• Produce plan.md and tasks.md in the current directory
• Omit supporting artifacts unless the user requests them

Operations

Use gwtd JSON operations for artifact persistence:

# Read spec section
"$GWT_BIN" <<'JSON'
{"schema_version":1,"operation":"issue.spec.section","params":{"number":123,"section":"spec"}}
JSON

# Write plan section
"$GWT_BIN" <<'JSON'
{"schema_version":1,"operation":"issue.spec.edit","params":{"number":123,"section":"plan","body":"<plan markdown>"}}
JSON

# Write tasks section
"$GWT_BIN" <<'JSON'
{"schema_version":1,"operation":"issue.spec.edit","params":{"number":123,"section":"tasks","body":"<tasks markdown>"}}
JSON

# List all SPEC Issues
"$GWT_BIN" <<'JSON'
{"schema_version":1,"operation":"issue.spec.list","params":{}}
JSON