deepflow 0.1.87 → 0.1.89

package/src/commands/df/report.md

@@ -6,225 +6,70 @@ allowed-tools: [Read, Write, Bash]
 
 # /df:report — Session Cost Report
 
+> **DEPRECATED:** Use `/df:dashboard` instead to view deepflow metrics and status.
+
 ## Orchestrator Role
 
-You aggregate token usage data from multiple sources and produce a structured report.
+Aggregate token usage data and produce a structured report.
 
-**NEVER:** Spawn agents, use Task tool, use AskUserQuestion, run git, use EnterPlanMode, use ExitPlanMode
+**NEVER:** Spawn agents, use Task tool, use AskUserQuestion, run git, EnterPlanMode, ExitPlanMode
 
 **ONLY:** Read data files, compute aggregates, write `.deepflow/report.json` and `.deepflow/report.md`
 
----
-
-## Purpose
-
-Produce a cost and context report for the current session. Reads token-history.jsonl, quota-history.jsonl, per-task YAML result files, and auto-memory.yaml. Outputs a machine-readable JSON report and a human-readable Markdown summary.
-
-## Usage
-
-```
-/df:report
-```
-
-No arguments. Operates on `.deepflow/` data written by the statusline hook, execute command, and quota logger.
-
----
-
 ## Behavior
 
 ### 1. LOAD DATA SOURCES
 
-Read each source gracefully — if a file does not exist, treat it as empty and continue.
-
-**a. Token history** — `.deepflow/token-history.jsonl`
-
-Parse each newline-delimited JSON object. Each line has fields:
-`timestamp`, `input_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens`, `context_window_size`, `used_percentage`, `model`, `session_id`
-
-Shell injection (use output directly):
-- `` !`cat .deepflow/token-history.jsonl 2>/dev/null || echo ''` ``
-
-Aggregate across all lines:
-- `total_input_tokens` = sum of `input_tokens`
-- `total_cache_creation` = sum of `cache_creation_input_tokens`
-- `total_cache_read` = sum of `cache_read_input_tokens`
-- `cache_hit_ratio` = `total_cache_read / (total_input_tokens + total_cache_creation + total_cache_read)` — clamp to `[0, 1]`, default `0` if denominator is 0
-- `peak_context_percentage` = max of `used_percentage` across all lines
-- `model` = value from the most recent line (last line)
-
-**b. Quota history** — `~/.claude/quota-history.jsonl`
-
-Parse the last 5 lines. Each line has `timestamp`, `event`, and API response payload fields.
-
-Shell injection:
-- `` !`tail -5 ~/.claude/quota-history.jsonl 2>/dev/null || echo ''` ``
-
-Extract the most recent quota entry. If the file does not exist or is empty, set `quota.available = false`.
-
-**c. Per-task results** — `.deepflow/results/T*.yaml`
-
-Shell injection:
-- `` !`ls .deepflow/results/T*.yaml 2>/dev/null || echo ''` ``
-
-For each YAML file found, read and extract the `tokens` block:
-```yaml
-tokens:
-  start_percentage: N
-  end_percentage: N
-  delta_percentage: N
-  input_tokens: N
-  cache_creation_input_tokens: N
-  cache_read_input_tokens: N
-```
-
-Derive `task_id` from the filename (e.g., `T3.yaml` → `"T3"`).
-
-If a file has no `tokens` block, skip it without error.
-
-**d. Session metadata** — `.deepflow/auto-memory.yaml`
-
-Shell injection:
-- `` !`cat .deepflow/auto-memory.yaml 2>/dev/null || echo ''` ``
+Read each source gracefully — missing files yield zero/empty values, never error out.
 
-Read for context (session_id, start time, etc.) if available. Optional — do not fail if absent.
+| Source | Path | Shell injection | Key fields |
+|--------|------|-----------------|------------|
+| Token history | `.deepflow/token-history.jsonl` | `` !`cat .deepflow/token-history.jsonl 2>/dev/null \|\| echo ''` `` | `timestamp`, `input_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens`, `used_percentage`, `model`, `session_id` |
+| Quota history | `~/.claude/quota-history.jsonl` | `` !`tail -5 ~/.claude/quota-history.jsonl 2>/dev/null \|\| echo ''` `` | `timestamp`, `event`, API payload |
+| Task results | `.deepflow/results/T*.yaml` | `` !`ls .deepflow/results/T*.yaml 2>/dev/null \|\| echo ''` `` | `tokens` block: `start_percentage`, `end_percentage`, `delta_percentage`, `input_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |
+| Session metadata | `.deepflow/auto-memory.yaml` | `` !`cat .deepflow/auto-memory.yaml 2>/dev/null \|\| echo ''` `` | session_id, start time (optional) |
 
 ### 2. COMPUTE AGGREGATES
 
-Using data from step 1:
-
 ```
-total_tokens_all = total_input_tokens + total_cache_creation + total_cache_read
-cache_hit_ratio  = total_cache_read / total_tokens_all   (0 if total_tokens_all == 0)
+total_input_tokens  = sum(input_tokens)
+total_cache_creation = sum(cache_creation_input_tokens)
+total_cache_read    = sum(cache_read_input_tokens)
+total_tokens_all    = total_input_tokens + total_cache_creation + total_cache_read
+cache_hit_ratio     = total_cache_read / total_tokens_all  (0 if denominator=0, clamp [0,1], round 4 decimals)
+peak_context_percentage = max(used_percentage)
+model               = most recent line's model
 ```
 
-Round `cache_hit_ratio` to 4 decimal places.
-
 ### 3. WRITE `.deepflow/report.json`
 
-Generate an ISO 8601 timestamp for the `generated` field (current time).
-
-Schema:
-```json
-{
-  "version": 1,
-  "generated": "2026-03-17T12:00:00Z",
-  "session_summary": {
-    "total_input_tokens": 0,
-    "total_cache_creation": 0,
-    "total_cache_read": 0,
-    "cache_hit_ratio": 0.0,
-    "peak_context_percentage": 0,
-    "model": "claude-sonnet-4-5"
-  },
-  "tasks": [
-    {
-      "task_id": "T1",
-      "start_percentage": 0,
-      "end_percentage": 0,
-      "delta_percentage": 0,
-      "input_tokens": 0,
-      "cache_creation": 0,
-      "cache_read": 0
-    }
-  ],
-  "quota": {
-    "available": false
-  }
-}
-```
+Structure: `{ version: 1, generated: ISO-8601-UTC, session_summary: {total_input_tokens, total_cache_creation, total_cache_read, cache_hit_ratio, peak_context_percentage, model}, tasks: [{task_id, start_percentage, end_percentage, delta_percentage, input_tokens, cache_creation, cache_read}], quota: {available: bool, ...API fields if available} }`
 
-Rules:
-- `version` is always `1`
-- `tasks` is an empty array `[]` if no task result files were found or none had a `tokens` block
-- `quota.available` is `false` if quota data is missing or could not be read; `true` with additional fields from the API payload if data was found
-- All token fields are integers >= 0
-- `cache_hit_ratio` is a float in `[0, 1]`
+Rules: `version` always 1. `tasks` = `[]` if no results found. `quota.available` = false if missing. All token fields integers >= 0. `cache_hit_ratio` float in [0,1].
 
 ### 4. WRITE `.deepflow/report.md`
 
-Generate a human-readable Markdown report. Use actual values from step 2.
-
-Required section headings (exact text):
-
-```markdown
-## Session Summary
-
-| Metric | Value |
-|--------|-------|
-| Model | {model} |
-| Total Input Tokens | {total_input_tokens} |
-| Cache Creation Tokens | {total_cache_creation} |
-| Cache Read Tokens | {total_cache_read} |
-| Cache Hit Ratio | {cache_hit_ratio} ({percentage}%) |
-| Peak Context Usage | {peak_context_percentage}% |
-
-## Per-Task Costs
+Required sections with exact headings:
 
-| Task | Start % | End % | Delta % | Input Tokens | Cache Creation | Cache Read |
-|------|---------|-------|---------|-------------|----------------|------------|
-| T1   | 0       | 5     | 5       | 12000        | 3000           | 1000       |
+**## Session Summary** — Table: Model, Total Input Tokens, Cache Creation Tokens, Cache Read Tokens, Cache Hit Ratio (with %), Peak Context Usage %.
 
-_(No task data available)_ if tasks array is empty
+**## Per-Task Costs** — Table: Task, Start %, End %, Delta %, Input Tokens, Cache Creation, Cache Read. Show `_(No task data available)_` if empty.
 
-## Quota Impact
-
-{quota data table or "Not available (non-macOS or no token)"}
-```
-
-For **Quota Impact**:
-- If `quota.available = true`: render a table with the quota fields from the API payload
-- If `quota.available = false`: write exactly `Not available (non-macOS or no token)`
+**## Quota Impact** — Quota fields table if `quota.available=true`, else exactly: `Not available (non-macOS or no token)`.
 
 ### 5. CONFIRM
 
-Report to the user:
-
 ```
 Report generated:
   .deepflow/report.json  — machine-readable (version=1)
   .deepflow/report.md    — human-readable summary
 ```
 
-If any data source was missing, list them as a note:
-```
-Note: Missing data sources: token-history.jsonl, quota-history.jsonl
-```
-
----
+List missing data sources as a note if any were absent.
 
 ## Rules
 
-- **Graceful degradation** — any missing file yields zero/empty values for that source; never error out
-- **No hallucination** — only write values derived from actual file contents; use 0 for missing numeric fields
-- **Idempotent** — re-running overwrites `.deepflow/report.json` and `.deepflow/report.md` with fresh data
-- **cache_hit_ratio always in [0,1]** — clamp if arithmetic produces out-of-range value
-- **ISO 8601 timestamps** — `generated` field uses UTC
-
----
-
-## Example
-
-```
-USER: /df:report
-
-CLAUDE: [Reads .deepflow/token-history.jsonl — 42 lines found]
-[Reads ~/.claude/quota-history.jsonl — last 5 lines found]
-[Reads .deepflow/results/T1.yaml, T2.yaml, T3.yaml — tokens blocks extracted]
-[Reads .deepflow/auto-memory.yaml — session metadata found]
-
-[Computes:
-  total_input_tokens = 185000
-  total_cache_creation = 45000
-  total_cache_read = 320000
-  cache_hit_ratio = 320000 / (185000 + 45000 + 320000) = 0.5818
-  peak_context_percentage = 73
-  model = claude-sonnet-4-5
-]
-
-[Writes .deepflow/report.json]
-[Writes .deepflow/report.md]
-
-Report generated:
-  .deepflow/report.json  — machine-readable (version=1)
-  .deepflow/report.md    — human-readable summary
-```
+- Graceful degradation — missing files yield zero/empty, never error
+- No hallucination — only values from actual file contents; 0 for missing fields
+- Idempotent — re-running overwrites both files with fresh data
+- ISO 8601 UTC timestamps for `generated` field

package/src/commands/df/resume.md

@@ -8,123 +8,40 @@ allowed-tools: [Read, Grep, Glob, Bash]
 
 ## Orchestrator Role
 
-You are a context synthesizer. Your ONLY job is to read project state from multiple sources and produce a concise, structured briefing so developers can resume work after a break.
+Read project state from multiple sources, produce a concise briefing for resuming work. Pure read-only.
 
-**NEVER:** Write files, create files, modify files, append to files, run git with write operations, use AskUserQuestion, spawn agents, use TaskOutput, use EnterPlanMode, use ExitPlanMode
+**NEVER:** Write/create/modify files, run git write ops, use AskUserQuestion, spawn agents, use TaskOutput, EnterPlanMode, ExitPlanMode
 
-**ONLY:** Read files (Bash read-only git commands, Read tool, Glob, Grep), write briefing to stdout
-
----
-
-## Purpose
-
-Synthesize project state into a 200-500 word briefing covering what happened, what decisions are live, and what to do next. Pure read-only — writes nothing.
-
-## Usage
-
-```
-/df:resume
-```
+**ONLY:** Read files (Bash read-only git commands, Read, Glob, Grep), write briefing to stdout
 
 ## Behavior
 
-### 1. GATHER SOURCES
-
-Read these sources in parallel (all reads, no writes):
+### 1. GATHER SOURCES (parallel, all reads)
 
 | Source | Command/Path | Purpose |
 |--------|-------------|---------|
-| Git timeline | `!`git log --oneline -20`` | What changed and when |
-| Decisions | `!`cat .deepflow/decisions.md 2>/dev/null \|\| echo 'NOT_FOUND'`` | Current [APPROACH], [PROVISIONAL], [ASSUMPTION] entries |
-| Plan | `!`cat PLAN.md 2>/dev/null \|\| echo 'NOT_FOUND'`` | Task status (checked vs unchecked) |
-| Spec headers | `!`head -20 specs/doing-*.md 2>/dev/null \|\| echo 'NOT_FOUND'`` | What features are in-flight |
-| Experiments | `!`ls .deepflow/experiments/ 2>/dev/null \|\| echo 'NOT_FOUND'`` | Validated and failed approaches |
-
-**Token budget:** Read only what's needed — ~2500 tokens total across all sources.
-
-If a source does not exist, skip it silently (do not error or warn).
-
-### 2. SYNTHESIZE BRIEFING
-
-Produce a 200-500 word briefing with exactly three sections:
-
----
-
-**## Timeline**
-
-Summarize what happened and when, derived from `git log --oneline -20` and spec/PLAN.md state. Describe the arc of work: what was completed, what is in-flight, notable milestones. Reference dates or commit messages where informative. Aim for 3-6 sentences.
-
-**## Live Decisions**
+| Git timeline | `` !`git log --oneline -20` `` | What changed and when |
+| Decisions | `` !`cat .deepflow/decisions.md 2>/dev/null \|\| echo 'NOT_FOUND'` `` | Live [APPROACH], [PROVISIONAL], [ASSUMPTION] entries |
+| Plan | `` !`cat PLAN.md 2>/dev/null \|\| echo 'NOT_FOUND'` `` | Task status (checked vs unchecked) |
+| Spec headers | `` !`head -20 specs/doing-*.md 2>/dev/null \|\| echo 'NOT_FOUND'` `` | In-flight features |
+| Experiments | `` !`ls .deepflow/experiments/ 2>/dev/null \|\| echo 'NOT_FOUND'` `` | Validated/failed approaches |
 
-List all current `[APPROACH]`, `[PROVISIONAL]`, and `[ASSUMPTION]` entries from `.deepflow/decisions.md`. Present each as a bullet with its tag, the decision text, and a brief rationale if available.
+Token budget: ~2500 tokens input. Skip missing sources silently.
 
-If `.deepflow/decisions.md` does not exist or is empty: state "No decisions recorded yet."
+### 2. SYNTHESIZE BRIEFING (200-500 words, 3 sections)
 
-Do not filter or editorialize — report all live decision entries as found. If a decision has been contradicted (a newer entry supersedes it), show only the newest entry for that topic.
+**## Timeline** — 3-6 sentences: arc of work from git log + spec/PLAN state. What completed, in-flight, notable milestones. Reference dates/commits where informative.
 
-**## Next Steps**
+**## Live Decisions** — All `[APPROACH]`, `[PROVISIONAL]`, `[ASSUMPTION]` from `.deepflow/decisions.md` as bullets with tag + text + rationale. Show newest entry per topic if contradictions exist. State "No decisions recorded yet." if absent/empty.
 
-Derive next steps from `PLAN.md` task status:
-- List unchecked tasks (`- [ ]`) that are not blocked
-- Note blocked tasks and what they are blocked by
-- If no PLAN.md exists: suggest running `/df:plan` to generate tasks
-
-Prioritize: unblocked tasks first, then blocked tasks with their blockers, then any tasks with no explicit status.
-
----
+**## Next Steps** — From PLAN.md: unblocked `- [ ]` tasks first, then blocked tasks with blockers. If no PLAN.md: suggest `/df:plan`.
 
 ### 3. OUTPUT
 
-Print the briefing directly to stdout. No file writes. No file creation.
-
-Format:
-
-```
-## Timeline
-[3-6 sentences on what happened]
-
-## Live Decisions
-- [APPROACH] ...
-- [PROVISIONAL] ...
-- [ASSUMPTION] ...
-
-## Next Steps
-- T1: ... (ready)
-- T2: ... (blocked by T1)
-```
-
-Word count target: 200-500 words. Do not pad. Do not truncate important information to hit limits.
-
----
+Print briefing to stdout. No file writes.
 
 ## Rules
 
-- Read sources in a single pass — do not loop or re-read
-- Contradicted decisions: show newest entry per topic only
-- Token budget: stay within ~2500 tokens of input to produce ~500 words of output
-
-## Example
-
-```
-USER: /df:resume
-
-CLAUDE:
-
-## Timeline
-Work began on the session-continuity feature on 2026-02-20, with the spec
-formalized after a discover and debate phase. The plan was generated with
-5 tasks across two areas: decision capture in existing commands and two new
-commands (note, resume). Tasks T1-T3 are complete (decisions.md format,
-discover capture, plan capture). T4 (execute capture) and T5 (resume command)
-remain in progress.
-
-## Live Decisions
-- [APPROACH] Store decisions in .deepflow/decisions.md as append-only markdown — chosen over database to keep diffs readable and avoid new dependencies
-- [PROVISIONAL] Max 4 candidates per AskUserQuestion call — matches tool limit, revisit if UX feels too chunked
-- [ASSUMPTION] Worktree execute writes to main tree .deepflow/ path — valid as long as main tree is always the parent
-
-## Next Steps
-- T4: Add decision capture to /df:execute (ready — unblocked)
-- T5: Create /df:resume command (ready — unblocked)
-- T6: Add decision capture to /df:verify (blocked by T4)
-```
+- Read sources in a single pass — no re-reads
+- Contradicted decisions: show newest per topic only
+- Token budget: ~2500 input tokens to produce ~500 words output

package/src/commands/df/spec.md

@@ -7,98 +7,61 @@ description: Transform conversation context into a structured specification file
 
 ## Orchestrator Role
 
-You coordinate agents and ask questions. You never search code directly.
+Coordinate agents and ask questions. Never search code directly.
 
-**NEVER:** Read source files, use Glob/Grep directly, run git, use TaskOutput, use EnterPlanMode, use ExitPlanMode
+**NEVER:** Read source files, use Glob/Grep directly, run git, use TaskOutput, EnterPlanMode, ExitPlanMode
 
 **ONLY:** Spawn agents (non-background), ask user questions, write spec file
 
----
-
-## Purpose
-Transform conversation context into a structured specification file.
+## Agents
 
-## Usage
-```
-/df:spec <name>
-```
+| Agent | subagent_type | model | Count | Purpose |
+|-------|---------------|-------|-------|---------|
+| Explore | `Explore` | `haiku` | 2-3 (<20 files), 5-8 (20-100), 10-15 (100+) | Find related code, patterns |
+| Reasoner | `reasoner` | `opus` | 1 | Synthesize into requirements |
 
-## Skills & Agents
-- Skill: `gap-discovery` — Proactive requirement gap identification
+Skill: `gap-discovery` — Proactive requirement gap identification
 
-**Use Task tool to spawn agents:**
-| Agent | subagent_type | model | Purpose |
-|-------|---------------|-------|---------|
-| Context | `Explore` | `haiku` | Codebase context gathering |
-| Synthesizer | `reasoner` | `opus` | Synthesize findings into requirements |
+**IMPORTANT**: Always use `Task` tool with explicit `subagent_type` and `model` parameters.
 
 ## Behavior
 
 ### 1. GATHER CODEBASE CONTEXT
 
-**Check for debate file first:** If `specs/.debate-{name}.md` exists, read it using the Read tool. Pass its content (especially the Synthesis section) to the reasoner agent in step 3 as additional context.
-
-Follow `templates/explore-agent.md` for spawn rules, prompt structure, and scope restrictions.
-
-Find: related implementations, code patterns/conventions, integration points, existing TODOs.
-
-| Codebase Size | Agents |
-|---------------|--------|
-| <20 files | 2-3 |
-| 20-100 | 5-8 |
-| 100+ | 10-15 |
-
-### 2. GAP CHECK
-Use the `gap-discovery` skill to analyze conversation + agent findings.
-
-**Required clarity:**
-- [ ] Core objective clear
-- [ ] Scope boundaries defined (what's in/out)
-- [ ] Key constraints identified
-- [ ] Success criteria stated
-
-**If gaps exist**, use the `AskUserQuestion` tool to ask structured questions:
-
-```json
-{
-  "questions": [
-    {
-      "question": "Clear, specific question ending with ?",
-      "header": "Short label",
-      "multiSelect": false,
-      "options": [
-        {"label": "Option 1", "description": "What this means"},
-        {"label": "Option 2", "description": "What this means"}
-      ]
-    }
-  ]
-}
-```
+Check for `specs/.debate-{name}.md` first — if exists, read it and pass Synthesis section to reasoner in step 3.
 
-Max 4 questions per tool call. Wait for answers before proceeding.
+Follow `templates/explore-agent.md` for spawn rules, prompt structure, scope restrictions. Find: related implementations, code patterns/conventions, integration points, existing TODOs.
 
-### 3. SYNTHESIZE FINDINGS
+### 2. GAP CHECK (layer-aware)
 
-**Use Task tool to spawn reasoner agent:**
-```
-Task tool parameters:
-- subagent_type: "reasoner"
-- model: "opus"
-```
+Use `gap-discovery` skill. Gaps determine spec layer — they do NOT block spec creation.
+
+**Clarity checklist (maps to layers):**
+- Core objective clear → L0
+- Requirements enumerated → L1
+- Testable ACs stated → L2
+- Scope boundaries + constraints + technical context → L3
+
+**L0-L1 gaps** (no objective/requirements): Use `AskUserQuestion` tool (max 4 questions per call, wait for answers). See `gap-discovery` skill for format.
+
+**L2-L3 gaps**: Do NOT block. Write spec at current layer — spikes will discover what's missing.
+
+### 3. SYNTHESIZE FINDINGS
 
-The reasoner will:
-- Analyze codebase context from Explore agents
-- Identify constraints from existing architecture
-- Suggest requirements based on patterns found
-- Flag potential conflicts with existing code
-- Verify every REQ-N has at least one corresponding Acceptance Criterion; flag any uncovered requirements
-- Identify and flag vague or untestable requirements before finalizing (e.g., "should be fast" without a metric)
+Spawn reasoner agent (`subagent_type: "reasoner"`, `model: "opus"`). The reasoner:
+- Analyzes codebase context from Explore agents
+- Identifies constraints from existing architecture
+- Suggests requirements based on patterns found
+- Flags conflicts with existing code
+- Verifies every REQ-N has a corresponding AC; flags uncovered requirements
+- Flags vague/untestable requirements (e.g., "should be fast" without a metric)
 
 ### 4. GENERATE SPEC
 
-Once gaps covered and context gathered, run `validateSpec` on the generated content **before** writing the file.
-- **Hard failure:** Do NOT write the file. Show errors to the user with actionable fix suggestions and re-synthesize.
-- **Advisory warnings:** Write the file but display the warnings to the user after confirmation.
+Run `validateSpec` on generated content **before** writing.
+- **Hard failure:** Do NOT write. Show errors with fix suggestions, re-synthesize.
+- **Advisory warnings:** Write file, display warnings after confirmation.
+- **Layer < 2:** Expected when info incomplete. Write the spec.
 
 Create `specs/{name}.md`:
 
@@ -111,19 +74,15 @@ Create `specs/{name}.md`:
 ## Requirements
 - REQ-1: [Requirement]
 - REQ-2: [Requirement]
-- REQ-3: [Requirement]
 
 ## Constraints
-- [Constraint 1]
-- [Constraint 2]
+- [Constraint]
 
 ## Out of Scope
 - [Explicitly excluded item]
 
 ## Acceptance Criteria
-- [ ] [Testable criterion 1]
-- [ ] [Testable criterion 2]
-- [ ] [Testable criterion 3]
+- [ ] [Testable criterion]
 
 ## Technical Notes
 [Implementation hints from codebase analysis — patterns, integration points, constraints discovered by agents]
@@ -131,9 +90,8 @@ Create `specs/{name}.md`:
 
 ### 5. CONFIRM
 
-After writing:
 ```
-✓ Created specs/{name}.md
+✓ Created specs/{name}.md — Layer {N} ({label})
 
 Requirements: {count}
 Acceptance criteria: {count}
@@ -141,70 +99,16 @@ Acceptance criteria: {count}
 Next: Run /df:plan to generate tasks
 ```
 
-## Rules
-- **Orchestrator never searches** — Spawn agents for all codebase exploration
-- Do NOT generate spec if critical gaps remain
-- Ask maximum 4 questions per tool call (not overwhelming)
-- Requirements must be testable
-- Acceptance criteria must be verifiable
-- Include agent-discovered context in Technical Notes
-- Keep specs concise (<100 lines)
-
-## Agent Scaling
-
-| Agent | subagent_type | model | Base | Purpose |
-|-------|---------------|-------|------|---------|
-| Explore | `Explore` | `haiku` | 3-5 | Find related code, patterns |
-| Reasoner | `reasoner` | `opus` | 1 | Synthesize into requirements |
-
-**IMPORTANT**: Always use the `Task` tool with explicit `subagent_type` and `model` parameters.
+**Layer labels:** L0="problem defined", L1="requirements known", L2="verifiable", L3="fully constrained"
 
-## Example
+If layer < 2: `ℹ Spec is at L{N} — /df:plan will generate spikes to discover what's missing. To deepen: add {missing sections for next layer}.`
 
-```
-USER: I want to add image upload
-
-CLAUDE: [Spawns 3 Explore agents in parallel]
-- "Find existing file handling patterns"
-- "Find API endpoint conventions"
-- "Find storage service implementations"
-
-[Agents return: Express multer middleware, REST conventions, no cloud storage yet]
-
-CLAUDE: [Uses AskUserQuestion tool]
-{
-  "questions": [
-    {
-      "question": "What file types should be supported?",
-      "header": "File types",
-      "multiSelect": true,
-      "options": [
-        {"label": "JPG/PNG only", "description": "Standard formats"},
-        {"label": "Include WebP", "description": "Modern compression"}
-      ]
-    },
-    {
-      "question": "Where should files be stored?",
-      "header": "Storage",
-      "multiSelect": false,
-      "options": [
-        {"label": "S3 (Recommended)", "description": "Scalable cloud storage"},
-        {"label": "Local filesystem", "description": "Simple, matches current setup"}
-      ]
-    }
-  ]
-}
-
-USER: [Selects: JPG/PNG + WebP, S3]
-
-CLAUDE: [Spawns reasoner agent]
-- Synthesize: multer + S3 + existing API patterns
-
-CLAUDE: ✓ Created specs/image-upload.md
-
-Requirements: 4
-Acceptance criteria: 5
-Technical notes: Express/multer pattern, REST conventions from existing API
+## Rules
 
-Next: Run /df:plan to generate tasks
-```
+- Orchestrator never searches — spawn agents for all codebase exploration
+- Do NOT generate spec if L0 gaps remain (no clear objective)
+- L2+ gaps do NOT block spec creation
+- Max 4 questions per AskUserQuestion call
+- Requirements must be testable; ACs must be verifiable (when present)
+- Include agent-discovered context in Technical Notes
+- Keep specs concise (<100 lines)