akiojin/gwt-build-spec

gwt-build-spec

Implement code using strict TDD (Red-Green-Refactor) methodology. Operates in two modes:

• SPEC mode: driven by an existing SPEC directory with tasks.md, full progress tracking
• Standalone mode: user provides the task directly, TDD loop enforced, no SPEC artifacts needed

Execution ownership

Once started, keep moving until one of these is true:

• the scoped tasks are complete
• a real product or scope decision blocks the next task
• a merge conflict or reviewer request cannot be resolved with high confidence
• required auth or tooling is unavailable
• a spec-implementation mismatch is discovered that changes the design surface (not just a typo fix) — use gwt-discussion to investigate and discuss

Routine CI failures, update-branch merges, and test-first edits are handled autonomously.

Use the current user's language for task summaries, completion reports, task check updates, and any user-facing text generated while executing the workflow, unless an existing artifact must keep its established language.

Mode detection

Determine the mode at entry:

• SPEC mode if a SPEC ID is provided or discoverable from the current branch/context, AND gwt issue spec <N> --section tasks で tasks セクションが取得できる
• Standalone mode otherwise

Phase 1: Context Load

SPEC mode

1. gwt issue spec <N> で SPEC の全セクション（spec, plan, tasks）を読み込む。
2. Identify the next incomplete task slice in dependency order:
   • Setup before Foundational work
   • Foundational before story-specific work
3. SPEC セクションの読み書きは gwt issue spec <N> --section <name> / gwt issue spec <N> --edit <name> -f <file> を使用する。

Standalone mode

1. Accept the user's task description, requirements, and acceptance criteria.
2. Identify target files and test locations from the task description and codebase exploration.
3. No SPEC artifacts are required or created.

Phase 2: TDD Loop (Red-Green-Refactor)

This phase is non-optional in both modes. See references/tdd-workflow.md for detailed methodology.

Step 1: Red — Write a failing test

• Add or update the narrowest failing test that proves the task.
• Reuse existing test suites when they already cover the target behavior.
• Rust: place tests in crates/*/tests/ or #[cfg(test)] modules.
• Run the test and confirm it fails for the expected reason.
• If the test passes immediately, the behavior already exists — skip to the next task.

Step 2: Green — Implement the minimum

• Write the minimum code to make the failing test pass.
• Edit only the files implied by the task (or tasks.md in SPEC mode).
• Do not silently widen scope beyond the current task.
• In SPEC mode, keep changes aligned with spec.md and plan.md.
• Run the test and confirm it passes.

Step 3: Refactor

• Clean up the implementation while keeping all tests green.
• Apply project conventions: cargo fmt, naming, module structure.
• Run the full relevant test suite to catch regressions.

When to skip tests

Tests may be skipped only when the task does not change observable behavior:

• Documentation-only changes (docs:)
• Configuration/CI changes (chore:)
• Formatting-only changes
• CLAUDE.md / README updates

All other changes require the TDD loop.

Repeat

• In SPEC mode: continue task-by-task in dependency order until the scoped tasks are done.
• In standalone mode: continue until the user's stated task is complete.

Phase 3: Verification

Run the smallest meaningful validation set first, then broaden:

1. Tests: cargo test -p gwt-core -p gwt (or narrower scope first)
2. Lint: cargo clippy --all-targets --all-features -- -D warnings
3. Format: cargo fmt -- --check
4. Build: cargo build -p gwt

In SPEC mode, also verify:

• Implementation matches spec.md acceptance scenarios
• No scope creep beyond tasks.md
• If a failure indicates a spec gap (not a code bug), route back to gwt-discussion

Phase 4: PR Flow

Handle PR operations autonomously using the gwt-manage-pr skill:

• If there is no active PR for the branch, or prior PRs are already merged, use gwt-manage-pr to create one.
• If the current PR has CI failures, conflicts, or review blockers, use gwt-manage-pr to fix.
• Let gwt-manage-pr handle routine merge/push/fix loops.

Do not create a PR until Phase 3 verification passes.

Phase 5: Completion Gate

SPEC mode

Reconcile implemented behavior against all SPEC artifacts. See references/completion-gate.md for details.

Required checks:

• Every completed task in tasks.md matches the implementation
• tasks セクションの受け入れチェックボックスが実際の受け入れ済み動作を反映している
• tasks セクションの TDD チェックボックスが実際の検証エビデンスを反映している
• tasks セクションの完了マーカーがコードで裏付けられていない完了を主張していない
• If artifacts disagree, return to gwt-discussion — do not proceed to PR

Update execution tracking:

• Mark completed tasks in tasks.md
• tasks セクションのチェックボックスを gwt issue spec <N> --edit tasks -f <file> で更新する

Standalone mode

• Confirm all user-stated acceptance criteria are met
• Confirm all tests pass
• Confirm lint and type checks pass
• Summarize what was built and what was verified

Chain suggestion

On completion, suggest gwt-arch-review for code review if available, or proceed to gwt-manage-pr if not already done.

Stop conditions

Stop only when:

• the next task depends on a product or scope decision that is not inferable
• a merge conflict or review request is ambiguous enough to risk wrong behavior
• required repo/auth/tooling access is unavailable
• implementation reveals a gap between spec.md and the actual behavior (acceptance scenario inaccuracy, missing data-model section, undocumented registration table, dependency chain not captured in tasks.md, etc.) that changes the design surface — not just a typo fix. Route to gwt-discussion if the gap requires user discussion, or update the SPEC artifact directly if the fix is mechanical

Exit report

## <Build Report in the current user's language>

Mode: SPEC-<id> | Standalone
Completed tasks: <N> | <summary>
Updated files: <paths>
Verification:
- <command/result>

Next:
- `gwt-manage-pr` (create/update PR)
- `gwt-arch-review` (code review)
- return to `gwt-discussion` (artifact repair)
- ask user for decision