planflow-ai 1.4.1 → 1.4.3

package/.claude/resources/skills/execute-plan-skill.md

@@ -317,34 +317,84 @@ After ALL phases in the wave are approved, proceed to parallel spawning.
 Launch all approved wave phases simultaneously as independent Agent sub-agents:
 
 1. **Prepare context for each phase**: Use the phase-isolation context template (see `.claude/resources/core/phase-isolation.md`). Key addition for wave execution: the `Files Modified in Previous Phases` section includes files from ALL completed waves (1 through N-1), not just the immediately preceding phase.
-2. **No cross-phase awareness**: Sub-agents within the same wave do NOT know about each other. They receive no information about sibling phases.
+2. **Inject shared context from sibling phases** (multi-phase waves only):
+   - Skip this step for single-phase waves (no siblings to share with)
+   - Read `flow/.wave-context.jsonl` (create it if it doesn't exist yet — see wave lifecycle below)
+   - Filter entries: include only entries from OTHER phases in the current wave (not the agent's own phase). Also include entries from all previous waves.
+   - If there are matching entries, add an inline section in the sub-agent prompt after the phase spec:
+     ```
+     ## Shared Context from Sibling Phases
+
+     The following context entries were published by other phases. Use them to align on shared contracts, types, and architectural decisions.
+
+     - [phase N] (type: contract) name: UserAPI, signature: GET /users → { id, name, email }
+     - [phase N] (type: type_definition) name: UserRecord, fields: { id: string, name: string }
+     - [phase N] (type: decision) summary: Using Redis for session caching
+     ```
+   - If no matching entries exist, omit the section entirely
 3. **Spawn all in parallel**: Launch all wave phases simultaneously using Agent sub-agents with their respective model tiers.
 4. **Wait for all to complete**: All sub-agents must return before post-wave processing.
 
+**Wave context lifecycle**:
+- **Create** `flow/.wave-context.jsonl` at wave start (before first spawn in Step 4b), if it does not already exist. Start with an empty file.
+- Context entries **accumulate across all waves** — the file is NOT cleared between waves. Later waves benefit from contracts and decisions published by earlier waves.
+- **Delete** `flow/.wave-context.jsonl` after execution completes (Step 7, after build/test verification).
+
 ##### 4c. Wave Coordinator — Post-Wave Processing
 
 After all sub-agents in the wave return, process results **sequentially in phase number order**:
 
 1. **Collect JSON returns**: Gather the structured JSON summary from each sub-agent
 2. **Validate JSON**: Parse each return, check for required fields (status, phase, summary, files_created, files_modified)
-3. **Detect file conflicts**: Check for `files_modified` overlap between phases in this wave:
+3. **Collect context entries**: For each phase's JSON return, check for a `context_entries` array:
+   - If `context_entries` is present and non-empty, append each entry to `flow/.wave-context.jsonl` (one JSON object per line)
+   - If `context_entries` is absent or empty, treat as empty array — no entries to append
+   - Entry format: `{"phase": N, "type": "contract|type_definition|decision", "name": "...", "signature": "...", "fields": "...", "summary": "..."}`
+   - These entries become available to phases in subsequent waves via Step 4b
+4. **Detect file conflicts**: Check for `files_modified` overlap between phases in this wave:
    - For each pair of phases (A, B) in the wave: compute `overlap = A.files_modified ∩ B.files_modified`
    - If overlap is not empty → file conflict detected
-4. **Handle file conflicts** (if any):
+5. **Handle file conflicts** (if any):
    - Present the conflicting files and which phases modified them
    - Offer options:
      - **(1) Accept as-is**: Last writer wins (the phase with the higher number committed last)
      - **(2) Re-run conflicting phases sequentially**: Re-execute only the conflicting phases in order
      - **(3) Stop execution**: Halt for manual resolution
    - File conflicts do NOT affect non-conflicting phases — their results are preserved
-5. **Process each phase** (in phase number order):
+6. **Detect contract conflicts**: For each pair of phases (A, B) in the wave, check their `context_entries` for contract entries with the same `name` but different `signature` or `fields`:
+   - Compare all entries where `type` is `contract` or `type_definition`
+   - If same `name` but different `signature`/`fields` → contract conflict detected
+   - Present conflicts and offer resolution (see Contract Conflicts below)
+   - Contract conflicts do NOT affect non-conflicting phases — their results are preserved
+7. **Process each phase** (in phase number order):
    - Check `status` field: `success` → continue; `failure` → present errors, ask retry/skip/stop; `partial` → present deviations, ask user
    - Update plan file (mark tasks `[x]`)
    - Accumulate `files_created` and `files_modified` into running list
    - Buffer `patterns_captured` entries to `flow/resources/pending-patterns.md`
    - Git commit if enabled (sequential, one commit **per task** in phase/task order — see `.claude/resources/core/atomic-commits.md`). For each phase (in phase number order), iterate `tasks_completed` and commit: `git add -A && git commit -m "feat(phase-N.task-M): <desc> — <feature>"`
    - Log `decisions` in phase completion message
-6. **Report wave completion**: Present summary of all phases in this wave, including task verification stats:
+
+##### Contract Conflicts
+
+If contract conflicts are detected (same API name, different signatures):
+
+1. Present both versions:
+   ```
+   Warning: Contract conflict detected:
+   **API**: GET /users
+
+   Phase 1 signature: GET /users → { id: string, name: string }
+   Phase 3 signature: GET /users → { id: string, name: string, email: string }
+
+   Options:
+   1. Use Phase 1's version
+   2. Use Phase 3's version
+   3. Stop execution for manual resolution
+   ```
+2. Apply the chosen version: update the corresponding entry in `flow/.wave-context.jsonl` so subsequent waves see the resolved contract
+3. Contract conflicts do NOT affect non-conflicting phases — only the conflicting contract entries need resolution
+
+8. **Report wave completion**: Present summary of all phases in this wave, including task verification stats:
    - For each phase in the wave that returned `task_verifications`, include pass/fail counts and repairs applied
    - Wave completion report template:
      ```
@@ -572,18 +622,20 @@ This allows users to quickly jump to the PR from notifications without needing t
 
 After ALL phases are complete (including Tests phase):
 
-1. **Run final verification**:
+1. **Clean up shared context**: If `flow/.wave-context.jsonl` exists, delete it. This file is ephemeral and should not persist after execution completes.
+
+2. **Run final verification**:
 
 ```bash
 npm run build && npm run test
 ```
 
-2. **Handle failures**:
+3. **Handle failures**:
    - If build fails: Fix the issue, re-run verification
    - If tests fail: Fix the issue, re-run verification
    - Only proceed after everything passes
 
-3. **Present summary** of completed work, including model routing and wave execution info if enabled:
+4. **Present summary** of completed work, including model routing and wave execution info if enabled:
 
 **Sequential mode summary**:
 
@@ -616,6 +668,7 @@ npm run build && npm run test
 - Waves executed: 4
 - Parallel phases: 2 (in Wave 1)
 - File conflicts: 0
+- Contract conflicts: 0
 - Failed phases: 0
 - Estimated speedup: ~20%
 
@@ -625,9 +678,9 @@ npm run build && npm run test
 **PR**: https://github.com/owner/repo/pull/123
 ```
 
-4. **List all key changes** made
+5. **List all key changes** made
 
-5. **Ask if the plan should be archived**:
+6. **Ask if the plan should be archived**:
 
 ```bash
 mv flow/plans/plan_feature_name_v1.md flow/archive/
@@ -672,13 +725,17 @@ Wave 1: Phase 1 + Phase 2 (parallel, no dependencies)
 |   +-- Get user approval
 |
 +-- EXECUTION PHASE (parallel):
-|   +-- Spawn Agent: Phase 1 (model: haiku)  ──┐
-|   +-- Spawn Agent: Phase 2 (model: haiku)  ──┤ (running simultaneously)
-|   +-- Wait for all to return               ──┘
+|   +-- Create flow/.wave-context.jsonl (if not exists)
+|   +-- Read shared context from sibling phases (if multi-phase wave)
+|   +-- Spawn Agent: Phase 1 (model: haiku, + shared context)  ──┐
+|   +-- Spawn Agent: Phase 2 (model: haiku, + shared context)  ──┤ (running simultaneously)
+|   +-- Wait for all to return                                  ──┘
 |
 +-- POST-WAVE PROCESSING (sequential):
 |   +-- Collect JSON returns
+|   +-- Collect context_entries → append to .wave-context.jsonl
 |   +-- Check for file conflicts
+|   +-- Check for contract conflicts (same name, different signature)
 |   +-- Process Phase 1 result → update plan → git commit per task
 |   +-- Process Phase 2 result → update plan → git commit per task
 |   +-- Report wave completion
@@ -782,6 +839,9 @@ If the user wants to stop execution:
 | **Deterministic commits**    | Git commits happen per-task in phase/task order after wave completes: `feat(phase-N.task-M): <desc> — <feature>` |
 | **Failures are isolated**    | One failed phase does not cancel sibling phases in the same wave |
 | **File conflicts presented** | Never silently resolve file conflicts, always ask the user  |
+| **Shared context injected**  | Multi-phase waves inject sibling context entries; single-phase waves skip |
+| **Contract conflicts detected** | Same API name with different signatures triggers user resolution |
+| **Wave context is ephemeral** | `.wave-context.jsonl` accumulates across waves, deleted after execution completes |
 
 ---
 
@@ -796,4 +856,5 @@ If the user wants to stop execution:
 | `.claude/resources/core/per-task-verification.md` | Per-task verification system and debug sub-agents |
 | `.claude/resources/tools/plan-mode-tool.md` | Plan mode switching instructions |
 | `flow/plans/`                               | Input plan documents             |
+| `flow/.wave-context.jsonl`                  | Ephemeral shared context between wave phases (deleted after execution) |
 | `flow/archive/`                             | Completed plans destination      |

package/README.md

@@ -78,11 +78,13 @@ Installs for Claude Code, Cursor, OpenClaw, and Codex CLI simultaneously.
 | `/review-code` | Review local uncommitted changes (adaptive depth + multi-agent) |
 | `/review-pr` | Review a Pull Request (adaptive depth + multi-agent) |
 | `/write-tests` | Generate tests for coverage target |
+| `/brainstorm` | Free-form idea exploration with interactive questions |
 | `/flow` | Configure plan-flow settings (autopilot, git control, runtime options) |
 | `/note` | Capture meeting notes, ideas, brainstorms |
 | `/learn` | Extract reusable patterns or learn a topic step-by-step |
-| `/pattern-validate` | Scan and index global brain patterns |
 | `/heartbeat` | Manage scheduled automated tasks |
+| `/resume-work` | Resume interrupted work from STATE.md |
+| `state-query` | Query brain index for relevant documentation (CLI: `planflow-ai state-query "topic"`) |
 
 ## Workflow
 
@@ -90,10 +92,11 @@ Installs for Claude Code, Cursor, OpenClaw, and Codex CLI simultaneously.
 
 ```
 1. /setup           -> Index project patterns (run once)
-2. /discovery-plan  -> Gather requirements for a feature
-3. /create-plan     -> Create structured implementation plan
-4. /execute-plan    -> Execute the plan phase by phase
-5. /review-code     -> Review changes before committing
+2. /brainstorm      -> (Optional) Explore and crystallize a vague idea
+3. /discovery-plan  -> Gather requirements for a feature
+4. /create-plan     -> Create structured implementation plan
+5. /execute-plan    -> Execute the plan phase by phase
+6. /review-code     -> Review changes before committing
 ```
 
 ### Autopilot Mode
@@ -113,10 +116,85 @@ You: "Add dark mode support"
 
 Autopilot classifies every input and only triggers the full flow for feature requests (complexity 3+). Questions, trivial tasks, and slash commands are handled normally.
 
-**Mandatory checkpoints** — even in autopilot, the flow always pauses for:
+**Mandatory checkpoints** -- even in autopilot, the flow always pauses for:
 - **Discovery Q&A**: You answer requirements questions
 - **Plan approval**: You review and approve the plan before execution
 
+## Core Features
+
+### Wave-Based Parallel Execution
+
+Independent phases run in parallel within waves, with dependency-aware grouping:
+
+```
+Wave 1 (parallel): Phase 1: Types, Phase 2: Utilities
+Wave 2 (sequential): Phase 3: API Integration (depends on 1+2)
+Wave 3 (parallel): Phase 4: Config, Phase 5: UI Components
+Wave 4 (sequential): Phase 6: Tests (always last)
+```
+
+Plans support a `**Dependencies**:` field per phase. Topological sort assigns wave numbers automatically. Phases without dependencies run in Wave 1. Tests always run in their own final wave.
+
+Enable with `/flow wave_execution=true` (default: on).
+
+### Multi-Agent Coordination
+
+During wave execution, parallel phases share a context file (`flow/.wave-context.jsonl`) that enables real-time coordination. Agents share:
+
+- **API contracts** -- endpoint shapes, type interfaces, function signatures
+- **Decisions** -- architecture choices, library selections
+- **Progress** -- task completion status
+
+Before each task, sub-agents receive shared context from sibling phases -- preventing broken contracts and duplicate decisions. Post-wave processing includes contract conflict detection: same API name with different signatures triggers user intervention.
+
+### Brain Index (SQLite)
+
+All markdown files are indexed with SQLite FTS5 + vector embeddings for hybrid search. Query with `planflow-ai state-query "topic"` to find relevant documentation instantly. Replaces the previous reference code system — 10-50x faster context loading with semantic matching.
+
+### Phase Isolation
+
+Each phase runs in an isolated sub-agent with a clean context window. The sub-agent receives only the context it needs (phase spec, files modified so far, patterns, design context) and returns a structured JSON summary. This eliminates context rot -- phase 7 has the same quality as phase 1.
+
+Disable with `/flow phase_isolation=false`.
+
+### Per-Task Verification
+
+Plan tasks can include `<verify>` tags with shell commands. After completing each task, the sub-agent runs verification automatically. On failure, a debug sub-agent (haiku) diagnoses the root cause and the implementation agent applies repairs (up to `max_verify_retries` attempts, default: 2).
+
+### Atomic Commits Per Task
+
+When `commit=true`, each individual task within a phase gets its own git commit (not per phase). Format: `feat(phase-N.task-M): description`. Enables `git bisect`, independent reverts, and clearer git history.
+
+### Auto-PR Creation
+
+When `pr=true`, after execution completes (build+test pass), plan-flow automatically creates a feature branch and opens a PR via `gh pr create` with an auto-generated title and summary.
+
+### Model Routing
+
+By default, all phases use the most capable model from the active provider. Enable cost-based routing with `/flow model_routing=true` to auto-select models per phase based on complexity:
+
+| Complexity | Tier | Model |
+|-----------|------|-------|
+| 0-3 | Fast | haiku |
+| 4-5 | Standard | sonnet |
+| 6-10 | Powerful | opus |
+
+### Design Awareness
+
+Discovery asks whether features involve UI work. If confirmed, captures structured design tokens (colors, typography, spacing) into a Design Context section. During execution, tokens are auto-injected into UI phase prompts. Includes 6 built-in design personalities.
+
+### Pattern Capture
+
+During skill execution, the LLM silently buffers coding patterns and anti-patterns. At the end, captured patterns are presented for approval and written to `.claude/rules/core/allowed-patterns.md` or `forbidden-patterns.md`.
+
+### Session Resumability (STATE.md)
+
+`flow/STATE.md` tracks decisions, blockers, current position, and active phase. If a session is interrupted, `/resume-work` rebuilds full context from stored files and continues from where you left off.
+
+### Deterministic State Script
+
+Config and state parsing runs as a Node.js script (`planflow-ai state`) that returns structured JSON -- deterministic logic in code, not prompts. Ensures reliable flowconfig reading, phase calculations, and file existence checks.
+
 ## Flow Configuration (`/flow`)
 
 The `/flow` command is the central configuration hub. All settings use `key=value` syntax and persist in `flow/.flowconfig` (YAML).
@@ -124,58 +202,43 @@ The `/flow` command is the central configuration hub. All settings use `key=valu
 | Setting | Values | Default | Description |
 |---------|--------|---------|-------------|
 | `autopilot` | `true/false` | `false` | Enable/disable autopilot mode |
-| `commit` | `true/false` | `false` | Auto-commit after each completed phase |
+| `commit` | `true/false` | `false` | Auto-commit after each completed task |
 | `push` | `true/false` | `false` | Auto-push after all phases + build/test pass |
+| `pr` | `true/false` | `false` | Auto-create PR after execution |
 | `branch` | any string | current branch | Target branch for git operations |
+| `wave_execution` | `true/false` | `true` | Dependency-aware parallel phase execution |
+| `phase_isolation` | `true/false` | `true` | Isolated sub-agent per phase |
+| `model_routing` | `true/false` | `false` | Cost-based model selection per phase |
+| `max_verify_retries` | `1-5` | `2` | Max repair attempts per task verification |
 
 ### Examples
 
 ```bash
 /flow autopilot=true                    # Enable autopilot
-/flow commit=true push=true             # Enable git control (works without autopilot)
-/flow autopilot=true commit=true        # Enable both
-/flow branch=development                # Set target branch
+/flow commit=true push=true pr=true     # Full git control with auto-PR
+/flow wave_execution=false              # Disable parallel execution
+/flow phase_isolation=false             # Inline execution (for debugging)
+/flow model_routing=true                # Enable cost-based model routing
 /flow -status                           # Show current config
 /flow -reset                            # Reset everything
 
 # Shorthand: text without key=value enables autopilot and starts flow
 /flow add dark mode support             # autopilot=true + start discovery
-/flow commit=true add user auth         # autopilot=true + git + start discovery
 ```
 
 ### Git Control
 
-When `commit=true`, plan-flow auto-commits after each completed execution phase:
-
-```
-Phase 1: Setup types → git commit "Phase 1: Setup types — user-auth"
-Phase 2: API endpoints → git commit "Phase 2: API endpoints — user-auth"
-Phase 3: Tests → git commit "Phase 3: Tests — user-auth"
-Build + Test pass → git commit "Complete: user-auth — all phases done"
-                  → git push origin development (if push=true)
-```
-
-Git control works independently of autopilot — you can use `commit=true` with manual `/execute-plan` runs.
-
-## Project Tasklist
-
-Each project has a `flow/tasklist.md` that tracks work items across sessions. On session start, active tasks are summarized and you can pick one to work on.
-
-Every command automatically updates the tasklist:
-- On start: adds the task to **In Progress**
-- On complete: moves it to **Done** with the date
-- Next step: adds the logical follow-up to **To Do**
-
-### Scheduled Tasks
-
-Tasks can be scheduled for later execution by linking them to the heartbeat daemon:
+When `commit=true`, plan-flow auto-commits after each completed task:
 
 ```
-/flow add to tasklist: implement feature X and execute in 1 hour
+feat(phase-1.task-1): Create user types -- user-auth
+feat(phase-1.task-2): Add validation schemas -- user-auth
+feat(phase-2.task-1): Create login endpoint -- user-auth
+...
+Build + Test pass -> git push origin development (if push=true)
+                  -> gh pr create (if pr=true)
 ```
 
-This creates a tasklist entry linked to a heartbeat one-shot task via `[[]]` references. Both files cross-reference each other for Obsidian navigation.
-
 ## Heartbeat (Scheduled Automation)
 
 The heartbeat daemon is a background process that executes scheduled tasks defined in `flow/heartbeat.md`.
@@ -201,13 +264,17 @@ npx planflow-ai heartbeat status   # Show daemon status
 
 The daemon **auto-starts** during `planflow-ai init` if `flow/heartbeat.md` exists.
 
+### Notifications
+
+The daemon sends OS desktop notifications (via node-notifier) for task completions, failures, and blocked tasks. Events are also logged to `flow/log.md` and `flow/.heartbeat-events.jsonl`.
+
 ### One-Shot Tasks
 
-Tasks with `in {N} hours/minutes` schedules run once and auto-disable after execution. These are used for scheduled tasklist items.
+Tasks with `in {N} hours/minutes` schedules run once and auto-disable after execution.
 
 ### Retry on Active Session
 
-If a task fails because a Claude Code session is already active, the daemon retries up to 5 times at 60-second intervals instead of failing permanently.
+If a task fails because a Claude Code session is already active, the daemon retries up to 5 times at 60-second intervals.
 
 ## Code Review
 
@@ -215,25 +282,19 @@ If a task fails because a Claude Code session is already active, the daemon retr
 
 ### Adaptive Depth
 
-Review depth scales automatically based on changeset size:
-
 | Lines Changed | Mode | Behavior |
 |--------------|------|----------|
 | < 50 | Lightweight | Quick-scan for security, logic bugs, and breaking changes only |
-| 50–500 | Standard | Full review with pattern matching and similar implementation search |
+| 50-500 | Standard | Full review with pattern matching and similar implementation search |
 | 500+ | Deep | Multi-pass review with file categorization, executive summary, and multi-agent analysis |
 
 ### Verification Pass
 
-Every finding goes through a second-pass verification that re-reads surrounding context and asks structured questions to classify findings as Confirmed, Likely, or Dismissed. False positives are filtered before output.
-
-### Severity Re-Ranking
-
-Findings are sorted by impact (Critical > Major > Minor > Suggestion), related findings across files are grouped, and an executive summary is added when there are 5+ findings.
+Every finding goes through a second-pass verification that re-reads surrounding context to classify findings as Confirmed, Likely, or Dismissed. False positives are filtered before output.
 
 ### Multi-Agent Parallel Review
 
-In Deep mode (500+ lines), the review is split into 4 specialized subagents running in parallel:
+In Deep mode (500+ lines), 4 specialized subagents run in parallel:
 
 | Agent | Focus | Model |
 |-------|-------|-------|
@@ -242,8 +303,6 @@ In Deep mode (500+ lines), the review is split into 4 specialized subagents runn
 | Performance | N+1 queries, memory leaks, blocking I/O | sonnet |
 | Pattern Compliance | Forbidden/allowed patterns, naming consistency | haiku |
 
-The coordinator merges results, deduplicates overlapping findings, then runs verification and re-ranking.
-
 ## Complexity Scoring
 
 Every plan phase has a complexity score (0-10):
@@ -256,64 +315,63 @@ Every plan phase has a complexity score (0-10):
 | 7-8 | High | Complex, multiple considerations |
 | 9-10 | Very High | Significant complexity/risk |
 
-## Directory Structure
-
-All artifacts are stored in `flow/`:
-
-```
-flow/
-├── archive/           # Completed/abandoned plans
-├── brain/             # Automatic knowledge capture (Obsidian-compatible)
-│   ├── index.md       # Brain index (loaded at session start)
-│   ├── features/      # Feature history and context
-│   └── errors/        # Reusable error patterns
-├── contracts/         # Integration contracts
-├── discovery/         # Discovery documents
-├── plans/             # Active implementation plans
-├── references/        # Reference materials
-├── resources/         # Valuable artifacts captured during skill execution
-├── reviewed-code/     # Code review documents
-├── reviewed-pr/       # PR review documents
-├── tasklist.md        # Project task list (updated in real-time during execution)
-├── memory.md          # Persistent artifact tracker (completed work)
-├── heartbeat.md       # Scheduled task definitions for the heartbeat daemon
-├── log.md             # Heartbeat event log
-├── ledger.md          # Persistent project learning journal
-├── .flowconfig        # Central config file (autopilot, git control, settings)
-└── .gitcontrol        # Git control settings (backward compat)
-```
+## Discovery Sub-Agents
 
-## Session Start Behaviors
+During `/discovery-plan`, three parallel haiku sub-agents explore the codebase simultaneously (similar features, API/data patterns, schema/types). Returns condensed findings merged into a Codebase Analysis section.
 
-When a session starts, plan-flow automatically loads context from your project:
+## Project Brain and Knowledge Graph
 
-- **Tasklist** (`flow/tasklist.md`) — Presents active tasks and lets you pick one to work on
-- **Memory** (`flow/memory.md`) — Loads the last 7 days of completed work so context is never lost
-- **Brain** (`flow/brain/index.md`) — Internalizes active features and recent error patterns
-- **Ledger** (`flow/ledger.md`) — Internalizes project-specific lessons learned
-- **Autopilot** (`flow/.flowconfig`) — If `autopilot: true`, activates automatic workflow orchestration
+All projects are linked into a central Obsidian vault at `~/plan-flow/brain/`. Each `planflow-ai init` creates a project directory in the vault with symlinks for brain subdirectories.
 
-## Intelligent Learn Skill
+Features:
+- `flow/brain/features/` -- Feature history and context with `[[wiki-links]]`
+- `flow/brain/errors/` -- Reusable error patterns
+- `flow/ledger.md` -- Persistent project learning journal
+- `flow/memory.md` -- Last 7 days of completed work
+- `flow/.scratchpad.md` -- Ephemeral per-session notes
 
-The `/learn` skill supports step-by-step teaching. When you run `/learn about <topic>`, it creates a structured curriculum stored as a brain `.md` file. Each step requires your confirmation before progressing, and confirmed steps become learned patterns.
+Open `~/plan-flow/brain/` as an Obsidian vault to browse all projects in one graph.
 
-Commands also recommend `/learn` automatically when:
-- New dependencies are added during execution
-- Non-trivial errors are resolved (3+ attempts)
-- The user corrects the approach
-- A new technology or pattern is introduced
+## Directory Structure
 
-## Central Obsidian Vault
+```
+flow/
+├── archive/              # Completed/abandoned plans
+├── brain/                # Automatic knowledge capture (Obsidian-compatible)
+│   ├── index.md          # Brain index
+│   ├── features/         # Feature history and context
+│   └── errors/           # Reusable error patterns
+├── brainstorms/          # Brainstorm exploration documents
+├── contracts/            # Integration contracts
+├── discovery/            # Discovery documents
+├── plans/                # Active implementation plans
+├── references/           # Reference materials
+├── resources/            # Valuable artifacts from skill execution
+├── reviewed-code/        # Code review documents
+├── reviewed-pr/          # PR review documents
+├── tasklist.md           # Project task list
+├── memory.md             # Persistent artifact tracker
+├── heartbeat.md          # Scheduled task definitions
+├── log.md                # Heartbeat event log
+├── ledger.md             # Project learning journal
+├── STATE.md              # Execution state for session resumability
+├── .flowconfig           # Central config file
+├── .wave-context.jsonl   # Shared context for multi-agent coordination
+├── .heartbeat-events.jsonl  # Notification event stream
+├── .heartbeat-state.json    # Session read position tracking
+└── .gitcontrol        # Git control settings (backward compat)
+```
 
-All projects are linked into a central Obsidian vault at `~/plan-flow/brain/`. Each `planflow-ai init` creates a project directory in the vault with symlinks for brain subdirectories and the tasklist. A global tasklist at `~/plan-flow/brain/tasklist.md` aggregates task counts across all projects.
+### Brain Index Database
 
-Open `~/plan-flow/brain/` as an Obsidian vault to browse all projects in one graph.
+The SQLite brain index (`.brain.sqlite`) lives at the **project root** (not inside `flow/`). It's gitignored and rebuildable from markdown files.
+```
 
 ## Requirements
 
 - Node.js 18+
-- `git` - For version control
-- `gh` - GitHub CLI (for PR reviews)
+- `git` -- For version control
+- `gh` -- GitHub CLI (for PR reviews and auto-PR)
 
 ## Development
 

package/dist/cli/commands/brain.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Brain CLI command
+ *
+ * Provides semantic search and indexing over the shared planflow-brain knowledge base.
+ * The brain directory defaults to ~/plan-flow/brain but can be overridden with --brain-dir.
+ *
+ * Subcommands:
+ *   search <query>   Hybrid semantic + keyword search
+ *   ingest <file>    Index a markdown file into the brain
+ *   rebuild          Rebuild entire index from markdown files on disk
+ *   stats            Show brain statistics
+ *   sync             Incremental sync (re-index only changed files)
+ */
+export interface BrainOptions {
+    brainDir?: string;
+    limit?: number;
+    type?: string;
+}
+export declare function runBrain(action: string, args: string[], options: BrainOptions): Promise<void>;
+//# sourceMappingURL=brain.d.ts.map

package/dist/cli/commands/brain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/brain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AASH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wBAAsB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAgHnG"}