smith-new

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:

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

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

   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):

   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 wa

---

Content truncated.