deepflow 0.1.47 → 0.1.48

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepflow",
-  "version": "0.1.47",
+  "version": "0.1.48",
   "description": "Stay in flow state - lightweight spec-driven task orchestration for Claude Code",
   "keywords": [
     "claude",

package/src/commands/df/debate.md

@@ -4,7 +4,7 @@
 
 You coordinate reasoner agents to debate a problem from multiple perspectives, then synthesize their arguments into a structured document.
 
-**NEVER:** Read source files, use Glob/Grep directly, run git, use TaskOutput, use `run_in_background`, use Explore agents
+**NEVER:** Read source files, use Glob/Grep directly, run git, use TaskOutput, use `run_in_background`, use Explore agents, use EnterPlanMode, use ExitPlanMode
 
 **ONLY:** Spawn reasoner agents (non-background), write debate file, respond conversationally
 
@@ -233,6 +233,17 @@ Open decisions:
 Next: Run /df:spec {name} to formalize into a specification
 ```
 
+### 6. CAPTURE DECISIONS
+
+Extract up to 4 candidates from consensus/resolved tensions. Ask user via `AskUserQuestion(multiSelect=True)` with options like `{ label: "[APPROACH] {decision}", description: "{rationale}" }`.
+
+For confirmed decisions, append to `.deepflow/decisions.md` (create if absent) using format:
+```
+### {YYYY-MM-DD} — debate
+- [{TAG}] {decision text} — {rationale}
+```
+Tags: [APPROACH] directional choices · [PROVISIONAL] tentative · [ASSUMPTION] unverified premises. If a new decision contradicts an existing one, note the conflict inline.
+
 ---
 
 ## Rules

package/src/commands/df/discover.md

@@ -4,7 +4,7 @@
 
 You are a Socratic questioner. Your ONLY job is to ask questions that surface hidden requirements, assumptions, and constraints.
 
-**NEVER:** Read source files, use Glob/Grep, spawn agents, create files, run git, use TaskOutput, use Task tool
+**NEVER:** Read source files, use Glob/Grep, spawn agents, create files (except `.deepflow/decisions.md`), run git, use TaskOutput, use Task tool, use EnterPlanMode, use ExitPlanMode
 
 **ONLY:** Ask questions using `AskUserQuestion` tool, respond conversationally
 
@@ -90,6 +90,22 @@ Example questions:
 - Keep your responses short between questions — don't lecture
 - Acknowledge answers briefly before asking the next question
 
+### Decision Capture
+When the user signals they are ready to move on, before presenting next-step options, extract up to 4 candidate decisions from the session (meaningful choices about approach, scope, or constraints). Present via `AskUserQuestion` with `multiSelect: true`, e.g.:
+
+```json
+{"questions": [{"question": "Which decisions should be recorded?", "header": "Decisions", "multiSelect": true,
+  "options": [{"label": "[APPROACH] Use event sourcing", "description": "Matches audit requirements"}]}]}
+```
+
+For each confirmed decision, append to `.deepflow/decisions.md` (create if missing):
+```
+### {YYYY-MM-DD} — discover
+- [APPROACH] Decision text — rationale
+```
+
+Tags: `[APPROACH]` firm choice · `[PROVISIONAL]` revisit later · `[ASSUMPTION]` unverified belief.
+
 ### When the User Wants to Move On
 When the user signals they want to advance (e.g., "I think that's enough", "let's move on", "ready for next step"):
 

package/src/commands/df/execute.md

@@ -4,9 +4,9 @@
 
 You are a coordinator. Spawn agents, wait for results, update PLAN.md. Never implement code yourself.
 
-**NEVER:** Read source files, edit code, run tests, run git commands (except status), use TaskOutput
+**NEVER:** Read source files, edit code, run tests, run git commands (except status), use TaskOutput, use EnterPlanMode, use ExitPlanMode
 
-**ONLY:** Read PLAN.md, read specs/doing-*.md, spawn background agents, read `.deepflow/results/*.yaml` on completion notifications, update PLAN.md
+**ONLY:** Read PLAN.md, read specs/doing-*.md, spawn background agents, read `.deepflow/results/*.yaml` on completion notifications, update PLAN.md, write `.deepflow/decisions.md` in the main tree
 
 ---
 
@@ -524,6 +524,22 @@ After spawning wave agents, your turn ENDS. Completion notifications drive the l
 
 **Repeat** until: all done, all blocked, or context ≥50% (checkpoint).
 
+### 11. CAPTURE DECISIONS
+
+After all tasks complete (or all blocked), extract up to 4 candidate decisions from the session (implementation patterns, deviations from plan, key assumptions made).
+
+Present via AskUserQuestion with multiSelect: true. Labels: `[TAG] decision text`. Descriptions: rationale.
+
+For each confirmed decision, append to **main tree** `.deepflow/decisions.md` (create if missing):
+```
+### {YYYY-MM-DD} — execute
+- [APPROACH] Parallel agent spawn for independent tasks — confirmed no file conflicts
+```
+
+Main tree path: use the repo root (parent of `.deepflow/worktrees/`), NOT the worktree.
+
+Max 4 candidates per prompt. Tags: [APPROACH], [PROVISIONAL], [ASSUMPTION].
+
 ## Rules
 
 | Rule | Detail |

package/src/commands/df/note.md

@@ -0,0 +1,206 @@
+# /df:note — Capture Decisions from Free Conversations
+
+## Orchestrator Role
+
+You scan prior conversation context for candidate decisions, present them for user confirmation, and persist confirmed decisions to `.deepflow/decisions.md`.
+
+**NEVER:** Spawn agents, use Task tool, use Glob/Grep on source code, run git, use TaskOutput, use EnterPlanMode, use ExitPlanMode
+
+**ONLY:** Read `.deepflow/decisions.md` (if it exists), present candidates via `AskUserQuestion`, append confirmed decisions to `.deepflow/decisions.md`
+
+---
+
+## Purpose
+
+Capture decisions that emerged during free conversations outside of deepflow commands. Surfaces candidate decisions from the current conversation, lets the user confirm or discard each, and persists confirmed ones to the shared decisions log.
+
+## Usage
+
+```
+/df:note
+```
+
+No arguments required. Operates on the current conversation context.
+
+---
+
+## Behavior
+
+### 1. EXTRACT CANDIDATES
+
+Scan the prior conversation messages for candidate decisions. A decision is any resolved choice, adopted approach, or stated assumption that affects how the work is done. Look for:
+
+- **Approaches chosen**: "we'll use X instead of Y", "let's go with X"
+- **Provisional choices**: "for now we'll use X", "assuming X until we know more"
+- **Stated assumptions**: "assuming X is true", "treating X as given"
+- **Constraints accepted**: "we won't do X", "X is out of scope"
+- **Naming or structural choices**: "we'll call it X", "X goes in the Y layer"
+
+Extract **at most 4 candidates** from the conversation. Prioritize the most consequential or recent ones.
+
+For each candidate, determine:
+- **Tag**: one of `[APPROACH]`, `[PROVISIONAL]`, or `[ASSUMPTION]`
+  - `[APPROACH]` — a deliberate design or implementation choice
+  - `[PROVISIONAL]` — works for now, expected to revisit
+  - `[ASSUMPTION]` — treating something as true without full validation
+- **Decision text**: one concise line describing the choice
+- **Rationale**: one sentence explaining why this was chosen
+
+If fewer than 2 clear candidates are found, say so briefly and exit without calling `AskUserQuestion`.
+
+### 2. CHECK FOR CONTRADICTIONS
+
+Read `.deepflow/decisions.md` if it exists. For each candidate, check whether it contradicts a prior entry in the file.
+
+If a contradiction is found:
+- Keep the prior entry — never delete or modify it
+- Amend the candidate's rationale to reference the prior decision: `was "X", now "Y" because Z`
+
+### 3. PRESENT VIA AskUserQuestion
+
+Present candidates as a multi-select question with at most 4 options (tool limit).
+
+```json
+{
+  "questions": [
+    {
+      "question": "These decisions were detected in your conversation. Which should be saved to .deepflow/decisions.md?",
+      "header": "Save notes?",
+      "multiSelect": true,
+      "options": [
+        {
+          "label": "[APPROACH] <decision text>",
+          "description": "<rationale>"
+        },
+        {
+          "label": "[PROVISIONAL] <decision text>",
+          "description": "<rationale>"
+        }
+      ]
+    }
+  ]
+}
+```
+
+Each option's `label` is the tag + decision text. Each `description` is the rationale (one sentence).
+
+### 4. APPEND CONFIRMED DECISIONS
+
+For each option the user selects:
+
+1. If `.deepflow/decisions.md` does not exist, create it with a blank header:
+   ```
+   # Decisions
+   ```
+
+2. Append a new dated section using today's date in `YYYY-MM-DD` format and source `note`:
+
+   ```markdown
+   ### 2026-02-22 — note
+   - [APPROACH] Use event sourcing over CRUD — append-only log matches audit requirements
+   - [PROVISIONAL] Batch size = 50 — works for 4-game dataset, revisit at scale
+   ```
+
+3. If multiple decisions are confirmed in one invocation, group them under a single dated section.
+
+4. Never modify or delete any prior entries.
+
+### 5. CONFIRM
+
+After writing, report to the user:
+
+```
+Saved N decision(s) to .deepflow/decisions.md
+```
+
+If the user selected nothing, respond:
+
+```
+No decisions saved.
+```
+
+---
+
+## Decision Format
+
+```
+### YYYY-MM-DD — note
+- [TAG] Decision text — rationale
+```
+
+**Tags:**
+- `[APPROACH]` — deliberate design or implementation choice
+- `[PROVISIONAL]` — works for now, will revisit at scale or with more information
+- `[ASSUMPTION]` — treating something as true without full confirmation
+
+**Contradiction handling:** Never delete prior entries. When a new decision contradicts an older one, include a reference in the rationale: `was "X", now "Y" because Z`.
+
+---
+
+## Rules
+
+- **Maximum 4 candidates** per invocation (tool limit for AskUserQuestion options)
+- **multiSelect: true** — user can confirm any subset, including all or none
+- **Never invent decisions** — only extract what was genuinely discussed and resolved in the conversation
+- **Never modify prior entries** in `.deepflow/decisions.md`
+- **Create the file if absent** — first use initializes it with `# Decisions` header
+- **Source is always `note`** — this distinguishes from decisions captured by other df commands
+- **Date is today's date** — use the current date in `YYYY-MM-DD` format
+- **One AskUserQuestion call** — present all candidates in a single call, not sequentially
+
+---
+
+## Example
+
+```
+USER: /df:note
+
+CLAUDE: Let me scan our conversation for candidate decisions.
+
+[Reads .deepflow/decisions.md — finds prior entry:
+  "### 2026-02-10 — spec
+  - [APPROACH] Use PostgreSQL for primary storage — team already knows it"]
+
+[Extracts from conversation:
+  1. [APPROACH] Use Redis for session state — avoids DB round-trips on hot path
+  2. [PROVISIONAL] Skip auth for internal APIs — only 2 internal services for now
+  3. [ASSUMPTION] Peak load is 500 req/s — based on current traffic, unvalidated
+]
+
+[No contradictions found with prior entries]
+
+[Uses AskUserQuestion]
+{
+  "questions": [
+    {
+      "question": "These decisions were detected in your conversation. Which should be saved to .deepflow/decisions.md?",
+      "header": "Save notes?",
+      "multiSelect": true,
+      "options": [
+        {
+          "label": "[APPROACH] Use Redis for session state",
+          "description": "Avoids DB round-trips on hot path"
+        },
+        {
+          "label": "[PROVISIONAL] Skip auth for internal APIs",
+          "description": "Only 2 internal services for now, revisit when we open to more consumers"
+        },
+        {
+          "label": "[ASSUMPTION] Peak load is 500 req/s",
+          "description": "Based on current traffic patterns, not load-tested"
+        }
+      ]
+    }
+  ]
+}
+
+USER: [Selects: Use Redis for session state, Peak load is 500 req/s]
+
+CLAUDE: [Appends to .deepflow/decisions.md:]
+
+### 2026-02-22 — note
+- [APPROACH] Use Redis for session state — avoids DB round-trips on hot path
+- [ASSUMPTION] Peak load is 500 req/s — based on current traffic patterns, not load-tested
+
+Saved 2 decision(s) to .deepflow/decisions.md
+```

package/src/commands/df/plan.md

@@ -3,6 +3,8 @@
 ## Purpose
 Compare specs against codebase and past experiments. Generate prioritized tasks.
 
+**NEVER:** use EnterPlanMode, use ExitPlanMode — this command IS the planning phase; native plan mode conflicts with it
+
 ## Usage
 ```
 /df:plan                 # Plan all new specs
@@ -220,6 +222,17 @@ Append tasks grouped by `### doing-{spec-name}`. Include spec gaps and validatio
 
 `✓ Plan generated — {n} specs, {n} tasks. Run /df:execute`
 
+### 11. CAPTURE DECISIONS
+
+Extract up to 4 candidate decisions (approaches chosen, spike strategies, prioritization rationale). Present via AskUserQuestion with `multiSelect: true`. Each option: `label: "[TAG] <decision>"`, `description: "<rationale>"`. Tags: `[APPROACH]`, `[PROVISIONAL]`, `[ASSUMPTION]`.
+
+Append confirmed decisions to `.deepflow/decisions.md` (create if missing):
+```
+### {YYYY-MM-DD} — plan
+- [TAG] Decision text — rationale summary
+```
+If a decision contradicts a prior entry, add: `(supersedes: <prior text>)`
+
 ## Rules
 - **Never use TaskOutput** — Returns full transcripts that explode context
 - **Never use run_in_background for Explore agents** — Causes late notifications that pollute output

package/src/commands/df/resume.md

@@ -0,0 +1,130 @@
+# /df:resume — Session Continuity Briefing
+
+## 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.
+
+**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
+
+**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
+```
+
+## Behavior
+
+### 1. GATHER SOURCES
+
+Read these sources in parallel (all reads, no writes):
+
+| Source | Command/Path | Purpose |
+|--------|-------------|---------|
+| Git timeline | `git log --oneline -20` | What changed and when |
+| Decisions | `.deepflow/decisions.md` | Current [APPROACH], [PROVISIONAL], [ASSUMPTION] entries |
+| Plan | `PLAN.md` | Task status (checked vs unchecked) |
+| Spec headers | `specs/doing-*.md` (first 20 lines each) | What features are in-flight |
+| Experiments | `.deepflow/experiments/` (file listing + names) | 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**
+
+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.
+
+If `.deepflow/decisions.md` does not exist or is empty: state "No decisions recorded yet."
+
+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.
+
+**## Next Steps**
+
+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.
+
+---
+
+### 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.
+
+---
+
+## Rules
+
+- **NEVER write any file** — not decisions.md, not PLAN.md, not any new file
+- **NEVER use AskUserQuestion** — this command is read-only, no interaction
+- **NEVER spawn agents** — read directly using Bash (git log) and Read tool
+- **NEVER use TaskOutput** — returns full transcripts that explode context
+- **NEVER use EnterPlanMode or ExitPlanMode**
+- Read sources in a single pass — do not loop or re-read
+- If a source file is missing, skip it and note it only if relevant
+- 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)
+```

package/src/commands/df/spec.md

@@ -4,7 +4,7 @@
 
 You coordinate agents and ask questions. You never search code directly.
 
-**NEVER:** Read source files, use Glob/Grep directly, run git, use TaskOutput
+**NEVER:** Read source files, use Glob/Grep directly, run git, use TaskOutput, use EnterPlanMode, use ExitPlanMode
 
 **ONLY:** Spawn agents (non-background), ask user questions, write spec file
 
@@ -176,6 +176,18 @@ Acceptance criteria: {count}
 Next: Run /df:plan to generate tasks
 ```
 
+### 6. CAPTURE DECISIONS
+
+Extract up to 4 candidate decisions (requirements chosen, constraints accepted). Use `AskUserQuestion` with `multiSelect: true`:
+- `label`: `[APPROACH|PROVISIONAL|ASSUMPTION] <decision>`
+- `description`: rationale
+
+Append each confirmed selection to `.deepflow/decisions.md` (create if absent):
+```
+### {YYYY-MM-DD} — spec
+- [TAG] <decision> — <rationale>
+```
+
 ## Rules
 - **Orchestrator never searches** — Spawn agents for all codebase exploration
 - Do NOT generate spec if critical gaps remain

package/src/commands/df/verify.md

@@ -3,6 +3,8 @@
 ## Purpose
 Check that implemented code satisfies spec requirements and acceptance criteria.
 
+**NEVER:** use EnterPlanMode, use ExitPlanMode
+
 ## Usage
 ```
 /df:verify                  # Verify all done-* specs
@@ -325,3 +327,17 @@ rm -f .deepflow/checkpoint.json
 
 Workflow complete! Ready for next feature: /df:spec <name>
 ```
+
+### 4. CAPTURE DECISIONS (success path only)
+
+Extract up to 4 candidate decisions (quality findings, patterns validated, lessons learned). Present via AskUserQuestion with `multiSelect: true`; tags: `[APPROACH]`, `[PROVISIONAL]`, `[ASSUMPTION]`.
+
+```
+AskUserQuestion(question: "Which decisions to record?", multiSelect: true,
+  options: [{ label: "[APPROACH] <decision>", description: "<rationale>" }, ...])
+```
+
+For each confirmed decision, append to `.deepflow/decisions.md` (create if missing):
+`### {YYYY-MM-DD} — verify` / `- [TAG] {decision text} — {rationale}`
+
+Skip if user confirms none or declines.