planflow-ai 1.4.1 → 1.4.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/.claude/commands/brainstorm.md +6 -14
  2. package/.claude/commands/create-contract.md +6 -38
  3. package/.claude/commands/create-plan.md +7 -38
  4. package/.claude/commands/discovery-plan.md +7 -49
  5. package/.claude/commands/execute-plan.md +11 -63
  6. package/.claude/commands/heartbeat.md +12 -14
  7. package/.claude/commands/learn.md +20 -80
  8. package/.claude/commands/note.md +6 -23
  9. package/.claude/commands/review-code.md +8 -51
  10. package/.claude/commands/review-pr.md +10 -57
  11. package/.claude/commands/setup.md +8 -56
  12. package/.claude/commands/write-tests.md +7 -41
  13. package/.claude/resources/core/phase-isolation.md +46 -1
  14. package/.claude/resources/core/shared-context.md +110 -0
  15. package/.claude/resources/core/wave-execution.md +79 -1
  16. package/.claude/resources/skills/execute-plan-skill.md +74 -13
  17. package/README.md +154 -96
  18. package/dist/cli/commands/brain.d.ts +20 -0
  19. package/dist/cli/commands/brain.d.ts.map +1 -0
  20. package/dist/cli/commands/brain.js +127 -0
  21. package/dist/cli/commands/brain.js.map +1 -0
  22. package/dist/cli/commands/init.d.ts.map +1 -1
  23. package/dist/cli/commands/init.js +9 -0
  24. package/dist/cli/commands/init.js.map +1 -1
  25. package/dist/cli/commands/state-query.d.ts +13 -0
  26. package/dist/cli/commands/state-query.d.ts.map +1 -0
  27. package/dist/cli/commands/state-query.js +32 -0
  28. package/dist/cli/commands/state-query.js.map +1 -0
  29. package/dist/cli/daemon/shared-context.d.ts +38 -0
  30. package/dist/cli/daemon/shared-context.d.ts.map +1 -0
  31. package/dist/cli/daemon/shared-context.js +129 -0
  32. package/dist/cli/daemon/shared-context.js.map +1 -0
  33. package/dist/cli/handlers/claude.d.ts.map +1 -1
  34. package/dist/cli/handlers/claude.js +18 -0
  35. package/dist/cli/handlers/claude.js.map +1 -1
  36. package/dist/cli/handlers/shared.js +1 -1
  37. package/dist/cli/handlers/shared.js.map +1 -1
  38. package/dist/cli/index.js +21 -0
  39. package/dist/cli/index.js.map +1 -1
  40. package/dist/cli/state/brain-query.d.ts +48 -0
  41. package/dist/cli/state/brain-query.d.ts.map +1 -0
  42. package/dist/cli/state/brain-query.js +113 -0
  43. package/dist/cli/state/brain-query.js.map +1 -0
  44. package/dist/cli/state/types.d.ts +31 -0
  45. package/dist/cli/state/types.d.ts.map +1 -1
  46. package/package.json +4 -1
  47. package/.claude/resources/core/_index.md +0 -347
  48. package/.claude/resources/languages/_index.md +0 -76
  49. package/.claude/resources/patterns/_index.md +0 -200
  50. package/.claude/resources/skills/_index.md +0 -287
  51. package/.claude/resources/tools/_index.md +0 -110
  52. package/.claude/resources/tools/reference-expansion-tool.md +0 -326
@@ -179,22 +179,15 @@ After the skill completes:
179
179
  +------------------------------------------+
180
180
  ```
181
181
 
182
- ---
183
-
184
- ## Context Optimization
185
-
186
- ### Recommended Loading Order
182
+ ## Context Loading
187
183
 
188
- 1. **Always load first**: This command file (`commands/brainstorm.md`)
189
- 2. **Expand on-demand**: Load skill file when entering conversational loop
184
+ This command uses the **brain index** for context retrieval. Before executing, query the project brain for relevant documentation:
190
185
 
191
- ### Reference Codes for Brainstorm
186
+ **Queries**:
187
+ - `planflow-ai state-query "brainstorm workflow" --scope resources`
188
+ - `planflow-ai state-query "interactive questions" --scope resources`
192
189
 
193
- | Code | Description | When to Expand |
194
- |------|-------------|----------------|
195
- | SKL-BS-1 | Brainstorm skill restrictions and inputs | Understanding allowed actions |
196
- | SKL-BS-2 | Conversational loop and tracking | During the brainstorm |
197
- | SKL-BS-3 | End detection, summary, and output | When wrapping up |
190
+ The brain returns ranked chunks from indexed markdown files. Use the top results to inform execution.
198
191
 
199
192
  ---
200
193
 
@@ -202,7 +195,6 @@ After the skill completes:
202
195
 
203
196
  | Resource | Purpose |
204
197
  |----------|---------|
205
- | `resources/skills/_index.md` | Index of skills with reference codes |
206
198
  | `brainstorm-skill.md` | Skill that runs the brainstorm |
207
199
  | `brainstorm-templates.md` | Output file template |
208
200
  | `/discovery-plan` command | Next step after brainstorm |
@@ -193,44 +193,15 @@ The user will read the `.md` file themselves and decide when to proceed.
193
193
  4. Present contract summary
194
194
  5. User reviews and proceeds to `/discovery-plan`
195
195
 
196
- ---
197
-
198
- ## Context Optimization
199
-
200
- This command uses hierarchical context loading to reduce context consumption. Instead of loading full files, load indexes first and expand specific sections on-demand.
201
-
202
- ### Recommended Loading Order
203
-
204
- 1. **Always load first**: This command file (`commands/create-contract.md`)
205
- 2. **Load indexes**: Load `_index.md` files for relevant folders
206
- 3. **Expand on-demand**: Use reference codes to load specific sections when needed
207
-
208
- ### Index Files for Contract Creation
209
-
210
- | Index | When to Load |
211
- |-------|--------------|
212
- | `resources/patterns/_index.md` | To find contract patterns |
213
- | `resources/skills/_index.md` | To understand skill workflow |
214
- | `resources/tools/_index.md` | When using interactive questions |
215
-
216
- ### Reference Codes for Contract Creation
217
-
218
- | Code | Description | When to Expand |
219
- |------|-------------|----------------|
220
- | PTN-CON-1 | Contract document structure | Creating new contract |
221
- | PTN-CON-2 | Endpoint documentation format | Documenting API endpoints |
222
- | SKL-CON-1 | Contract skill workflow | Understanding full process |
223
- | TLS-IQ-2 | How to switch to Plan mode | Before asking questions |
224
- | TLS-IQ-3 | How to ask questions | When gathering scope info |
196
+ ## Context Loading
225
197
 
226
- ### Expansion Instructions
198
+ This command uses the **brain index** for context retrieval. Before executing, query the project brain for relevant documentation:
227
199
 
228
- When executing this command:
200
+ **Queries**:
201
+ - `planflow-ai state-query "contract creation" --scope resources`
202
+ - `planflow-ai state-query "contract patterns" --scope resources`
229
203
 
230
- 1. **Start with indexes**: Read `resources/patterns/_index.md` and `resources/skills/_index.md`
231
- 2. **Identify needed codes**: Based on current step, identify which codes are relevant
232
- 3. **Expand as needed**: Use the Read tool with specific line ranges from the index
233
- 4. **Don't expand everything**: Only load content required for the current step
204
+ The brain returns ranked chunks from indexed markdown files. Use the top results to inform execution.
234
205
 
235
206
  ---
236
207
 
@@ -238,9 +209,6 @@ When executing this command:
238
209
 
239
210
  | Resource | Purpose |
240
211
  | ------------------------------ | -------------------------------------- |
241
- | `resources/skills/_index.md` | Index of skills with reference codes |
242
- | `resources/patterns/_index.md` | Index of patterns with reference codes |
243
- | `resources/tools/_index.md` | Index of tools with reference codes |
244
212
  | `create-contract-skill.md` | Skill that creates the contract |
245
213
  | `contract-patterns.md` | Rules and patterns for contracts |
246
214
  | `interactive-questions-tool.md` | Interactive Questions UI workflow |
@@ -221,44 +221,16 @@ The user will read the `.md` file themselves and decide when to proceed.
221
221
  5. Present plan summary
222
222
  6. User reviews and proceeds to `/execute-plan`
223
223
 
224
- ---
225
-
226
- ## Context Optimization
227
-
228
- This command uses hierarchical context loading to reduce context consumption. Instead of loading full files, load indexes first and expand specific sections on-demand.
229
-
230
- ### Recommended Loading Order
231
-
232
- 1. **Always load first**: This command file (`commands/create-plan.md`)
233
- 2. **Load indexes**: Load `_index.md` files for relevant folders
234
- 3. **Expand on-demand**: Use reference codes to load specific sections when needed
235
-
236
- ### Index Files for Plan Creation
237
-
238
- | Index | When to Load |
239
- |-------|--------------|
240
- | `resources/patterns/_index.md` | To find plan patterns and templates |
241
- | `resources/skills/_index.md` | To understand skill workflow |
242
- | `resources/core/_index.md` | For complexity scoring reference |
243
-
244
- ### Reference Codes for Plan Creation
245
-
246
- | Code | Description | When to Expand |
247
- |------|-------------|----------------|
248
- | PTN-PLN-1 | Plan document structure | Creating new plan |
249
- | PTN-PLN-2 | Phase organization | Structuring phases |
250
- | PTN-PLNT-1 | Plan template | Creating output file |
251
- | SKL-PLN-1 | Create plan skill workflow | Understanding full process |
252
- | COR-CS-1 | Complexity scoring table | Assigning complexity scores |
224
+ ## Context Loading
253
225
 
254
- ### Expansion Instructions
226
+ This command uses the **brain index** for context retrieval. Before executing, query the project brain for relevant documentation:
255
227
 
256
- When executing this command:
228
+ **Queries**:
229
+ - `planflow-ai state-query "plan creation" --scope resources`
230
+ - `planflow-ai state-query "complexity scoring" --scope resources`
231
+ - `planflow-ai state-query "phase structure" --scope resources`
257
232
 
258
- 1. **Start with indexes**: Read `resources/patterns/_index.md` and `resources/core/_index.md`
259
- 2. **Identify needed codes**: Based on current step, identify which codes are relevant
260
- 3. **Expand as needed**: Use the Read tool with specific line ranges from the index
261
- 4. **Don't expand everything**: Only load content required for the current step
233
+ The brain returns ranked chunks from indexed markdown files. Use the top results to inform execution.
262
234
 
263
235
  ---
264
236
 
@@ -266,9 +238,6 @@ When executing this command:
266
238
 
267
239
  | Resource | Purpose |
268
240
  | --------------------------- | --------------------------------- |
269
- | `resources/skills/_index.md` | Index of skills with reference codes |
270
- | `resources/patterns/_index.md` | Index of patterns with reference codes |
271
- | `resources/core/_index.md` | Index of core rules with reference codes |
272
241
  | `create-plan-skill.md` | Skill that creates the plan |
273
242
  | `plans-patterns.md` | Rules and patterns for plans |
274
243
  | `plans-templates.md` | Plan templates |
@@ -248,55 +248,16 @@ The user will read the `.md` file themselves and decide when to proceed.
248
248
  6. User reviews and requests refinements (if any)
249
249
  7. User invokes `/create-plan` when ready
250
250
 
251
- ---
252
-
253
- ## Context Optimization
254
-
255
- This command uses hierarchical context loading to reduce context consumption. Instead of loading full files, load indexes first and expand specific sections on-demand.
256
-
257
- ### Recommended Loading Order
258
-
259
- 1. **Always load first**: This command file (`commands/discovery-plan.md`)
260
- 2. **Load indexes**: Load `_index.md` files for relevant folders
261
- 3. **Expand on-demand**: Use reference codes to load specific sections when needed
262
-
263
- ### Index Files for Discovery
264
-
265
- | Index | When to Load |
266
- |-------|--------------|
267
- | `resources/patterns/_index.md` | To find discovery templates and patterns |
268
- | `resources/skills/_index.md` | To understand skill workflow |
269
- | `resources/tools/_index.md` | When using interactive questions |
251
+ ## Context Loading
270
252
 
271
- ### Reference Codes for Discovery
253
+ This command uses the **brain index** for context retrieval. Before executing, query the project brain for relevant documentation:
272
254
 
273
- | Code | Description | When to Expand |
274
- |------|-------------|----------------|
275
- | PTN-DIS-1 | Discovery document structure | Creating new discovery doc |
276
- | PTN-DIS-2 | Requirements gathering example | Need example format |
277
- | PTN-DIST-1 | Discovery template | Creating output file |
278
- | SKL-DIS-1 | Discovery skill workflow | Understanding full process |
279
- | TLS-IQ-2 | How to switch to Plan mode | Before asking questions |
280
- | TLS-IQ-3 | How to ask questions | When gathering requirements |
281
- | COR-CG-1 | Compaction guide | Load when compacting mid-discovery |
255
+ **Queries**:
256
+ - `planflow-ai state-query "discovery workflow" --scope resources`
257
+ - `planflow-ai state-query "requirements gathering" --scope resources`
258
+ - `planflow-ai state-query "codebase analysis" --scope resources`
282
259
 
283
- ### Expansion Instructions
284
-
285
- When executing this command:
286
-
287
- 1. **Start with indexes**: Read `resources/patterns/_index.md` and `resources/skills/_index.md`
288
- 2. **Identify needed codes**: Based on current step, identify which codes are relevant
289
- 3. **Expand as needed**: Use the Read tool with specific line ranges from the index
290
- 4. **Don't expand everything**: Only load content required for the current step
291
-
292
- **Example expansion**:
293
- ```
294
- # To get the discovery template
295
- Read: resources/patterns/discovery-templates.md (lines from PTN-DIST-1)
296
-
297
- # To understand question workflow
298
- Read: resources/tools/interactive-questions-tool.md (lines from TLS-IQ-3)
299
- ```
260
+ The brain returns ranked chunks from indexed markdown files. Use the top results to inform execution.
300
261
 
301
262
  ---
302
263
 
@@ -304,9 +265,6 @@ Read: resources/tools/interactive-questions-tool.md (lines from TLS-IQ-3)
304
265
 
305
266
  | Resource | Purpose |
306
267
  | ------------------------------ | -------------------------------------- |
307
- | `resources/skills/_index.md` | Index of skills with reference codes |
308
- | `resources/patterns/_index.md` | Index of patterns with reference codes |
309
- | `resources/tools/_index.md` | Index of tools with reference codes |
310
268
  | `discovery-skill.md` | Skill that executes the discovery |
311
269
  | `discovery-patterns.md` | Rules and patterns for discovery |
312
270
  | `discovery-templates.md` | Document templates |
@@ -349,67 +349,18 @@ Execution Complete!
349
349
  5. Final build and test verification
350
350
  6. Auto-archive plan and discovery to flow/archive/
351
351
 
352
- ---
352
+ ## Context Loading
353
+
354
+ This command uses the **brain index** for context retrieval. Before executing, query the project brain for relevant documentation:
355
+
356
+ **Queries**:
357
+ - `planflow-ai state-query "phase execution" --scope resources`
358
+ - `planflow-ai state-query "wave execution" --scope resources`
359
+ - `planflow-ai state-query "phase isolation" --scope resources`
360
+ - `planflow-ai state-query "per-task verification" --scope resources`
361
+ - `planflow-ai state-query "atomic commits" --scope resources`
353
362
 
354
- ## Context Optimization
355
-
356
- This command uses hierarchical context loading to reduce context consumption. Instead of loading full files, load indexes first and expand specific sections on-demand.
357
-
358
- ### Recommended Loading Order
359
-
360
- 1. **Always load first**: This command file (`commands/execute-plan.md`)
361
- 2. **Load indexes**: Load `_index.md` files for relevant folders
362
- 3. **Expand on-demand**: Use reference codes to load specific sections when needed
363
-
364
- ### Index Files for Plan Execution
365
-
366
- | Index | When to Load |
367
- |-------|--------------|
368
- | `resources/skills/_index.md` | To understand execution workflow |
369
- | `resources/core/_index.md` | For complexity scoring reference |
370
- | `resources/tools/_index.md` | When switching to Plan mode |
371
-
372
- ### Reference Codes for Plan Execution
373
-
374
- | Code | Description | When to Expand |
375
- |------|-------------|----------------|
376
- | SKL-EXEC-2 | Critical rules (build, DB) | Need build/DB command restrictions |
377
- | SKL-EXEC-4 | Analyze complexity | Determining execution strategy |
378
- | SKL-EXEC-6 | Execute phase with Plan mode | Running a specific phase |
379
- | SKL-EXEC-8 | Phase-boundary compaction | Compacting between phases |
380
- | SKL-EXEC-9 | Handle tests phase | Executing the tests phase |
381
- | SKL-EXEC-10 | Build and test verification | Final verification step |
382
- | SKL-EXEC-11 | Complexity-based behavior | Need low/medium/high behavior details |
383
- | SKL-EXEC-12 | Error handling | Build/test failure or cancellation |
384
- | COR-CS-1 | Complexity scoring table | Interpreting phase complexity |
385
- | TLS-PLN-1 | Plan mode switching | Before each phase |
386
- | TLS-PLN-2 | Plan mode workflow | Presenting phase details |
387
- | COR-CG-1 | Compaction guide purpose | When compacting at phase boundaries |
388
- | COR-CG-2 | Preserve rules | Crafting compact summary — what to keep |
389
- | COR-CG-3 | Discard rules | Crafting compact summary — what to drop |
390
- | COR-CG-4 | Compact summary template | Structuring compact instructions |
391
- | COR-PI-1 | Phase isolation architecture | Understanding isolated sub-agent flow |
392
- | COR-PI-2 | Sub-agent context template | Preparing focused prompt for sub-agent |
393
- | COR-PI-3 | Return format schema | Parsing sub-agent JSON response |
394
- | COR-PI-4 | Coordinator processing rules | Handling success/failure/partial returns |
395
- | COR-WAVE-1 | Wave execution architecture and dependency syntax | Need wave execution architecture or dependency declaration syntax |
396
- | COR-WAVE-2 | Wave grouping algorithm (topological sort) | Need wave grouping algorithm or backward compatibility rules |
397
- | COR-WAVE-3 | Parallel spawning rules and wave summary format | Need parallel spawning rules or wave execution summary format |
398
- | COR-WAVE-4 | Wave coordinator behavior and failure handling | Need wave coordinator behavior, file conflict detection, or failure handling |
399
- | COR-WAVE-5 | Wave execution configuration and interaction matrix | Need wave execution configuration, interaction matrix, or aggregation rules |
400
- | COR-PTV-1 | Per-task verification architecture and verify tag syntax | Need verification system overview or `<verify>` tag parsing rules |
401
- | COR-PTV-2 | Debug sub-agent prompt template and return schema | Need debug sub-agent configuration or diagnosis JSON format |
402
- | COR-PTV-3 | Verification loop flow and retry behavior | Need verification loop details or retry/escalation rules |
403
- | COR-PTV-4 | Task verifications JSON return field schema | Need `task_verifications` array format or field descriptions |
404
-
405
- ### Expansion Instructions
406
-
407
- When executing this command:
408
-
409
- 1. **Start with indexes**: Read `resources/skills/_index.md` and `resources/core/_index.md`
410
- 2. **Identify needed codes**: Based on current phase, identify which codes are relevant
411
- 3. **Expand as needed**: Use the Read tool with specific line ranges from the index
412
- 4. **Don't expand everything**: Only load content required for the current phase
363
+ The brain returns ranked chunks from indexed markdown files. Use the top results to inform execution.
413
364
 
414
365
  ---
415
366
 
@@ -417,9 +368,6 @@ When executing this command:
417
368
 
418
369
  | Resource | Purpose |
419
370
  | -------------------------- | --------------------------------- |
420
- | `resources/skills/_index.md` | Index of skills with reference codes |
421
- | `resources/core/_index.md` | Index of core rules with reference codes |
422
- | `resources/tools/_index.md` | Index of tools with reference codes |
423
371
  | `per-task-verification.md` | Per-task verification system, debug sub-agents, JSON schemas |
424
372
  | `execute-plan-skill.md` | Skill that executes the plan |
425
373
  | `plans-patterns.md` | Rules and patterns for plans |
@@ -93,19 +93,6 @@ RELATED COMMANDS:
93
93
  1. Read `flow/heartbeat.md`
94
94
  2. Display all tasks with their schedule, status, and description
95
95
 
96
- ---
97
-
98
- ## Context Optimization
99
-
100
- ### Reference Codes for Heartbeat
101
-
102
- | Code | Description | When to Expand |
103
- |------|-------------|----------------|
104
- | COR-HB-1 | Heartbeat file format and schedule syntax | Creating or editing heartbeat tasks |
105
- | COR-HB-2 | Daemon architecture and CLI commands | Starting/stopping the daemon |
106
-
107
- ---
108
-
109
96
  ## Brain Capture
110
97
 
111
98
  <!-- brain-capture
@@ -117,9 +104,20 @@ captures:
117
104
 
118
105
  ---
119
106
 
107
+ ## Context Loading
108
+
109
+ This command uses the **brain index** for context retrieval. Before executing, query the project brain for relevant documentation:
110
+
111
+ **Queries**:
112
+ - `planflow-ai state-query "heartbeat daemon" --scope resources`
113
+ - `planflow-ai state-query "scheduled tasks" --scope resources`
114
+
115
+ The brain returns ranked chunks from indexed markdown files. Use the top results to inform execution.
116
+
117
+ ---
118
+
120
119
  ## Related Resources
121
120
 
122
121
  | Resource | Purpose |
123
122
  |----------|---------|
124
123
  | `resources/core/heartbeat.md` | File format rules and daemon architecture |
125
- | `resources/core/_index.md` | Index of core rules with reference codes |
@@ -76,7 +76,7 @@ TEACHING MODE (/learn about <topic>):
76
76
  Completed curricula are saved globally and reused across projects.
77
77
 
78
78
  Output: ~/plan-flow/brain/learns/{topic-kebab}.md (global)
79
- Index: ~/plan-flow/brain/learns/_index.md (LRN-* codes)
79
+ Index: Indexed via brain query system (searchable with state-query)
80
80
 
81
81
  RELATED COMMANDS:
82
82
  /note Capture meeting notes, ideas, brainstorms
@@ -248,7 +248,7 @@ Before designing the curriculum:
248
248
 
249
249
  1. **Use web search** to get up-to-date information (official docs, latest version, recent changes)
250
250
  2. **Read the project's stack** from `flow/brain/index.md` and `flow/references/tech-foundation.md`
251
- 3. **Check existing learns** at `~/plan-flow/brain/learns/_index.md` — if the topic already exists, offer to resume, expand, or start fresh
251
+ 3. **Check existing learns** via `planflow-ai state-query "{topic}" --scope learns` — if the topic already exists, offer to resume, expand, or start fresh
252
252
 
253
253
  ### Step 3: Design an Adaptive Curriculum
254
254
 
@@ -305,7 +305,7 @@ After all steps are confirmed (or user stops early):
305
305
 
306
306
  **For general knowledge / concept:**
307
307
  1. Save to `~/plan-flow/brain/learns/{topic-kebab}.md`
308
- 2. Auto-index with `LRN-*` codes in `~/plan-flow/brain/learns/_index.md`
308
+ 2. Auto-indexed by the brain query system (searchable via `planflow-ai state-query`)
309
309
  3. Update `flow/brain/index.md` with `## Global Learns` section
310
310
 
311
311
  **For project implementation:**
@@ -370,65 +370,15 @@ After all steps are confirmed (or user stops early):
370
370
  - [[{project-name}]]
371
371
  ```
372
372
 
373
- ### Learns Index Template (`~/plan-flow/brain/learns/_index.md`)
373
+ ### Learns Index
374
374
 
375
- ```markdown
376
- # Global Learns Index
377
-
378
- ## Overview
379
-
380
- Shared learning curricula accumulated across all projects. Use reference codes to load specific sections on-demand.
381
-
382
- **Total Files**: X files
383
- **Reference Codes**: LRN-{ABBR}-1 through LRN-{ABBR}-N
384
- **Last Updated**: YYYY-MM-DD
385
-
386
- ---
387
-
388
- ## Reference Codes
389
-
390
- ### MCP (`mcp.md`)
391
-
392
- | Code | Description | Lines |
393
- |------|-------------|-------|
394
- | LRN-MCP-1 | What is MCP and why it matters | 10-35 |
395
- | LRN-MCP-2 | MCP server architecture | 36-70 |
396
- | LRN-MCP-3 | Building your first MCP server | 71-120 |
375
+ Learns are automatically indexed by the brain query system. Query existing curricula with:
397
376
 
398
- ---
399
-
400
- ## When to Expand
401
-
402
- | Code | Expand When |
403
- |------|-------------|
404
- | LRN-MCP-1 | Need to understand MCP fundamentals |
405
- | LRN-MCP-2 | Designing an MCP server |
406
-
407
- ---
408
-
409
- ## Projects Using Learns
410
-
411
- | Learn | Projects |
412
- |-------|----------|
413
- | mcp | [[project-1]], [[project-2]] |
377
+ ```
378
+ planflow-ai state-query "{topic}" --scope learns
414
379
  ```
415
380
 
416
- ### Reference Code Convention for Learns
417
-
418
- | Learn File | Code Prefix | Example Codes |
419
- |---|---|---|
420
- | `mcp.md` | `LRN-MCP` | LRN-MCP-1, LRN-MCP-2, LRN-MCP-3 |
421
- | `docker.md` | `LRN-DK` | LRN-DK-1, LRN-DK-2 |
422
- | `graphql.md` | `LRN-GQ` | LRN-GQ-1, LRN-GQ-2 |
423
- | Other `<name>.md` | `LRN-XX` | Use first 2-3 consonants or unique abbreviation |
424
-
425
- ### Reference Codes for Teaching
426
-
427
- | Code | Description | When to Expand |
428
- |------|-------------|----------------|
429
- | SKL-LRN-3 | Teaching mode restrictions and workflow | Starting teaching mode |
430
- | SKL-LRN-4 | Curriculum template and global storage | Generating curriculum |
431
- | SKL-LRN-5 | Learns index template and LRN-* code convention | Updating learns index |
381
+ Learns are stored at `~/plan-flow/brain/learns/{topic-kebab}.md` and automatically discoverable via brain queries. No manual index maintenance required.
432
382
 
433
383
  ---
434
384
 
@@ -471,25 +421,6 @@ Teach step by step (adaptive: skip / deep dive / tangent / rephrase)
471
421
  Save to ~/plan-flow/brain/learns/ → Auto-index LRN-* codes → Link to project
472
422
  ```
473
423
 
474
- ---
475
-
476
- ## Context Optimization
477
-
478
- ### Recommended Loading Order
479
-
480
- 1. **Always load first**: This command file (`commands/learn.md`)
481
- 2. **Load indexes**: Load `_index.md` files for relevant folders
482
- 3. **Expand on-demand**: Use reference codes to load specific sections when needed
483
-
484
- ### Reference Codes for Learn
485
-
486
- | Code | Description | When to Expand |
487
- |------|-------------|----------------|
488
- | SKL-LRN-1 | Purpose, restrictions, and extraction criteria | Understanding what to extract |
489
- | SKL-LRN-2 | Workflow, output format, and validation | Processing and saving patterns |
490
-
491
- ---
492
-
493
424
  ## Brain Capture
494
425
 
495
426
  <!-- brain-capture
@@ -507,11 +438,20 @@ During pattern extraction, if you encounter valuable reference materials (API sp
507
438
 
508
439
  ---
509
440
 
441
+ ## Context Loading
442
+
443
+ This command uses the **brain index** for context retrieval. Before executing, query the project brain for relevant documentation:
444
+
445
+ **Queries**:
446
+ - `planflow-ai state-query "learn skill" --scope resources`
447
+ - `planflow-ai state-query "pattern extraction" --scope resources`
448
+
449
+ The brain returns ranked chunks from indexed markdown files. Use the top results to inform execution.
450
+
451
+ ---
452
+
510
453
  ## Related Resources
511
454
 
512
455
  | Resource | Purpose |
513
456
  | --------------------------- | --------------------------------- |
514
- | `resources/skills/_index.md` | Index of skills with reference codes |
515
457
  | `resources/skills/learn-skill.md` | Detailed skill implementation |
516
- | `resources/patterns/_index.md` | Index of patterns with reference codes |
517
- | `resources/core/_index.md` | Index of core rules with reference codes |
@@ -208,29 +208,15 @@ Brain entry captured!
208
208
  +------------------------------------------+
209
209
  ```
210
210
 
211
- ---
212
-
213
- ## Context Optimization
214
-
215
- ### Recommended Loading Order
211
+ ## Context Loading
216
212
 
217
- 1. **Always load first**: This command file (`commands/note.md`)
218
- 2. **Load indexes**: Load `_index.md` files for relevant folders
219
- 3. **Expand on-demand**: Use reference codes to load specific sections when needed
213
+ This command uses the **brain index** for context retrieval. Before executing, query the project brain for relevant documentation:
220
214
 
221
- ### Reference Codes for Brain
215
+ **Queries**:
216
+ - `planflow-ai state-query "brain capture" --scope resources`
217
+ - `planflow-ai state-query "brain patterns" --scope resources`
222
218
 
223
- | Code | Description | When to Expand |
224
- |------|-------------|----------------|
225
- | SKL-BR-1 | Brain skill restrictions | Understanding allowed actions |
226
- | SKL-BR-2 | Brain skill workflow | Processing entries |
227
- | SKL-BR-3 | Output format and validation | Formatting output |
228
- | PTN-BR-1 | Directory structure and naming | Creating brain files |
229
- | PTN-BR-2 | Wiki-link patterns | Creating cross-references |
230
- | PTN-BR-3 | Feature status lifecycle | Updating feature entries |
231
- | COR-BR-1 | Session start behavior | Understanding brain loading |
232
- | COR-BR-2 | File templates | Creating new brain files |
233
- | COR-BR-3 | Index management caps | Enforcing index limits |
219
+ The brain returns ranked chunks from indexed markdown files. Use the top results to inform execution.
234
220
 
235
221
  ---
236
222
 
@@ -238,9 +224,6 @@ Brain entry captured!
238
224
 
239
225
  | Resource | Purpose |
240
226
  | --------------------------- | --------------------------------- |
241
- | `resources/skills/_index.md` | Index of skills with reference codes |
242
- | `resources/patterns/_index.md` | Index of patterns with reference codes |
243
- | `resources/core/_index.md` | Index of core rules with reference codes |
244
227
  | `brain-skill.md` | Skill that processes brain entries |
245
228
  | `brain-patterns.md` | File naming and link conventions |
246
229
  | `brain-capture.md` | Processing rules and templates |
@@ -126,57 +126,17 @@ review-code --scope staged
126
126
  review-code src/services/userService.ts
127
127
  ```
128
128
 
129
- ---
130
-
131
- ## Context Optimization
132
-
133
- This command uses hierarchical context loading to reduce context consumption. Instead of loading full files, load indexes first and expand specific sections on-demand.
134
-
135
- ### Recommended Loading Order
136
-
137
- 1. **Always load first**: This command file (`commands/review-code.md`)
138
- 2. **Load indexes**: Load `_index.md` files for relevant folders
139
- 3. **Expand on-demand**: Use reference codes to load specific sections when needed
140
-
141
- ### Index Files for Code Review
142
-
143
- | Index | When to Load |
144
- |-------|--------------|
145
- | `resources/skills/_index.md` | To understand review workflow |
146
- | `resources/patterns/_index.md` | For review patterns and templates |
147
- | `resources/core/_index.md` | For allowed/forbidden patterns reference |
148
-
149
- ### Reference Codes for Code Review
150
-
151
- | Code | Description | When to Expand |
152
- |------|-------------|----------------|
153
- | SKL-REV-1 | Purpose and restrictions | Understanding allowed actions |
154
- | SKL-REV-2 | Identify changed files | Starting the review |
155
- | SKL-REV-3 | Determine review depth | Adaptive depth selection |
156
- | SKL-REV-5 | Find similar implementations | Searching for comparable code |
157
- | SKL-REV-7 | Pattern conflicts + verify + re-rank | Processing findings |
158
- | SKL-REV-8 | Generate review document | Creating the output file |
159
- | SKL-REV-9 | Severity and conflict resolution | Severity levels and resolution options |
160
- | PTN-REV-1 | Review document structure | Creating review output |
161
- | COR-AP-1 | Allowed patterns overview | Checking pattern compliance |
162
- | COR-FP-1 | Forbidden patterns overview | Identifying anti-patterns |
163
- | COR-MA-1 | Multi-agent subagent definitions | Deep mode parallel review setup |
164
- | COR-MA-2 | Coordinator dedup and merge | Deep mode result processing |
165
- | COR-SR-1 | Severity re-ranking algorithm | Ordering findings by impact |
166
- | COR-SR-2 | Finding grouping rules | Grouping related findings |
167
- | COR-AD-1 | Adaptive depth size detection | Determining review mode |
168
- | COR-AD-2 | Lightweight review mode | Changeset < 50 lines |
169
- | COR-AD-3 | Deep review mode | Changeset 500+ lines |
170
- | COR-CG-1 | Compaction guide | Load when compacting mid-review |
129
+ ## Context Loading
171
130
 
172
- ### Expansion Instructions
131
+ This command uses the **brain index** for context retrieval. Before executing, query the project brain for relevant documentation:
173
132
 
174
- When executing this command:
133
+ **Queries**:
134
+ - `planflow-ai state-query "code review workflow" --scope resources`
135
+ - `planflow-ai state-query "adaptive depth" --scope resources`
136
+ - `planflow-ai state-query "severity ranking" --scope resources`
137
+ - `planflow-ai state-query "multi-agent review" --scope resources`
175
138
 
176
- 1. **Start with indexes**: Read `resources/skills/_index.md` and `resources/patterns/_index.md`
177
- 2. **Identify needed codes**: Based on detected language/framework, expand relevant patterns
178
- 3. **Expand as needed**: Use the Read tool with specific line ranges from the index
179
- 4. **Don't expand everything**: Only load patterns relevant to the files being reviewed
139
+ The brain returns ranked chunks from indexed markdown files. Use the top results to inform execution.
180
140
 
181
141
  ---
182
142
 
@@ -184,9 +144,6 @@ When executing this command:
184
144
 
185
145
  | Resource | Purpose |
186
146
  | ------------------------------ | -------------------------------------- |
187
- | `resources/skills/_index.md` | Index of skills with reference codes |
188
- | `resources/patterns/_index.md` | Index of patterns with reference codes |
189
- | `resources/core/_index.md` | Index of core rules with reference codes |
190
147
  | `review-code-skill.md` | Skill that executes the review |
191
148
  | `review-pr-patterns.md` | Review patterns and guidelines |
192
149