planflow-ai 1.3.0 → 1.3.4

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

@@ -0,0 +1,111 @@
+
+# Compaction Guide
+
+## Purpose
+
+When a plan-flow session runs `/compact`, the compaction model summarizes the conversation history. Without guidance, it may discard critical state (phase progress, decisions) or keep low-value tokens (old file reads, resolved searches).
+
+**Core principle**: Preserve decisions, discard outputs.
+
+### When to Compact
+
+- At **phase boundaries** during `/execute-plan` (between phases, never mid-phase)
+- When context feels heavy (many tool calls, large file reads accumulated)
+- Before starting a complex phase (complexity >= 6)
+- During long `/review-code` or `/discovery-plan` sessions with many file reads
+
+---
+
+## Preserve Rules (High-Signal Tokens)
+
+Always include these in the compact summary:
+
+| Category | What to Keep | Examples |
+|----------|-------------|----------|
+| **Execution state** | Current skill, phase number, plan slug, completed vs pending phases | "Executing plan_user_auth_v1.md, phase 3 of 5 complete" |
+| **Decision log** | Architecture choices, pattern selections, user preferences, rejected alternatives | "Chose JWT over sessions (discovery DR-4). User rejected Redis caching." |
+| **Error context** | Unresolved errors, failed attempts, workarounds in progress, retry count | "Build fails on type mismatch in auth.ts:42 — tried 2 approaches" |
+| **User requirements** | Original request, clarified constraints, acceptance criteria | "User wants OAuth2 with Google only, no email/password" |
+| **Tasklist state** | Current in-progress items from `flow/tasklist.md` | "In progress: Execute user-auth" |
+| **Pattern buffer** | Pending pattern captures not yet saved | "Buffered: async error handling pattern for approval" |
+| **Active file list** | Files created or modified during the session | "Modified: src/auth/middleware.ts, src/auth/types.ts" |
+| **Scratchpad notes** | Contents of `flow/.scratchpad.md` — ephemeral session notes not yet promoted | "Scratchpad: 3 notes, 1 open question" |
+
+---
+
+## Discard Rules (Low-Signal Tokens)
+
+Safe to drop from the compact summary:
+
+| Category | What to Drop | Why |
+|----------|-------------|-----|
+| **Completed tool results** | File reads from resolved steps, grep results already acted on | Can be re-read if needed |
+| **Superseded content** | Earlier versions of files that were subsequently edited | Only the final state matters |
+| **Verbose output** | Full build logs, test output — keep only pass/fail + error messages | Details can be regenerated |
+| **Exploration dead-ends** | Files read but found irrelevant, abandoned approaches | No future value |
+| **Redundant context** | Content repeated across multiple tool calls | One copy is enough |
+| **Index file contents** | `_index.md` files read for navigation | Re-read on demand |
+
+---
+
+## Compact Summary Template
+
+When crafting `/compact` instructions, use this structure:
+
+```
+## Session State
+- **Active skill**: {skill name — e.g., execute-plan, review-code, discovery}
+- **Active plan**: {plan file path or "none"}
+- **Current phase**: {N of M} — {phase name}
+- **Completed phases**: {list with brief outcomes}
+
+## Decisions Made
+- {decision}: {choice} (reason: {why})
+
+## Unresolved Issues
+- {error/issue}: {status, what was tried}
+
+## Files Modified
+- {file path}: {what changed}
+
+## Next Action
+{What to do immediately after compaction}
+```
+
+---
+
+## Skill-Specific Examples
+
+### Execute-Plan Compaction
+
+```
+/compact Executing plan_user_auth_v1.md. Completed: Phase 1 (types — done),
+Phase 2 (API endpoints — done). Next: Phase 3 of 5 (Frontend UI, complexity 6).
+Decisions: JWT auth (not sessions), Zod validation. Files modified:
+src/auth/types.ts, src/api/auth.ts. Resume from Phase 3.
+```
+
+### Review-Code Compaction
+
+```
+/compact Reviewing 47 changed files. Completed: file categorization, security scan
+(2 findings), logic analysis (3 findings). Next: performance scan. Findings so far:
+1 critical (SQL injection in query.ts), 4 minor. Resume with performance analysis.
+```
+
+### Discovery Compaction
+
+```
+/compact Discovery for payment-integration. Questions answered: 5 of 8.
+Key requirements: Stripe only, webhook verification required, idempotency keys.
+Open questions: retry policy, refund flow. Resume with remaining questions.
+```
+
+---
+
+## 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.

package/.claude/resources/core/discovery-sub-agents.md

@@ -0,0 +1,266 @@
+
+# Discovery Sub-Agents
+
+## Purpose
+
+During `/discovery-plan`, three parallel Agent sub-agents explore the codebase simultaneously. Each focuses on a specific aspect (similar features, API/data patterns, schema/types) and returns condensed JSON findings. The coordinator merges these into a **Codebase Analysis** section in the discovery document, enabling better-informed clarifying questions.
+
+**Core principle**: Parallel exploration, condensed returns, cleaner context.
+
+---
+
+## Architecture
+
+```
+Discovery Skill (main session)
+    │
+    ├─ Step 1: Read referenced documents (unchanged)
+    │
+    ├─ Step 1b: Spawn exploration sub-agents in parallel
+    │   ├─► Agent: Similar Features     (model: haiku)
+    │   ├─► Agent: API/Data Patterns   (model: haiku)
+    │   └─► Agent: Schema/Types        (model: haiku)
+    │
+    ├─ Step 1c: Collect and merge findings into Codebase Analysis
+    │
+    ├─ Step 2: Ask clarifying questions (informed by findings)
+    │   ... (rest of discovery unchanged)
+```
+
+All three sub-agents use **haiku** — exploration is search-heavy (Glob, Grep, Read) with lightweight summarization.
+
+---
+
+## Agent Definitions
+
+### 1. Similar Features Agent
+
+**Focus**: Find existing features or code that does something similar to the proposed feature.
+
+**Prompt template**:
+```
+You are a codebase explorer. Your task is to find existing code that is similar to a proposed feature.
+
+Feature: {feature_name}
+Context: {context_summary_from_step_1}
+
+Search for:
+- Components, modules, or services that handle related functionality
+- Route handlers or endpoints with similar purpose
+- Existing UI patterns that address similar use cases
+- Utility functions that could be reused
+
+Use Glob and Grep to search the codebase. Read relevant files to understand their purpose.
+
+Return your findings as JSON:
+{
+  "agent": "similar-features",
+  "status": "success",
+  "findings": [
+    {
+      "file": "path/to/file.ts",
+      "description": "Brief description of what this file does and how it relates",
+      "relevance": "high" | "medium" | "low"
+    }
+  ],
+  "summary": "2-3 sentence overview of similar features found",
+  "patterns_noticed": ["List of coding conventions or patterns observed"]
+}
+
+Rules:
+- Only READ files (Glob, Grep, Read) — never write or edit
+- Return at most 10 findings, sorted by relevance
+- Keep the summary under 200 words
+- Focus on HIGH relevance findings
+```
+
+### 2. API/Data Patterns Agent
+
+**Focus**: Scan for existing API endpoints, data models, service patterns, and integration points.
+
+**Prompt template**:
+```
+You are a codebase explorer. Your task is to map the API and data patterns in this project.
+
+Feature: {feature_name}
+Context: {context_summary_from_step_1}
+
+Search for:
+- API route definitions and endpoint patterns (REST, GraphQL, tRPC)
+- Controller/handler organization and naming conventions
+- Service layer patterns (repository pattern, direct DB access, etc.)
+- Data flow: how requests are processed from route → handler → service → response
+- Middleware patterns (auth, validation, error handling)
+- API response shapes and error formats
+
+Use Glob and Grep to search the codebase. Read relevant files to understand patterns.
+
+Return your findings as JSON:
+{
+  "agent": "api-data-patterns",
+  "status": "success",
+  "findings": [
+    {
+      "file": "path/to/file.ts",
+      "description": "Brief description of the API/data pattern found",
+      "relevance": "high" | "medium" | "low"
+    }
+  ],
+  "summary": "2-3 sentence overview of API architecture and data flow patterns",
+  "patterns_noticed": ["List of API/data conventions observed"]
+}
+
+Rules:
+- Only READ files (Glob, Grep, Read) — never write or edit
+- Return at most 10 findings, sorted by relevance
+- Keep the summary under 200 words
+- Focus on patterns the new feature would need to follow
+```
+
+### 3. Schema/Types Agent
+
+**Focus**: Explore type definitions, database schemas, shared interfaces, and data structures.
+
+**Prompt template**:
+```
+You are a codebase explorer. Your task is to map the type system and data schemas in this project.
+
+Feature: {feature_name}
+Context: {context_summary_from_step_1}
+
+Search for:
+- TypeScript interfaces and type definitions relevant to the feature
+- Database schemas (Prisma, TypeORM, Drizzle, raw SQL migrations)
+- Shared types and enums used across the codebase
+- Zod/Yup/Joi validation schemas
+- API request/response type definitions
+
+Use Glob and Grep to search the codebase. Read relevant files to understand the type system.
+
+Return your findings as JSON:
+{
+  "agent": "schema-types",
+  "status": "success",
+  "findings": [
+    {
+      "file": "path/to/file.ts",
+      "description": "Brief description of the type/schema and its relevance",
+      "relevance": "high" | "medium" | "low"
+    }
+  ],
+  "summary": "2-3 sentence overview of relevant type system and schemas",
+  "patterns_noticed": ["List of type/schema conventions observed"]
+}
+
+Rules:
+- Only READ files (Glob, Grep, Read) — never write or edit
+- Return at most 10 findings, sorted by relevance
+- Keep the summary under 200 words
+- Focus on types the new feature would interact with
+```
+
+---
+
+## Return Format
+
+Each sub-agent returns structured JSON:
+
+```json
+{
+  "agent": "similar-features" | "api-data-patterns" | "schema-types",
+  "status": "success" | "failure",
+  "findings": [
+    {
+      "file": "string — relative file path",
+      "description": "string — what this file does and how it relates to the feature",
+      "relevance": "high" | "medium" | "low"
+    }
+  ],
+  "summary": "string — 2-3 sentence overview (under 200 words)",
+  "patterns_noticed": ["string — coding conventions or patterns observed"]
+}
+```
+
+**Size target**: Each return should be under 2K tokens.
+
+---
+
+## Coordinator Behavior
+
+### Step 1b: Spawn Sub-Agents
+
+Launch all 3 sub-agents in parallel using the Agent tool:
+
+```
+Launch in parallel:
+- Agent(model: "haiku", subagent_type: "Explore", prompt: similar_features_prompt)
+- Agent(model: "haiku", subagent_type: "Explore", prompt: api_data_prompt)
+- Agent(model: "haiku", subagent_type: "Explore", prompt: schema_types_prompt)
+```
+
+Each sub-agent receives:
+1. **Feature name** — from the user's input
+2. **Context summary** — brief summary of what Step 1 found in referenced documents
+3. **Exploration instructions** — the agent-specific prompt template above
+
+### Step 1c: Collect and Merge Findings
+
+1. **Parse returns**: Extract JSON from each sub-agent response
+2. **Handle failures**: If a sub-agent returns `status: "failure"` or fails to return valid JSON, skip its findings and continue. Log the failure but do not block discovery.
+3. **Filter**: Remove findings with `relevance: "low"` if there are more than 15 total findings
+4. **Merge patterns**: Collect all `patterns_noticed` entries across agents, deduplicate, and append to `flow/resources/pending-patterns.md`
+5. **Format Codebase Analysis**: Build the section for the discovery document
+
+### Codebase Analysis Section Format
+
+```markdown
+## Codebase Analysis
+
+### Similar Features
+{summary from similar-features agent}
+
+| File | Description | Relevance |
+|------|-------------|-----------|
+| `path/to/file.ts` | Description | High |
+| ... | ... | ... |
+
+### API & Data Patterns
+{summary from api-data-patterns agent}
+
+| File | Description | Relevance |
+|------|-------------|-----------|
+| ... | ... | ... |
+
+### Schema & Types
+{summary from schema-types agent}
+
+| File | Description | Relevance |
+|------|-------------|-----------|
+| ... | ... | ... |
+```
+
+If a sub-agent returned no findings or failed, omit its subsection entirely.
+
+---
+
+## Error Handling
+
+| Scenario | Behavior |
+|----------|----------|
+| Sub-agent fails (timeout, error) | Skip its findings, continue with other agents' results |
+| Sub-agent returns invalid JSON | Skip its findings, log warning |
+| All sub-agents fail | Continue discovery without Codebase Analysis section |
+| No relevant findings | Omit Codebase Analysis section — discovery proceeds normally |
+
+Discovery must never be blocked by sub-agent failures. Findings are supplementary.
+
+---
+
+## Related Files
+
+| File | Purpose |
+|------|---------|
+| `.claude/resources/skills/discovery-skill.md` | Discovery skill (Steps 1b + 1c added) |
+| `.claude/resources/core/review-multi-agent.md` | Similar pattern: parallel specialized subagents |
+| `.claude/resources/core/phase-isolation.md` | Similar pattern: sub-agent with focused prompt → JSON return |
+| `.claude/resources/core/pattern-capture.md` | patterns_noticed entries routed to pending-patterns.md |

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

@@ -0,0 +1,222 @@
+
+# Phase Isolation
+
+## Purpose
+
+When `phase_isolation: true` in `flow/.flowconfig` (default), each `/execute-plan` phase implementation runs in an **isolated Agent sub-agent** with a clean context window. The sub-agent receives only the context it needs and returns a structured JSON summary. This eliminates context rot — phase 7 has the same quality as phase 1.
+
+**Core principle**: Clean context in, structured summary out.
+
+---
+
+## Architecture
+
+```
+Coordinator (main session)
+    │
+    ├─ Present phase in Plan Mode → User approves
+    │
+    ├─ Prepare isolated context (see Context Template below)
+    │
+    ├─ Spawn Agent sub-agent:
+    │   model: [tier from model routing]
+    │   mode: "auto"
+    │   prompt: [focused context + instructions + return format]
+    │
+    ├─ Receive structured JSON summary (1-2K tokens)
+    │
+    ├─ Process summary:
+    │   ├─ Update plan file (mark tasks [x])
+    │   ├─ Accumulate files_modified list
+    │   ├─ Append patterns to pending-patterns.md
+    │   ├─ Git commit (if enabled)
+    │   └─ Handle errors (present to user if status != success)
+    │
+    └─ Next phase...
+```
+
+Planning and user approval always happen in the **main session** (full context). Only the **implementation step** is isolated.
+
+---
+
+## Context Template
+
+The Agent sub-agent prompt must include exactly these sections:
+
+```markdown
+# Phase Implementation: {Phase N — Phase Name}
+
+## Plan
+**Feature**: {feature name}
+**Plan file**: {path to plan file}
+
+## Phase Scope
+{Scope description from plan}
+
+## Tasks
+{Task list from plan, as checklist}
+
+## Files Modified in Previous Phases
+{List of file paths created/modified so far, or "None — this is Phase 1"}
+
+## Project Patterns
+Read these files before implementing:
+- `.claude/rules/core/allowed-patterns.md`
+- `.claude/rules/core/forbidden-patterns.md`
+
+## Design Context
+{Only if UI phase — include design tokens from discovery doc}
+{Otherwise omit this section entirely}
+
+## 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
+
+## Return Format
+Return ONLY a JSON object (no markdown fences, no explanation):
+{see Return Format Schema below}
+```
+
+### Context Size Target
+
+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.
+
+---
+
+## Return Format Schema
+
+The sub-agent must return a JSON object with this structure:
+
+```json
+{
+  "status": "success",
+  "phase": "Phase 1: Create Core Resource",
+  "summary": "One-paragraph description of what was implemented and any notable decisions.",
+  "files_created": [
+    "src/types/auth.ts"
+  ],
+  "files_modified": [
+    "src/api/routes.ts",
+    "src/utils/helpers.ts"
+  ],
+  "decisions": [
+    "Chose JWT over sessions because discovery DR-4 specified stateless auth"
+  ],
+  "deviations": [
+    "Task 3 deferred — requires database migration first"
+  ],
+  "errors": [],
+  "patterns_captured": [
+    {
+      "category": "allowed",
+      "name": "Zod schema co-location",
+      "description": "All Zod schemas live next to their type definitions",
+      "confidence": "high"
+    }
+  ]
+}
+```
+
+### Field Descriptions
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `status` | `"success" \| "failure" \| "partial"` | Yes | Overall phase outcome |
+| `phase` | string | Yes | Phase number and name |
+| `summary` | string | Yes | 1-3 sentence description of what was done |
+| `files_created` | string[] | Yes | Paths of new files created (empty array if none) |
+| `files_modified` | string[] | Yes | Paths of existing files modified (empty array if none) |
+| `decisions` | string[] | No | Architecture/design decisions made during implementation |
+| `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 |
+
+### Failure Return Example
+
+```json
+{
+  "status": "failure",
+  "phase": "Phase 3: API Integration",
+  "summary": "Failed to implement API routes. Missing dependency '@auth/core' not in package.json.",
+  "files_created": [],
+  "files_modified": ["src/api/auth.ts"],
+  "decisions": [],
+  "deviations": [],
+  "errors": [
+    "Cannot find module '@auth/core' — dependency not installed",
+    "Partial implementation in src/api/auth.ts — needs cleanup"
+  ],
+  "patterns_captured": []
+}
+```
+
+---
+
+## Coordinator Processing
+
+After receiving the sub-agent's JSON summary, the coordinator:
+
+### On Success (`status: "success"`)
+
+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}"`
+5. **Log decisions**: Include `decisions` in phase completion message
+6. **Proceed**: Move to next phase
+
+### On Failure (`status: "failure"`)
+
+1. **Present error**: Show `errors` array to user
+2. **Show partial work**: List `files_modified` so user knows what was touched
+3. **Ask user**: "Phase failed. Options: (1) Retry phase, (2) Skip and continue, (3) Stop execution"
+4. **Do NOT auto-retry**: Let user decide
+
+### On Partial (`status: "partial"`)
+
+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?"
+
+---
+
+## Aggregated Phases
+
+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.
+
+---
+
+## Configuration
+
+### `.flowconfig` Setting
+
+```yaml
+phase_isolation: true    # Run phases in isolated sub-agents (default: true)
+```
+
+- `true` (default): Each phase runs in an isolated Agent sub-agent
+- `false`: Phases execute inline in the main session (legacy behavior, useful for debugging)
+
+### Interaction with Model Routing
+
+Phase isolation **enhances** model routing — it doesn't replace it:
+
+| Setting | Behavior |
+|---------|----------|
+| `model_routing: true` + `phase_isolation: true` | Sub-agent spawned with correct tier model AND clean context |
+| `model_routing: true` + `phase_isolation: false` | Sub-agent spawned with correct tier model, inherits session context |
+| `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) |
+
+---
+
+## Rules
+
+1. **Planning stays in session** — only implementation is isolated
+2. **Under 2K token prompts** — keep context focused, let sub-agent read files
+3. **JSON return only** — no markdown in the return, pure JSON
+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

package/.claude/resources/core/resource-capture.md

@@ -13,7 +13,7 @@ During any skill execution, the LLM watches for information that could be valuab
 
 ### During Any Skill Execution
 
-While executing any plan-flow skill (`/setup`, `/discovery-plan`, `/create-plan`, `/execute-plan`, `/review-code`, `/review-pr`, `/write-tests`, `/create-contract`, `/brain`), watch for information that meets the capture criteria below.
+While executing any plan-flow skill (`/setup`, `/discovery-plan`, `/create-plan`, `/execute-plan`, `/review-code`, `/review-pr`, `/write-tests`, `/create-contract`, `/note`), watch for information that meets the capture criteria below.
 
 When you identify something worth preserving: