attckdigital/smith/smith-build

SpecKit Autonomous Build

Executes the full build pipeline from answered questions through to merged PR and release notes. This command runs entirely without user interaction, using subagents to manage context.

Arguments: $ARGUMENTS

Vault Logging

Throughout this action, log significant events to the vault session log. Read the session log path from .smith/vault/.current-session. If the file is missing or the vault is not initialized, skip all logging silently.

Marker before first append: the workflow-gate denies markerless Bash redirection, so cat >> "$SESSION" appends are blocked until the active-workflow marker exists. Create the marker (Phase 0 step 0 helper) FIRST, then write the invocation entry immediately after — do not log before the marker.

Timestamps are UTC. HH:MM:SS comes from date -u +%H:%M:%S — never a local clock, never a time from memory. The append already runs through a shell, so read the clock in that same command (TS=$(date -u +%H:%M:%S)) and spend no extra tool call. Substitute the resulting value: an unexpanded $(...) reaching the log is a known regression and will not parse. Every hook-written stamp in this log is date -u, so a local-clock entry lands hours away from its neighbours and skews the workflow window hooks/workflow_summary_lib.py derives from them.

Append entries using this format:

### [HH:MM:SS] /smith-build <event>
 
**User Request:**
> <verbatim user message that triggered this action — if invoked via /smith-new, reference the original request logged there. If invoked manually for recovery, capture the recovery command.>
 
**Synthesized Input:** <brief summary of what's being built>
**Outcome:** <what happened>
**Artifacts:** <files created/modified>
**Systems affected:** <system IDs>

Log at these points:

1. On invocation — which feature is being built, fresh run or recovery, reference to original user request
2. After each phase completes — phase name, tasks completed count, key artifacts produced
3. After system spec updates — which system specs were updated and what changed
4. After PR created — PR number, title
5. After merge — success/failure, branch cleanup status
6. On completion — brief release notes summary, total files created/modified, services rebuilt

Subagent Invocation Logging

Immediately before every Agent tool call in this workflow (including each phase subagent, testing subagent, and spec-update subagent), append a block to the session log. The Agent tool's return value does not expose subagent_type or model to the parent, so this is the only place that information can be captured.

### [HH:MM:SS] Subagent invoked: <description>
 
**Type:** <subagent_type or "general">
**Model:** <model override passed to Agent, or "inherited" if none>

HH:MM:SS here is UTC as well — date -u +%H:%M:%S, same rule as above. The subagent-vault-writeback.sh block that lands beside this one is hook-written and therefore already UTC; a local-clock invocation stamp would make a subagent appear to finish hours before it started.

After the Agent tool returns, the subagent-vault-writeback.sh hook automatically appends a matching "Subagent completed" block with metrics read from the sidechain transcript — do not duplicate that logging in the skill.

This command can be invoked in two ways:

1. Automatically by `/smith-new` after questions are answered (normal flow)
2. Manually by the user via /smith-build for recovery if a previous build failed partway

Phase 0: Context Discovery

1. Activate workflow tracking — invoke the shipped helper to create the per-branch marker. The workflow-gate hook (PR #20) exempts this exact helper by basename so the bootstrap runs even when no marker exists yet (per spec/31-workflow-gate-bootstrap). The helper also stamps the current session log with a workflow-start line so workflow-summary.sh --totals-only can attribute tokens correctly:

``bash BRANCH=$(git rev-parse --abbrev-ref HEAD) # Derive a slug from the branch (drop number prefix if numbered): SLUG=$(echo "$BRANCH" | sed 's/^[0-9]*-//') ~/.smith/scripts/create-active-workflow.sh \ --branch "$BRANCH" \ --workflow smith-build \ --slug "$SLUG" \ --worktree "$(pwd)" ` (Falls back to scripts/create-active-workflow.sh in repo-dev layouts.) Clear this marker at the end of Phase 7 (after release notes) or on unrecoverable failure. Use the shipped helper so this works even on projects that deny Bash(rm:*): `bash .specify/scripts/bash/clear-active-workflow.sh "$BRANCH" ``

1. Detect worktree context:

``bash COMMON_DIR=$(git rev-parse --git-common-dir) GIT_DIR=$(git rev-parse --git-dir) ``

• If COMMON_DIR ≠ GIT_DIR: we are in a worktree. Set WORKTREE_MODE=true and WORKTREE_PATH=$(pwd).
• Detect the primary repo path: PRIMARY_REPO=$(git rev-parse --git-common-dir | sed 's|/\.git$||')
• Log worktree status to vault session log.

1. Run prerequisites check:

``bash .specify/scripts/bash/check-prerequisites.sh --json --paths-only ` Parse JSON for FEATURE_DIR and AVAILABLE_DOCS`.

If the script fails (e.g., not on a feature branch), check:

• Is there a feature branch that matches $ARGUMENTS?
• Are there incomplete tasks in any specs/*/tasks.md?
• If recovery is possible, switch to the correct branch and retry.
• If not, ERROR with guidance.

1. Load feature context from FEATURE_DIR:

• spec.md (REQUIRED)
• plan.md (REQUIRED)
• questions.md (REQUIRED — verify Status is "ANSWERED")
• tasks.md (OPTIONAL — may not exist yet if this is first run)
• data-model.md (IF EXISTS)
• contracts/ (IF EXISTS)
• research.md (IF EXISTS)
• quickstart.md (IF EXISTS)

Ledger Context (Optional)

If .smith/vault/ledger/ exists and contains non-empty files, load relevant Ledger sections to inform this workflow. If the directory is missing, empty, or unreadable, skip silently — the Ledger is purely additive and never required.

1. Check: ls .smith/vault/ledger/*.md 2>/dev/null
2. If files exist, read the following sections (higher-confidence entries first, truncate at ~2000 tokens per file):

• .smith/vault/ledger/patterns.md
• .smith/vault/ledger/antipatterns.md
• .smith/vault/ledger/tool-preferences.md
• .smith/vault/ledger/edge-cases.md
• .smith/vault/ledger/project-quirks.md

1. Use loaded patterns as additional context — not as hard rules. The Ledger informs judgment, it does not override spec/plan/constitution.
2. Budget violation tracking: If any Ledger file was truncated (entries were dropped to fit within the ~2000 token budget per file), increment context_budget_violations in .smith/vault/ledger/.meta.json by 1. If .meta.json does not exist, create it from the default template first. This signal tells the reconciliation system that the Ledger is too large for the configured budget.

1. Determine build state (for recovery):

• If tasks.md exists, check for completed tasks [X] vs incomplete [ ]
• If some tasks are complete, this is a recovery run — skip to Phase 2 (implementation)
• If no tasks.md exists, this is a fresh run — start from Phase 1

Phase 1: Task Generation (Subagent)

Launch a subagent to generate the task breakdown.

The subagent should:

1. Read artifacts: spec.md, plan.md, data-model.md, contracts/, research.md, quickstart.md
2. Generate `tasks.md` following the strict format:

```

• [ ] [TaskID] [P?] [Story?] Description with file path

```

• Phase 1: Setup (project initialization)
• Phase 2: Foundational (blocking prerequisites)
• Phase 3+: User Stories in priority order
• Final Phase: Polish & Cross-Cutting Concerns

1. Run consistency analysis (smith-analyze logic):

• Check spec ↔ plan ↔ tasks alignment
• Check for missing coverage, contradictions
• If CRITICAL issues found: fix them in-place (do not halt)
• Log any issues found for the release notes

Ledger-Informed Auto-Retry

If the build execution fails, check config for auto-retry:

1. Read .smith/config.json — check ledger.auto_retry and ledger.max_retries
2. If auto_retry is false (default) or config is missing, do NOT retry — fail normally
3. If auto_retry is true:

a. Re-read .smith/vault/ledger/antipatterns.md to get the latest failure patterns b. Analyze the failure against known antipatterns to adjust the approach c. Retry the execution with the adjusted approach d. Repeat up to max_retries times (default: 2), re-reading antipatterns before each attempt e. If all retries exhausted, fail with a summary of all attempts

1. Each retry attempt is logged to the session log with attempt number and adjusted approach

Note: Auto-retry applies to the Phase 2 implementation loop. If a phase's subagent fails after 3 internal attempts AND auto-retry is enabled, the entire phase is retried with updated Ledger context.

Phase 2: Implementation (Subagent per Phase)

Execute tasks phase-by-phase, each phase in its own subagent to manage context.

Pre-implementation checks:

1. Verify/create ignore files based on plan.md tech stack:

• .gitignore, .dockerignore, .eslintignore, .prettierignore as applicable
• Only append missing patterns to existing files

1. Parse tasks.md to extract phases and their tasks.

Execute each phase:

For each phase in tasks.md:

1. Launch a subagent with:

• The phase's tasks (incomplete ones only)
• Relevant context: plan.md tech stack, data-model.md, contracts/
• File paths from task descriptions
• Instructions to mark each task [X] in tasks.md upon completion

1. Phase execution rules:

• Sequential tasks: execute in order
• Parallel tasks [P]: can run together (but subagent decides based on file conflicts)
• If a task fails: attempt fix up to 3 times, then log error and continue with remaining tasks
• After each task completion, update tasks.md with [X] marker

1. Phase completion check:

• Verify all tasks in the phase are marked [X]
• If any failed permanently, log them for the summary
• Proceed to next phase