planflow-ai 1.3.5 → 1.4.3

package/.claude/commands/setup.md

@@ -648,59 +648,15 @@ flow/
    - Component structure
    - Error handling approach
 
----
+## Context Loading
+
+This command uses the **brain index** for context retrieval. Before executing, query the project brain for relevant documentation:
+
+**Queries**:
+- `planflow-ai state-query "project setup" --scope resources`
+- `planflow-ai state-query "pattern generation" --scope resources`
 
-## Context Optimization
-
-This command uses hierarchical context loading to reduce context consumption. Instead of loading full files, load indexes first and expand specific sections on-demand.
-
-### Recommended Loading Order
-
-1. **Always load first**: This command file (`commands/setup.md`)
-2. **Load indexes**: Load `_index.md` files for relevant folders
-3. **Expand on-demand**: Use reference codes to load specific sections when needed
-
-### Index Files for Setup
-
-| Index | When to Load |
-|-------|--------------|
-| `resources/skills/_index.md` | To understand setup workflow |
-| `resources/tools/_index.md` | For interactive questions tool |
-| `resources/core/_index.md` | For pattern references |
-| `resources/languages/_index.md` | For language-specific patterns |
-
-### Reference Codes for Setup
-
-| Code | Description | When to Expand |
-|------|-------------|----------------|
-| SKL-SETUP-1 | Purpose and critical approach | Understanding setup goals |
-| SKL-SETUP-2 | Scan project structure | Scanning files and directories |
-| SKL-SETUP-3 | Deep dependency analysis | Analyzing package dependencies |
-| SKL-SETUP-4 | Deep code analysis | Sampling files and extracting patterns |
-| SKL-SETUP-7 | Ask confirming questions | Presenting questions via Plan mode |
-| SKL-SETUP-8 | Generate pattern files | Creating framework/library pattern files |
-| SKL-SETUP-9 | Update core pattern files | Updating allowed/forbidden patterns |
-| SKL-SETUP-11 | Create analysis document | Generating project analysis doc |
-| SKL-SETUP-12 | Index documentation | Indexing project docs with reference codes |
-| SKL-SETUP-13 | Create flow folder | Setting up flow/ directory structure |
-| SKL-SETUP-14 | Present summary | Final setup summary output |
-| TLS-IQ-1 | Interactive questions overview | Before asking questions |
-| TLS-IQ-2 | Switch to Plan mode | Starting question session |
-| TLS-IQ-3 | Ask questions format | Asking confirmation questions |
-| COR-AP-1 | Allowed patterns structure | Updating allowed patterns |
-| COR-FP-1 | Forbidden patterns structure | Updating forbidden patterns |
-| LNG-TS-1 | TypeScript patterns | If TS project detected |
-| LNG-PY-1 | Python patterns | If Python project detected |
-
-### Expansion Instructions
-
-When executing this command:
-
-1. **Start with indexes**: Read `resources/skills/_index.md` and `resources/tools/_index.md`
-2. **Expand for detection phase**: Load minimal context during code analysis
-3. **Expand for questions**: Load TLS-IQ-* before asking confirmation questions
-4. **Expand for generation**: Load relevant language patterns when generating files
-5. **Don't expand everything**: Only load patterns relevant to detected stack
+The brain returns ranked chunks from indexed markdown files. Use the top results to inform execution.
 
 ---
 
@@ -708,10 +664,6 @@ When executing this command:
 
 | Resource                       | Purpose                                |
 | ------------------------------ | -------------------------------------- |
-| `resources/skills/_index.md`      | Index of skills with reference codes   |
-| `resources/tools/_index.md`       | Index of tools with reference codes    |
-| `resources/core/_index.md`        | Index of core rules with reference codes |
-| `resources/languages/_index.md`   | Index of language patterns with reference codes |
 | `setup-skill.md`              | Detailed execution logic               |
 | `interactive-questions-tool.md` | Questions UI for confirmations       |
 | `allowed-patterns.md`         | Core allowed patterns                  |

package/.claude/commands/write-tests.md

@@ -199,47 +199,16 @@ All metrics (Lines, Branches, Functions, Statements) meet the target.
 3. Invoke write-tests skill
 4. Present final coverage summary
 
----
-
-## Context Optimization
-
-This command uses hierarchical context loading to reduce context consumption. Instead of loading full files, load indexes first and expand specific sections on-demand.
-
-### Recommended Loading Order
-
-1. **Always load first**: This command file (`commands/write-tests.md`)
-2. **Load indexes**: Load `_index.md` files for relevant folders
-3. **Expand on-demand**: Use reference codes to load specific sections when needed
-
-### Index Files for Writing Tests
-
-| Index | When to Load |
-|-------|--------------|
-| `resources/skills/_index.md` | To understand test writing workflow |
-| `resources/patterns/_index.md` | For testing patterns |
-| `resources/tools/_index.md` | For testing tool commands |
-
-### Reference Codes for Writing Tests
-
-| Code | Description | When to Expand |
-|------|-------------|----------------|
-| SKL-TEST-1 | Write tests skill workflow | Understanding full process |
-| PTN-JEST-1 | Jest test structure | Writing Jest tests |
-| PTN-JEST-2 | Jest mocking patterns | When mocking is needed |
-| PTN-PYTEST-1 | Pytest test structure | Writing Pytest tests |
-| PTN-PYTEST-2 | Pytest fixtures | When fixtures are needed |
-| TLS-JEST-1 | Jest commands | Running Jest tests |
-| TLS-PYTEST-1 | Pytest commands | Running Pytest tests |
+## Context Loading
 
-### Expansion Instructions
+This command uses the **brain index** for context retrieval. Before executing, query the project brain for relevant documentation:
 
-When executing this command:
+**Queries**:
+- `planflow-ai state-query "test writing" --scope resources`
+- `planflow-ai state-query "jest patterns" --scope resources`
+- `planflow-ai state-query "pytest patterns" --scope resources`
 
-1. **Start with indexes**: Read `resources/skills/_index.md` and `resources/patterns/_index.md`
-2. **Detect framework first**: Determine Jest or Pytest before expanding patterns
-3. **Expand framework-specific**: Only load PTN-JEST-* or PTN-PYTEST-*, not both
-4. **Expand tool commands**: Load TLS-JEST-* or TLS-PYTEST-* for running tests
-5. **Don't expand everything**: Only load patterns relevant to detected framework
+The brain returns ranked chunks from indexed markdown files. Use the top results to inform execution.
 
 ---
 
@@ -247,9 +216,6 @@ When executing this command:
 
 | Resource                  | Purpose                         |
 | ------------------------- | ------------------------------- |
-| `resources/skills/_index.md` | Index of skills with reference codes |
-| `resources/patterns/_index.md` | Index of patterns with reference codes |
-| `resources/tools/_index.md`  | Index of tools with reference codes |
 | `write-tests-skill.md`   | Skill that writes the tests     |
 | `jest-patterns.md`       | Jest testing patterns           |
 | `pytest-patterns.md`     | Pytest testing patterns         |

package/.claude/resources/core/atomic-commits.md

@@ -0,0 +1,380 @@
+
+# Atomic Commits Per Task
+
+## Purpose
+
+When `commit: true` in `flow/.flowconfig`, `/execute-plan` creates a **git commit after each individual task** completes (and passes verification, if applicable), rather than one commit per phase. This enables `git bisect` to pinpoint task-level regressions, independent reverts of specific task changes, and clearer git history.
+
+**Core principle**: Fine-grained commit history, tied to task completion.
+
+---
+
+## Commit Format
+
+All per-task commits follow a consistent format:
+
+```
+feat(phase-N.task-M): <description truncated to 50 chars> — <feature>
+```
+
+### Format Breakdown
+
+| Part | Example | Description |
+|------|---------|-------------|
+| **Type** | `feat` | Always `feat` for feature implementation (per plan-flow convention) |
+| **Scope** | `phase-1.task-2` | Phase number (N) and task number (M, 1-indexed within phase) |
+| **Description** | `Create user auth middleware` | Short description of what the task did, truncated to 50 characters |
+| **Feature** | `— user-auth-system` | Feature name from the plan, separated by ` — ` |
+
+### Example Commits
+
+```
+feat(phase-1.task-1): Define user and session types — user-auth-system
+feat(phase-1.task-2): Create user schema with Prisma — user-auth-system
+feat(phase-2.task-1): Implement authentication middleware — user-auth-system
+feat(phase-2.task-2): Add rate limiting to API routes — user-auth-system
+feat(phase-3.task-1): Update API documentation — user-auth-system
+```
+
+### Description Truncation
+
+- Truncate task descriptions to **50 characters maximum**
+- Preserve the most meaningful part of the task name
+- Use ellipsis (`...`) if truncation occurs: `Create user authentication middle...`
+- This keeps commit messages concise and readable in `git log`
+
+---
+
+## Sequential Mode Behavior
+
+In **sequential mode** (default, `wave_execution: false`), each phase runs in an **isolated Agent sub-agent**:
+
+```
+Coordinator (main session)
+    │
+    ├─ Spawn Phase sub-agent
+    │   │
+    │   ├─ Task 1: Implement → ✅ Pass verification → Commit immediately
+    │   ├─ Task 2: Implement → ✅ Pass verification → Commit immediately
+    │   └─ Task 3: Implement → ✅ Pass verification → Commit immediately
+    │
+    ├─ Receive JSON return with tasks_completed array
+    │
+    ├─ Process summary:
+    │   └─ Sub-agent commits are already in git
+    │       (files are in working dir from sub-agent context)
+    │
+    └─ Next phase...
+```
+
+### Sub-Agent Commit Behavior
+
+In sequential mode, the **phase sub-agent commits directly** after each task:
+
+1. Complete task implementation in isolation
+2. Run verification (if `<verify>` tag present)
+3. If verification passes: run `git add -A && git commit -m "feat(phase-N.task-M): ..."`
+4. Proceed to next task
+5. Return JSON summary with `tasks_completed` array
+
+The coordinator receives the JSON return and knows which tasks were completed by checking `tasks_completed`. File conflicts do not occur in sequential mode because only one sub-agent runs at a time.
+
+**Context template extension**: Add to phase sub-agent context:
+
+```markdown
+## Commit Instructions
+- 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
+     - 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 Behavior
+
+In **wave mode** (`wave_execution: true`), multiple sub-agents run in **parallel per wave**, and the **coordinator commits after the wave completes**:
+
+```
+Coordinator (main session)
+    │
+    ├─ For each Wave:
+    │   │
+    │   ├─ Spawn MULTIPLE Phase sub-agents IN PARALLEL:
+    │   │   ├─► Phase A sub-agent (runs tasks, NO commits)
+    │   │   └─► Phase B sub-agent (runs tasks, NO commits)
+    │   │
+    │   ├─ Wait for all to complete
+    │   │
+    │   ├─ Collect JSON returns with tasks_completed arrays
+    │   │
+    │   ├─ Post-wave processing (sequential, in phase order):
+    │   │   │
+    │   │   ├─ Detect file conflicts
+    │   │   │
+    │   │   ├─ For each phase (A, then B):
+    │   │   │   └─ For each task in phase (1, 2, 3, ...):
+    │   │   │       └─ Commit: git add -A && git commit -m "feat(phase-N.task-M): ..."
+    │   │   │
+    │   │   └─ Commit all tasks from Phase A, then all from Phase B
+    │   │
+    │   └─ Next Wave...
+    │
+    └─ Completion summary
+```
+
+### Sub-Agent Behavior in Wave Mode
+
+In wave mode, **sub-agents do NOT commit**. They implement all tasks and return a JSON summary:
+
+1. Implement all phase tasks
+2. Run per-task verification (if applicable)
+3. **Do NOT commit** — parallel git conflicts would occur
+4. Return JSON with `tasks_completed` array containing per-task metadata
+5. Exit
+
+The coordinator collects all JSON returns, detects file conflicts, then commits sequentially.
+
+**Context template extension**: Add to phase sub-agent context in wave mode:
+
+```markdown
+## Commit Instructions (Wave Mode)
+- 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
+```
+
+---
+
+## JSON Return Schema Extension
+
+The phase isolation return format is extended with a **`tasks_completed` array** for per-task file tracking:
+
+```json
+{
+  "status": "success",
+  "phase": "Phase 1: Create Core Resource",
+  "summary": "Implemented three core resource files...",
+  "files_created": [
+    ".claude/resources/core/atomic-commits.md",
+    ".claude/resources/core/_index.md"
+  ],
+  "files_modified": [],
+  "decisions": [],
+  "deviations": [],
+  "errors": [],
+  "patterns_captured": [],
+  "tasks_completed": [
+    {
+      "task_number": 1,
+      "task_name": "Create atomic-commits.md resource file",
+      "files_created": [".claude/resources/core/atomic-commits.md"],
+      "files_modified": []
+    },
+    {
+      "task_number": 2,
+      "task_name": "Update _index.md with reference entry",
+      "files_created": [],
+      "files_modified": [".claude/resources/core/_index.md"]
+    }
+  ]
+}
+```
+
+### tasks_completed Field
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `task_number` | number | 1-indexed task number within the phase |
+| `task_name` | string | Short task description from the plan |
+| `files_created` | string[] | Files created by this task (empty array if none) |
+| `files_modified` | string[] | Files modified by this task (empty array if none) |
+
+### When to Include
+
+- Always include `tasks_completed` if any tasks ran in the phase
+- Omit `tasks_completed` only if the phase has no tasks (edge case)
+- Include all tasks, even those without `<verify>` tags
+- Order entries by task_number (1, 2, 3, ...)
+
+---
+
+## Coordinator Processing: Sequential Mode
+
+After receiving the sub-agent JSON return in sequential mode:
+
+1. **Validate return**: Check `status` field
+2. **Verify commits exist**: The sub-agent has already created per-task commits
+3. **Update plan file**: Mark phase tasks as `[x]`
+4. **Accumulate file list**: Merge `files_created` and `files_modified` into running list
+5. **Buffer patterns**: Append `patterns_captured` entries
+6. **Display summary**: Show tasks completed with verification results
+7. **Do NOT create phase commit**: Sub-agent already created per-task commits
+8. **Proceed**: Move to next phase
+
+---
+
+## Coordinator Processing: Wave Mode
+
+After collecting all sub-agent JSON returns from a wave:
+
+1. **Validate all returns**: Check `status` field for each
+2. **Detect file conflicts**: Check `files_modified` overlap between phases (same as existing wave behavior)
+3. **For each phase** (in phase number order):
+   - **For each task** (in task_number order):
+     - Extract `task_name`, `files_created`, `files_modified` from `tasks_completed[i]`
+     - **Stage files**: `git add -A` (stages all task changes in working directory)
+     - **Create commit**: `git commit -m "feat(phase-N.task-M): <truncated task_name> — <feature>"`
+       - Truncate `task_name` to 50 chars if needed
+       - Use task_number from JSON (not computed)
+       - Use feature name from plan
+   - **Update plan file**: Mark phase tasks as `[x]` (after all phase tasks are committed)
+   - **Accumulate file list**: Merge task file lists into running list
+4. **Buffer patterns**: Collect `patterns_captured` from all phases
+5. **Display summary**: Show all phases and tasks completed, including verification results
+6. **Do NOT create wave commit**: Per-task commits already created
+7. **Proceed**: Next wave
+
+### Deterministic Commit Ordering
+
+Commits are created in **strict phase order, then task order**:
+
+```
+Wave 1 complete:
+  Phase A, Task 1 → commit
+  Phase A, Task 2 → commit
+  Phase A, Task 3 → commit
+  Phase B, Task 1 → commit
+  Phase B, Task 2 → commit
+```
+
+This ensures **deterministic git history** regardless of which sub-agent finished first.
+
+---
+
+## Interaction with Per-Task Verification
+
+Verification runs **before** the task's commit:
+
+```
+Phase sub-agent:
+  Task 1: Implement
+    ├─ Implementation complete
+    ├─ Run verification (if <verify> tag present)
+    ├─ If fail: debug sub-agent → repair loop → re-verify
+    ├─ If pass or fail (max retries): commit this task
+    └─ Continue to Task 2
+```
+
+**Rule**: A task commits even if verification failed (after max retries). The coordinator and user see the failure in `task_verifications[i].status == "fail"`.
+
+---
+
+## Interaction with Phase Isolation
+
+Atomic commits per task is **independent of phase isolation**:
+
+| phase_isolation | Behavior |
+|---|---|
+| `true` (default) | Sub-agent isolated with clean context; per-task commits work normally |
+| `false` (legacy) | Phases execute inline in main session; per-task commits still work but less clean context isolation |
+
+Per-task commits work the same way in both modes — the difference is context isolation, not commit behavior.
+
+---
+
+## Interaction with Wave Execution
+
+Atomic commits per task **requires wave execution to work correctly**:
+
+| wave_execution | Behavior |
+|---|---|
+| `true` (default) | Coordinator commits per-task after wave completes (no parallel git conflicts) |
+| `false` (sequential) | Sub-agent commits per-task directly (no coordinator involvement) |
+
+Per-task commits are the **only reason wave mode does NOT commit** in the sub-agent. Without per-task commits, we might revert to per-phase commits from the coordinator.
+
+---
+
+## Aggregated Phases
+
+When phases are aggregated (combined complexity ≤ 6), they run as **one sub-agent call** with all tasks from all aggregated phases. Commit format still uses **relative phase numbering**:
+
+```
+Phase 1 (aggregated with Phase 2):
+  Aggregated Phase tasks:
+    feat(phase-1.task-1): ...
+    feat(phase-1.task-2): ...
+    feat(phase-2.task-1): ...
+    feat(phase-2.task-2): ...
+```
+
+**Rule**: Use the **actual phase number** from the plan, not a computed aggregate phase number.
+
+---
+
+## Configuration
+
+### `.flowconfig` Setting
+
+Per-task commits are **not a separate feature flag**. They are **controlled by the existing `commit` setting**:
+
+```yaml
+commit: true    # Enable per-task commits (default: true)
+```
+
+- `true`: Create atomic per-task commits (this feature)
+- `false`: No commits during execution (existing behavior)
+
+No new `.flowconfig` setting is needed — `commit: true` automatically upgrades from per-phase to per-task commits.
+
+### Toggle via `/flow`
+
+```
+/flow commit=true
+/flow commit=false
+```
+
+---
+
+## Error Handling
+
+| Scenario | Behavior |
+|---|---|
+| Task implementation fails | Task does NOT commit; coordinator reports failure in `errors` array |
+| Verification fails (max retries) | Task commits anyway; coordinator shows failure in `task_verifications[i].status == "fail"` |
+| Git commit command fails | Coordinator reports error and asks user whether to retry, skip, or stop |
+| File conflict in wave mode | Same as existing wave conflict handling — present to user with options |
+
+---
+
+## Rules
+
+1. **Format is strict**: `feat(phase-N.task-M): <50 chars max> — <feature>`
+2. **Sequential mode**: Sub-agents commit; coordinator validates
+3. **Wave mode**: Sub-agents do NOT commit; coordinator commits in phase/task order
+4. **No final phase commit**: Replaced by per-task commits
+5. **Backward compatible**: When `commit: false`, no commits (existing behavior)
+6. **Verification before commit**: Tasks commit after passing verification
+7. **Failure still commits**: Failed verification after max retries still commits the task
+8. **Deterministic order**: Wave mode commits always in phase order, task order
+9. **Truncate descriptions**: 50 character max for readability
+10. **Task numbers reset per phase**: Phase 1 Task 1, Phase 2 Task 1 (not global numbering)
+
+---
+
+## Related Files
+
+| File | Purpose |
+|---|---|
+| `.claude/resources/core/phase-isolation.md` | Sub-agent context template, JSON return format (extended by this feature) |
+| `.claude/resources/core/wave-execution.md` | Wave coordinator behavior (changed to commit per-task after waves) |
+| `.claude/resources/core/per-task-verification.md` | Per-task verification (runs before task's commit) |
+| `.claude/resources/skills/execute-plan-skill.md` | Execute-plan skill (updated for per-task commit format) |
+| `.claude/commands/execute-plan.md` | Execute-plan command docs (updated for per-task format) |

package/.claude/resources/core/autopilot-mode.md

@@ -97,8 +97,9 @@ Check `flow/contracts/` for any relevant integration contracts. If found, note t
 5. If `commit: true`: auto-commit after each completed phase
 6. Run build + test verification at the end
 7. If `push: true` and build+test pass: auto-push
-8. Write transition summary
-9. **Auto-proceed** to Step 5
+8. If `pr: true` and push succeeds: create feature branch `feat/<feature>`, open PR via `gh pr create`, capture PR URL
+9. Write transition summary
+10. **Auto-proceed** to Step 5
 
 ### Step 5: Review Code
 

package/.claude/resources/core/compaction-guide.md

@@ -103,9 +103,23 @@ Open questions: retry policy, refund flow. Resume with remaining questions.
 
 ---
 
+## STATE.md Integration
+
+Before compaction, write current execution state to `flow/STATE.md` using the standard state format (skill, phase, status, decisions, errors). This ensures that even if the compaction summary loses detail, the full execution position is recoverable from the file.
+
+After compaction, re-read `flow/STATE.md` to restore execution context. This supplements the compaction summary with structured state that the summary format may not fully capture (phase numbers, file lists, decision references).
+
+**Workflow**:
+1. Before `/compact`: Update `flow/STATE.md` with current state (or create it if it doesn't exist)
+2. Run `/compact` with the summary
+3. After compaction: Re-read `flow/STATE.md` and the active plan file to restore full context
+
+---
+
 ## Rules
 
 1. **Never compact mid-phase** — only at phase boundaries
 2. **Always include enough context to resume** — the model after compaction should know exactly what to do next
 3. **After compaction, re-read the plan file** — don't rely on memory of plan contents
-4. **Default to preserving** — when in doubt, keep it. It's better to preserve something unnecessary than lose something critical.
+4. **After compaction, re-read STATE.md** — restore structured execution state that the summary may not fully capture
+5. **Default to preserving** — when in doubt, keep it. It's better to preserve something unnecessary than lose something critical.