planflow-ai 1.0.7 → 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                                              |
@@ -111,7 +118,7 @@ The skill will:
 3. Ask clarifying questions via Interactive Questions Tool
 4. Generate contract document
 
-See: `.claude/rules/skills/create-contract-skill.md`
+See: `.claude/resources/skills/create-contract-skill.md`
 
 ---
 
@@ -204,9 +211,9 @@ This command uses hierarchical context loading to reduce context consumption. In
 
 | Index | When to Load |
 |-------|--------------|
-| `rules/patterns/_index.md` | To find contract patterns |
-| `rules/skills/_index.md` | To understand skill workflow |
-| `rules/tools/_index.md` | When using interactive questions |
+| `resources/patterns/_index.md` | To find contract patterns |
+| `resources/skills/_index.md` | To understand skill workflow |
+| `resources/tools/_index.md` | When using interactive questions |
 
 ### Reference Codes for Contract Creation
 
@@ -222,7 +229,7 @@ This command uses hierarchical context loading to reduce context consumption. In
 
 When executing this command:
 
-1. **Start with indexes**: Read `rules/patterns/_index.md` and `rules/skills/_index.md`
+1. **Start with indexes**: Read `resources/patterns/_index.md` and `resources/skills/_index.md`
 2. **Identify needed codes**: Based on current step, identify which codes are relevant
 3. **Expand as needed**: Use the Read tool with specific line ranges from the index
 4. **Don't expand everything**: Only load content required for the current step
@@ -233,9 +240,9 @@ When executing this command:
 
 | Resource                       | Purpose                                |
 | ------------------------------ | -------------------------------------- |
-| `rules/skills/_index.md`      | Index of skills with reference codes   |
-| `rules/patterns/_index.md`    | Index of patterns with reference codes |
-| `rules/tools/_index.md`       | Index of tools with reference codes    |
+| `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    |
 | `create-contract-skill.md`    | Skill that creates the contract        |
 | `contract-patterns.md`        | Rules and patterns for contracts       |
 | `interactive-questions-tool.md` | Interactive Questions UI workflow    |
@@ -244,225 +251,44 @@ When executing this command:
 
 ---
 
-# Implementation Details
-
-
-## Restrictions - CONTRACT CREATION ONLY
-
-This skill is **strictly for creating contract documents**. The process:
-
-1. **Fetches** information from the source URL
-2. **Analyzes** the API structure and schemas
-3. **Asks** clarifying questions via Interactive Questions Tool
-4. **Generates** a contract markdown file
-
-**No code, no implementation, no source file modifications.**
-
-### NEVER Do These Actions
-
-| Forbidden Action                       | Reason                              |
-| -------------------------------------- | ----------------------------------- |
-| Create/edit source code files          | Contract creation only              |
-| Write implementation code              | Contracts describe, not implement   |
-| Modify configuration files             | No codebase changes                 |
-| Run build or test commands             | No execution commands               |
-| Create files outside `flow/contracts/` | Only write contract documents       |
-
-### Allowed Actions
-
-| Allowed Action                         | Purpose                              |
-| -------------------------------------- | ------------------------------------ |
-| Use Web Search tool                    | Fetch documentation from URLs        |
-| Read repository files                  | Analyze API structure                |
-| Use Interactive Questions Tool         | Gather requirements from user        |
-| Write to `flow/contracts/`             | Save contract document               |
-| Read project rule files                | Understand patterns to follow        |
-
-> **Important**: The ONLY writable location is `flow/contracts/`. No source code or other files should be modified.
-
----
-
-## Inputs
-
-| Input         | Required | Description                                          |
-| ------------- | -------- | ---------------------------------------------------- |
-| `source_url`  | Yes      | Documentation URL or repository URL                  |
-| `description` | Yes      | What the user wants to integrate on the frontend     |
-
----
-
-## Workflow
+## Compaction Suggestion
 
-### Step 1: Detect Source Type
+After contract creation completes, suggest context cleanup if the contract was complex (> 5 endpoints):
 
-Analyze the provided URL to determine the source type:
+> Contract created. Consider running `/compact` to free context before the next task.
 
-| Source Type      | Detection                                      |
-| ---------------- | ---------------------------------------------- |
-| Documentation    | Contains `/docs`, `/api`, swagger, openapi     |
-| Repository       | Contains github.com, gitlab.com, bitbucket.org |
-| OpenAPI Spec     | Ends with `.json`, `.yaml`, `/swagger`         |
+Skip if autopilot is ON.
 
 ---
 
-### Step 2A: Handle Documentation URL
-
-If the source is a documentation URL:
-
-1. Use Web Search tool to fetch documentation content
-2. Extract key information:
-   - API endpoints
-   - Request/response schemas
-   - Authentication methods
-   - Error formats
-   - Rate limits
-
----
-
-### Step 2B: Handle Repository URL
-
-If the source is a repository URL:
-
-1. Analyze repository structure
-2. Identify relevant files:
-   - API route definitions
-   - Type definitions
-   - Schema files
-   - README/docs
-3. Read and extract key information
-
----
-
-### Step 3: Ask Clarifying Questions
-
-**Use Interactive Questions Tool** to gather requirements.
+## Brain Capture
 
-Follow `.claude/rules/tools/interactive-questions-tool.md`:
+After contract creation completes, append a brain-capture block. See `.claude/resources/core/brain-capture.md` for processing rules.
 
-1. Call `SwitchMode` tool to enter Plan mode
-2. Call `Ask the user directly in conversation` tool for each question about:
-   - **Scope**: Which specific endpoints/features are needed?
-   - **Authentication**: How will the FE authenticate?
-   - **Error Handling**: How should the FE handle errors?
-   - **Caching**: Any caching requirements?
-3. Wait for all responses
-4. Call `SwitchMode` tool to return to Agent mode
-5. Document answers for use in the contract document
+**Capture the following**:
 
----
-
-### Step 4: Generate Contract Document
-
-Create the contract with all gathered information:
-
-**Location**: `flow/contracts/<service_name>_contract.md`
-
-**Required Sections**:
-
-1. Overview
-2. Authentication
-3. Endpoints (with request/response schemas)
-4. Error Handling
-5. Integration Notes
-6. Usage Examples
-
----
-
-## Output Format
-
-### Contract Template
-
-```markdown
-# Integration Contract: [Service Name]
-
-## Overview
-
-**Source**: [URL]
-**Description**: [What this integration provides]
-**Version**: [API version if applicable]
-
-## Authentication
-
-**Method**: [Bearer token, API key, OAuth, etc.]
-**Header**: [Authorization header format]
-**Token Source**: [Where FE gets the token]
-
-## Endpoints
-
-### [Endpoint Name]
-
-**Method**: [GET/POST/PUT/DELETE]
-**URL**: [Endpoint URL]
-**Description**: [What this endpoint does]
-
-**Request**:
-```typescript
-interface RequestBody {
-  // Request schema
-}
-```
-
-**Response**:
-```typescript
-interface Response {
-  // Response schema
-}
 ```
-
-**Example**:
-```bash
-curl -X POST /api/endpoint \
-  -H "Authorization: Bearer token" \
-  -d '{"field": "value"}'
+<!-- 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]
+-->
 ```
 
-## Error Handling
-
-| Status Code | Meaning              | FE Action                 |
-| ----------- | -------------------- | ------------------------- |
-| 400         | Bad Request          | Show validation error     |
-| 401         | Unauthorized         | Redirect to login         |
-| 404         | Not Found            | Show not found message    |
-| 500         | Server Error         | Show generic error        |
-
-## Integration Notes
-
-### Rate Limits
-[Any rate limiting information]
-
-### Caching
-[Caching recommendations]
-
-### Pagination
-[Pagination format if applicable]
-
-## Usage Examples
-
-### [Use Case 1]
-[Code example or description]
-```
+Update `flow/brain/features/[service-name].md` with contract context and update `flow/brain/index.md`.
 
 ---
 
-## Validation Checklist
+## Resource Capture
 
-Before completing the contract, verify:
+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.
 
-- [ ] Contract is saved in `flow/contracts/` folder
-- [ ] File uses naming: `<service_name>_contract.md`
-- [ ] All requested endpoints are documented
-- [ ] Authentication method is clear
-- [ ] Request/response schemas are defined
-- [ ] Error handling is documented
-- [ ] **NO implementation code is included**
-- [ ] **NO source files were created or modified**
-
----
+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/`?"
 
-## Related Files
+Only save if the user approves. Do not re-ask if declined.
 
-| File                                               | Purpose                           |
-| -------------------------------------------------- | --------------------------------- |
-| `.claude/rules/patterns/contract-patterns.md`     | Rules and patterns for contracts  |
-| `.claude/rules/tools/interactive-questions-tool.md` | Interactive Questions workflow  |
-| `flow/contracts/`                                  | Output folder for contracts       |