sw-build

Category: Tools & Productivity | Uploader: Obsidian-Owl | Downloads: 0 | Version: v1.0（Latest）
Changelog: Source: GitHub https://github.com/Obsidian-Owl/specwright
Directory Structure

Current level: adapters/opencode/skills/sw-build/
📄 SKILL.md 8.2 KB
SKILL.md

---
name: sw-build
description: >-
  TDD implementation of one work unit. Delegates test writing to the tester
  agent and implementation to the executor agent. Commits per task.
argument-hint: "[work-id] [task-id]"
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - Task
  - AskUserQuestion
---

# Specwright Build

## Goal

Implement the current work unit using test-driven development. Each task
goes through RED (tester writes failing tests) → GREEN (executor makes
them pass) → REFACTOR. The user sees progress after every task and the
codebase stays green between tasks.

## Inputs

- `.specwright/state/workflow.json` -- current work unit and task progress
- `{currentWork.workDir}/spec.md` -- acceptance criteria to implement
- `{currentWork.workDir}/plan.md` -- architecture decisions
- `.specwright/work/{currentWork.id}/design.md` -- solution design from sw-design (design-level)
- `{currentWork.workDir}/context.md` -- research findings, file paths, gotchas
- `.specwright/CONSTITUTION.md` -- coding standards to follow
- `.specwright/config.json` -- build/test commands, agent config

## Outputs

After each task:
- Tests written and passing
- Implementation committed (one commit per task)
- `workflow.json` updated with task progress

After all tasks:
- `workflow.json` status set to `building` → ready for verify
- All acceptance criteria have corresponding tests and implementation

## Constraints

**Stage boundary (LOW freedom):**
- Follow `protocols/stage-boundary.md`.
- You implement ONE work unit via TDD. You NEVER run quality gates, create PRs, ship code, or start the next work unit.
- After all tasks for this unit are committed, STOP and present the handoff to `/sw-verify`.

**Branch setup (LOW freedom) — FIRST action before any coding:**
- Read `config.json` `git` section. Follow `protocols/git.md` branch lifecycle.
- Determine branch name:
  - If `currentWork.unitId` is set (multi-unit): `{git.branchPrefix}{currentWork.unitId}`
  - If `currentWork.unitId` is null (single-unit): `{git.branchPrefix}{currentWork.id}`
- If `git.branchPerWorkUnit` is true (default):
  - Check if the determined branch already exists (recovery case).
  - If exists: `git checkout {branch}`. Pull latest if remote tracking exists.
  - If not: checkout `git.baseBranch`, pull latest, create branch.
- If `git.branchPerWorkUnit` is false: stay on current branch.
- All task commits happen on the feature branch. NEVER commit to baseBranch.

**Task loop (MEDIUM freedom):**
- Work one task at a time. Complete it before starting the next.
- If no task ID given, pick the next incomplete task from `{currentWork.workDir}/spec.md`.
- If no work unit ID given, use `currentWork` from workflow.json.
- After each task commit, emit a status card (see Context management for format).

**TDD cycle (HIGH freedom for test design, LOW freedom for sequence):**

The sequence is strict: RED → GREEN → REFACTOR. Never skip RED.

1. **RED**: Delegate to `specwright-tester` with the task's acceptance criteria,
   context.md, and constitution. The tester writes tests designed to be hard to
   pass. Run tests to confirm they fail.
2. **GREEN**: Delegate to `specwright-executor` with the failing tests, context.md,
   plan.md, and constitution. The executor writes minimal code to pass. Run
   build + tests to confirm they pass.
3. **REFACTOR**: Executor may refactor code written in THIS task only. Tests must still pass. No adjacent code cleanup.

**Context envelope (LOW freedom):**
When delegating, include in the prompt:
- The specific task and its acceptance criteria
- Relevant sections of design.md, plan.md, and context.md
- File paths the agent needs to read or modify
- The constitution's relevant practices
- Build and test commands from config.json
- Behavioral reminder: surface confusion, prefer simplicity, touch only task files
- Build agents MAY read parent `.specwright/work/{currentWork.id}/context.md` as a fallback if unit context is insufficient

**Build failures (MEDIUM freedom):**
- If tests fail after GREEN: delegate to `specwright-build-fixer` (max 2 attempts)
- If build-fixer fails twice: STOP and show the user the error. Don't loop.
- If RED phase tests don't fail: the tests are wrong. Tell the tester to fix them.

**Commits (LOW freedom):**
- One commit per completed task. Follow `protocols/git.md`.
- Commit message references the work unit ID and task.
- Stage only files changed for this task. Never `git add -A`.
- Before committing: if `config.commands.format` is configured, run it. If
  `config.commands.lint` is configured, run it. If formatting changes files,
  restage them. If lint fails, fix inline (orchestrator self-heals trivial
  issues; re-delegate to executor for non-trivial). This is task hygiene,
  not a build-fixer scenario.

**Post-build review (MEDIUM freedom):**
- After all tasks committed, if unit qualifies (4+ tasks OR 5+ files OR security-tagged criteria): delegate review to `specwright-reviewer`. Triage findings: BLOCK → user, WARN → awareness, INFO → skip.
- Units that don't qualify skip directly to handoff.
- Follow `protocols/build-quality.md` for delegation details and findings triage.

**Parallel execution — experimental (MEDIUM freedom):**
- Follow `protocols/parallel-build.md` when all prerequisites are met:
  `config.experimental.agentTeams.enabled`, `SPECWRIGHT_AGENT_TEAMS` env var, 4+ tasks.
- If any prerequisite fails: execute tasks sequentially (normal behavior). No error.
- Do NOT start implementing tasks yourself while teammates are working.

**As-built notes (LOW freedom):**
- After all tasks committed (and after optional post-build review), append `## As-Built Notes` to `{currentWork.workDir}/plan.md`: plan deviations, implementation decisions, actual file paths.
- spec.md stays untouched. gate-spec does NOT consume as-built notes. Primary consumer: sw-learn.
- Follow `protocols/build-quality.md` for content scope.

**State updates (LOW freedom):**
- Follow `protocols/state.md` for all workflow.json mutations.
- Acquire lock before starting. Release after each task commit.
- Update `tasksCompleted` array after each successful task.

**Context management (MEDIUM freedom):**
- After each task commit, write `.specwright/state/continuation.md`: current unit, task just completed, key files modified, remaining tasks. Overwrites each time.
- After each task commit, emit a status card:
  ```
  ───────────────────────────────────────
  ✓ {task-id} committed — {task name}
    Progress: {n} of {total} tasks complete
    Next:     {next-task-id} — {next task name}
    Ahead:    {remaining task ids and names}
  ───────────────────────────────────────
  ```
- Context nudge: after the 3rd completed task, if 4+ tasks remain, append
  to the status card: "Context growing — consider /clear. I'll recover from workflow.json."
- If user responds "stop" or "pause" to a status card: halt cleanly.
  Advise: `/sw-pivot` if the plan changed, `/sw-build` to resume.

## Protocol References

- `protocols/stage-boundary.md` -- scope, termination, and handoff
- `protocols/state.md` -- workflow state and locking
- `protocols/git.md` -- commit discipline
- `protocols/delegation.md` -- agent delegation with fallback
- `protocols/recovery.md` -- compaction recovery
- `protocols/build-quality.md` -- post-build review and as-built notes
- `protocols/parallel-build.md` -- parallel task execution with agent teams

## Failure Modes

| Condition | Action |
|-----------|--------|
| No active work unit | STOP: "Run /sw-design and /sw-plan first" |
| Build/test command not configured | STOP: "Configure commands in config.json or run /sw-init" |
| Tester writes tests that pass immediately | Tests are wrong. Re-delegate with instruction to write tests that FAIL first. |
| Executor can't pass tests after 2 build-fixer attempts | STOP. Show error to user. Don't loop forever. |
| Compaction during build | Read workflow.json, find last completed task, resume next task. |
| Compaction during parallel execution | Read workflow.json, check `.specwright/worktrees/` for orphans, clean up, resume sequential. |
| Lock held by another skill | STOP with lock info. Don't force-clear. |
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
sw-build

Directory Structure

SKILL.md

Report

Notice
