planflow-ai 1.3.5 → 1.4.3

package/.claude/resources/core/phase-isolation.md

@@ -7,10 +7,16 @@ When `phase_isolation: true` in `flow/.flowconfig` (default), each `/execute-pla
 
 **Core principle**: Clean context in, structured summary out.
 
+### Per-Task Verification
+
+Phase sub-agents support **per-task verification** when plan tasks include `<verify>` tags. After completing each task, the sub-agent runs the verification command and, on failure, spawns a debug sub-agent (haiku) for diagnosis and repair. See `.claude/resources/core/per-task-verification.md` for the complete verification system, debug sub-agent prompt template, JSON schemas, and configuration.
+
 ---
 
 ## Architecture
 
+### Sequential Mode (default)
+
 ```
 Coordinator (main session)
     │
@@ -35,6 +41,40 @@ Coordinator (main session)
     └─ Next phase...
 ```
 
+### Wave Mode (when `wave_execution: true`)
+
+```
+Coordinator (main session)
+    │
+    ├─ For each Wave:
+    │   │
+    │   ├─ Approve each phase sequentially in Plan Mode
+    │   │
+    │   ├─ Prepare isolated context for EACH phase in the wave
+    │   │
+    │   ├─ Spawn MULTIPLE Agent sub-agents IN PARALLEL:
+    │   │   ├─► Agent: Phase A  (model: [tier_A], prompt: phase_A_context)
+    │   │   ├─► Agent: Phase B  (model: [tier_B], prompt: phase_B_context)
+    │   │   └─► Agent: Phase C  (model: [tier_C], prompt: phase_C_context)
+    │   │
+    │   ├─ Wait for ALL sub-agents to complete
+    │   │
+    │   ├─ Collect JSON returns from all sub-agents
+    │   │
+    │   ├─ Post-wave processing (sequential, in phase order):
+    │   │   ├─ Detect file conflicts (files_modified overlap)
+    │   │   ├─ Process each phase result
+    │   │   ├─ Update plan file (mark tasks [x])
+    │   │   ├─ Accumulate files_modified list
+    │   │   ├─ Buffer patterns from all phases
+    │   │   ├─ Git commit sequentially (Phase A, then B, then C)
+    │   │   └─ Handle failures (present to user)
+    │   │
+    │   └─ Next Wave...
+    │
+    └─ Completion summary with wave execution stats
+```
+
 Planning and user approval always happen in the **main session** (full context). Only the **implementation step** is isolated.
 
 ---
@@ -68,11 +108,51 @@ Read these files before implementing:
 {Only if UI phase — include design tokens from discovery doc}
 {Otherwise omit this section entirely}
 
+## Shared Context from Sibling Phases
+
+{Only included for multi-phase waves. Omitted for single-phase waves and sequential execution.}
+
+The following contracts, decisions, and progress updates were emitted by other phases running in parallel with yours. Use these to inform your implementation:
+
+{Injected context entries as formatted text}
+
+**Instructions**:
+- Before each task, review shared context entries for relevant contracts or decisions
+- If a sibling phase defined an API endpoint you consume, match its signature exactly
+- If a sibling phase made an architectural decision, follow it for consistency
+- If you define a new API endpoint, type interface, or make an architectural decision, include it in your `context_entries` return array
+
+## Commit Instructions
+{Only include this section when `commit: true` in `.flowconfig`}
+
+### Sequential Mode (wave_execution: false)
+- After each task completes and verification passes (if applicable):
+  1. Stage changed files: `git add -A`
+  2. Create atomic commit: `git commit -m "feat(phase-N.task-M): <truncated description> — <feature>"`
+     - Use format: feat(phase-{phase_number}.task-{task_number_in_phase}): <description> — <feature>
+     - Truncate description to 50 chars (use ellipsis if truncated)
+     - Task numbers are 1-indexed within each phase
+  3. Continue to next task
+- Return `tasks_completed` array in JSON with files_created/files_modified per task
+- Do NOT create a final phase commit (coordinator will not create one either)
+
+### Wave Mode (wave_execution: true)
+- Do NOT create any commits during task implementation
+- The coordinator will commit your changes after this wave completes
+- Return `tasks_completed` array with per-task file lists (see Return Format below)
+- Coordinator will iterate tasks and commit: feat(phase-N.task-M): ... per task
+
 ## Instructions
 1. Read the plan file to understand the full feature context
 2. Implement all tasks listed above
 3. Follow the project patterns from the files listed
-4. Return a JSON summary in the exact format below — do NOT return markdown
+4. After completing each task, check if it has a `<verify>` tag indented beneath it:
+   - If yes: run the verification command inside the tag
+   - If the command exits 0: record a pass result and continue to the next task
+   - If the command exits non-zero: spawn a debug sub-agent (haiku, mode: "auto") with the error output, task context, and file content. Apply the repair actions from the diagnosis and re-run the verification command (up to `max_verify_retries` attempts, default 2). See `.claude/resources/core/per-task-verification.md` for the debug sub-agent prompt template and return schema.
+   - If max retries exceeded: record a fail result and continue to the next task (do NOT abort)
+   - If no `<verify>` tag: skip verification for that task
+5. Return a JSON summary in the exact format below — do NOT return markdown
 
 ## Return Format
 Return ONLY a JSON object (no markdown fences, no explanation):
@@ -83,6 +163,29 @@ Return ONLY a JSON object (no markdown fences, no explanation):
 
 The prompt should be **under 2K tokens** (excluding files the sub-agent reads itself via the Read tool). Keep it focused — the sub-agent will read project files as needed during implementation.
 
+### Wave Mode Context Additions
+
+When spawning sub-agents within a wave, the context template is **identical** to sequential mode with one key difference:
+
+- **`Files Modified in Previous Phases`**: Include files from ALL completed waves (Wave 1 through Wave N-1), not just the immediately preceding phase. This gives each sub-agent awareness of everything that changed before the current wave.
+
+Sub-agents within the same wave do NOT receive information about each other — no cross-phase awareness. Each sub-agent operates as if it is the only phase running.
+
+**Exception**: When shared context is available from sibling phases (via `.wave-context.jsonl`), the coordinator injects a "Shared Context from Sibling Phases" section into the context template. See below for details.
+
+### Shared Context Injection
+
+**When shared context is injected**:
+- Multi-phase waves only (2+ phases in the same wave)
+- Coordinator reads `.wave-context.jsonl` before spawning each sub-agent
+- Entries from OTHER phases in the wave are injected (not the agent's own)
+- Single-phase waves and sequential mode: section is omitted entirely
+
+**When to emit context entries**:
+- After implementing a task that creates or modifies an API endpoint, type interface, function signature, or makes an architectural decision
+- Include in the `context_entries` array of your JSON return
+- Format as ContextEntry objects (see `shared-context.md` COR-SC-2 for schema)
+
 ---
 
 ## Return Format Schema
@@ -115,6 +218,52 @@ The sub-agent must return a JSON object with this structure:
       "description": "All Zod schemas live next to their type definitions",
       "confidence": "high"
     }
+  ],
+  "task_verifications": [
+    {
+      "task": "Create user authentication middleware",
+      "verify_command": "npx tsc --noEmit src/middleware/auth.ts",
+      "status": "pass",
+      "attempts": 2,
+      "repairs_applied": [
+        "Added missing import for AuthMiddleware type"
+      ]
+    },
+    {
+      "task": "Add rate limiting to API routes",
+      "verify_command": "npx jest src/middleware/__tests__/rate-limit.test.ts --no-coverage",
+      "status": "pass",
+      "attempts": 1,
+      "repairs_applied": []
+    }
+  ],
+  "tasks_completed": [
+    {
+      "task_number": 1,
+      "task_name": "Create user authentication middleware",
+      "files_created": ["src/middleware/auth.ts"],
+      "files_modified": []
+    },
+    {
+      "task_number": 2,
+      "task_name": "Add rate limiting to API routes",
+      "files_created": ["src/middleware/rate-limit.ts"],
+      "files_modified": ["src/api/routes.ts"]
+    }
+  ],
+  "context_entries": [
+    {
+      "agent": "phase-N",
+      "type": "contract",
+      "timestamp": "ISO8601",
+      "data": { "name": "GET /users", "kind": "endpoint", "signature": "GET /users → { id, name, email }", "fields": ["id", "name", "email"] }
+    },
+    {
+      "agent": "phase-N",
+      "type": "decision",
+      "timestamp": "ISO8601",
+      "data": { "choice": "Using Redis for session caching", "reason": "Low latency requirement" }
+    }
   ]
 }
 ```
@@ -132,6 +281,9 @@ The sub-agent must return a JSON object with this structure:
 | `deviations` | string[] | No | Tasks skipped or changed from plan |
 | `errors` | string[] | No | Errors encountered (even if resolved) |
 | `patterns_captured` | object[] | No | Patterns observed during implementation |
+| `task_verifications` | object[] | No | Array of per-task verification results. Only present when at least one task had a `<verify>` tag. Each entry contains: `task` (string), `verify_command` (string), `status` (`"pass" \| "fail"`), `attempts` (number), `repairs_applied` (string[]), and optionally `last_diagnosis` (object, only when status is `"fail"`). See `.claude/resources/core/per-task-verification.md` for full schema. |
+| `tasks_completed` | object[] | No | Array of per-task file tracking for atomic commits. Each entry: `task_number` (number, 1-indexed within phase), `task_name` (string), `files_created` (string[]), `files_modified` (string[]). Present when any tasks ran. Used by coordinator for per-task commit messages. See `.claude/resources/core/atomic-commits.md` for full schema. |
+| `context_entries` | object[] | No | Array of context entries emitted by this phase for sibling phases. Each entry: `agent` (string, e.g. "phase-3"), `type` (`"contract" \| "decision" \| "progress"`), `timestamp` (ISO8601 string), `data` (object with type-specific fields). Only relevant in multi-phase waves. See `.claude/resources/core/shared-context.md` COR-SC-2 for full schema. |
 
 ### Failure Return Example
 
@@ -163,9 +315,15 @@ After receiving the sub-agent's JSON summary, the coordinator:
 1. **Update plan file**: Mark all phase tasks as `[x]`
 2. **Accumulate file list**: Merge `files_created` and `files_modified` into running list
 3. **Buffer patterns**: Append `patterns_captured` entries to `flow/resources/pending-patterns.md`
-4. **Git commit**: If `commit: true`, run `git add -A && git commit -m "Phase N: {name} — {feature}"`
+4. **Git commit (per-task)**: If `commit: true` and `tasks_completed` is present:
+   - **Sequential mode**: Sub-agent already created per-task commits — verify they exist, do NOT create phase commit
+   - **Wave mode**: Coordinator iterates `tasks_completed` in task_number order and creates per-task commits:
+     - For each task: `git add -A && git commit -m "feat(phase-N.task-M): <truncated task_name> — <feature>"`
+     - Truncate `task_name` to 50 chars if needed
+   - **Fallback**: If `tasks_completed` is absent (legacy sub-agent), fall back to single phase commit: `git add -A && git commit -m "Phase N: {name} — {feature}"`
 5. **Log decisions**: Include `decisions` in phase completion message
-6. **Proceed**: Move to next phase
+6. **Display verification results**: If `task_verifications` is present, show pass/fail counts and any repairs applied
+7. **Proceed**: Move to next phase
 
 ### On Failure (`status: "failure"`)
 
@@ -178,7 +336,49 @@ After receiving the sub-agent's JSON summary, the coordinator:
 
 1. **Present summary**: Show what was completed and what wasn't
 2. **Show deviations**: List `deviations` explaining what was skipped
-3. **Ask user**: "Phase partially complete. Continue to next phase or retry remaining tasks?"
+3. **Display verification failures**: If `task_verifications` contains failed entries, show task name, last diagnosis, and repair attempts
+4. **Ask user**: "Phase partially complete. Continue to next phase or retry remaining tasks?"
+
+---
+
+## Wave Coordinator Processing
+
+When multiple sub-agents return simultaneously from a wave, the coordinator handles them differently from sequential mode. See `.claude/resources/core/wave-execution.md` for the full wave system and `.claude/resources/skills/execute-plan-skill.md` Step 4c for the detailed processing flow.
+
+**Per-task commits in wave mode**: After collecting all JSON returns from a wave, the coordinator commits per-task (not per-phase). For each phase in phase-number order, iterate `tasks_completed` and create atomic commits: `feat(phase-N.task-M): <desc> — <feature>`. See `.claude/resources/core/atomic-commits.md` for the complete commit format and coordinator processing rules.
+
+### Collecting Multiple JSON Returns
+
+After all sub-agents in a wave complete, the coordinator collects all JSON returns before processing any of them. This allows file conflict detection before committing.
+
+### Processing Order
+
+Results are always processed **sequentially in phase number order**, regardless of which sub-agent finished first. This ensures:
+- Deterministic commit history (Phase A committed before Phase B)
+- Predictable plan file updates
+- Consistent file accumulation order
+
+### File Conflict Detection
+
+After collecting all wave results, check for `files_modified` overlap between phases:
+
+```
+For each pair of phases (A, B) in the wave:
+  overlap = A.files_modified ∩ B.files_modified
+  if overlap is not empty:
+    → File conflict detected
+```
+
+**On conflict**: Present to user with options (accept as-is, re-run conflicting phases sequentially, or stop). Never silently resolve conflicts.
+
+### Wave Failure Isolation
+
+A failed phase in a wave does NOT affect other phases in the same wave:
+- Successful phases are processed normally (plan updates, file accumulation, git commits)
+- Failed phases are presented to the user after all successful phases are processed
+- The user chooses per failed phase: retry, skip, or stop
+
+This differs from sequential mode where a failure immediately pauses execution. In wave mode, all parallel phases complete independently before any failure handling.
 
 ---
 
@@ -186,6 +386,8 @@ After receiving the sub-agent's JSON summary, the coordinator:
 
 When phases are aggregated (combined complexity ≤ 6), they run as **one sub-agent call** with all tasks from all aggregated phases. The context template lists all phases and tasks together. The return uses the highest phase number as the `phase` field.
 
+In wave mode, aggregated phases within the same wave are treated as a **single unit** — they share one wave slot, one dependency set (union of all aggregated phases' dependencies), and one sub-agent call.
+
 ---
 
 ## Configuration
@@ -210,6 +412,19 @@ Phase isolation **enhances** model routing — it doesn't replace it:
 | `model_routing: false` + `phase_isolation: true` | Sub-agent spawned with session model, clean context |
 | `model_routing: false` + `phase_isolation: false` | Inline execution, no sub-agents (original behavior) |
 
+### Interaction with Wave Execution
+
+Phase isolation is the **foundation** for wave execution — wave mode spawns multiple isolated sub-agents per wave instead of one at a time:
+
+| Setting | Behavior |
+|---------|----------|
+| `wave_execution: true` + `phase_isolation: true` | Multiple sub-agents per wave, each with clean context (optimal) |
+| `wave_execution: true` + `phase_isolation: false` | Multiple sub-agents per wave, but sharing session context (may cause interference) |
+| `wave_execution: false` + `phase_isolation: true` | One sub-agent at a time, clean context (existing behavior) |
+| `wave_execution: false` + `phase_isolation: false` | Inline execution, no sub-agents (original behavior) |
+
+**Recommendation**: `wave_execution: true` works best with `phase_isolation: true`. Without phase isolation, parallel sub-agents may interfere with each other's context.
+
 ---
 
 ## Rules
@@ -220,3 +435,21 @@ Phase isolation **enhances** model routing — it doesn't replace it:
 4. **Coordinator validates** — check status field before proceeding
 5. **Never auto-retry** — on failure, present to user and ask
 6. **Pass paths, not content** — give file paths, sub-agent reads them
+7. **Each phase gets own sub-agent** — even in wave mode, phases are never merged into one sub-agent (except for aggregated phases per complexity rules)
+8. **No cross-wave awareness** — sub-agents in the same wave know nothing about each other unless shared context entries are injected from `.wave-context.jsonl`
+9. **Deterministic processing** — wave results are always processed in phase number order
+10. **Collect before commit** — in wave mode, all JSON returns are collected before any commits happen
+11. **Verification is internal** — per-task verification loops run inside the phase sub-agent; the coordinator sees only the final `task_verifications` results
+
+---
+
+## Related Files
+
+| File | Purpose |
+|------|---------|
+| `.claude/resources/core/wave-execution.md` | Full wave-based parallel execution system |
+| `.claude/resources/core/model-routing.md` | Model tier selection per phase complexity |
+| `.claude/resources/core/discovery-sub-agents.md` | Parallel spawning pattern reference |
+| `.claude/resources/core/per-task-verification.md` | Per-task verification system, debug sub-agent, and repair loops |
+| `.claude/resources/core/shared-context.md` | Shared context schema, JSONL format, and coordinator injection rules |
+| `.claude/resources/skills/execute-plan-skill.md` | Execute-plan skill with wave integration (Steps 2b, 3, 4) |

package/.claude/resources/core/session-scratchpad.md

@@ -103,3 +103,4 @@ After compaction, the model should re-read `flow/.scratchpad.md` to restore any
 3. **Self-manage size** — promote or discard when approaching 50 lines
 4. **Promote before ending** — always scan for promotable items before session ends
 5. **Not a task list** — use `flow/tasklist.md` for tasks, scratchpad is for observations
+6. **Different from STATE.md** — `flow/STATE.md` tracks structured execution position (current skill, phase, status) for session resumability. The scratchpad tracks informal observations, insights, and open questions. They coexist and serve different purposes: STATE.md is machine-readable execution state, scratchpad is human-readable notes.

package/.claude/resources/core/shared-context.md

@@ -0,0 +1,110 @@
+# Shared Context System
+
+## COR-SC-1: Purpose
+
+Inter-agent communication during parallel wave execution via a shared JSONL context file. When multiple phases run in parallel (wave execution), each sub-agent may produce contracts, decisions, or progress updates that sibling agents need. The shared context file acts as the coordination bus.
+
+## COR-SC-2: Context Entry Types
+
+Each entry in the context file is a JSON object with these fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `agent` | string | Phase identifier (e.g., `"phase-3"`) |
+| `type` | `'contract' \| 'decision' \| 'progress'` | Entry category |
+| `timestamp` | string | ISO-8601 timestamp |
+| `data` | object | Type-specific payload (see below) |
+
+### Contract Entries (`type: 'contract'`)
+
+Declare API shapes, interfaces, function signatures, or type definitions that other phases may depend on.
+
+```json
+{
+  "agent": "phase-2",
+  "type": "contract",
+  "timestamp": "2026-03-24T10:00:00.000Z",
+  "data": {
+    "name": "UserService.getById",
+    "kind": "function",
+    "signature": "(id: string) => Promise<User>",
+    "fields": ["id", "name", "email"]
+  }
+}
+```
+
+`data` fields for contracts:
+- `name` (required): Unique identifier for the contract
+- `kind` (required): One of `endpoint`, `interface`, `function`, `type`
+- `signature` (required): The type signature or shape
+- `fields` (optional): Array of field/property names
+
+### Decision Entries (`type: 'decision'`)
+
+Record architecture or implementation choices made during execution.
+
+```json
+{
+  "agent": "phase-3",
+  "type": "decision",
+  "timestamp": "2026-03-24T10:01:00.000Z",
+  "data": {
+    "choice": "Use Redis for session storage",
+    "reason": "Faster than DB lookups for frequent reads"
+  }
+}
+```
+
+### Progress Entries (`type: 'progress'`)
+
+Report task completion status within a phase.
+
+```json
+{
+  "agent": "phase-2",
+  "type": "progress",
+  "timestamp": "2026-03-24T10:02:00.000Z",
+  "data": {
+    "task": 1,
+    "status": "complete",
+    "summary": "Created UserService with CRUD operations"
+  }
+}
+```
+
+## COR-SC-3: File Format and Lifecycle
+
+**File**: `.wave-context.jsonl` inside the `flow/` directory. Append-only JSONL — one JSON object per line.
+
+**Lifecycle**:
+
+1. **Created** — at the start of each wave, an empty `.wave-context.jsonl` is created
+2. **Injected** — before spawning sub-agents (Step 4b), existing entries are read and passed as context
+3. **Appended** — sub-agents append entries during execution via atomic write (read, append, write-to-temp, rename)
+4. **Collected** — after sub-agents return (Step 4c), all entries are read and checked for conflicts
+5. **Cleared** — between waves, the file is deleted to start fresh for the next wave
+6. **Deleted** — after plan execution completes, the file is removed
+
+## COR-SC-4: Contract Conflict Detection
+
+A conflict exists when two or more entries share the same `name` but have different `signature` or `fields` values.
+
+**Detection rules**:
+- Filter entries to `type === 'contract'`
+- Group by `data.name`
+- For each group with 2+ entries: compare `signature` and `fields` (order-insensitive for fields)
+- If any pair within a group differs: flag as conflict
+
+**Resolution**: Present both conflicting versions to the user with the originating agent names. The user decides which version to keep or how to reconcile.
+
+## COR-SC-5: Integration Points and Backward Compatibility
+
+**Integration points**:
+- **Step 4b (inject)**: Read `.wave-context.jsonl`, pass entries array to sub-agent prompt
+- **Step 4c (collect)**: Parse `context_entries` from sub-agent return JSON, append to file, run conflict detection
+
+**Backward compatibility**:
+- Single-phase waves: context injection is skipped (no sibling data to share)
+- Sequential mode (`wave_execution: false`): shared context system is not used
+- `context_entries` field is optional in sub-agent return JSON — absence means no entries to contribute
+- Existing plans without wave execution are completely unaffected