Feature

/feature "<description>"

Opens a new feature session. Interviews the user, confirms a brief, writes brief.md, and initialises status.md as the restart checkpoint.

---

Idempotency pre-flight (ALWAYS FIRST)

1. Generate the feature-slug from the description (kebab-case)
2. Check if .feature/<slug>/status.md exists
3. If it exists, read it:
   • If stage is scoping and substage is complete or later:

     🔍 SCOPING AGENT · <slug>
     ───────────────────────────────────────────────
     Scoping is already complete for '<slug>'.
     Brief: .feature/<slug>/brief.md
     

     Use AskUserQuestion with options:
     • "Proceed to domain analysis"
     • "Stop" If "Proceed to domain analysis": invoke /feature-domains "<slug>" as a sub-agent immediately. If "Stop": display Next: /feature-domains "<slug>" and stop. Stop if the user says "redo" or "update brief" — proceed with re-scoping.
   • If stage is scoping and substage is in-progress: Display the opening header, then say "Scoping was in progress — resuming from last checkpoint." Re-display the last saved brief draft if it exists in status.md, then continue from Step 3 (confirm brief).
4. If status.md does not exist: proceed to Step 0.

---

Step 0 — Parse and slug

• Extract the description
• Generate feature-slug in kebab-case
• Create .feature/<slug>/ directory
• Write initial status.md (see Status File Template below) with stage scoping, substage interviewing Display opening header immediately:

───────────────────────────────────────────────
🔍 SCOPING AGENT · <slug>
───────────────────────────────────────────────

---

Step 1 — Read project config

Read .feature/project-config.md. If missing: stop and say "Run /setup-vallorcine to set up the project profile first."

If PROJECT-CONTEXT.md exists in the project root: read the ## Active section. Use global entries and any scoped entries matching the feature description to inform the scoping interview. Do not ask questions that active context entries already answer.

---

Step 2 — The scoping interview

Pre-interview analysis (internal — do not display)

Before asking anything, read the description and project-config.md and privately build a list of unknowns across these six dimensions:

Dimension	What to resolve
Scope	What is in and explicitly out of scope
Actors	Who or what initiates and receives this
Interface	Inputs, outputs, formats, protocols
Behaviour	Business rules, error cases, edge cases, performance
Integration	External services, storage, existing codebase dependencies
Success	Acceptance criteria, definition of done, concerns

For each dimension, mark it as:

• known — the description or project-config.md answers it clearly
• inferable — you can make a reasonable assumption; record it, don't ask
• unknown — genuinely unclear and affects how downstream agents work

Only unknowns become questions. Inferable items become assumptions in the brief. Simple features may have 1–2 unknowns. Complex ones may have 5–6. Either is fine.

Rank unknowns by impact: questions whose answers would change the most about the brief come first. Scope and interface questions almost always rank highest.

Opening display

── Scoping · <slug> ────────────────────────────
<one-sentence restatement of what you understood>

I have <n> question<s> before I can write the brief.
I'll go one at a time.

If n is 0 (description is fully specified): skip directly to Step 3, noting "Description is complete — no clarification needed." in the brief's assumptions.

Question loop (one question per turn, always)

For each unknown in ranked order:

Display:

── Question <i> of <n> ─────────────────────────
<The question — one focused question only>

<One sentence of context explaining why this matters for the brief.>

Rules for good questions:

• One question per turn. Never combine two questions into one turn.
• Ask about things that would change the brief if answered differently.
• Frame the question with the specific tradeoff or consequence so the user understands why you're asking: "This affects whether we need a migration path for existing data."
• If a yes/no framing helps, offer it: "Does X need to support Y? (yes / no / it depends — <elaboration welcome>"

After the user responds:

• Absorb the answer into your internal model
• Check if the answer resolved any other unknowns (skip those questions)
• If the answer raises a new unknown that ranks higher than remaining questions, insert it next
• If you have remaining questions: ask the next one
• If all unknowns are resolved: move directly to Step 3 — do not announce it, just transition: "Got it — let me draft the brief."

What NOT to ask

Never ask questions the implementation can answer:

• Naming ("What should I call the method?")
• Standard practice ("Should I add error handling?" — yes, always)
• Obvious defaults ("Should I write tests?" — yes, always)
• Things project-config.md already answers (language, test framework, conventions)

Never ask for information just to be thorough. If a dimension is inferable, infer it and record the assumption. Ask only when the answer genuinely changes what gets built.

If a question opens a deeper conversation

The user may give a long or complex answer that warrants a follow-up. That is fine — stay in the conversation. The question count is a guide, not a strict limit. If the user's answer to Q2 requires a follow-up, ask it before moving to Q3. Depth on one question is better than breadth across all.

Record any discussion points that affect the brief as you go — don't rely on reconstructing them at brief-writing time.

Recognising research signals in user answers

When the user responds with uncertainty about a topic that could influence the design — phrases like "I'm not sure," "I don't know," "might be worth investigating," "my feeling is," or similar hedging — treat this as a research signal, not a deferral.

Do not put research signals in "Explicit Out of Scope" or "Open Assumptions." Those sections are dead ends — the Domain Scout may never surface them as domains.

Instead, capture each research signal in the brief's ## Research Commissions section with:

• Topic — what needs investigating
• Key questions — the specific unknowns the user expressed
• Purpose — how findings would influence the design of this feature

The scoping agent does not do research — it captures the signal so the Domain Scout can commission it during domain analysis. When in doubt about whether something is a deferral or a research signal, ask the user: "Would it help to research this before we design, or is it safe to defer?"

---

Step 3 — Present the brief for confirmation

Update status.md: substage → confirming-brief. Save the draft brief text into status.md under ## Draft Brief so it survives a crash.

Display:

── Brief ───────────────────────────────────────
🔍 FEATURE BRIEF · <slug>
───────────────────────────────────────────────
SUMMARY
<2–3 sentences>

ACTORS / INPUTS / OUTPUTS & SIDE EFFECTS / BUSINESS RULES /
ERROR CASES / EXPLICIT OUT OF SCOPE / ACCEPTANCE CRITERIA /
OPEN ASSUMPTIONS / RESEARCH COMMISSIONS / PERFORMANCE EXPECTATIONS
───────────────────────────────────────────────
Does this capture it correctly? Confirm or tell me what to change.

Iterate until confirmed. Do not write brief.md until confirmed.

---

Step 4 — Write brief.md and initialise cycle-log.md

Write .feature/<slug>/brief.md (Brief File Template below).

Write .feature/<slug>/cycle-log.md:

---
feature: "<feature-slug>"
created: "<YYYY-MM-DD>"
---
# Cycle Log — <feature-slug>
This file is append-only. Each agent appends entries. Nothing is edited or deleted.
---
## <YYYY-MM-DD> — scoped
**Agent:** 🔍 Scoping Agent
**Summary:** Feature brief confirmed by user.
**Brief:** [brief.md](brief.md)
**Token estimate:** ~<N>K (loaded: project-config ~1K / wrote: brief ~2K, status ~1K, cycle-log ~1K)
---

Update status.md: stage → scoping, substage → complete. Update the Stage Completion table: Scoping row → Est. Tokens ~5K, status → complete. Remove the ## Draft Brief section from status.md now that brief.md is written. Update .feature/CLAUDE.md Active Features table.

---

Step 5 — Hand off

Display:

───────────────────────────────────────────────
🔍 SCOPING AGENT complete · <slug>
  Tokens : <TOKEN_USAGE>
───────────────────────────────────────────────
Brief written to .feature/<slug>/brief.md

Take a moment to review the brief before continuing — domain analysis builds
directly on it and fixing scope issues now is much cheaper than later.

Step 5a — Feature branch

Read branch_naming from .feature/project-config.md.

If branch_naming: none or project-config.md does not exist: skip this step.

If a branch naming convention is defined:

Expand the convention by substituting <slug> with the feature slug. Check the current git branch (git branch --show-current). If already on a branch that matches the convention, skip silently — branch already created.

Display:

── Feature branch ──────────────────────────────
  Suggested branch: <expanded branch name>

Use AskUserQuestion with options:

• "Create branch" (description: checks out the suggested branch)
• "Skip" (description: continue without creating a branch)

If "Create branch": run git checkout -b <branch-name>. Display the result. If the branch already exists locally, run git checkout <branch-name> instead. If "Skip": continue without creating a branch.

Step 5b — Continue

Use AskUserQuestion with options:

• "Continue"
• "Stop"

If "Continue": invoke /feature-domains "<slug>" as a sub-agent immediately. If "Stop":

When you're ready:
  /feature-domains "<slug>"

---

Status File Template

Written at Step 0, updated in-place by every agent throughout the pipeline.

Token tracking in Stage Completion table

Every pipeline agent updates the Stage Completion table with token data:

Est. Tokens — written at stage start. The agent's estimate of context window load for this stage, derived from the construct count and file sizes. Format: ~<N>K (e.g., ~8K, ~15K). Based on:

• Scoping: project-config (~1K) + brief writing (~2K) + status (~1K)
• Domains: brief (~2K) + KB/decisions indexes (~2K) + ADR files loaded
• Planning: brief (~2K) + domains (~3K) + ADRs + source scan
• Testing: project-config (~1K) + brief (~2K) + work-plan section (~2K)
• Implementation: work-plan section (~2K) + test files (~3K) + stubs (~1K)
• Refactor: project-config (~1K) + work-plan (~2K) + impl files + test files

Actual Tokens — written automatically by the token tracking Stop hook when a stage transition is detected. The hook reads the session transcript and logs usage to token-log.md. Format: <N>K in / <N>K out (e.g., 12K in / 8K out). Agents do not need to run any bash commands for token tracking.

---
feature: "<feature-slug>"
created: "<YYYY-MM-DD HH:MM>"
last_updated: "<YYYY-MM-DD HH:MM>"
---

# Feature Status — <feature-slug>

## Current Position
**Stage:** scoping
**Substage:** interviewing
**Last successful checkpoint:** feature directory created
**Automation mode:** not-set
**Execution strategy:** not-set
**Pipeline mode:** full

## Stage Completion

| Stage | Status | Completed | Est. Tokens | Actual Tokens | Notes |
|-------|--------|-----------|-------------|---------------|-------|
| Scoping | in-progress | — | — | — | |
| Domains | not-started | — | — | — | |
| Spec Authoring | not-started | — | — | — | if .spec/ exists |
| Planning | not-started | — | — | — | |
| Testing | not-started | — | — | — | cycle 0 |
| Hardening | not-started | — | — | — | cycle 0 |
| Implementation | not-started | — | — | — | cycle 0 |
| Refactor | not-started | — | — | — | cycle 0 |

## Domain Resolution Tracker
<!-- Populated by /feature-domains -->

| Domain | Status | ADR | KB entries | Commissioned | Resolved |
|--------|--------|-----|------------|--------------|----------|

## Work Units
<!-- Populated by /feature-plan if feature is split into units -->
<!-- work_units: none  ← set this if no split was done -->
<!-- execution_strategy: not-set -->
<!-- current_batch: 0 -->

| Unit | Name | Constructs | Depends On | Status | Cycle |
|------|------|------------|------------|--------|-------|

## TDD Cycle Tracker
<!-- Single-unit: one row per cycle -->
<!-- Multi-unit: rows labelled "Cycle N · WU-N" -->

| Cycle | Unit | Tests written | Tests passing | Refactor done | Missing tests |
|-------|------|--------------|---------------|---------------|---------------|

Pipeline mode

The Pipeline mode field controls which stages are active:

• full (default) — all stages: scoping → domains → spec authoring → planning → testing → hardening → implementation → refactor → audit. The audit runs as feature-refactor Step 4b (delegated to /audit) after the first clean refactor cycle; later refactor cycles skip it unless you invoke /audit directly.
• specification — specification-only: scoping → domains → spec authoring → complete. Used when a work definition's job is to produce artifacts (specs, ADRs, interface contracts) rather than implement behavior. Set by /work-plan.
• implementation — implementation-only: planning → testing → hardening → implementation → refactor → audit → complete. Skips scoping and domains (done during a prior specification phase). Starts from planning, consuming the artifacts produced by specification-phase runs. Set by /work-start.

When pipeline_mode is specification:

• The Stage Completion table omits Planning, Testing, Hardening, Implementation, Refactor rows
• After Spec Authoring completes, the specification phase is done. Do NOT proceed to /feature-retro or /feature-complete — those run after implementation via /work-start. Report that specs are ready and stop.

When pipeline_mode is implementation:

• The Stage Completion table omits Scoping, Domains, Spec Authoring rows
• status.md starts at planning stage (set by /work-start or /work-plan)
• The planner reads specification artifacts directly instead of running scoping/domains

---

Brief File Template

---
feature: "<description>"
slug: "<slug>"
created: "<YYYY-MM-DD>"
status: "scoped"
---

# Feature Brief — <slug>

## Summary
## Actors
## Inputs
## Outputs / Side Effects
## Business Rules
## Error Cases
## Explicit Out of Scope
## Acceptance Criteria
## Open Assumptions
## Research Commissions
<!-- Topics where user expressed uncertainty that could influence the design.
     Each entry: Topic, Key questions, Purpose (how findings affect this feature).
     Domain Scout will commission /research for each during domain analysis.
     If none: "None — no research signals identified during scoping." -->
## Performance Expectations

## Project Context
- Language: <from project-config.md>
- Framework: <from project-config.md>
- Test framework: <from project-config.md>