--- name: smith-build description: Autonomous build phase — generates tasks, implements, tests, commits, pushes, merges, and produces release notes. Runs without user interaction. --- # 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. Append entries using this format: ``` ### [HH:MM:SS] /smith-build **User Request:** > **Synthesized Input:** **Outcome:** **Artifacts:** **Systems affected:** ``` 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: **Type:** **Model:** ``` 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 0. **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. 2. **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. 3. **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` 3. Use loaded patterns as additional context — not as hard rules. The Ledger informs judgment, it does not override spec/plan/constitution. 4. **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. 4. **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 3. **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 4. 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 2. **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 2. **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 3. **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 ### Implementation rules: - Follow the plan.md architecture and file structure - Respect data-model.md entity definitions - Match contracts/ API specifications - Use existing project patterns (read surrounding code before writing) - Follow constitution.md principles - **Clean-code architecture** — apply this checklist directly (it implements the constitution's **Clean Architecture Policy** and mirrors the `/smith-clean-code` skill; do NOT rely on being able to load that skill, as build subagents may not have skill access): - Small, single-responsibility functions and files; one clear reason to change. - Intention-revealing names (avoid `data`, `temp`, `handler`, `util` when a meaningful name exists). - Guard clauses over deep nesting; keep control flow shallow. - Separation of concerns — keep I/O, business rules, and persistence in distinct units. - No dead code, commented-out blocks, or duplicated logic. - Honor the file structure `plan.md` prescribed; do not collapse it back into large monolithic files. - **Reuse over duplication**: before writing new code, check for an existing component that already does it — extend or import it rather than recreating it. Use the reuse list in `plan.md` (and `/smith-navigate` / `.smith/index/` when available) to locate existing modules, services, and utilities. Do not copy-paste near-identical logic; factor shared logic into a common helper. - **Keep files small**: follow the constitution **File Size Policy** (300-line soft target, 500-line decomposition threshold). When a file you are editing approaches the threshold, split it proactively during the build rather than leaving it for the post-hoc File Size Warnings flag in the PR body (§5.3). - **After any code changes to a Docker service**: run `docker compose up -d --build ` immediately ## Phase 3: Testing (Subagent) Launch a testing subagent after all implementation is complete. ### 3.1 Unit Tests - **If frontend code changed**: `cd services/command-center && pnpm test` - **If Python service changed**: `cd services/ && poetry run pytest` - Run existing test suites — do NOT skip tests ### 3.2 Playwright E2E Tests (MANDATORY for UI changes) - **Check if any frontend files were modified** in this feature: - Files matching `services/command-center/src/components/**` - Files matching `services/command-center/src/pages/**` - Files matching `services/command-center/src/hooks/**` - Files matching `services/command-center/src/App.tsx` - **If YES**: 1. Run existing Playwright suite for regression: `cd services/command-center && pnpm exec playwright test` 2. Write NEW Playwright tests for the changed/added UI flows 3. Run the new tests - **If NO frontend changes**: Skip Playwright ### 3.3 Test Failure Handling - If tests fail: fix the code and re-run (up to 3 attempts per failure) - If a test is flaky (passes on retry without code changes): note in release notes - If tests cannot be fixed after 3 attempts: log the failure and continue - The release notes will flag this as requiring manual attention ## Phase 4: Spec Updates (Subagent) Launch a subagent to update related system spec files. 1. **Identify modified files** from git diff against the configured base branch: ```bash BASE_BRANCH=$(.specify/scripts/bash/get-base-branch.sh) git diff "$BASE_BRANCH" --name-only ``` 2. **Map modified files to system specs**: - `services/command-center/` → `specs/system-15-command-center/spec.md` - `services/email-pipeline/` → `specs/system-03-email-archive-contact-graph/spec.md` - `services/sentiment-engine/` → `specs/sentiment-engine/spec.md` - `services/communication-triage/` → `specs/system-05-communication-triage/spec.md` - `services/voice-training/` → `specs/system-04-personal-voice/spec.md` - `docker-compose.yml` → `specs/system-01-core-infrastructure/spec.md` - Other mappings as discovered from `specs/*/spec.md` content 3. **For each affected spec.md**: - Read the current spec - Add an "Implementation History" section (or append to existing) - Add a dated entry describing changes relevant to that system - Keep entries concise and factual 4. **Update STATUS.md** at project root with current progress. ### 4.5 System Spec Updates via `.specify/systems/` After updating the legacy `specs/system-*/spec.md` files above, also update the canonical system specs in `.specify/systems/`: 1. **Read the feature spec frontmatter** — extract `primary_system` and `also_affects` fields. If the feature spec has no frontmatter (legacy spec in `specs/`), fall back to the file-path mapping in step 2 above. 2. **Update primary system spec** — Read `.specify/systems//spec.md` and update any sections affected by the feature: - New API endpoints or modified routes - New or changed data models / database tables - Changed behavior or configuration - New dependencies or service interactions 3. **Update affected system specs** — For each system in `also_affects`, read its `.specify/systems//spec.md` and update relevant sections. 4. **Log updates to vault** — If `.smith/vault/.current-session` exists, append an entry to the session log noting which system specs were updated and what changed. 5. **Commit system spec updates** as part of the same feature branch before creating the PR. If the build cannot determine what to update in a system spec (ambiguous changes), flag this in the vault session log for the user to review rather than making incorrect updates. ## Phase 5: Commit, Push & Merge ### 5.1 Commit ```bash git add git commit -m "" ``` - Use conventional commits format - Reference the feature spec in the commit message - Stage files explicitly (never `git add -A` or `git add .`) - Do NOT stage `.env` files or credentials ### 5.2 Push ```bash git push -u origin ``` ### 5.3 Pre-PR File-Size Scan Before composing the PR body, scan all files modified on this branch for oversized source files. This is a non-blocking advisory — always proceed with the PR. ```bash # Enumerate files changed vs the configured base branch BASE_BRANCH=$(.specify/scripts/bash/get-base-branch.sh) git diff "$BASE_BRANCH" --name-only > /tmp/smith-build-changed.txt # For each modified file that exists on disk, count lines while IFS= read -r f; do [ -f "$f" ] || continue lines=$(wc -l < "$f" | tr -d ' ') if [ "$lines" -gt 300 ]; then printf -- "- \`%s\` — %s lines (exceeds 300)\n" "$f" "$lines" fi done < /tmp/smith-build-changed.txt > /tmp/smith-build-oversized.txt ``` If `/tmp/smith-build-oversized.txt` is non-empty, include a **"File Size Warnings"** section in the PR body (see Step 5.4 template). If empty, omit the section entirely. Source extensions in scope: `.py`, `.js`, `.jsx`, `.ts`, `.tsx`, `.css`, `.html`, `.sh`. Exclude paths matching `vendor/`, `node_modules/`, `.venv/`, `dist/`, `build/`, `.smith/`. This is a FLAG, never a blocker. Always proceed with PR creation. ### 5.3.1 Pre-PR Description Coverage Scan In addition to the file-size flag, scan the diff for methods that were ADDED or EDITED in this PR but lack a `.meta` description. This is the v2 description-coverage check from data-model.md §9. Like the file-size flag, it is informational — the PR opens unconditionally. ```bash # Reuse /tmp/smith-build-changed.txt from Step 5.3 above. > /tmp/smith-build-coverage-misses.txt while IFS= read -r f; do case "$f" in *.py|*.js|*.jsx|*.ts|*.tsx) ;; *) continue ;; esac [ -f "$f" ] || continue # Skip files inside excluded directories. case "$f" in vendor/*|*/vendor/*|node_modules/*|*/node_modules/*|.venv/*|*/.venv/*|dist/*|*/dist/*|build/*|*/build/*|.smith/*|*/.smith/*) continue ;; esac # Resolve parser path: prefer per-project override, then ~/.smith, # then repo-shipped parsers. case "$f" in *.py) for cand in .smith/scripts/parse-python.py "$HOME/.smith/scripts/parse-python.py" scripts/parsers/parse-python.py; do [ -f "$cand" ] && PARSER="python3 $cand" && break done ;; *) for cand in .smith/scripts/parse-js.js "$HOME/.smith/scripts/parse-js.js" scripts/parsers/parse-js.js; do [ -f "$cand" ] && PARSER="node $cand" && break done ;; esac [ -z "${PARSER:-}" ] && continue # Parse the file at HEAD (current branch). Capture the (id, name, scope) # triples plus class scope. CUR_JSON=$($PARSER "$f" 2>/dev/null || true) [ -z "$CUR_JSON" ] && continue # Build a list of HEAD method ids and their qualified names. python3 - "$f" "$CUR_JSON" >> /tmp/smith-build-coverage-misses.txt <<'PY' || true import json, os, sys, subprocess, re rel = sys.argv[1] cur = json.loads(sys.argv[2]) # Collect (id, qualified_name) for HEAD. head_methods = [] for fn in cur.get("functions") or []: fid = fn.get("id") name = fn.get("name", "") if fid: head_methods.append((fid, f"{rel}::{name}")) for cls in cur.get("classes") or []: cname = cls.get("name", "") for m in cls.get("methods") or []: mid = m.get("id") mname = m.get("name", "") if mid: head_methods.append((mid, f"{rel}::{cname}::{mname}")) # Compare against `git show main:` parse to find added/changed ids. try: main_src = subprocess.check_output( ["git", "show", f"main:{rel}"], stderr=subprocess.DEVNULL ).decode("utf-8", errors="replace") except subprocess.CalledProcessError: main_src = None prev_ids = set() if main_src is not None: # Re-parse main:. The stable method id incorporates the # project-relative module_path, so we MUST stage the bytes at the # same relative path inside a scratch directory and run the parser # with that directory as CWD. Otherwise the temp-file path leaks # into the id hash and every method looks "added". import tempfile, pathlib suffix = pathlib.Path(rel).suffix parser_cmd = os.environ.get("SMITH_PARSER_CMD", "") if not parser_cmd: if suffix == ".py": for cand in (".smith/scripts/parse-python.py", os.path.expanduser("~/.smith/scripts/parse-python.py"), "scripts/parsers/parse-python.py"): if os.path.isfile(cand): parser_cmd = f"python3 {os.path.abspath(cand)}" break else: for cand in (".smith/scripts/parse-js.js", os.path.expanduser("~/.smith/scripts/parse-js.js"), "scripts/parsers/parse-js.js"): if os.path.isfile(cand): parser_cmd = f"node {os.path.abspath(cand)}" break if parser_cmd: with tempfile.TemporaryDirectory() as scratch: staged = os.path.join(scratch, rel) os.makedirs(os.path.dirname(staged), exist_ok=True) with open(staged, "w", encoding="utf-8") as fh: fh.write(main_src) try: out = subprocess.check_output( parser_cmd.split() + [rel], stderr=subprocess.DEVNULL, cwd=scratch, ) prev = json.loads(out.decode("utf-8", errors="replace")) for fn in prev.get("functions") or []: if fn.get("id"): prev_ids.add(fn["id"]) for cls in prev.get("classes") or []: for m in cls.get("methods") or []: if m.get("id"): prev_ids.add(m["id"]) except (subprocess.CalledProcessError, json.JSONDecodeError): pass # Touched = HEAD ids not in main (added) OR signature changed (id differs). touched = [(fid, qname) for (fid, qname) in head_methods if fid not in prev_ids] # Load .meta description layer to check which touched ids have descriptions. meta_path = os.path.join(".smith", "index", "files", rel + ".meta") desc_ids = set() if os.path.isfile(meta_path): in_funcs = False current_id = None with open(meta_path, "r", encoding="utf-8") as fh: for line in fh: line = line.rstrip("\n") if line.startswith("## Functions") or line.startswith("## Classes"): in_funcs = True current_id = None continue if line.startswith("## ") and in_funcs: in_funcs = False current_id = None continue if in_funcs: m = re.match(r"^\s*Id:\s+(\S+)", line) if m: current_id = m.group(1) continue m = re.match(r"^\s*Description:\s+(.+)$", line) if m and current_id: if m.group(1).strip(): desc_ids.add(current_id) current_id = None for fid, qname in touched: if fid not in desc_ids: print(f"- {qname} (id: {fid})") PY done < /tmp/smith-build-changed.txt ``` If `/tmp/smith-build-coverage-misses.txt` is non-empty, include a **"Description Coverage Warnings"** section in the PR body (see Step 5.4 template). If empty, omit the section entirely. This is a FLAG, never a blocker. Always proceed with PR creation. If `git diff "$BASE_BRANCH"` returns no files (clean tree, target branch ahead), the section is a no-op. Per data-model.md §9.3. ### 5.4 Create PR & Merge ```bash BASE_BRANCH=$(.specify/scripts/bash/get-base-branch.sh) gh pr create --base "$BASE_BRANCH" --title "" --body "$(cat <<'EOF' ## Summary ## Test plan ## File Size Warnings The following files exceed the 300-line threshold and should be considered for decomposition in follow-up work: - `backend/src/api/v1/products.py` — 1,250 lines (exceeds 300) - `services/billing/main.py` — 487 lines (exceeds 300) ## Description Coverage Warnings methods in this diff lack `.meta` descriptions: - backend/src/services/webhook.py::WebhookRetryHandler::backoff (id: 4b8d6e2a9f1c0e7d) - backend/src/services/webhook.py::WebhookRetryHandler::dead_letter (id: a3f0c8d2e7b14955) - frontend/src/lib/api/products.ts::fetchProductBundle (id: 9c1d4e0a8f2b5c63) Run `/smith-index --describe --system ` to backfill before merge, or rely on the next `/smith-bugfix`/`/smith-new` workflow to update descriptions for touched methods in-context. ## Release notes See specs//release.md Generated with [Claude Code](https://claude.com/claude-code) EOF )" ``` Then merge the PR. **IMPORTANT**: Always run `gh pr merge` from the **primary repo directory**, not from a worktree. Running from a worktree causes "fatal: 'main' is already checked out" errors. ```bash # If in worktree mode: cd && gh pr merge --squash --delete-branch # If in normal mode: gh pr merge --squash --delete-branch ``` ### 5.5 Return to the base branch **Normal mode:** ```bash BASE_BRANCH=$(.specify/scripts/bash/get-base-branch.sh) git checkout "$BASE_BRANCH" git pull origin "$BASE_BRANCH" ``` **Worktree mode:** Do NOT run `git checkout "$BASE_BRANCH"` — the base branch is already checked out in the primary repo. Instead, proceed directly to Phase 6. The worktree cleanup in Phase 7 handles branch deletion. ## Phase 6: Service Rebuild After merging to the base branch: 1. **Identify affected services** from the changed files 2. **Docker-touching detection** (worktree mode only): - Check if changes include `docker-compose.yml`, `Dockerfile`, or service build contexts - If Docker-touching: display warning: > "This feature modifies Docker configuration. Worktree isolates git only — Docker operations will affect running containers." - Proceed with Docker operations after warning. 3. **Rebuild each affected service** — always run from the **primary repo directory** (not the worktree), since Docker Compose resolves paths relative to the compose file and Colima cannot mount `/tmp`: ```bash # If in worktree mode: pull changes to primary repo first cd && git pull origin "$(.specify/scripts/bash/get-base-branch.sh)" docker compose up -d --build ``` ```bash # Normal mode: docker compose up -d --build ``` 4. **Copy `.env`**: If in worktree mode and Docker operations are needed, ensure `.env` exists in the primary repo (it always should — this is a safety check). 5. **Run health check**: ```bash bash scripts/health-check.sh ``` 6. If any service is unhealthy: attempt restart, log issue ## Phase 7: Release Notes & Summary ### 7.1 Generate Release Notes Write `specs//release.md`: ```markdown # Release: [Feature Name] **Date**: [YYYY-MM-DD] **Branch**: [branch-name] **PR**: [#number](link) **Spec**: [spec.md](spec.md) ## Summary [2-3 sentence description of what was built] ## Changes ### Files Created | File | Purpose | |------|---------| | path/to/file.tsx | Description | ### Files Modified | File | Change | |------|--------| | path/to/file.tsx | What changed | ### System Specs Updated | Spec | Changes Recorded | |------|-----------------| | system-15-command-center/spec.md | Description | ## Testing ### Unit Tests - [PASS/FAIL] pnpm test — X tests passed - [PASS/FAIL] poetry run pytest — X tests passed ### E2E Tests (if applicable) - [PASS/FAIL] Existing Playwright suite — X tests passed - [PASS/FAIL] New Playwright tests — X tests for [flows tested] ### Known Issues - [Any test failures that couldn't be resolved] ## Deviations from Spec [Any differences between what was spec'd and what was implemented, with reasoning] ## Infrastructure - Docker services rebuilt: [list] - Health check: [PASS/FAIL] ``` ### 7.2 Commit Release Notes ```bash git add specs//release.md git commit -m "docs: add release notes for " git push origin main ``` ### 7.3 Worktree Cleanup (if applicable) If `WORKTREE_MODE=true`: 1. **On success**: Remove the worktree from the **primary repo directory**: ```bash cd && git worktree remove ``` 2. **On failure**: Preserve the worktree for debugging. Log the worktree path to the vault session log: > "Worktree preserved at for debugging. Clean up with: `git worktree remove `" ### 7.4 Clear Workflow Tracking Remove the active-workflow file to signal the workflow is complete. Use the shipped helper, which coexists with a broad `Bash(rm:*)` deny rule: ```bash .specify/scripts/bash/clear-active-workflow.sh "$BRANCH" ``` ### 7.4.1 Post-Workflow Reflection After workflow completion (success or failure), trigger a Ledger reflection if enabled: 1. Read `.smith/config.json` — if `ledger.auto_reflect` is `true` (default), proceed 2. Launch a **non-blocking** background sub-agent using the configured reflection model (default: Haiku): - Pass: current session log path, `.smith/vault/ledger/` path - The sub-agent runs the `smith-reflect` workflow - Do NOT wait for the sub-agent to complete 3. If `.smith/config.json` is missing or `ledger.auto_reflect` is `false`, skip silently ### Post-Reflection Reconciliation Check After reflection completes (or is skipped): 1. Read `.smith/config.json` — if `ledger.reconcile.auto_reconcile` is `false`, skip 2. Read `.smith/vault/ledger/.meta.json` — check signals against thresholds: - `estimated_tokens > thresholds.total_tokens_max` (default 30000) - `context_budget_violations > thresholds.context_violations_threshold` (default 3) - `reinforcements_since_reconcile > thresholds.reinforcements_threshold` (default 50) 3. Check minimum interval: if `last_reconcile` is less than `minimum_hours_between_reconciles` (default 6) hours ago, skip 4. If any threshold exceeded AND minimum interval has passed: - Launch a **non-blocking** background sub-agent using the configured `reconcile_model` (default: Haiku) - Pass: "Run /smith-ledger reconcile on this project" - Do NOT wait for the sub-agent to complete 5. If no threshold exceeded, `.meta.json` is missing, or config is missing, skip silently ### 7.5 Display Summary Output to the user: - Feature name - PR link - Release notes summary (inline, not just a file link) - Any issues requiring manual attention - Link to full release notes file - Confirmation that we're back on `main` with services healthy ## Recovery Mode If `/smith-build` is run manually (not from `/smith-new`): 1. Detect current state by checking: - Which branch we're on - Whether tasks.md exists and has incomplete tasks - Whether code changes exist but aren't committed - Whether a PR exists but isn't merged 2. Resume from the appropriate phase: - No tasks.md → start from Phase 1 - Tasks partially complete → resume Phase 2 from first incomplete task - All tasks complete, uncommitted → start from Phase 5 - PR exists, not merged → start from Phase 5.4 - PR merged, services not rebuilt → start from Phase 6 - Everything done → just generate release notes (Phase 7) ## Key Rules - ALL phases run without user interaction - Use subagents for each major phase to manage context - If a subagent fails, retry once before logging the error and continuing - Always rebuild Docker after code changes — never skip this - Never use `git add -A` or `git add .` — always stage specific files - Never commit `.env` files or credentials - Playwright tests are MANDATORY when frontend files are modified - The release.md file is the permanent record of what was built