shipwright-build

Shipwright Build Skill

TDD implementation with code review, Conventional Commits, and feature branch workflow. Enhanced fork of deep-implement with decision logging, session handoff, and migration safety.

Autonomous orchestrated mode: When invoked by /shipwright-run in autonomous mode, sections are delegated to the section-builder subagent (see agents/section-builder.md). Each subagent gets a fresh context window and runs the full TDD cycle independently. This skill is still used directly in guided mode and for standalone invocations.

Phase Index — Where the prose lives

Section	Reference
First Actions C/D/D2/E/F/G detail	first-actions
Step 3 TDD (Integration / pgTAP / E2E)	tdd-tests
Step 4 Implementation loop, Migration apply, Vite DX	implementation-loop · migrations-apply · migration-safety
Step 4.5 Browser Verify	browser-verify · debugging-protocol
Step 6 Code Review (Self / Full / External)	code-review · self-review-checklist · code-review-protocol · code-review-interview
Step 7 Apply review fixes	apply-interview-fixes
Step 8 Commit (Conventional Commits)	git-operations · pre-commit-handling
Step 9 Decision log	section-doc-update
Step 10 Section state, record_event, split-done canon	section-state
Step 10a Reflection	reflection
Autonomous Section Loop	autonomous-loop
Error handling (tests / hooks / context)	error-handling
Performance / Simplification / Finalization	performance-checklist · simplification-patterns · finalization

---

CRITICAL: First Actions

Governing rules: Read and follow shared/constitution.md (ALWAYS / ASK FIRST / NEVER boundaries).

BEFORE using any other tools, do these in order:

A. Print Intro Banner

================================================================================
SHIPWRIGHT-BUILD: TDD Implementation
================================================================================
Implements code from /shipwright-plan section files.

Usage: /shipwright-build @path/to/sections/01-auth.md
   or: Invoked by /shipwright-run (orchestrator)

Workflow per section:
  1. Read section spec
  2. Write tests first (TDD)
  3. Implement until tests pass
  4. Code review (subagent)
  5. Fix review findings
  6. Commit (Conventional Commits)
  7. Update decision log + docs

Features:
  - Auto feature branch (build/{slug}-{session-id}, derived from run config)
  - Conventional Commits (feat:, fix:, refactor:, etc.)
  - Migration safety (down.sql + destructive change detection)
  - Session handoff before context limits
================================================================================

B. Validate Input

Check if user provided @file argument pointing to a section markdown file. If NO argument or invalid, print the "Section File Required" notice and stop and wait for user to re-invoke with correct path.

================================================================================
SHIPWRIGHT-BUILD: Section File Required
================================================================================

This skill requires a path to a section markdown file.

Example: /shipwright-build @sections/01-auth.md

Section files are generated by /shipwright-plan.
================================================================================

C. Detect Invocation Mode

Resolve it with {shared_root}/scripts/tools/get_phase_context.py --phase-task-id "{phaseTaskId}" --phase build (omit --phase-task-id entirely if the orchestrator did not hand you one — that is what selects standalone) and store the returned mode as invocation_mode (pipeline | standalone | error → STOP). The dispatch token the orchestrator hands you is the authority — never re-derive the mode from run-config state. See first-actions for the full decision tree (incl. the out-of-sequence warning + the Single-Session Gate Discipline).

D. Discover Plugin Root, Run Setup Script

SHIPWRIGHT_PLUGIN_ROOT comes from the SessionStart hook. Then run setup_implementation_session.py and parse its JSON (success, mode == "resume", etc.). Full procedure: first-actions.

D2. Initialize & Validate Environment

Run validate_env.py --init then validate_env.py (no --init). Handle created / updated / unchanged / success == false / optional_missing per first-actions.

E. Create Feature Branch

Always feature-branch before changes. Resume path: git checkout {branch_name}. Create path: anchor on the default branch first. Full snippet + naming fallbacks in first-actions.

F. Load Config

Read shipwright_build_config.json from project root; defaults in first-actions (auto_push false, conventional_commits true, decision_log true, session_handoff true, migration_safety true).

G. Print Session Report

Print the SESSION REPORT block (Mode / Section / Branch / Auto-push / Migration safe / Resume from). Template in first-actions.

---

Step 0: Phase Session Context Recovery

If the orchestrator handed you a phaseTaskId — i.e. /shipwright-run dispatched you as a phase-runner subagent — you are part of an active pipeline. Run this as your very first action:

uv run "${SHIPWRIGHT_PLUGIN_ROOT}/../../shared/scripts/tools/get_phase_context.py" \
  --phase-task-id <phaseTaskId-from-context>

The tool prints structured JSON with runId, phase, splitId, prerequisites, runConditions, and a skill_artifacts_to_read list. Read those artifacts before proceeding so this phase session has full context for what came before.

If NO phaseTaskId was handed to you, this is a standalone invocation — continue with Step 1.

---

Step 1: Read Section Spec

Goal: Understand what to implement.

Read the section file. Identify prerequisites, test strategy, implementation steps, files to create/modify.

Design Reference (mandatory for UI sections): If the section contains a ## Design Reference block, you MUST read the referenced mockup HTML file before writing any implementation code. The mockup is the visual truth — match layout, component hierarchy, colors/spacing/typography from .shipwright/designs/visual-guidelines.md, and responsive behavior. If no ## Design Reference exists but .shipwright/designs/screens/ contains relevant mockups, read them anyway. When in doubt, the mockup wins over your assumptions.

If prerequisites reference other sections, verify those are complete (commits on the branch or main).

uv run "{shared_root}/scripts/tools/update_build_dashboard.py" \
  --project-root "$(pwd)" --section "{section_name}" --step 1 --detail "Reading section spec" --session-id "{SHIPWRIGHT_SESSION_ID}"

---

Step 2: Install Dependencies

If section spec lists npm/pip packages: npm install {packages} or uv add {packages}. Do NOT commit package changes yet — they'll be part of the section commit.

---

Step 3: Write Tests First (TDD)

See implementation-loop for the TDD cycle and tdd-tests for Integration / pgTAP / E2E test selection (incl. the decision table).

Red phase: write failing tests, run npm test or uv run pytest, verify they fail.

---

Step 4: Implement

See implementation-loop for guidance.

Goal: Write code to make tests pass (green phase).

1. Follow implementation steps from section spec
2. After each significant change, run tests
3. Continue until all tests pass

Migration Safety (if enabled): when creating up.sql, also generate down.sql. See migration-safety. The PostToolUse hook will warn on destructive operations automatically.

Vite DX scaffold (Vite profiles only): see migrations-apply "Vite DX Scaffold" section.

Apply migrations immediately if migration files were created — preflight / apply / verify / post-apply manual steps per migrations-apply.

Checkpoint: All tests pass. Run integration / pgTAP tests if files exist. Capture tests_passed / tests_total for Step 10. Dashboard update + context pressure check per migrations-apply.

---

Step 4.5: Browser Verify (MANDATORY when frontend files changed)

See browser-verify.

Detect frontend changes with detect_frontend_changes.py. If has_frontend_changes == false, skip. Otherwise: prerequisite self-healing, Playwright setup, dev server, run browser_verify.py, auto-fix loop (max 3 retries) per debugging-protocol. Missing dev_server config is a RESOLUTION problem, not a skip trigger.

---

Step 5: Refactor (Optional)

Remove duplication, improve naming, extract utilities if warranted. Run tests after each refactor.

---

Step 6: Reviewer Cascade — Spec → Code → Doubt (+ Optional External)

See code-review for the full cascade: the spec-reviewer HARD-GATE re-review loop and the doubt-reviewer trigger heuristic.

• 6a Self-Review (always): 5-point checklist per self-review-checklist. Fix all failures.
• Stage 1 — spec-reviewer (HARD-GATE): spec-compliance gate; runs whenever 6b runs (same trigger, so Stage 1 always precedes Stage 2). On REJECT, fix and re-review; 6b does NOT run until PASS.
• 6b Full Review — code-reviewer (Stage 2, conditional): triggered when diff > 100 lines, section risk: high, or security-sensitive files. Full flow per code-review-protocol; user interaction per code-review-interview.
• 6c External Cascade (opt-in): external_code_review.enabled: true in shipwright_build_config.json. Generic code-quality second opinion only — the internal spec-reviewer/doubt-reviewer do NOT cascade externally. See code-review.
• Stage 3 — doubt-reviewer (conditional, advisory): after 6b passes, a fresh-context disprove pass for non-trivial touches (migrations, async/concurrency, cross-plugin imports, irreversible ops). Implementer must address each doubt.

---

Step 7: Apply Review Fixes

See apply-interview-fixes. Autonomous mode: all findings arrive as "accepted" — apply all fixes, re-run tests, mark resolved. Track findings for Step 10 with statuses fixed / declined / deferred.

---

Step 8: Commit (Conventional Commits)

See git-operations.

Format: <type>(<scope>): <description>\n\n<body>\n\nCo-Authored-By: Claude <[email protected]>. Types: feat / fix / refactor / test / docs / chore. Scope = section name.

git add -A
git commit -m "<message>"

Auto-push (if enabled): git push -u origin {branch_name}.

Dashboard update + context pressure check (same pattern as Step 4 — see migrations-apply). Pre-commit hook failures: see error-handling + pre-commit-handling.

---

Step 9: Update Decision Log

See section-doc-update. If .shipwright/agent_docs/decision_log.md exists, log each significant decision via write_decision_log.py:

uv run "{plugin_root}/../../shared/scripts/tools/write_decision_log.py" \
  --section "Build — {section_name}" \
  --commit "$(git rev-parse HEAD)" \
  --title "{short title}" \
  --context "{why needed}" --decision "{what decided}" \
  --consequences "{impact}" --rationale "{reasoning}" \
  --rejected "{alternatives}" --project-root "$(pwd)"

Log architecture choices, accepted/declined review findings, deviations from the section spec.

---

Step 10: Update Section State

See section-state for the full procedure: update_section_state.py, record_event.py (per section — do NOT batch), dashboard update, phase-complete trigger, and the canon-hybrid split-done finalization (C3 handoff + C5 changelog entries + phase_history once per split — both all_done == true and all_done == false branches).

---

Step 10a: Reflection — Capture Learnings

Apply the reflection protocol (reflection): decisions -> ADR; observations -> conventions.md; cross-project insights -> Memory.

---

Step 11: Session Handoff Check

If conversation is long:

uv run "{shared_root}/scripts/tools/generate_session_handoff.py" \
  --project-root "$(pwd)" \
  --reason "mid-build handoff: section {section_name} {complete|in_progress}"

Do NOT pass --canon-marker here; mid-build handoffs are not canon closures (canon marker reserved for the split-level C3 closure in section-state).

---

Autonomous Section Loop

When invoked with --autonomous, build all pending sections sequentially. Full procedure: autonomous-loop. When NOT autonomous: skip this section, proceed to Step 12.

---

Step 12: Completion

Verify: all tests pass, code review complete, commit on feature branch, decision log updated. Print the SHIPWRIGHT-BUILD COMPLETE summary block (Section / Branch / Commit / Tests / Review counts / Next steps).

---

Error Handling

See error-handling for test failures, pre-commit hook failures, and context-window-pressure checkpoint procedure (Steps 4 and 8 fire estimate_context_pressure.py).