create-universal-ai-context 2.4.0 → 2.6.0-final

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 (153) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +331 -294
  3. package/bin/create-ai-context.js +1507 -764
  4. package/lib/adapters/aider.js +131 -131
  5. package/lib/adapters/antigravity.js +205 -205
  6. package/lib/adapters/claude.js +397 -397
  7. package/lib/adapters/cline.js +125 -125
  8. package/lib/adapters/continue.js +138 -138
  9. package/lib/adapters/copilot.js +131 -131
  10. package/lib/adapters/index.js +78 -78
  11. package/lib/adapters/windsurf.js +138 -138
  12. package/lib/ai-context-generator.js +234 -234
  13. package/lib/ai-orchestrator.js +432 -432
  14. package/lib/call-tracer.js +444 -444
  15. package/lib/content-preservation.js +243 -243
  16. package/lib/cross-tool-sync/file-watcher.js +274 -274
  17. package/lib/cross-tool-sync/index.js +41 -40
  18. package/lib/cross-tool-sync/sync-manager.js +540 -512
  19. package/lib/cross-tool-sync/sync-service.js +297 -297
  20. package/lib/detector.js +726 -726
  21. package/lib/doc-discovery.js +741 -741
  22. package/lib/drift-checker.js +920 -920
  23. package/lib/environment-detector.js +239 -239
  24. package/lib/index.js +399 -399
  25. package/lib/install-hooks.js +82 -82
  26. package/lib/installer.js +419 -419
  27. package/lib/migrate.js +328 -328
  28. package/lib/placeholder.js +632 -632
  29. package/lib/prompts.js +341 -341
  30. package/lib/smart-merge.js +540 -540
  31. package/lib/spinner.js +60 -60
  32. package/lib/static-analyzer.js +729 -729
  33. package/lib/template-coordination.js +148 -148
  34. package/lib/template-populator.js +843 -843
  35. package/lib/template-renderer.js +392 -392
  36. package/lib/utils/fs-wrapper.js +79 -79
  37. package/lib/utils/path-utils.js +60 -60
  38. package/lib/validate.js +155 -155
  39. package/package.json +1 -1
  40. package/templates/AI_CONTEXT.md.template +245 -245
  41. package/templates/base/README.md +260 -257
  42. package/templates/base/RPI_WORKFLOW_PLAN.md +325 -320
  43. package/templates/base/agents/api-developer.md +76 -76
  44. package/templates/base/agents/context-engineer.md +525 -525
  45. package/templates/base/agents/core-architect.md +76 -76
  46. package/templates/base/agents/database-ops.md +76 -76
  47. package/templates/base/agents/deployment-ops.md +76 -76
  48. package/templates/base/agents/integration-hub.md +76 -76
  49. package/templates/base/analytics/README.md +114 -114
  50. package/templates/base/automation/config.json +58 -58
  51. package/templates/base/automation/generators/code-mapper.js +308 -308
  52. package/templates/base/automation/generators/index-builder.js +321 -321
  53. package/templates/base/automation/hooks/post-commit.sh +83 -83
  54. package/templates/base/automation/hooks/pre-commit.sh +103 -103
  55. package/templates/base/ci-templates/README.md +108 -108
  56. package/templates/base/ci-templates/github-actions/context-check.yml +144 -144
  57. package/templates/base/ci-templates/github-actions/validate-docs.yml +105 -105
  58. package/templates/base/commands/analytics.md +238 -238
  59. package/templates/base/commands/auto-sync.md +172 -172
  60. package/templates/base/commands/collab.md +194 -194
  61. package/templates/base/commands/context-optimize.md +226 -0
  62. package/templates/base/commands/help.md +485 -450
  63. package/templates/base/commands/rpi-implement.md +164 -115
  64. package/templates/base/commands/rpi-plan.md +147 -93
  65. package/templates/base/commands/rpi-research.md +145 -88
  66. package/templates/base/commands/session-resume.md +144 -144
  67. package/templates/base/commands/session-save.md +112 -112
  68. package/templates/base/commands/validate-all.md +77 -77
  69. package/templates/base/commands/verify-docs-current.md +86 -86
  70. package/templates/base/config/base.json +57 -57
  71. package/templates/base/config/environments/development.json +13 -13
  72. package/templates/base/config/environments/production.json +17 -17
  73. package/templates/base/config/environments/staging.json +13 -13
  74. package/templates/base/config/local.json.example +21 -21
  75. package/templates/base/context/.meta/generated-at.json +18 -18
  76. package/templates/base/context/ARCHITECTURE_SNAPSHOT.md +156 -156
  77. package/templates/base/context/CODE_TO_WORKFLOW_MAP.md +94 -94
  78. package/templates/base/context/FILE_OWNERSHIP.md +57 -57
  79. package/templates/base/context/INTEGRATION_POINTS.md +92 -92
  80. package/templates/base/context/KNOWN_GOTCHAS.md +195 -195
  81. package/templates/base/context/TESTING_MAP.md +95 -95
  82. package/templates/base/context/WORKFLOW_INDEX.md +129 -129
  83. package/templates/base/context/workflows/WORKFLOW_TEMPLATE.md +294 -294
  84. package/templates/base/indexes/agents/CAPABILITY_MATRIX.md +255 -255
  85. package/templates/base/indexes/agents/CATEGORY_INDEX.md +44 -44
  86. package/templates/base/indexes/code/CATEGORY_INDEX.md +38 -38
  87. package/templates/base/indexes/routing/CATEGORY_INDEX.md +39 -39
  88. package/templates/base/indexes/search/CATEGORY_INDEX.md +39 -39
  89. package/templates/base/indexes/workflows/CATEGORY_INDEX.md +38 -38
  90. package/templates/base/knowledge/README.md +98 -98
  91. package/templates/base/knowledge/sessions/README.md +88 -88
  92. package/templates/base/knowledge/sessions/TEMPLATE.md +150 -150
  93. package/templates/base/knowledge/shared/decisions/0001-adopt-context-engineering.md +144 -144
  94. package/templates/base/knowledge/shared/decisions/README.md +49 -49
  95. package/templates/base/knowledge/shared/decisions/TEMPLATE.md +123 -123
  96. package/templates/base/knowledge/shared/patterns/README.md +62 -62
  97. package/templates/base/knowledge/shared/patterns/TEMPLATE.md +120 -120
  98. package/templates/base/plans/PLAN_TEMPLATE.md +316 -250
  99. package/templates/base/research/RESEARCH_TEMPLATE.md +245 -153
  100. package/templates/base/schemas/agent.schema.json +141 -141
  101. package/templates/base/schemas/anchors.schema.json +54 -54
  102. package/templates/base/schemas/automation.schema.json +93 -93
  103. package/templates/base/schemas/command.schema.json +134 -134
  104. package/templates/base/schemas/hashes.schema.json +40 -40
  105. package/templates/base/schemas/manifest.schema.json +117 -117
  106. package/templates/base/schemas/plan.schema.json +136 -136
  107. package/templates/base/schemas/research.schema.json +115 -115
  108. package/templates/base/schemas/roles.schema.json +34 -34
  109. package/templates/base/schemas/session.schema.json +77 -77
  110. package/templates/base/schemas/settings.schema.json +244 -244
  111. package/templates/base/schemas/staleness.schema.json +53 -53
  112. package/templates/base/schemas/team-config.schema.json +42 -42
  113. package/templates/base/schemas/workflow.schema.json +126 -126
  114. package/templates/base/session/checkpoints/.gitkeep +2 -2
  115. package/templates/base/session/current/state.json +20 -20
  116. package/templates/base/session/history/.gitkeep +2 -2
  117. package/templates/base/settings.json +3 -3
  118. package/templates/base/standards/COMPATIBILITY.md +219 -219
  119. package/templates/base/standards/EXTENSION_GUIDELINES.md +280 -280
  120. package/templates/base/standards/QUALITY_CHECKLIST.md +211 -211
  121. package/templates/base/standards/README.md +66 -66
  122. package/templates/base/sync/anchors.json +6 -6
  123. package/templates/base/sync/hashes.json +6 -6
  124. package/templates/base/sync/staleness.json +10 -10
  125. package/templates/base/team/README.md +168 -168
  126. package/templates/base/team/config.json +79 -79
  127. package/templates/base/team/roles.json +145 -145
  128. package/templates/base/tools/bin/claude-context.js +151 -151
  129. package/templates/base/tools/lib/anchor-resolver.js +276 -276
  130. package/templates/base/tools/lib/config-loader.js +363 -363
  131. package/templates/base/tools/lib/detector.js +350 -350
  132. package/templates/base/tools/lib/diagnose.js +206 -206
  133. package/templates/base/tools/lib/drift-detector.js +373 -373
  134. package/templates/base/tools/lib/errors.js +199 -199
  135. package/templates/base/tools/lib/index.js +36 -36
  136. package/templates/base/tools/lib/init.js +192 -192
  137. package/templates/base/tools/lib/logger.js +230 -230
  138. package/templates/base/tools/lib/placeholder.js +201 -201
  139. package/templates/base/tools/lib/session-manager.js +354 -354
  140. package/templates/base/tools/lib/validate.js +521 -521
  141. package/templates/base/tools/package.json +49 -49
  142. package/templates/handlebars/aider-config.hbs +146 -80
  143. package/templates/handlebars/antigravity.hbs +377 -377
  144. package/templates/handlebars/claude.hbs +183 -183
  145. package/templates/handlebars/cline.hbs +62 -62
  146. package/templates/handlebars/continue-config.hbs +116 -116
  147. package/templates/handlebars/copilot.hbs +130 -130
  148. package/templates/handlebars/partials/gotcha-list.hbs +11 -11
  149. package/templates/handlebars/partials/header.hbs +3 -3
  150. package/templates/handlebars/partials/workflow-summary.hbs +16 -16
  151. package/templates/handlebars/windsurf-rules.hbs +69 -69
  152. package/templates/hooks/post-commit.hbs +28 -29
  153. package/templates/hooks/pre-commit.hbs +46 -46
@@ -1,450 +1,485 @@
1
- ---
2
- name: help
3
- version: "1.0.0"
4
- description: "Display help for all available commands and agents"
5
- category: "system"
6
- context_budget_estimate: "5K tokens"
7
- typical_context_usage: "2%"
8
- prerequisites: []
9
- outputs:
10
- - "Command and agent reference information"
11
- next_commands: []
12
- related_agents: []
13
- examples:
14
- - command: "/help"
15
- description: "List all commands and agents"
16
- - command: "/help commands"
17
- description: "Detailed command reference"
18
- - command: "/help agents"
19
- description: "Agent capability overview"
20
- - command: "/help rpi"
21
- description: "RPI workflow deep dive"
22
- - command: "/help rpi-research"
23
- description: "Specific command help"
24
- ---
25
-
26
- # Help Command
27
-
28
- Display help and reference information for Claude Context Engineering.
29
-
30
- ## Syntax
31
-
32
- ```bash
33
- /help [topic]
34
- ```
35
-
36
- ## Topics
37
-
38
- | Topic | Description |
39
- |-------|-------------|
40
- | *(none)* | Overview of all commands and agents |
41
- | `commands` | Detailed command reference |
42
- | `agents` | Agent capabilities and selection guide |
43
- | `rpi` | RPI workflow deep dive |
44
- | `[command-name]` | Specific command help |
45
- | `[agent-name]` | Specific agent help |
46
-
47
- ---
48
-
49
- ## Quick Reference
50
-
51
- ### Available Commands
52
-
53
- | Command | Category | Description |
54
- |---------|----------|-------------|
55
- | `/rpi-research [name]` | RPI | Research phase - systematic codebase exploration |
56
- | `/rpi-plan [name]` | RPI | Plan phase - create implementation blueprint |
57
- | `/rpi-implement [name]` | RPI | Implement phase - execute with continuous testing |
58
- | `/verify-docs-current [file]` | Validation | Check documentation accuracy against code |
59
- | `/validate-all` | Validation | Run complete validation suite |
60
- | `/help [topic]` | System | Display this help information |
61
-
62
- ### Available Agents
63
-
64
- | Agent | Domain | Primary Use |
65
- |-------|--------|-------------|
66
- | `@context-engineer` | Initialization | Transform template for any codebase |
67
- | `@core-architect` | Architecture | System design, state machines, high-level planning |
68
- | `@database-ops` | Database | Migrations, schema, query optimization |
69
- | `@api-developer` | API | Endpoints, contracts, API documentation |
70
- | `@integration-hub` | Integration | External services, webhooks, third-party APIs |
71
- | `@deployment-ops` | DevOps | CI/CD, infrastructure, deployment strategies |
72
-
73
- ---
74
-
75
- ## Commands Reference
76
-
77
- ### RPI Workflow Commands
78
-
79
- The Research-Plan-Implement workflow prevents cascading errors through structured development.
80
-
81
- #### `/rpi-research [feature-name]`
82
-
83
- **Purpose:** Systematic, zero-code-modification exploration of the codebase.
84
-
85
- **Context Budget:** ~50K tokens (25%)
86
-
87
- **What it does:**
88
- 1. Launches 3 parallel exploration agents
89
- 2. Traces call chains 3 levels deep with file:line references
90
- 3. Maps dependencies (internal and external)
91
- 4. Identifies test coverage gaps
92
- 5. Creates research document in `.ai-context/research/active/`
93
-
94
- **Exit Criteria:**
95
- - [ ] 3-20 relevant files identified
96
- - [ ] Call chains traced with line numbers
97
- - [ ] Dependencies mapped
98
- - [ ] 150-word summary for parent context
99
-
100
- **Example:**
101
- ```bash
102
- /rpi-research user-authentication
103
- ```
104
-
105
- ---
106
-
107
- #### `/rpi-plan [feature-name]`
108
-
109
- **Purpose:** Create detailed implementation blueprint with file:line precision.
110
-
111
- **Context Budget:** ~35K tokens (17%)
112
-
113
- **Prerequisites:** Research document must exist in `.ai-context/research/active/`
114
-
115
- **What it does:**
116
- 1. Loads research document
117
- 2. Defines scope (in-scope, out-of-scope)
118
- 3. Creates modification table with file, lines, change, risk level
119
- 4. Designs step-by-step implementation
120
- 5. Defines test strategy
121
- 6. Requires human approval before proceeding
122
-
123
- **Exit Criteria:**
124
- - [ ] All modifications listed with file:line
125
- - [ ] Step-by-step implementation defined
126
- - [ ] Test strategy documented
127
- - [ ] Human approval obtained
128
-
129
- **Example:**
130
- ```bash
131
- /rpi-plan user-authentication
132
- ```
133
-
134
- ---
135
-
136
- #### `/rpi-implement [feature-name]`
137
-
138
- **Purpose:** Execute approved plan with atomic changes and continuous testing.
139
-
140
- **Context Budget:** ~60K tokens (30%)
141
-
142
- **Prerequisites:** Approved plan in `.ai-context/plans/active/`
143
-
144
- **Golden Rule:** ONE CHANGE → ONE TEST → ONE COMMIT
145
-
146
- **What it does:**
147
- 1. Verifies preconditions (plan approved, clean branch, tests pass)
148
- 2. For each step: make change run test → commit if pass
149
- 3. Updates documentation after each change
150
- 4. Runs full test suite after completion
151
- 5. Archives plan to `.ai-context/plans/completed/`
152
-
153
- **Error Recovery:**
154
- - Syntax error: Fix immediately
155
- - Test failure: Stop, investigate, don't proceed
156
- - 3+ failures: Stop, start fresh session
157
-
158
- **Example:**
159
- ```bash
160
- /rpi-implement user-authentication
161
- ```
162
-
163
- ---
164
-
165
- ### Validation Commands
166
-
167
- #### `/verify-docs-current [file_path]`
168
-
169
- **Purpose:** Validate documentation accuracy against current code.
170
-
171
- **Context Budget:** ~20K tokens (10%)
172
-
173
- **What it does:**
174
- 1. Looks up file in CODE_TO_WORKFLOW_MAP.md
175
- 2. Finds all workflows that document this file
176
- 3. Verifies line number references (±10 line tolerance)
177
- 4. Checks markdown links resolve
178
- 5. Generates accuracy report
179
-
180
- **Output:** Status per workflow (HEALTHY / NEEDS UPDATE / STALE)
181
-
182
- **Example:**
183
- ```bash
184
- /verify-docs-current src/services/auth.py
185
- ```
186
-
187
- ---
188
-
189
- #### `/validate-all`
190
-
191
- **Purpose:** Run complete validation suite.
192
-
193
- **Context Budget:** ~40K tokens (20%)
194
-
195
- **What it does:**
196
- 1. Documentation validation (line numbers, links, CODE_TO_WORKFLOW_MAP)
197
- 2. Test validation (unit, integration, coverage threshold)
198
- 3. Code quality checks (linting, type checking, security)
199
- 4. Configuration validation
200
-
201
- **Output:** Report with PASS/FAIL per category, overall READY/NOT READY
202
-
203
- **Example:**
204
- ```bash
205
- /validate-all
206
- ```
207
-
208
- ---
209
-
210
- ## Agents Reference
211
-
212
- ### Agent Selection Guide
213
-
214
- ```
215
- START
216
-
217
- ├── Is this initialization/setup? → @context-engineer
218
-
219
- ├── Does it involve external APIs/webhooks? → @integration-hub
220
-
221
- ├── Does it involve database changes? → @database-ops
222
-
223
- ├── Does it involve API endpoints? → @api-developer
224
-
225
- ├── Does it involve deployment/CI/CD? → @deployment-ops
226
-
227
- └── Is it architecture/system design? → @core-architect
228
- ```
229
-
230
- ### Agent Details
231
-
232
- #### `@context-engineer`
233
-
234
- **Type:** Initialization Agent
235
- **Complexity:** Very High
236
- **Context Usage:** Up to 80K tokens (40%)
237
-
238
- **Capabilities:**
239
- - Tech stack detection
240
- - Workflow discovery (8-15 workflows)
241
- - Template population
242
- - System validation
243
- - Documentation generation
244
-
245
- **Invocation:**
246
- ```bash
247
- @context-engineer "Initialize context engineering for this repository"
248
- @context-engineer "Document workflow: [name]"
249
- @context-engineer "Refresh workflow: [name]"
250
- ```
251
-
252
- ---
253
-
254
- #### `@core-architect`
255
-
256
- **Type:** Architecture Specialist
257
- **Complexity:** High
258
- **Context Usage:** ~50K tokens (25%)
259
-
260
- **Capabilities:**
261
- - System architecture design
262
- - State machine analysis
263
- - Dependency mapping
264
- - Scalability planning
265
- - High-level design patterns
266
-
267
- **Invocation:**
268
- ```bash
269
- @core-architect "Document system architecture"
270
- @core-architect "Analyze state transitions in [component]"
271
- @core-architect "Identify scalability bottlenecks"
272
- ```
273
-
274
- ---
275
-
276
- #### `@database-ops`
277
-
278
- **Type:** Database Specialist
279
- **Complexity:** Medium-High
280
- **Context Usage:** ~40K tokens (20%)
281
-
282
- **Capabilities:**
283
- - Schema design and validation
284
- - Migration planning and execution
285
- - Query optimization
286
- - Data integrity checks
287
- - Performance tuning
288
-
289
- **Invocation:**
290
- ```bash
291
- @database-ops "Document database schema"
292
- @database-ops "Analyze query performance for [query]"
293
- @database-ops "Plan migration for [change]"
294
- ```
295
-
296
- ---
297
-
298
- #### `@api-developer`
299
-
300
- **Type:** API Specialist
301
- **Complexity:** Medium
302
- **Context Usage:** ~35K tokens (17%)
303
-
304
- **Capabilities:**
305
- - API design (REST, GraphQL)
306
- - Contract definition
307
- - Endpoint documentation
308
- - API testing strategies
309
- - Version management
310
-
311
- **Invocation:**
312
- ```bash
313
- @api-developer "Document API endpoints for [resource]"
314
- @api-developer "Validate API contracts"
315
- @api-developer "Generate OpenAPI spec"
316
- ```
317
-
318
- ---
319
-
320
- #### `@integration-hub`
321
-
322
- **Type:** Integration Specialist
323
- **Complexity:** Medium-High
324
- **Context Usage:** ~40K tokens (20%)
325
-
326
- **Capabilities:**
327
- - Third-party API integration
328
- - Webhook handling
329
- - Authentication management
330
- - Rate limiting implementation
331
- - Error handling for external services
332
-
333
- **Invocation:**
334
- ```bash
335
- @integration-hub "Document integration with [service]"
336
- @integration-hub "Analyze webhook endpoints"
337
- @integration-hub "Review authentication flows"
338
- ```
339
-
340
- ---
341
-
342
- #### `@deployment-ops`
343
-
344
- **Type:** DevOps Specialist
345
- **Complexity:** High
346
- **Context Usage:** ~45K tokens (22%)
347
-
348
- **Capabilities:**
349
- - CI/CD pipeline design
350
- - Infrastructure as code
351
- - Deployment strategies (blue-green, canary)
352
- - Environment management
353
- - Monitoring and rollback
354
-
355
- **Invocation:**
356
- ```bash
357
- @deployment-ops "Document deployment pipeline"
358
- @deployment-ops "Review infrastructure configuration"
359
- @deployment-ops "Plan rollback strategy"
360
- ```
361
-
362
- ---
363
-
364
- ## RPI Workflow Deep Dive
365
-
366
- ### Philosophy
367
-
368
- The Research-Plan-Implement methodology prevents "slop" (degraded output quality) by:
369
-
370
- 1. **Separating concerns:** Research loads context, Plan uses it, Implement executes
371
- 2. **Human checkpoints:** Approval required between Plan and Implement
372
- 3. **Atomic changes:** Small, testable, reversible modifications
373
- 4. **Context discipline:** Each phase has a budget, compacts before next phase
374
-
375
- ### Token Budget Strategy
376
-
377
- | Phase | Budget | Cumulative |
378
- |-------|--------|------------|
379
- | Research | 50K | 50K (25%) |
380
- | Plan | 35K | 85K (42%) |
381
- | Implement | 60K | 145K (72%) |
382
- | Buffer | 55K | 200K (100%) |
383
-
384
- ### Workflow Diagram
385
-
386
- ```
387
- User Request
388
-
389
-
390
- ┌─────────────────┐
391
- │ /rpi-research │ → .ai-context/research/active/[name]_research.md
392
- └────────┬────────┘
393
-
394
-
395
- ┌─────────────────┐
396
- │ /rpi-plan │ → .ai-context/plans/active/[name]_plan.md
397
- └────────┬────────┘
398
-
399
-
400
- ┌─────────┐
401
- APPROVE │ ← Human Review
402
- └────┬────┘
403
-
404
-
405
- ┌─────────────────┐
406
- /rpi-implement │ Code changes + Doc updates
407
- └────────┬────────┘
408
-
409
-
410
- .ai-context/plans/completed/[name]_plan.md
411
- ```
412
-
413
- ---
414
-
415
- ## CLI Tools
416
-
417
- In addition to slash commands, CLI tools are available:
418
-
419
- ```bash
420
- # Validate setup
421
- npx claude-context validate
422
-
423
- # Run diagnostics
424
- npx claude-context diagnose
425
-
426
- # Initialize (partial - requires agent for full init)
427
- npx claude-context init
428
-
429
- # View configuration
430
- npx claude-context config
431
- ```
432
-
433
- ---
434
-
435
- ## Quick Tips
436
-
437
- 1. **Start with indexes:** Load CATEGORY_INDEX.md before detail files
438
- 2. **Use progressive loading:** 5K → 15K → 40K tokens as needed
439
- 3. **After code changes:** Always run `/verify-docs-current`
440
- 4. **For complex features:** Full RPI cycle prevents errors
441
- 5. **When stuck:** Use `@context-engineer "help with [problem]"`
442
-
443
- ---
444
-
445
- ## Getting More Help
446
-
447
- - **Quick Start:** See `docs/QUICK_START_5MIN.md`
448
- - **Troubleshooting:** See `docs/TROUBLESHOOTING.md`
449
- - **Full Documentation:** See `.ai-context/README.md`
450
- - **RPI Details:** See `.ai-context/RPI_WORKFLOW_PLAN.md`
1
+ ---
2
+ name: help
3
+ version: "1.0.0"
4
+ description: "Display help for all available commands and agents"
5
+ category: "system"
6
+ context_budget_estimate: "5K tokens"
7
+ typical_context_usage: "2%"
8
+ prerequisites: []
9
+ outputs:
10
+ - "Command and agent reference information"
11
+ next_commands: []
12
+ related_agents: []
13
+ examples:
14
+ - command: "/help"
15
+ description: "List all commands and agents"
16
+ - command: "/help commands"
17
+ description: "Detailed command reference"
18
+ - command: "/help agents"
19
+ description: "Agent capability overview"
20
+ - command: "/help rpi"
21
+ description: "RPI workflow deep dive"
22
+ - command: "/help rpi-research"
23
+ description: "Specific command help"
24
+ ---
25
+
26
+ # Help Command
27
+
28
+ Display help and reference information for Claude Context Engineering.
29
+
30
+ ## Syntax
31
+
32
+ ```bash
33
+ /help [topic]
34
+ ```
35
+
36
+ ## Topics
37
+
38
+ | Topic | Description |
39
+ |-------|-------------|
40
+ | *(none)* | Overview of all commands and agents |
41
+ | `commands` | Detailed command reference |
42
+ | `agents` | Agent capabilities and selection guide |
43
+ | `rpi` | RPI workflow deep dive |
44
+ | `[command-name]` | Specific command help |
45
+ | `[agent-name]` | Specific agent help |
46
+
47
+ ---
48
+
49
+ ## Quick Reference
50
+
51
+ ### Available Commands
52
+
53
+ | Command | Category | Description |
54
+ |---------|----------|-------------|
55
+ | `/rpi-research [name]` | RPI | Research phase - systematic codebase exploration |
56
+ | `/rpi-plan [name]` | RPI | Plan phase - create implementation blueprint |
57
+ | `/rpi-implement [name]` | RPI | Implement phase - execute with continuous testing |
58
+ | `/context-optimize` | Orchestration | Generate RPI TODO list with interactive scoping |
59
+ | `/verify-docs-current [file]` | Validation | Check documentation accuracy against code |
60
+ | `/validate-all` | Validation | Run complete validation suite |
61
+ | `/help [topic]` | System | Display this help information |
62
+
63
+ ### Available Agents
64
+
65
+ | Agent | Domain | Primary Use |
66
+ |-------|--------|-------------|
67
+ | `@context-engineer` | Initialization | Transform template for any codebase |
68
+ | `@core-architect` | Architecture | System design, state machines, high-level planning |
69
+ | `@database-ops` | Database | Migrations, schema, query optimization |
70
+ | `@api-developer` | API | Endpoints, contracts, API documentation |
71
+ | `@integration-hub` | Integration | External services, webhooks, third-party APIs |
72
+ | `@deployment-ops` | DevOps | CI/CD, infrastructure, deployment strategies |
73
+
74
+ ---
75
+
76
+ ## Commands Reference
77
+
78
+ ### RPI Workflow Commands
79
+
80
+ The Research-Plan-Implement workflow prevents cascading errors through structured development.
81
+
82
+ #### `/rpi-research [feature-name]`
83
+
84
+ **Purpose:** Systematic, zero-code-modification exploration of the codebase.
85
+
86
+ **Context Budget:** ~50K tokens (25%)
87
+
88
+ **What it does:**
89
+ 1. Launches 3 parallel exploration agents
90
+ 2. Traces call chains 3 levels deep with file:line references
91
+ 3. Maps dependencies (internal and external)
92
+ 4. Identifies test coverage gaps
93
+ 5. Creates research document in `.ai-context/research/active/`
94
+
95
+ **Exit Criteria:**
96
+ - [ ] 3-20 relevant files identified
97
+ - [ ] Call chains traced with line numbers
98
+ - [ ] Dependencies mapped
99
+ - [ ] 150-word summary for parent context
100
+
101
+ **Example:**
102
+ ```bash
103
+ /rpi-research user-authentication
104
+ ```
105
+
106
+ ---
107
+
108
+ #### `/rpi-plan [feature-name]`
109
+
110
+ **Purpose:** Create detailed implementation blueprint with file:line precision.
111
+
112
+ **Context Budget:** ~35K tokens (17%)
113
+
114
+ **Prerequisites:** Research document must exist in `.ai-context/research/active/`
115
+
116
+ **What it does:**
117
+ 1. Loads research document
118
+ 2. Defines scope (in-scope, out-of-scope)
119
+ 3. Creates modification table with file, lines, change, risk level
120
+ 4. Designs step-by-step implementation
121
+ 5. Defines test strategy
122
+ 6. Requires human approval before proceeding
123
+
124
+ **Exit Criteria:**
125
+ - [ ] All modifications listed with file:line
126
+ - [ ] Step-by-step implementation defined
127
+ - [ ] Test strategy documented
128
+ - [ ] Human approval obtained
129
+
130
+ **Example:**
131
+ ```bash
132
+ /rpi-plan user-authentication
133
+ ```
134
+
135
+ ---
136
+
137
+ #### `/rpi-implement [feature-name]`
138
+
139
+ **Purpose:** Execute approved plan with atomic changes and continuous testing.
140
+
141
+ **Context Budget:** ~60K tokens (30%)
142
+
143
+ **Prerequisites:** Approved plan in `.ai-context/plans/active/`
144
+
145
+ **Golden Rule:** ONE CHANGE → ONE TEST → ONE COMMIT
146
+
147
+ **What it does:**
148
+ 1. Verifies preconditions (plan approved, clean branch, tests pass)
149
+ 2. For each step: make change → run test → commit if pass
150
+ 3. Updates documentation after each change
151
+ 4. Runs full test suite after completion
152
+ 5. Archives plan to `.ai-context/plans/completed/`
153
+
154
+ **Error Recovery:**
155
+ - Syntax error: Fix immediately
156
+ - Test failure: Stop, investigate, don't proceed
157
+ - 3+ failures: Stop, start fresh session
158
+
159
+ **Example:**
160
+ ```bash
161
+ /rpi-implement user-authentication
162
+ ```
163
+
164
+ ---
165
+
166
+ ### Orchestration Commands
167
+
168
+ #### `/context-optimize`
169
+
170
+ **Purpose:** Generate RPI workflow TODO list with interactive scoping to optimize the context engineering system.
171
+
172
+ **Context Budget:** ~40K tokens (20%)
173
+
174
+ **What it does:**
175
+ 1. Asks up to 4 multiple choice questions to scope optimization goals
176
+ 2. Audits current context system for completeness and accuracy
177
+ 3. Generates actionable TODO list with RPI phases (research, plan, implement)
178
+ 4. Identifies redundant or outdated context files
179
+ 5. Recommends new agents or commands based on codebase patterns
180
+
181
+ **Scoping Questions:**
182
+ - Optimization focus (functionalize, update, cleanup, enhance)
183
+ - Codebase coverage priority (core logic, API, database, all)
184
+ - Enhancement preferences (agents, commands, docs, navigation)
185
+ - TODO priority order (quick wins, high impact, grouped, dependency order)
186
+
187
+ **Output:**
188
+ - TODO checklist: `.ai-context/plans/active/context-optimization_plan.md`
189
+ - Audit report: `.ai-context/research/active/context-audit_research.md`
190
+
191
+ **Examples:**
192
+ ```bash
193
+ /context-optimize # Interactive mode
194
+ /context-optimize --auto # Automatic scoping
195
+ /context-optimize --scope documentation
196
+ ```
197
+
198
+ ---
199
+
200
+ ### Validation Commands
201
+
202
+ #### `/verify-docs-current [file_path]`
203
+
204
+ **Purpose:** Validate documentation accuracy against current code.
205
+
206
+ **Context Budget:** ~20K tokens (10%)
207
+
208
+ **What it does:**
209
+ 1. Looks up file in CODE_TO_WORKFLOW_MAP.md
210
+ 2. Finds all workflows that document this file
211
+ 3. Verifies line number references (±10 line tolerance)
212
+ 4. Checks markdown links resolve
213
+ 5. Generates accuracy report
214
+
215
+ **Output:** Status per workflow (HEALTHY / NEEDS UPDATE / STALE)
216
+
217
+ **Example:**
218
+ ```bash
219
+ /verify-docs-current src/services/auth.py
220
+ ```
221
+
222
+ ---
223
+
224
+ #### `/validate-all`
225
+
226
+ **Purpose:** Run complete validation suite.
227
+
228
+ **Context Budget:** ~40K tokens (20%)
229
+
230
+ **What it does:**
231
+ 1. Documentation validation (line numbers, links, CODE_TO_WORKFLOW_MAP)
232
+ 2. Test validation (unit, integration, coverage threshold)
233
+ 3. Code quality checks (linting, type checking, security)
234
+ 4. Configuration validation
235
+
236
+ **Output:** Report with PASS/FAIL per category, overall READY/NOT READY
237
+
238
+ **Example:**
239
+ ```bash
240
+ /validate-all
241
+ ```
242
+
243
+ ---
244
+
245
+ ## Agents Reference
246
+
247
+ ### Agent Selection Guide
248
+
249
+ ```
250
+ START
251
+
252
+ ├── Is this initialization/setup? → @context-engineer
253
+
254
+ ├── Does it involve external APIs/webhooks? → @integration-hub
255
+
256
+ ├── Does it involve database changes? → @database-ops
257
+
258
+ ├── Does it involve API endpoints? → @api-developer
259
+
260
+ ├── Does it involve deployment/CI/CD? → @deployment-ops
261
+
262
+ └── Is it architecture/system design? → @core-architect
263
+ ```
264
+
265
+ ### Agent Details
266
+
267
+ #### `@context-engineer`
268
+
269
+ **Type:** Initialization Agent
270
+ **Complexity:** Very High
271
+ **Context Usage:** Up to 80K tokens (40%)
272
+
273
+ **Capabilities:**
274
+ - Tech stack detection
275
+ - Workflow discovery (8-15 workflows)
276
+ - Template population
277
+ - System validation
278
+ - Documentation generation
279
+
280
+ **Invocation:**
281
+ ```bash
282
+ @context-engineer "Initialize context engineering for this repository"
283
+ @context-engineer "Document workflow: [name]"
284
+ @context-engineer "Refresh workflow: [name]"
285
+ ```
286
+
287
+ ---
288
+
289
+ #### `@core-architect`
290
+
291
+ **Type:** Architecture Specialist
292
+ **Complexity:** High
293
+ **Context Usage:** ~50K tokens (25%)
294
+
295
+ **Capabilities:**
296
+ - System architecture design
297
+ - State machine analysis
298
+ - Dependency mapping
299
+ - Scalability planning
300
+ - High-level design patterns
301
+
302
+ **Invocation:**
303
+ ```bash
304
+ @core-architect "Document system architecture"
305
+ @core-architect "Analyze state transitions in [component]"
306
+ @core-architect "Identify scalability bottlenecks"
307
+ ```
308
+
309
+ ---
310
+
311
+ #### `@database-ops`
312
+
313
+ **Type:** Database Specialist
314
+ **Complexity:** Medium-High
315
+ **Context Usage:** ~40K tokens (20%)
316
+
317
+ **Capabilities:**
318
+ - Schema design and validation
319
+ - Migration planning and execution
320
+ - Query optimization
321
+ - Data integrity checks
322
+ - Performance tuning
323
+
324
+ **Invocation:**
325
+ ```bash
326
+ @database-ops "Document database schema"
327
+ @database-ops "Analyze query performance for [query]"
328
+ @database-ops "Plan migration for [change]"
329
+ ```
330
+
331
+ ---
332
+
333
+ #### `@api-developer`
334
+
335
+ **Type:** API Specialist
336
+ **Complexity:** Medium
337
+ **Context Usage:** ~35K tokens (17%)
338
+
339
+ **Capabilities:**
340
+ - API design (REST, GraphQL)
341
+ - Contract definition
342
+ - Endpoint documentation
343
+ - API testing strategies
344
+ - Version management
345
+
346
+ **Invocation:**
347
+ ```bash
348
+ @api-developer "Document API endpoints for [resource]"
349
+ @api-developer "Validate API contracts"
350
+ @api-developer "Generate OpenAPI spec"
351
+ ```
352
+
353
+ ---
354
+
355
+ #### `@integration-hub`
356
+
357
+ **Type:** Integration Specialist
358
+ **Complexity:** Medium-High
359
+ **Context Usage:** ~40K tokens (20%)
360
+
361
+ **Capabilities:**
362
+ - Third-party API integration
363
+ - Webhook handling
364
+ - Authentication management
365
+ - Rate limiting implementation
366
+ - Error handling for external services
367
+
368
+ **Invocation:**
369
+ ```bash
370
+ @integration-hub "Document integration with [service]"
371
+ @integration-hub "Analyze webhook endpoints"
372
+ @integration-hub "Review authentication flows"
373
+ ```
374
+
375
+ ---
376
+
377
+ #### `@deployment-ops`
378
+
379
+ **Type:** DevOps Specialist
380
+ **Complexity:** High
381
+ **Context Usage:** ~45K tokens (22%)
382
+
383
+ **Capabilities:**
384
+ - CI/CD pipeline design
385
+ - Infrastructure as code
386
+ - Deployment strategies (blue-green, canary)
387
+ - Environment management
388
+ - Monitoring and rollback
389
+
390
+ **Invocation:**
391
+ ```bash
392
+ @deployment-ops "Document deployment pipeline"
393
+ @deployment-ops "Review infrastructure configuration"
394
+ @deployment-ops "Plan rollback strategy"
395
+ ```
396
+
397
+ ---
398
+
399
+ ## RPI Workflow Deep Dive
400
+
401
+ ### Philosophy
402
+
403
+ The Research-Plan-Implement methodology prevents "slop" (degraded output quality) by:
404
+
405
+ 1. **Separating concerns:** Research loads context, Plan uses it, Implement executes
406
+ 2. **Human checkpoints:** Approval required between Plan and Implement
407
+ 3. **Atomic changes:** Small, testable, reversible modifications
408
+ 4. **Context discipline:** Each phase has a budget, compacts before next phase
409
+
410
+ ### Token Budget Strategy
411
+
412
+ | Phase | Budget | Cumulative |
413
+ |-------|--------|------------|
414
+ | Research | 50K | 50K (25%) |
415
+ | Plan | 35K | 85K (42%) |
416
+ | Implement | 60K | 145K (72%) |
417
+ | Buffer | 55K | 200K (100%) |
418
+
419
+ ### Workflow Diagram
420
+
421
+ ```
422
+ User Request
423
+
424
+
425
+ ┌─────────────────┐
426
+ │ /rpi-research │ .ai-context/research/active/[name]_research.md
427
+ └────────┬────────┘
428
+
429
+
430
+ ┌─────────────────┐
431
+ │ /rpi-plan │ → .ai-context/plans/active/[name]_plan.md
432
+ └────────┬────────┘
433
+
434
+
435
+ ┌─────────┐
436
+ │ APPROVE │ ← Human Review
437
+ └────┬────┘
438
+
439
+
440
+ ┌─────────────────┐
441
+ /rpi-implement │ Code changes + Doc updates
442
+ └────────┬────────┘
443
+
444
+
445
+ .ai-context/plans/completed/[name]_plan.md
446
+ ```
447
+
448
+ ---
449
+
450
+ ## CLI Tools
451
+
452
+ In addition to slash commands, CLI tools are available:
453
+
454
+ ```bash
455
+ # Validate setup
456
+ npx claude-context validate
457
+
458
+ # Run diagnostics
459
+ npx claude-context diagnose
460
+
461
+ # Initialize (partial - requires agent for full init)
462
+ npx claude-context init
463
+
464
+ # View configuration
465
+ npx claude-context config
466
+ ```
467
+
468
+ ---
469
+
470
+ ## Quick Tips
471
+
472
+ 1. **Start with indexes:** Load CATEGORY_INDEX.md before detail files
473
+ 2. **Use progressive loading:** 5K → 15K → 40K tokens as needed
474
+ 3. **After code changes:** Always run `/verify-docs-current`
475
+ 4. **For complex features:** Full RPI cycle prevents errors
476
+ 5. **When stuck:** Use `@context-engineer "help with [problem]"`
477
+
478
+ ---
479
+
480
+ ## Getting More Help
481
+
482
+ - **Quick Start:** See `docs/QUICK_START_5MIN.md`
483
+ - **Troubleshooting:** See `docs/TROUBLESHOOTING.md`
484
+ - **Full Documentation:** See `.ai-context/README.md`
485
+ - **RPI Details:** See `.ai-context/RPI_WORKFLOW_PLAN.md`