smith-new git:20260912.27402c1A

Immutable. This exact content is served forever at /api/v1/blob/be64d7f453f3eea5.

---
name: smith-new
description: Start a new feature from scratch or from conversation context. Conversational requirements gathering, planning, questions gate, then fully autonomous build.
---

# SpecKit New Feature Workflow

This is the primary entry point for all new features. It combines requirements gathering, planning, and a questions gate into a single conversational flow, then hands off to autonomous execution.

**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.

Append entries to the session log using this format:

```
### [HH:MM:SS] /smith-new <event>

**User Request:**
> <verbatim user message that triggered this action — capture the exact words the user typed, including any conversation context that led to the request. For natural language triggers, capture the trigger message. For explicit /smith-new invocations, capture $ARGUMENTS.>

**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** — capture the verbatim user request AND the synthesized feature description
2. **After system detection** — which primary system was identified, which other systems are affected
3. **After spec creation** — path to created spec folder and spec.md
4. **After questions generated** — how many questions, path to questions file
5. **After questions answered** — summary of each answer (topic + decision, not full text)
6. **On handoff to build** — note that `/smith-build` autonomous phase was triggered

## Subagent Invocation Logging

Immediately before every Agent tool call in this workflow, 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>
```

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.

## Natural Language Triggers

If the user says any of the following (or similar phrases) during a conversation, treat it as invoking this command using the full conversation context as the feature description:
- "start a smith workflow"
- "let's smith this"
- "kick off a new feature for this"
- "let's build this"
- "start a new workflow for this"
- "can you smith this"

When triggered by natural language, synthesize the entire conversation history into a comprehensive feature description and proceed as if that description was passed as `$ARGUMENTS`.

## Phase 0: Pre-Change Exploration (Conditional)

Before creating a worktree, check if the proposed feature warrants impact analysis.

### When to Run Exploration

Run `/smith-explore` automatically if ANY of these conditions are met:
- `$ARGUMENTS` or conversation context mentions: "skill", "hook", "constitution", "CLAUDE.md", "MEMORY.md", "config", "policy"
- The feature touches core Smith infrastructure (`.claude/skills/`, `.smith/`, `.specify/`)
- `--explore` flag is passed explicitly

### Exploration Flow

1. **Run `/smith-explore`** with the feature description and scope auto-detected from context
2. **Wait for the exploration report** — this produces a structured analysis of:
   - Skills affected
   - Configuration file conflicts (per File Purpose Policy in constitution.md §VI)
   - Hooks that might be impacted
   - Cross-system architectural concerns
3. **Evaluate exploration status:**
   - **`clear`**: Continue to Phase 1 (worktree creation)
   - **`conflicts-found`** (warnings only): Present summary to user, ask to proceed or resolve first
   - **`blocking-issues`**: STOP. Present blocking issues and require resolution before continuing

### Skip Exploration

If none of the trigger conditions are met, skip directly to Phase 1. Exploration adds overhead and is only valuable for changes that may have system-wide impacts.

---

## Phase 1: Worktree Creation & Setup

The worktree is created after exploration passes (or is skipped). This ensures the user's current working directory and branch are never touched — the entire workflow is isolated from the start.

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 to this workflow:
   ```bash
   # After determining branch name in step 4 and feature slug:
   ~/.smith/scripts/create-active-workflow.sh \
     --branch "$BRANCH" \
     --workflow smith-new \
     --slug "<feature-slug>" \
     --worktree "$WORKTREE_PATH"
   ```
   (Falls back to `scripts/create-active-workflow.sh` in repo-dev layouts.) Clear this marker at the end of Phase 6 (after merge) or if the workflow is abandoned. Use the shipped helper so this works even on projects that set `Bash(rm:*)` in the deny list:
   ```bash
   .specify/scripts/bash/clear-active-workflow.sh "$BRANCH"
   ```

1. **Resolve the configured base branch, then fetch it** (does NOT change the user's current branch). Smith reads the project's integration branch from the constitution; it falls back to `main` when unconfigured:
   ```bash
   BASE_BRANCH=$(.specify/scripts/bash/get-base-branch.sh)
   git fetch origin "$BASE_BRANCH"
   ```

2. **Generate branch short-name** (2-4 words) from `$ARGUMENTS` or conversation context. If no feature description is available yet (empty args, no context), use a placeholder like `new-feature` and rename the branch later after Phase 2.

3. **Find next feature number** by checking all three sources:
   - Remote branches: `git ls-remote --heads origin | grep -oP '(?<=refs/heads/)\d+' | sort -n | tail -1`
   - Local branches: `git branch | grep -oP '^\s*\d+' | sort -n | tail -1`
   - Specs directories: `ls -d .specify/systems/*/features/[0-9]*-* 2>/dev/null | grep -oP '\d+(?=-)' | sort -n | tail -1`
   - GitHub issues: `gh issue list --limit 1 --json number --jq '.[0].number'`
   Take the maximum across all sources and add 1.

4. **Create worktree with feature branch from the configured base branch (`origin/$BASE_BRANCH`)**:
   ```bash
   git worktree add /tmp/smith-<slug> -b <number>-<short-name> "origin/$BASE_BRANCH"
   ```
   Store the worktree path (`/tmp/smith-<slug>`) as `WORKTREE_PATH`. The active-workflow file was already created in step 0 with the branch and worktree info.

   **Note**: The user's current branch is completely unaffected. They can be on any branch — `main`, a feature branch, even a detached HEAD — and this workflow will not interfere.

## 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 the loaded entries as additional context throughout this workflow — both during the conversational requirements-gathering phase (to know what to ask about, what failure modes to anticipate) and during spec generation (to steer the spec away from known antipatterns and toward established patterns / tool preferences). 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.

## Phase 2: Requirements Conversation

**Goal**: Arrive at a clear, detailed feature description through conversation. This phase is purely conversational — no file operations needed. The worktree already exists from Phase 1.

### If `$ARGUMENTS` is empty AND no prior conversation context:
- Prompt the user: "What would you like to build?"
- Enter a conversational loop:
  - Ask clarifying questions about scope, user flows, constraints
  - Reflect back your understanding
  - Let the user refine and add detail
  - Continue until the user indicates they're satisfied (e.g., "that's it", "looks good", "let's go")

### If `$ARGUMENTS` is provided:
- Use the provided description as the starting point
- Reflect back your understanding and ask if anything is missing
- Allow one round of refinement if the user wants to adjust

### If triggered mid-conversation (natural language trigger):
- Synthesize the conversation history into a comprehensive feature description
- Present it to the user: "Based on our conversation, here's what I understand you want to build: [summary]. Anything to add or change?"
- Allow refinement

### Output of Phase 2:
A complete feature description string that will be passed to the spec generation step.

## Phase 3: Spec Generation (Subagent — in Worktree)

Once requirements are finalized, launch a subagent to handle spec generation. The worktree (`WORKTREE_PATH`) was already created in Phase 1. All file operations happen there.

If the branch was created with a placeholder name in Phase 1 (because `$ARGUMENTS` was empty), rename it now:
```bash
cd $WORKTREE_PATH && git branch -m <old-placeholder-name> <number>-<short-name>
```
Rename the active-workflow file if the branch name changed:
   ```bash
   OLD_SAFE=$(echo "$OLD_BRANCH" | sed 's/[^a-zA-Z0-9._-]/-/g')
   NEW_SAFE=$(echo "$NEW_BRANCH" | sed 's/[^a-zA-Z0-9._-]/-/g')
   mv .smith/vault/active-workflows/${OLD_SAFE}.yaml .smith/vault/active-workflows/${NEW_SAFE}.yaml
   ```

1. **Auto-detect primary system** (reading from worktree):
   - Read all system spec files at `$WORKTREE_PATH/.specify/systems/system-*/spec.md`
   - Analyze the feature requirements against each system's scope, services, endpoints, and data models
   - Determine `primary_system` (the system most directly impacted) and `also_affects` (other systems touched)
   - Set the feature spec folder path to `.specify/systems/<primary-system>/features/<NNN-short-name>/`
   - If no single system is clearly primary (genuinely cross-cutting), use `.specify/systems/cross-system/features/<NNN-short-name>/`
   - Do NOT ask the user which system to use — determine this automatically
2. **Create feature folder in worktree**:
   ```bash
   mkdir -p $WORKTREE_PATH/.specify/systems/<primary-system>/features/<NNN-short-name>/checklists
   ```
   Note: Do NOT run `create-new-feature.sh` — the worktree creation in Phase 1 already created the branch.
3. **Load spec template**: Read `$WORKTREE_PATH/.specify/templates/spec-template.md`
4. **Write spec.md** to the system-routed feature folder in the worktree with frontmatter:
   ```yaml
   ---
   feature: <NNN-short-name>
   primary_system: <system-folder-name>
   also_affects:
     - <other-system-folder-name>
   branch: <branch-name>
   created: <YYYY-MM-DD>
   status: in-progress
   ---
   ```
   Fill all sections from the requirements conversation:
   - Focus on WHAT and WHY, not HOW
   - Make informed guesses for unspecified details (document in Assumptions)
   - Maximum 0 [NEEDS CLARIFICATION] markers — all ambiguities should have been resolved in conversation
5. **Write quality checklist** at `$WORKTREE_PATH/<feature-folder>/checklists/requirements.md`
6. **Validate spec** against quality criteria (up to 3 iterations)

## Phase 4: Plan Generation (Subagent — in Worktree)

Launch a separate subagent to generate the implementation plan. This preserves context window for the questions phase. **All work happens in `WORKTREE_PATH`.**

The subagent should:

1. **Run setup script** (from worktree):
   ```bash
   cd $WORKTREE_PATH && .specify/scripts/bash/setup-plan.sh --json
   ```
   Parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH.

2. **Load context** (from worktree):
   - Read FEATURE_SPEC (spec.md)
   - Read `$WORKTREE_PATH/.specify/memory/constitution.md`
   - Read IMPL_PLAN template

3. **Execute plan workflow**:
   - Fill Technical Context
   - Evaluate constitution gates
   - **Phase 0**: Generate `research.md` (resolve unknowns, research dependencies)
   - **Phase 1**: Generate `data-model.md`, `contracts/`, `quickstart.md`
   - Run `cd $WORKTREE_PATH && .specify/scripts/bash/update-agent-context.sh claude`

4. **Return**: Confirm plan artifacts are written to SPECS_DIR.

### Clean-Architecture & Reuse Requirements (plan.md)

Before finalizing the file structure in `plan.md`, the plan subagent MUST bake
in clean-code / clean-architecture principles so the feature ships as small,
reusable, single-responsibility modules rather than a few large files:

1. **Reuse before creating.** Find existing components that already do (or
   nearly do) what the feature needs, and prefer extending/importing them over
   writing new code:
   - If `.smith/index/` exists, run `/smith-navigate "<feature description>"`
     (or read the relevant `.smith/index/systems/*` manifest) to surface
     reusable modules, services, and utilities. A built, current manifest
     makes this lookup fast and comprehensive — if the project has none,
     consider running `/smith-index` once up front so future features get
     accurate reuse detection cheaply.
   - If no manifest exists, grep the affected system paths for existing
     helpers, models, and components covering the same concern.
   - In `plan.md`, list the existing components the feature will reuse and call
     out anything that would otherwise be duplicated so the build phase extends
     rather than recreates it.

2. **Prescribe a decomposed file structure.** The `plan.md` file-structure
   section MUST split responsibilities (interface / application / domain /
   infrastructure where applicable) into small, focused files rather than
   monolithic ones. Follow the constitution's **File Size Policy** (300-line
   soft target, 500-line decomposition threshold) — do NOT restate a different
   number. Flag any planned file expected to exceed 300 lines and split it up
   front.

3. **Apply the Clean Code rubric.** Use the `/clean-code` skill as the canonical
   rubric — intention-revealing names, small single-purpose functions,
   separation of concerns, low duplication. Reference it rather than restating
   it; record only the feature-specific structural decisions in `plan.md`.

These are planning-time advisories that shape `plan.md` — they inform the
build, they do not block it.

## Phase 5: Questions Gate (MANDATORY STOP — in Worktree)

After the plan subagent completes, read ALL plan artifacts from `WORKTREE_PATH` and generate a comprehensive questions file. All file reads/writes in this phase use the worktree.

1. **Read plan artifacts**:
   - `plan.md` — architecture, file structure, tech decisions
   - `research.md` — decisions and alternatives
   - `data-model.md` — entities and relationships (if exists)
   - `contracts/` — API specifications (if exists)
   - `quickstart.md` — integration scenarios (if exists)

2. **Generate `<feature-folder>/questions.md`** (inside the feature's spec folder under `.specify/systems/`) with this structure:

   ```markdown
   # Implementation Questions: [Feature Name]

   **Generated**: [DATE]
   **Feature**: [Link to spec.md]
   **Plan**: [Link to plan.md]
   **Status**: AWAITING ANSWERS

   ---

   ## Q1: [Topic]

   **Context**: [Quote relevant section from plan/spec/research that raises this question]

   **Question**: [Specific question about an implementation decision]

   **Options**:

   | Option | Description | Implications |
   |--------|-------------|--------------|
   | A      | [First option] | [Tradeoffs, effort, risk] |
   | B      | [Second option] | [Tradeoffs, effort, risk] |
   | C      | [Third option] | [Tradeoffs, effort, risk] |

   **Recommended**: [A/B/C] — [Reasoning for recommendation]

   **Answer**: ___

   ---

   [Repeat for all questions]
   ```

3. **Question quality rules**:
   - Questions should be informed by the plan artifacts — technical decisions, not basic requirements
   - Each question must have at least 2 options with clear tradeoffs
   - Every question must have a recommended answer with reasoning
   - Questions should be ordered by impact (highest impact first)
   - Aim for 5-10 questions. Fewer if the feature is straightforward.
   - Do NOT ask about things that have clear best practices or obvious defaults

4. **Walk through questions interactively, one at a time.**

   For each question in the generated questions.md:

   a. **Present** the question with its full context, all options with pros/cons, and the recommended answer with clear reasoning:
      ```
      ## Question [N] of [Total]: [Topic]

      **Context:** [Quote from plan/spec that raises this question]

      **Question:** [Specific implementation decision]

      **Options:**
      | Option | Description | Implications |
      |--------|-------------|--------------|
      | A | [description] | [pros: ..., cons: ...] |
      | B | [description] | [pros: ..., cons: ...] |
      | C | [description] | [pros: ..., cons: ...] |

      **Recommended:** [Option letter] — [Reasoning]

      Reply with an option letter, "yes" to accept the recommendation,
      "skip" to defer, or type a custom answer.
      ```

   b. **Wait for the user's response**, then:
      - `"yes"` / `"recommended"` → use the recommended answer
      - Option letter (`"A"`, `"B"`, etc.) → use that option
      - `"skip"` → mark as `**Answer:** SKIPPED — needs follow-up`
      - Anything else → accept as custom answer

   c. **Immediately update questions.md** — fill in the `**Answer:**` field for that question

   d. **Confirm** and move to the next question: `"Saved: Q[N] → [answer]. ([remaining] remaining)"`

   e. If the user says "done" before all questions, mark remaining as SKIPPED

5. **After all questions answered:**

   a. Display a summary table of all answers
   b. Ask: "Would you like to change any answers? Reply with a question number or 'looks good'."
   c. If changes requested, re-present that question and collect a new answer
   d. Update **Status** in questions.md from "AWAITING ANSWERS" to "ANSWERED"

## Phase 6: Update Plan, Then Build or Queue (in Worktree)

After answers are confirmed. All work continues in `WORKTREE_PATH`. The user's main working directory is never touched.

1. **Update `plan.md`** if any answers change the planned approach:
   - Launch a subagent to read answered questions and update plan.md accordingly
   - This is a targeted update, not a full rewrite

2. **Copy `.env`** from main repo to worktree if Docker-touching (scan plan.md for `docker-compose.yml`, `Dockerfile` references):
   ```bash
   cp <main-repo-path>/.env $WORKTREE_PATH/.env
   ```
   If Docker-touching, display warning:
   > "This feature modifies Docker configuration. The worktree isolates git only — Docker operations will affect running containers."

3. **Build or Queue decision point.** Ask the user:

   > All questions answered and spec is ready. Would you like to:
   > 1. **Build now** — launch `/smith-build` in the worktree for autonomous implementation
   > 2. **Queue for later** — commit spec artifacts, push, and add to the Smith queue for batch processing

   ---

   **If "Queue for later"** (or "2", "queue", "later"):

   a. Ask: "Priority? (critical / high / medium / low)" — default to `medium` if the user just says "queue" without specifying
   b. **Commit spec artifacts** in the worktree — stage and commit all files in the feature spec folder (spec.md, plan.md, questions.md, research.md, data-model.md, contracts/, checklists/):
      ```bash
      cd $WORKTREE_PATH && git add <feature-spec-folder>/
      cd $WORKTREE_PATH && git commit -m "docs: spec artifacts for <feature-name> — ready for queued build"
      ```
   c. **Push the feature branch from the worktree:**
      ```bash
      cd $WORKTREE_PATH && git push -u origin <branch-name>
      ```
   d. **Create the queue entry** in the **main repo** at `.smith/vault/queue/<NNN-short-name>.md` with this format:
      ```yaml
      ---
      task: "Build feature: <feature-name>"
      branch: "<feature-branch-name>"
      spec_path: "<path to the feature spec folder on the feature branch>"
      primary_system: "<system ID from spec frontmatter>"
      created: "<ISO timestamp>"
      complexity: autonomous
      priority: <user's choice or medium>
      status: pending
      depends_on: []
      ---

      ## Context

      <brief description of the feature and key decisions from the questions phase>

      ## Artifacts on branch

      - spec.md — feature specification
      - plan.md — implementation plan
      - questions.md — clarification questions (all answered)
      - <list any other artifacts: research.md, data-model.md, contracts/, etc.>

      ## Execution Instructions

      Run `/smith-build` from the `<branch-name>` branch with feature dir `<spec_path>`.
      ```
   e. **Clean up worktree:**
      ```bash
      git worktree remove $WORKTREE_PATH
      ```
   f. **Clear active-workflow file** in the main repo (via the shipped helper, which coexists with a broad `Bash(rm:*)` deny rule):
      ```bash
      .specify/scripts/bash/clear-active-workflow.sh "$BRANCH"
      ```
   g. Confirm: "Queued: `<filename>` (priority: `<level>`, complexity: autonomous). Feature branch `<branch-name>` pushed with all spec artifacts. Run `/smith-queue list` to see pending tasks, or the 2am scheduler will pick it up automatically."
   h. **STOP here.** Do NOT launch `/smith-build`.

   ---

   **If "Build now"** (or "1", "build now", "yes", "go"):

4. **Launch `/smith-build`** in the worktree to execute the entire autonomous phase:
   - Pass `WORKTREE_PATH` and the feature directory path as context
   - This runs as a subagent chain (see smith-build skill)
   - Instruct the build subagent: after every Write or Edit to a `.py`,
     `.js`, `.jsx`, `.ts`, or `.tsx` file, update the touched file's
     `.meta` description layer in-context — see the "Update `.meta`
     Descriptions for Touched Methods" sub-step pattern in the
     `/smith-bugfix` skill (Phase 3.5). Touched-method-only regeneration
     keeps token cost bounded and preserves previously-accepted
     descriptions for untouched methods, per the v2 manifest contract
     (data-model.md §4 and spec.md C1). Failures of the helper are
     non-blocking — the missing descriptions are surfaced by
     `/smith-build`'s PR-body Description Coverage Warnings section.
   - Wait for completion

4.5 **In-context `.meta` description update (mid-conversation code edits).**
   If `/smith-new` itself wrote or edited any source code directly
   (i.e. before delegating to `/smith-build`), apply the v3 inline
   Task-spawning prose from `/smith-bugfix` Phase 3.5 (step 3) per
   modified file. The flow is: discover → build-prompt → spawn Task
   (subagent_type=general, model=claude-haiku-4-5) → pipe JSON into
   `describe_write.py apply --update-touched`. Subscription billing
   via session auth — no `ANTHROPIC_API_KEY`. See `/smith-bugfix`
   Phase 3.5 for the full identification heuristic and prompt
   assembly. Skip silently if no source code was edited at this stage.

5. **Display final summary** to the user. Emit a chat message that starts with "Feature `<name>` complete. Here's the summary:" and includes the feature name and branch, files created/modified, PR link, release notes summary, and link to `specs/<feature>/release.md`. At the bottom, run the totals command and paste the lines it prints verbatim — do this BEFORE step 9 (clearing the active-workflow file) so the numbers are fresh. Pass the workflow's own session log via `--session` so totals are computed against the correct file even if the session log rolled over mid-workflow:
   ```bash
   # $SESSION was captured at workflow start (step 0). Fall back to the marker's
   # session_log field, then to .current-session, if it's not in scope here.
   SESSION="${SESSION:-$(cat .smith/vault/.current-session 2>/dev/null)}"
   bash "$HOME/.claude/hooks/workflow-summary.sh" --totals-only --session "$SESSION"
   ```
   The bash invocation is a required action, not an optional extra — the totals lines must appear in the chat message. If it prints `n/a (no workflow invocation found)` and exits non-zero, do NOT present those as real numbers — note that totals were unavailable and which session file was checked.

6. **Merge PR** from the **main repo directory** (not the worktree — avoids "main already checked out" errors):
   **IMPORTANT**: Always run `gh pr merge` from the **primary repo directory**.
   ```bash
   cd <main-repo-path> && gh pr merge <PR_NUMBER> --squash --delete-branch
   cd <main-repo-path> && git pull origin "$(.specify/scripts/bash/get-base-branch.sh)"
   ```
   - Squash-merge the PR to keep history clean
   - Delete the remote feature branch
   - Pull latest from the configured base branch so the local copy is up to date

7. **Full workflow summary (session log only)** — emitted automatically. The `workflow-summary.sh` Stop hook appends a "=== Workflow Summary ===" block with duration, estimated tokens, tool calls, subagent totals, and files changed to the session log file once the active-workflow file is removed (step 9 below). Do not emit the full block to the user manually — the two-line totals already surfaced in step 5 are the chat-visible version; the full block is for audit only.

8. **Clean up worktree:**
   ```bash
   git worktree remove $WORKTREE_PATH
   ```

9. **Clear workflow tracking** — remove the active-workflow file via the shipped helper (safe against a `Bash(rm:*)` deny rule):
   ```bash
   .specify/scripts/bash/clear-active-workflow.sh "$BRANCH"
   ```

### 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

### Post-Workflow Sync (run last)

As the VERY LAST action — after the PR merge, worktree removal, marker clear, and
the reflection/reconciliation launches above — **Run `/smith-sync`** from the
primary repo on the default branch. This sweeps the team-shareable `.smith/`
artifacts (manifest, `.meta` describe layer, ledger, bank, agents, sessions)
accumulated this session into a single `chore(smith): … [skip ci]` commit and
pushes it to the default branch, so teammates receive the updated context.

Do NOT block on the background reflection sub-agent — this session's ledger
update (written asynchronously by reflection) will be captured by the NEXT
`/smith-sync` run. `/smith-sync` no-ops cleanly if there is nothing to sync.

## Key Rules

- All paths must be absolute
- For single quotes in args, use escape syntax: `'I'\''m Groot'`
- **Worktree isolation**: The worktree is created in Phase 1, before any other work. ALL file operations from Phase 3 onward happen in the worktree (`WORKTREE_PATH`). Never checkout the feature branch or write files in the user's main working directory. The only files written to the main repo are vault entries (`.smith/vault/queue/`, `.smith/vault/.active-workflow`). The user's current branch is never changed or checked.
- The questions gate is MANDATORY — never skip it
- If context window is getting large after the conversation phase, summarize requirements before launching subagents