planflow-ai 1.0.8 → 1.1.0

package/.claude/commands/brain.md

@@ -0,0 +1,251 @@
+---
+description: Manual brain entry - capture meeting notes, ideas, brainstorms, and insights into the project brain
+---
+
+# Brain: Manual Knowledge Capture
+
+## Command Description
+
+This command allows manual brain entries for capturing meeting notes, brainstorms, ad-hoc ideas, and insights that don't come from automatic skill execution. Supports two modes: free-text (default) and guided prompts.
+
+**Output**: Brain entries in `flow/brain/` with `[[wiki-links]]` for Obsidian compatibility.
+
+---
+
+
+## Help
+
+**If the user invokes this command with `-help`, display only this section and stop:**
+
+```
+/brain - Manual Brain Entry
+
+DESCRIPTION:
+  Capture meeting notes, brainstorms, ideas, and insights into the
+  project brain. Creates Obsidian-compatible markdown with [[wiki-links]].
+
+USAGE:
+  /brain <free text>        Free-text mode (default)
+  /brain -guided            Guided mode with structured questions
+  /brain -help              Show this help
+
+ARGUMENTS:
+  free text     Unstructured text to parse and categorize
+  -guided       Triggers structured question mode
+
+EXAMPLES:
+  /brain Had a call with the team about auth flow. Decision: use JWT with refresh tokens.
+  /brain Discovered that the API rate limits at 100 req/min. Need to add throttling.
+  /brain -guided
+
+OUTPUT:
+  - Writes to appropriate flow/brain/ subdirectory
+  - Creates [[wiki-links]] to related entries
+  - Updates flow/brain/index.md if needed
+
+MODES:
+  Free-text:  Parses input, extracts entities, categorizes, writes entry
+  Guided:     Asks structured questions about work, insights, meetings, decisions
+
+BRAIN STRUCTURE:
+  flow/brain/
+  ├── index.md        # Brain index (always loaded at session start)
+  ├── features/       # Feature history and context
+  ├── errors/         # Reusable error patterns
+  ├── decisions/      # Decision records
+  └── sessions/       # Daily activity logs
+
+RELATED COMMANDS:
+  /setup             Creates brain directory structure
+  /discovery-plan    Auto-captures to brain after completion
+  /execute-plan      Auto-captures to brain after completion
+```
+
+---
+
+> **AGENT_PROFILE: write-restricted**
+> See `.claude/resources/core/agent-profiles.md` for tool access rules.
+
+## Critical Rules
+
+| Rule                     | Description                                              |
+| ------------------------ | -------------------------------------------------------- |
+| **Brain Only**           | ONLY write to `flow/brain/` - no source code, no config  |
+| **Wiki-Links**           | All cross-references use `[[kebab-case-name]]` format    |
+| **Index Caps**           | Max 5 errors, 3 decisions, 3 cross-project in index      |
+| **No Code**              | Brain is for knowledge capture, never write source code   |
+| **Complete and Stop**    | After writing entry, STOP and wait for user               |
+
+---
+
+## Instructions
+
+### Step 1: Validate Inputs
+
+| Input       | Required | Description                                    |
+| ----------- | -------- | ---------------------------------------------- |
+| `content`   | Yes      | Free-text or triggered by `-guided` flag       |
+| `-guided`   | Optional | Triggers structured question mode              |
+
+If no content and no `-guided` flag, ask:
+
+```markdown
+What would you like to capture? You can:
+1. Type free text and I'll categorize it automatically
+2. Use `/brain -guided` for structured prompts
+```
+
+---
+
+### Step 2: Ensure Brain Directory Exists
+
+Check if `flow/brain/` exists. If not, create:
+
+```bash
+mkdir -p flow/brain/features flow/brain/errors flow/brain/decisions flow/brain/sessions
+```
+
+Check if `flow/brain/index.md` exists. If not, create initial index:
+
+```markdown
+# Project Brain
+
+## Active Features
+_No features tracked yet._
+
+## Recent Errors
+_No errors captured yet._
+
+## Recent Decisions
+_No decisions recorded yet._
+
+## Cross-Project Patterns
+_No cross-project patterns yet._
+```
+
+---
+
+### Step 3: Invoke Brain Skill
+
+The skill will handle:
+
+**Free-text mode**:
+1. Parse input text
+2. Extract entities (features, technologies, people, errors, decisions)
+3. Categorize into appropriate brain subdirectory
+4. Create/update brain files with `[[wiki-links]]`
+5. Update `flow/brain/index.md` if needed
+
+**Guided mode** (`-guided`):
+1. Ask structured questions via `AskUserQuestion`
+2. Gather responses and follow-up text
+3. Generate properly formatted brain files
+4. Link everything with `[[wiki-links]]`
+5. Update `flow/brain/index.md`
+
+See: `.claude/resources/skills/brain-skill.md`
+
+---
+
+### Step 4: Present Results
+
+After the skill completes:
+
+**Free-text result**:
+
+```markdown
+Brain entry captured!
+
+**Written to**: flow/brain/[subdirectory]/[file].md
+**Links created**: [[feature-1]], [[error-name]]
+**Index updated**: Yes/No
+```
+
+**Guided result**:
+
+```markdown
+Brain entry captured!
+
+**Topics covered**:
+- Feature: [[feature-name]] - summary
+- Decision: [[decision-name]] - choice
+- Meeting notes added to [[YYYY-MM-DD]]
+
+**Index updated**: Yes
+```
+
+---
+
+## Flow Diagram
+
+```
++------------------------------------------+
+|           /brain COMMAND                 |
++------------------------------------------+
+                    |
+                    v
++------------------------------------------+
+| Step 1: Validate Inputs                  |
+| - Check for content or -guided flag      |
++------------------------------------------+
+                    |
+                    v
++------------------------------------------+
+| Step 2: Ensure Brain Directory           |
+| - Create flow/brain/ if needed           |
+| - Create index.md if needed              |
++------------------------------------------+
+                    |
+                    v
++------------------------------------------+
+| Step 3: Invoke Brain Skill               |
+| - Free-text: parse, extract, categorize  |
+| - Guided: structured questions           |
+| - See brain-skill.md                    |
++------------------------------------------+
+                    |
+                    v
++------------------------------------------+
+| Step 4: Present Results                  |
+| - Show files written                     |
+| - Show links created                     |
+| - Show index update status               |
++------------------------------------------+
+```
+
+---
+
+## Context Optimization
+
+### Recommended Loading Order
+
+1. **Always load first**: This command file (`commands/brain.md`)
+2. **Load indexes**: Load `_index.md` files for relevant folders
+3. **Expand on-demand**: Use reference codes to load specific sections when needed
+
+### Reference Codes for Brain
+
+| Code | Description | When to Expand |
+|------|-------------|----------------|
+| SKL-BR-1 | Brain skill restrictions | Understanding allowed actions |
+| SKL-BR-2 | Brain skill workflow | Processing entries |
+| SKL-BR-3 | Output format and validation | Formatting output |
+| PTN-BR-1 | Directory structure and naming | Creating brain files |
+| PTN-BR-2 | Wiki-link patterns | Creating cross-references |
+| PTN-BR-3 | Feature status lifecycle | Updating feature entries |
+| COR-BR-1 | Session start behavior | Understanding brain loading |
+| COR-BR-2 | File templates | Creating new brain files |
+| COR-BR-3 | Index management caps | Enforcing index limits |
+
+---
+
+## Related Resources
+
+| Resource                    | Purpose                           |
+| --------------------------- | --------------------------------- |
+| `resources/skills/_index.md`   | Index of skills with reference codes |
+| `resources/patterns/_index.md` | Index of patterns with reference codes |
+| `resources/core/_index.md`     | Index of core rules with reference codes |
+| `brain-skill.md`           | Skill that processes brain entries |
+| `brain-patterns.md`        | File naming and link conventions  |
+| `brain-capture.md`         | Processing rules and templates    |

package/.claude/commands/create-contract.md

@@ -55,6 +55,13 @@ RELATED COMMANDS:
 
 ---
 
+> **MODE: Research**
+> Explore before concluding. Read 3x more than you write. Prefer Read/Grep/Glob/WebSearch tools.
+> Ask clarifying questions when uncertain. Don't jump to implementation.
+
+> **AGENT_PROFILE: read-only**
+> See `.claude/resources/core/agent-profiles.md` for tool access rules.
+
 ## Critical Rules
 
 | Rule                     | Description                                              |
@@ -242,3 +249,46 @@ When executing this command:
 | `/discovery-plan` command      | Create discovery from contract         |
 | `/create-plan` command         | Create plan from discovery             |
 
+---
+
+## Compaction Suggestion
+
+After contract creation completes, suggest context cleanup if the contract was complex (> 5 endpoints):
+
+> Contract created. Consider running `/compact` to free context before the next task.
+
+Skip if autopilot is ON.
+
+---
+
+## Brain Capture
+
+After contract creation completes, append a brain-capture block. See `.claude/resources/core/brain-capture.md` for processing rules.
+
+**Capture the following**:
+
+```
+<!-- brain-capture
+skill: create-contract
+feature: [service name]
+status: completed
+data:
+  service_name: [API/service name]
+  endpoints_documented: [count]
+  auth_type: [detected auth type]
+  contract_doc: [path to contract document]
+-->
+```
+
+Update `flow/brain/features/[service-name].md` with contract context and update `flow/brain/index.md`.
+
+---
+
+## Resource Capture
+
+During this skill's execution, watch for valuable reference materials worth preserving. See `.claude/resources/core/resource-capture.md` for capture rules, file format, and naming conventions.
+
+At natural break points, if you encounter information that could be useful for future development (API specs, architecture notes, config references, domain knowledge, etc.), ask the user: "I found something that could be useful for future reference: _{brief description}_. Should I save it to `flow/resources/`?"
+
+Only save if the user approves. Do not re-ask if declined.
+

package/.claude/commands/create-plan.md

@@ -64,6 +64,13 @@ RELATED COMMANDS:
 > - **If YES**: Autopilot is ON. After creating the plan and getting user approval, **auto-proceed** to `/execute-plan` with the plan output. Do NOT wait for manual invocation.
 > - **If NO**: Follow the standard rules below (stop and wait for user).
 
+> **MODE: Research**
+> Explore before concluding. Read 3x more than you write. Prefer Read/Grep/Glob/WebSearch tools.
+> Ask clarifying questions when uncertain. Don't jump to implementation.
+
+> **AGENT_PROFILE: read-only**
+> See `.claude/resources/core/agent-profiles.md` for tool access rules.
+
 ## Critical Rules
 
 | Rule                     | Description                                              |
@@ -293,3 +300,62 @@ When executing this command:
 | `/discovery-plan` command   | Run discovery first               |
 | `/execute-plan` command     | Execute the created plan          |
 
+---
+
+## Compaction Suggestion
+
+After plan creation completes, suggest context cleanup:
+
+> Plan created. Consider running `/compact` before execution to maximize available context for the implementation phases.
+
+Only suggest if the plan has > 3 phases. Skip if autopilot is ON.
+
+---
+
+## Brain Capture
+
+After plan creation completes successfully, append a brain-capture block. See `.claude/resources/core/brain-capture.md` for processing rules.
+
+**Capture the following**:
+
+```
+<!-- brain-capture
+skill: create-plan
+feature: [feature name]
+status: completed
+data:
+  phase_count: [number of phases]
+  total_complexity: [sum of complexity scores]
+  highest_phase: [phase name with highest score]
+  discovery_link: [[discovery-feature-name]]
+  plan_doc: [path to plan document]
+-->
+```
+
+Update `flow/brain/features/[feature-name].md` with plan details and link to discovery entry.
+
+---
+
+## Resource Capture
+
+During this skill's execution, watch for valuable reference materials worth preserving. See `.claude/resources/core/resource-capture.md` for capture rules, file format, and naming conventions.
+
+At natural break points, if you encounter information that could be useful for future development (API specs, architecture notes, config references, domain knowledge, etc.), ask the user: "I found something that could be useful for future reference: _{brief description}_. Should I save it to `flow/resources/`?"
+
+Only save if the user approves. Do not re-ask if declined.
+
+---
+
+## Handoff
+
+### Consumption
+
+Before creating the plan, check for `flow/handoffs/handoff_<feature>_discovery_to_plan.md` (or `handoff_<feature>_review_to_plan.md` for bugfix workflow). If it exists, read it silently and use its focus guidance to inform plan structure. If it doesn't exist, proceed normally (backward compatible).
+
+### Production
+
+After the plan is created, produce a handoff for the execution step.
+
+**Output**: `flow/handoffs/handoff_<feature>_plan_to_execute.md`
+
+Include: feature name, workflow type, phase count, total complexity, highest complexity phase, plan and discovery paths, and focus guidance for execution.

package/.claude/commands/discovery-plan.md

@@ -18,6 +18,13 @@ This command creates a discovery document for gathering and clarifying requireme
 > - **If YES**: Autopilot is ON. After completing discovery and user Q&A, **auto-proceed** to `/create-plan` with the discovery output. Do NOT ask "Would you like to proceed?" - just continue.
 > - **If NO**: Follow the standard rules below (stop and wait for user).
 
+> **MODE: Research**
+> Explore before concluding. Read 3x more than you write. Prefer Read/Grep/Glob/WebSearch tools.
+> Ask clarifying questions when uncertain. Don't jump to implementation.
+
+> **AGENT_PROFILE: read-only**
+> See `.claude/resources/core/agent-profiles.md` for tool access rules.
+
 > ⚠️ **IMPORTANT - DISCOVERY ONLY**
 >
 > This command ONLY creates a discovery document. It does NOT:
@@ -66,8 +73,9 @@ WORKFLOW:
   4. Documents requirements (FR, NFR, Constraints)
   5. Proposes high-level approach (no code)
   6. Creates discovery document for review
-  7. Asks user if they want to proceed to /create-plan
-  8. Waits for user confirmation before proceeding
+  7. Asks user if they want to proceed, refine, or stop
+  8. Supports iterative refinement (max 3 rounds)
+  9. Waits for user confirmation before proceeding
 
 RECOMMENDED MODEL:
   Claude Opus 4.6 or Sonnet 4.5 for best results
@@ -121,6 +129,24 @@ To start the discovery process, I need to understand:
 
 ---
 
+### Step 1.5: Search for Existing Solutions
+
+**Before recommending implementation**, check if the problem is already solved:
+
+1. **Project code**: Use Grep/Glob to search for existing implementations, similar patterns, or utilities that already address part of the requirement
+2. **Package registries**: Use WebSearch to check npm (for JS/TS projects) or PyPI (for Python projects) for established libraries
+   - Search: `"{problem description} npm package"` or `"{problem description} python library"`
+   - Evaluate: maintenance status (last publish date), weekly downloads, compatibility with project stack
+3. **Document findings** in an "Existing Solutions Analysis" section in the discovery document
+
+**Decision criteria**:
+- If an existing library covers **>80%** of the need → recommend using it instead of building from scratch
+- If **<80%** → note what it covers and what custom work remains
+
+**Graceful degradation**: If WebSearch is unavailable, skip registry search and note "Package registry search skipped — WebSearch unavailable" in the discovery document. Always perform the project code search.
+
+---
+
 ### Step 2: Extract Feature Name
 
 From the user input, extract or derive a feature name for the discovery document.
@@ -155,8 +181,9 @@ The skill will:
 7. Propose high-level approach
 8. Document risks and unknowns
 9. Generate discovery document
-10. Ask user if they want to proceed to /create-plan
-11. Wait for user confirmation before proceeding
+10. Support iterative refinement (max 3 rounds) if user requests it
+11. Ask user if they want to proceed to /create-plan
+12. Wait for user confirmation before proceeding
 
 See: `.claude/resources/skills/discovery-skill.md`
 
@@ -193,7 +220,7 @@ AskUserQuestion({
     options: [
       { label: "Yes, create plan", description: "I'll invoke /create-plan with the discovery document" },
       { label: "No, review first", description: "You can review the discovery and invoke /create-plan when ready" },
-      { label: "Refine discovery", description: "Let me know what needs to be adjusted in the discovery" }
+      { label: "Refine discovery", description: "Iteratively refine the discovery document (max 3 rounds)" }
     ],
     multiSelect: false
   }]
@@ -204,6 +231,31 @@ AskUserQuestion({
 
 Do NOT auto-invoke `/create-plan` without user confirmation.
 
+#### Refinement Loop (when "Refine discovery" is selected)
+
+When the user selects "Refine discovery", invoke the discovery skill's **Step 9: Refinement Loop**:
+
+1. **Accept feedback**: Ask user what areas need adjustment (requirements, approach, scope, risks)
+2. **Follow-up questions**: Ask 1-3 targeted questions about the refinement areas only
+3. **Update document**: Modify the discovery document in-place, add/update Refinement History section
+4. **Re-present**: Show the updated document and offer the same 3 options again
+5. **Round tracking**: Track refinement round count (max 3). After 3 rounds, only offer "Yes, create plan" and "No, review first" — the "Refine discovery" option is removed
+
+```typescript
+// After 3 refinement rounds, remove the refine option:
+AskUserQuestion({
+  questions: [{
+    question: "Discovery refined 3 times (maximum). Would you like to proceed?",
+    header: "Next step",
+    options: [
+      { label: "Yes, create plan", description: "I'll invoke /create-plan with the discovery document" },
+      { label: "No, stop here", description: "You can review and invoke /create-plan manually when ready" }
+    ],
+    multiSelect: false
+  }]
+})
+```
+
 ---
 
 ## Flow Diagram
@@ -323,3 +375,59 @@ Read: resources/tools/interactive-questions-tool.md (lines from TLS-IQ-3)
 | `interactive-questions-tool.md` | Interactive Questions UI workflow    |
 | `/create-plan` command         | Creates plan from discovery document   |
 
+---
+
+## Compaction Suggestion
+
+After discovery completes, suggest context cleanup:
+
+> Discovery complete. Consider running `/compact` before creating a plan to free context for the planning phase.
+
+Only suggest if the discovery was substantial (> 5 requirements gathered). Skip if autopilot is ON (context will be managed automatically).
+
+---
+
+## Brain Capture
+
+After discovery completes successfully, append a brain-capture block. See `.claude/resources/core/brain-capture.md` for processing rules.
+
+**Capture the following**:
+
+```
+<!-- brain-capture
+skill: discovery
+feature: [feature name from discovery]
+status: completed
+data:
+  user_prompt: [original user request]
+  questions_asked: [count]
+  questions_answered: [count]
+  requirements_fr: [count of functional requirements]
+  requirements_nfr: [count of non-functional requirements]
+  discovery_doc: [path to discovery document]
+-->
+```
+
+Write/update `flow/brain/features/[feature-name].md` with discovery context and update `flow/brain/index.md`.
+
+---
+
+## Resource Capture
+
+During this skill's execution, watch for valuable reference materials worth preserving. See `.claude/resources/core/resource-capture.md` for capture rules, file format, and naming conventions.
+
+At natural break points, if you encounter information that could be useful for future development (API specs, architecture notes, config references, domain knowledge, etc.), ask the user: "I found something that could be useful for future reference: _{brief description}_. Should I save it to `flow/resources/`?"
+
+Only save if the user approves. Do not re-ask if declined.
+
+---
+
+## Handoff Production
+
+After discovery completes, produce a handoff document for the next step. See `.claude/resources/patterns/handoff-patterns.md` [PTN-HND-1] for the template.
+
+**Output**: `flow/handoffs/handoff_<feature>_discovery_to_plan.md`
+
+Include: feature name, workflow type, requirements summary (FR/NFR/C counts), key decisions from Q&A, top risks, discovery doc path, and focus guidance for planning.
+
+Create the `flow/handoffs/` directory if it doesn't exist.