aiblueprint-cli 1.4.59 → 1.4.61

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 (184) hide show
  1. package/README.md +16 -36
  2. package/agents-config/agents/action.md +1 -1
  3. package/agents-config/agents/explore-codebase.md +53 -53
  4. package/agents-config/agents/explore-docs.md +50 -69
  5. package/agents-config/agents/websearch.md +36 -40
  6. package/agents-config/claude-config/scripts/.claude/skills/fix-on-my-computer/SKILL.md +81 -0
  7. package/agents-config/claude-config/scripts/CLAUDE.md +10 -4
  8. package/agents-config/claude-config/scripts/bun.lockb +0 -0
  9. package/agents-config/claude-config/scripts/package.json +22 -30
  10. package/agents-config/claude-config/scripts/statusline/CLAUDE.md +37 -155
  11. package/agents-config/claude-config/scripts/statusline/README.md +18 -94
  12. package/agents-config/claude-config/scripts/statusline/defaults.json +13 -10
  13. package/agents-config/claude-config/scripts/statusline/fixtures/mock-transcript.jsonl +4 -4
  14. package/agents-config/claude-config/scripts/statusline/fixtures/test-input.json +4 -4
  15. package/agents-config/claude-config/scripts/statusline/src/commands/interactive-config.ts +403 -0
  16. package/agents-config/claude-config/scripts/statusline/src/index.ts +33 -82
  17. package/agents-config/claude-config/scripts/statusline/src/lib/config-types.ts +7 -1
  18. package/agents-config/claude-config/scripts/statusline/src/lib/formatters.ts +40 -0
  19. package/agents-config/claude-config/scripts/statusline/src/lib/presets.ts +13 -13
  20. package/agents-config/claude-config/scripts/statusline/src/lib/render-pure.ts +24 -5
  21. package/agents-config/claude-config/scripts/statusline/statusline.config.free.json +79 -0
  22. package/agents-config/claude-config/scripts/statusline/statusline.config.json +77 -77
  23. package/agents-config/codex-config/config.toml +9 -0
  24. package/agents-config/codex-config/hooks/command-deny-list.ts +203 -0
  25. package/agents-config/commands/prompts/create-vitejs-app.md +272 -0
  26. package/agents-config/commands/prompts/nextjs-add-prisma-db.md +136 -0
  27. package/agents-config/commands/prompts/nextjs-setup-better-auth.md +173 -0
  28. package/agents-config/commands/prompts/nextjs-setup-project.md +200 -0
  29. package/agents-config/commands/prompts/prompt.md +55 -0
  30. package/agents-config/commands/prompts/saas-challenge-idea.md +135 -0
  31. package/agents-config/commands/prompts/saas-create-architecture.md +242 -0
  32. package/agents-config/commands/prompts/saas-create-headline.md +132 -0
  33. package/agents-config/commands/prompts/saas-create-landing-copywritting.md +267 -0
  34. package/agents-config/commands/prompts/saas-create-legals-docs.md +176 -0
  35. package/agents-config/commands/prompts/saas-create-logos.md +240 -0
  36. package/agents-config/commands/prompts/saas-create-prd.md +195 -0
  37. package/agents-config/commands/prompts/saas-create-tasks.md +240 -0
  38. package/agents-config/commands/prompts/saas-define-pricing.md +293 -0
  39. package/agents-config/commands/prompts/saas-find-domain-name.md +190 -0
  40. package/agents-config/commands/prompts/saas-implement-landing-page.md +257 -0
  41. package/agents-config/commands/prompts/setup-tmux.md +160 -0
  42. package/agents-config/commands/prompts/tools.md +148 -0
  43. package/agents-config/scripts/.claude/skills/fix-on-my-computer/SKILL.md +81 -0
  44. package/agents-config/scripts/CLAUDE.md +37 -0
  45. package/agents-config/scripts/biome.json +37 -0
  46. package/agents-config/scripts/bun.lockb +0 -0
  47. package/agents-config/scripts/package.json +24 -0
  48. package/agents-config/scripts/statusline/CLAUDE.md +87 -0
  49. package/agents-config/scripts/statusline/README.md +117 -0
  50. package/agents-config/scripts/statusline/__tests__/context.test.ts +229 -0
  51. package/agents-config/scripts/statusline/__tests__/formatters.test.ts +108 -0
  52. package/agents-config/scripts/statusline/__tests__/statusline.test.ts +309 -0
  53. package/agents-config/scripts/statusline/defaults.json +82 -0
  54. package/agents-config/scripts/statusline/fixtures/mock-transcript.jsonl +4 -0
  55. package/agents-config/scripts/statusline/fixtures/test-input.json +35 -0
  56. package/agents-config/scripts/statusline/src/commands/interactive-config.ts +403 -0
  57. package/agents-config/scripts/statusline/src/index.ts +141 -0
  58. package/agents-config/scripts/statusline/src/lib/config-types.ts +110 -0
  59. package/agents-config/scripts/statusline/src/lib/config.ts +21 -0
  60. package/agents-config/scripts/statusline/src/lib/context.ts +103 -0
  61. package/agents-config/scripts/statusline/src/lib/formatters.ts +426 -0
  62. package/agents-config/scripts/statusline/src/lib/git.ts +100 -0
  63. package/agents-config/scripts/statusline/src/lib/menu-factories.ts +224 -0
  64. package/agents-config/scripts/statusline/src/lib/presets.ts +177 -0
  65. package/agents-config/scripts/statusline/src/lib/render-pure.ts +516 -0
  66. package/agents-config/scripts/statusline/src/lib/types.ts +36 -0
  67. package/agents-config/scripts/statusline/src/lib/utils.ts +15 -0
  68. package/agents-config/scripts/statusline/statusline.config.free.json +79 -0
  69. package/agents-config/scripts/statusline/statusline.config.json +79 -0
  70. package/agents-config/scripts/statusline/test-with-fixtures.ts +37 -0
  71. package/agents-config/scripts/statusline/test.ts +20 -0
  72. package/agents-config/scripts/statusline/tsconfig.json +27 -0
  73. package/agents-config/scripts/tsconfig.json +27 -0
  74. package/agents-config/skills/{subagent-creator → agents-managers}/SKILL.md +47 -47
  75. package/agents-config/skills/{subagent-creator/references/subagents.md → agents-managers/references/agents.md} +45 -45
  76. package/agents-config/skills/{subagent-creator → agents-managers}/references/context-management.md +20 -20
  77. package/agents-config/skills/{subagent-creator → agents-managers}/references/debugging-agents.md +27 -27
  78. package/agents-config/skills/{subagent-creator → agents-managers}/references/error-handling-and-recovery.md +19 -19
  79. package/agents-config/skills/{subagent-creator → agents-managers}/references/evaluation-and-testing.md +29 -29
  80. package/agents-config/skills/{subagent-creator → agents-managers}/references/orchestration-patterns.md +5 -5
  81. package/agents-config/skills/{subagent-creator/references/writing-subagent-prompts.md → agents-managers/references/writing-agent-prompts.md} +23 -23
  82. package/agents-config/skills/codex-environment/SKILL.md +2 -0
  83. package/agents-config/skills/commit/SKILL.md +2 -0
  84. package/agents-config/skills/create-pr/SKILL.md +2 -0
  85. package/agents-config/skills/environments-manager/SKILL.md +271 -0
  86. package/agents-config/skills/environments-manager/examples/claude/.worktreeinclude +3 -0
  87. package/agents-config/skills/environments-manager/examples/claude/commands/dev.md +5 -0
  88. package/agents-config/skills/environments-manager/examples/claude/commands/lint.md +5 -0
  89. package/agents-config/skills/environments-manager/examples/claude/commands/test.md +5 -0
  90. package/agents-config/skills/environments-manager/examples/claude/commands/typecheck.md +5 -0
  91. package/agents-config/skills/environments-manager/examples/claude/settings.json +24 -0
  92. package/agents-config/skills/environments-manager/examples/codex/environments/environment.toml +29 -0
  93. package/agents-config/skills/environments-manager/examples/cursor/worktrees.json +3 -0
  94. package/agents-config/skills/environments-manager/examples/scripts/claude-worktree-create.sh +96 -0
  95. package/agents-config/skills/environments-manager/examples/scripts/claude-worktree-remove.sh +66 -0
  96. package/agents-config/skills/environments-manager/examples/scripts/dev.sh +15 -0
  97. package/agents-config/skills/environments-manager/examples/scripts/worktree-down.sh +22 -0
  98. package/agents-config/skills/environments-manager/examples/scripts/worktree-up.sh +50 -0
  99. package/agents-config/skills/environments-manager/references/claude.md +156 -0
  100. package/agents-config/skills/environments-manager/references/codex.md +97 -0
  101. package/agents-config/skills/environments-manager/references/cursor.md +88 -0
  102. package/agents-config/skills/fix-pr-comments/SKILL.md +2 -0
  103. package/agents-config/skills/grill-me/SKILL.md +10 -0
  104. package/agents-config/skills/merge/SKILL.md +2 -0
  105. package/agents-config/skills/rules-manager/SKILL.md +191 -0
  106. package/agents-config/skills/rules-manager/references/agents-vs-claude.md +66 -0
  107. package/agents-config/skills/rules-manager/references/examples.md +117 -0
  108. package/agents-config/skills/skill-manager/SKILL.md +101 -0
  109. package/agents-config/skills/skill-manager/references/claude-code.md +81 -0
  110. package/agents-config/skills/skill-manager/references/codex.md +288 -0
  111. package/agents-config/skills/skill-manager/references/cursor.md +125 -0
  112. package/agents-config/skills/skill-manager/references/description-recommandation.md +97 -0
  113. package/agents-config/skills/skill-manager/scripts/inspect-description.ts +743 -0
  114. package/agents-config/skills/ultrathink/SKILL.md +2 -0
  115. package/dist/cli.js +581 -299
  116. package/package.json +1 -1
  117. package/agents-config/claude-config/scripts/statusline/data/.gitignore +0 -8
  118. package/agents-config/claude-config/scripts/statusline/data/.gitkeep +0 -0
  119. package/agents-config/claude-config/scripts/statusline/docs/ARCHITECTURE.md +0 -166
  120. package/agents-config/claude-config/scripts/statusline/src/tests/spend-v2.test.ts +0 -306
  121. package/agents-config/skills/apex/SKILL.md +0 -261
  122. package/agents-config/skills/apex/scripts/setup-templates.sh +0 -100
  123. package/agents-config/skills/apex/scripts/update-progress.sh +0 -80
  124. package/agents-config/skills/apex/steps/step-00-init.md +0 -267
  125. package/agents-config/skills/apex/steps/step-00b-branch.md +0 -126
  126. package/agents-config/skills/apex/steps/step-00b-economy.md +0 -244
  127. package/agents-config/skills/apex/steps/step-00b-interactive.md +0 -153
  128. package/agents-config/skills/apex/steps/step-01-analyze.md +0 -361
  129. package/agents-config/skills/apex/steps/step-02-plan.md +0 -264
  130. package/agents-config/skills/apex/steps/step-03-execute.md +0 -239
  131. package/agents-config/skills/apex/steps/step-04-validate.md +0 -251
  132. package/agents-config/skills/apex/templates/00-context.md +0 -43
  133. package/agents-config/skills/apex/templates/01-analyze.md +0 -10
  134. package/agents-config/skills/apex/templates/02-plan.md +0 -10
  135. package/agents-config/skills/apex/templates/03-execute.md +0 -10
  136. package/agents-config/skills/apex/templates/04-validate.md +0 -10
  137. package/agents-config/skills/apex/templates/README.md +0 -176
  138. package/agents-config/skills/apex/templates/step-complete.md +0 -7
  139. package/agents-config/skills/claude-memory/SKILL.md +0 -293
  140. package/agents-config/skills/claude-memory/references/comprehensive-example.md +0 -175
  141. package/agents-config/skills/claude-memory/references/optimize-guide.md +0 -300
  142. package/agents-config/skills/claude-memory/references/project-patterns.md +0 -334
  143. package/agents-config/skills/claude-memory/references/prompting-techniques.md +0 -411
  144. package/agents-config/skills/claude-memory/references/rules-directory-guide.md +0 -298
  145. package/agents-config/skills/claude-memory/references/section-templates.md +0 -347
  146. package/agents-config/skills/fix-errors/SKILL.md +0 -61
  147. package/agents-config/skills/fix-grammar/SKILL.md +0 -59
  148. package/agents-config/skills/ralph-loop/SKILL.md +0 -117
  149. package/agents-config/skills/ralph-loop/scripts/setup.sh +0 -278
  150. package/agents-config/skills/ralph-loop/steps/step-00-init.md +0 -215
  151. package/agents-config/skills/ralph-loop/steps/step-01-interactive-prd.md +0 -366
  152. package/agents-config/skills/ralph-loop/steps/step-02-create-stories.md +0 -273
  153. package/agents-config/skills/ralph-loop/steps/step-03-finish.md +0 -245
  154. package/agents-config/skills/skill-creator/LICENSE.txt +0 -202
  155. package/agents-config/skills/skill-creator/SKILL.md +0 -421
  156. package/agents-config/skills/skill-creator/package.json +0 -5
  157. package/agents-config/skills/skill-creator/references/output-patterns.md +0 -82
  158. package/agents-config/skills/skill-creator/references/progressive-disclosure-patterns.md +0 -374
  159. package/agents-config/skills/skill-creator/references/prompting-integration.md +0 -363
  160. package/agents-config/skills/skill-creator/references/real-world-examples.md +0 -513
  161. package/agents-config/skills/skill-creator/references/script-patterns.md +0 -385
  162. package/agents-config/skills/skill-creator/references/workflows.md +0 -28
  163. package/agents-config/skills/skill-creator/references/xml-tag-guide.md +0 -606
  164. package/agents-config/skills/skill-creator/scripts/init-skill.ts +0 -214
  165. package/agents-config/skills/skill-creator/scripts/package-skill.ts +0 -146
  166. package/agents-config/skills/skill-creator/scripts/validate.ts +0 -138
  167. package/agents-config/skills/workflow-apex-free/SKILL.md +0 -261
  168. package/agents-config/skills/workflow-apex-free/scripts/setup-templates.sh +0 -100
  169. package/agents-config/skills/workflow-apex-free/scripts/update-progress.sh +0 -80
  170. package/agents-config/skills/workflow-apex-free/steps/step-00-init.md +0 -267
  171. package/agents-config/skills/workflow-apex-free/steps/step-00b-branch.md +0 -126
  172. package/agents-config/skills/workflow-apex-free/steps/step-00b-economy.md +0 -244
  173. package/agents-config/skills/workflow-apex-free/steps/step-00b-interactive.md +0 -153
  174. package/agents-config/skills/workflow-apex-free/steps/step-01-analyze.md +0 -361
  175. package/agents-config/skills/workflow-apex-free/steps/step-02-plan.md +0 -264
  176. package/agents-config/skills/workflow-apex-free/steps/step-03-execute.md +0 -239
  177. package/agents-config/skills/workflow-apex-free/steps/step-04-validate.md +0 -251
  178. package/agents-config/skills/workflow-apex-free/templates/00-context.md +0 -43
  179. package/agents-config/skills/workflow-apex-free/templates/01-analyze.md +0 -10
  180. package/agents-config/skills/workflow-apex-free/templates/02-plan.md +0 -10
  181. package/agents-config/skills/workflow-apex-free/templates/03-execute.md +0 -10
  182. package/agents-config/skills/workflow-apex-free/templates/04-validate.md +0 -10
  183. package/agents-config/skills/workflow-apex-free/templates/README.md +0 -176
  184. package/agents-config/skills/workflow-apex-free/templates/step-complete.md +0 -7
@@ -1,7 +1,7 @@
1
1
  # Orchestration Patterns for Multi-Agent Systems
2
2
 
3
3
  <core_concept>
4
- Orchestration defines how multiple subagents coordinate to complete complex tasks.
4
+ Orchestration defines how multiple agents coordinate to complete complex tasks.
5
5
 
6
6
  **Single agent**: Sequential execution within one context.
7
7
  **Multi-agent**: Coordination between multiple specialized agents, each with focused expertise.
@@ -61,7 +61,7 @@ Main chat orchestrates:
61
61
  </sequential>
62
62
 
63
63
  <parallel>
64
- **Parallel/Concurrent pattern**: Multiple specialized subagents perform tasks simultaneously.
64
+ **Parallel/Concurrent pattern**: Multiple specialized agents perform tasks simultaneously.
65
65
 
66
66
  <characteristics>
67
67
  - Agents execute independently and concurrently
@@ -76,7 +76,7 @@ Main chat orchestrates:
76
76
  - Processing multiple independent items (review multiple files)
77
77
  - Research tasks (gather information from multiple sources)
78
78
 
79
- **Performance data**: Anthropic's research system with 3-5 subagents in parallel achieved 90% time reduction.
79
+ **Performance data**: Anthropic's research system with 3-5 agents in parallel achieved 90% time reduction.
80
80
 
81
81
  **Example**:
82
82
  ```markdown
@@ -372,7 +372,7 @@ Coordinator:
372
372
  <implementation_guidance>
373
373
 
374
374
 
375
- <coordinator_subagent>
375
+ <coordinator_agent>
376
376
  **Example coordinator implementation**:
377
377
 
378
378
  ```markdown
@@ -418,7 +418,7 @@ If agent fails:
418
418
  - Escalate to human if critical
419
419
  </error_handling>
420
420
  ```
421
- </coordinator_subagent>
421
+ </coordinator_agent>
422
422
 
423
423
  <handoff_protocol>
424
424
  **Clean handoffs between agents**:
@@ -1,20 +1,20 @@
1
1
  <key_insight>
2
- Subagent prompts should be task-specific, not generic. They define a specialized role with clear focus areas, workflows, and constraints.
2
+ Agent prompts should be task-specific, not generic. They define a specialized role with clear focus areas, workflows, and constraints.
3
3
 
4
- **Critical**: Subagent.md files use pure XML structure (no markdown headings). Like skills and slash commands, this improves parsing and token efficiency.
4
+ **Critical**: Agent.md files use pure XML structure (no markdown headings). Like skills and slash commands, this improves parsing and token efficiency.
5
5
  </key_insight>
6
6
 
7
7
  <xml_structure_rule>
8
- **Remove ALL markdown headings (##, ###) from subagent body.** Use semantic XML tags instead.
8
+ **Remove ALL markdown headings (##, ###) from agent body.** Use semantic XML tags instead.
9
9
 
10
10
  Keep markdown formatting WITHIN content (bold, italic, lists, code blocks, links).
11
11
 
12
- See @skills/create-agent-skills/references/use-xml-tags.md for XML structure principles - they apply to subagents too.
12
+ See @skills/create-agent-skills/references/use-xml-tags.md for XML structure principles - they apply to agents too.
13
13
  </xml_structure_rule>
14
14
 
15
15
  <core_principles>
16
16
  <principle name="specificity">
17
- Define exactly what the subagent does and how it approaches tasks.
17
+ Define exactly what the agent does and how it approaches tasks.
18
18
 
19
19
  ❌ Bad: "You are a helpful coding assistant"
20
20
  ✅ Good: "You are a React performance optimizer. Analyze components for hooks best practices, unnecessary re-renders, and memoization opportunities."
@@ -28,7 +28,7 @@ State the role, focus areas, and approach explicitly.
28
28
  </principle>
29
29
 
30
30
  <principle name="constraints">
31
- Include what the subagent should NOT do. Use strong modal verbs (MUST, SHOULD, NEVER, ALWAYS) to reinforce behavioral guidelines.
31
+ Include what the agent should NOT do. Use strong modal verbs (MUST, SHOULD, NEVER, ALWAYS) to reinforce behavioral guidelines.
32
32
 
33
33
  Example:
34
34
  ```markdown
@@ -45,7 +45,7 @@ Example:
45
45
  </core_principles>
46
46
 
47
47
  <structure_with_xml>
48
- Use XML tags to structure subagent prompts for clarity:
48
+ Use XML tags to structure agent prompts for clarity:
49
49
 
50
50
  <example type="security_reviewer">
51
51
  ```markdown
@@ -220,7 +220,7 @@ You are a debugging specialist skilled at root cause analysis and systematic pro
220
220
  You are a helpful assistant that helps with code.
221
221
  ```
222
222
 
223
- This provides no specialization. The subagent won't know what to focus on or how to approach tasks.
223
+ This provides no specialization. The agent won't know what to focus on or how to approach tasks.
224
224
  </anti_pattern>
225
225
 
226
226
  <anti_pattern name="no_workflow">
@@ -229,7 +229,7 @@ This provides no specialization. The subagent won't know what to focus on or how
229
229
  You are a code reviewer. Review code for issues.
230
230
  ```
231
231
 
232
- Without a workflow, the subagent may skip important steps or review inconsistently.
232
+ Without a workflow, the agent may skip important steps or review inconsistently.
233
233
 
234
234
  ✅ Good:
235
235
  ```markdown
@@ -277,7 +277,7 @@ description: Handles current billing statements and payment processing. Use when
277
277
  <anti_pattern name="missing_constraints">
278
278
  ❌ Bad: No constraints specified
279
279
 
280
- Without constraints, subagents might:
280
+ Without constraints, agents might:
281
281
  - Modify code they shouldn't touch
282
282
  - Run dangerous commands
283
283
  - Skip important steps
@@ -293,7 +293,7 @@ Without constraints, subagents might:
293
293
  </anti_pattern>
294
294
 
295
295
  <anti_pattern name="requires_user_interaction">
296
- ❌ **Critical**: Subagents cannot interact with users.
296
+ ❌ **Critical**: Agents cannot interact with users.
297
297
 
298
298
  **Bad example:**
299
299
  ```markdown
@@ -311,25 +311,25 @@ tools: AskUserQuestion
311
311
  ```
312
312
 
313
313
  **Why this fails:**
314
- Subagents execute in isolated contexts ("black boxes"). They cannot use AskUserQuestion or any tool requiring user interaction. The user never sees intermediate steps.
314
+ Agents execute in isolated contexts ("black boxes"). They cannot use AskUserQuestion or any tool requiring user interaction. The user never sees intermediate steps.
315
315
 
316
316
  **Correct approach:**
317
317
  ```markdown
318
318
  # Main chat handles user interaction
319
319
  1. Main chat: Use AskUserQuestion to gather requirements
320
- 2. Launch subagent: Research based on requirements (no user interaction)
320
+ 2. Launch agent: Research based on requirements (no user interaction)
321
321
  3. Main chat: Present research to user, get confirmation
322
- 4. Launch subagent: Generate code based on confirmed plan
322
+ 4. Launch agent: Generate code based on confirmed plan
323
323
  5. Main chat: Present results to user
324
324
  ```
325
325
 
326
- **Tools that require user interaction (cannot use in subagents):**
326
+ **Tools that require user interaction (cannot use in agents):**
327
327
  - AskUserQuestion
328
328
  - Any workflow expecting user to respond mid-execution
329
329
  - Presenting options and waiting for selection
330
330
 
331
331
  **Design principle:**
332
- If your subagent prompt includes "ask user", "present options", or "wait for confirmation", it's designed incorrectly. Move user interaction to main chat.
332
+ If your agent prompt includes "ask user", "present options", or "wait for confirmation", it's designed incorrectly. Move user interaction to main chat.
333
333
  </anti_pattern>
334
334
  </anti_patterns>
335
335
 
@@ -405,8 +405,8 @@ Include examples for complex behaviors:
405
405
  ```markdown
406
406
  <example>
407
407
  Input: [scenario]
408
- Expected action: [what the subagent should do]
409
- Output: [what the subagent should produce]
408
+ Expected action: [what the agent should do]
409
+ Output: [what the agent should produce]
410
410
  </example>
411
411
  ```
412
412
  </practice>
@@ -456,9 +456,9 @@ Task is complete when:
456
456
  </practice>
457
457
  </best_practices>
458
458
 
459
- <testing_subagents>
459
+ <testing_agents>
460
460
  <test_checklist>
461
- 1. **Invoke the subagent** with a representative task
461
+ 1. **Invoke the agent** with a representative task
462
462
  2. **Check if it follows the workflow** specified in the prompt
463
463
  3. **Verify output format** matches what you defined
464
464
  4. **Test edge cases** - does it handle unusual inputs well?
@@ -467,18 +467,18 @@ Task is complete when:
467
467
  </test_checklist>
468
468
 
469
469
  <common_issues>
470
- - **Subagent too broad**: Narrow the focus areas
470
+ - **Agent too broad**: Narrow the focus areas
471
471
  - **Skipping steps**: Make workflow more explicit
472
472
  - **Inconsistent output**: Define output format more clearly
473
473
  - **Overstepping bounds**: Add or clarify constraints
474
474
  - **Not automatically invoked**: Improve description field with trigger keywords
475
475
  </common_issues>
476
- </testing_subagents>
476
+ </testing_agents>
477
477
 
478
478
  <quick_reference>
479
479
  ```markdown
480
480
  ---
481
- name: subagent-name
481
+ name: agent-name
482
482
  description: What it does and when to use it. Include trigger keywords.
483
483
  tools: Tool1, Tool2, Tool3
484
484
  model: sonnet
@@ -1,6 +1,8 @@
1
1
  ---
2
2
  name: codex-environment
3
3
  description: Create, inspect, or repair Codex app Local Environment configuration for worktrees, including .codex/environments/environment.toml, setup and cleanup scripts, worktree up/down scripts, copied env files, isolated databases, and reusable app actions.
4
+ disable-model-invocation: true
5
+ allow_implicit_invocation: false
4
6
  ---
5
7
 
6
8
  # Codex Environment
@@ -3,6 +3,8 @@ name: commit
3
3
  description: Quick commit and push with minimal, clean messages
4
4
  model: haiku
5
5
  allowed-tools: Bash(git :*), Bash(npm :*), Bash(pnpm :*)
6
+ disable-model-invocation: true
7
+ allow_implicit_invocation: false
6
8
  ---
7
9
 
8
10
  # Commit
@@ -3,6 +3,8 @@ name: create-pr
3
3
  description: Create and push PR with auto-generated title and description
4
4
  model: haiku
5
5
  allowed-tools: Bash(git :*), Bash(gh :*)
6
+ disable-model-invocation: true
7
+ allow_implicit_invocation: false
6
8
  ---
7
9
 
8
10
  # Create PR
@@ -0,0 +1,271 @@
1
+ ---
2
+ name: environments-manager
3
+ description: Set up per-worktree environments for Claude Code, Cursor, or Codex. Use for worktree-ready repos, IDE environment config, worktree-up/down scripts, or dev.sh wiring.
4
+ disable-model-invocation: false
5
+ allow_implicit_invocation: true
6
+ ---
7
+
8
+ # Environments Manager
9
+
10
+ Set up per-worktree environments so a fresh worktree is instantly ready to run: env files copied, dependencies installed, isolated database created, and common commands one click away. Supports Claude Code, Cursor, and Codex - the **shared scripts are the same on every IDE**; only the config file that points at them differs.
11
+
12
+ ## Interactive Flow
13
+
14
+ This skill is interactive. Ask the user the two questions below before writing anything - the right setup depends on the project. Use whichever interactive question mechanism the host harness provides. Do not assume answers.
15
+
16
+ ### Step 1: What should happen in a fresh worktree?
17
+
18
+ Ask the user what the setup script should do, as a multi-select. The first option is the default-on baseline; the rest are additive opt-ins:
19
+
20
+ | Option | What it adds to `scripts/worktree-up.sh` |
21
+ | :--- | :--- |
22
+ | Copy ignored env files from the source checkout | `cp` of `.env`, `.env.local`, `.env.development.local` (default - almost always wanted) |
23
+ | Install dependencies | `pnpm install` / `bun install` / `npm install` based on lockfile |
24
+ | Create an isolated database for this worktree | Build a unique DB name from the worktree dir, rewrite `DATABASE_URL` in `.env`, run `createdb` + import |
25
+ | Run codegen (Prisma, Drizzle, generated types) | `pnpm prisma:generate` / `bun run db:generate` / etc. |
26
+
27
+ If the user has project-specific steps (seed data, S3 sync, etc.), ask a follow-up free-form question to capture them.
28
+
29
+ ### Step 2: Which IDEs should be wired up?
30
+
31
+ Ask a multi-select with options: Claude Code, Cursor, Codex. The user can pick any combination - the shared `scripts/` directory only gets generated once.
32
+
33
+ ### Step 3: Apply each selected IDE
34
+
35
+ For each selected IDE, read the matching reference file and apply only its linking config. Do not duplicate the script logic - the IDE config just points at `scripts/worktree-up.sh`, `scripts/worktree-down.sh`, and `scripts/dev.sh`.
36
+
37
+ - Claude Code → load `references/claude.md`
38
+ - Cursor → load `references/cursor.md`
39
+ - Codex → load `references/codex.md`
40
+
41
+ ## Shared Shape
42
+
43
+ Every project that uses this skill ends up with:
44
+
45
+ ```text
46
+ scripts/
47
+ ├── worktree-up.sh # idempotent setup
48
+ ├── worktree-down.sh # cleanup before worktree teardown
49
+ ├── dev.sh # start dev server on a free port
50
+ └── (project-specific helpers, all *.sh)
51
+ ```
52
+
53
+ Plus one or more IDE config files (see references). The IDE config is thin; all logic lives in `scripts/`.
54
+
55
+ **Naming convention**: every generated script MUST end in `.sh`. No bare `worktree-up`, no `dev`. IDE configs reference scripts by full filename (`scripts/worktree-up.sh`, not `scripts/worktree-up`). This is enforced in every reference file and example.
56
+
57
+ ## Environment Variable Cascade
58
+
59
+ Each IDE exposes different variables. The shared scripts accept all of them, in this priority:
60
+
61
+ ```bash
62
+ WORKTREE_PATH="${CODEX_WORKTREE_PATH:-${CURSOR_WORKTREE_PATH:-$(pwd)}}"
63
+ SOURCE_PATH="${CODEX_SOURCE_TREE_PATH:-${ROOT_WORKTREE_PATH:-}}"
64
+ ```
65
+
66
+ | Platform | Worktree path | Source checkout path | Setup trigger |
67
+ | :------- | :----------------------- | :------------------------ | :--- |
68
+ | Codex | `$CODEX_WORKTREE_PATH` | `$CODEX_SOURCE_TREE_PATH` | `[setup] script` in TOML, runs once per worktree |
69
+ | Cursor | `pwd` inside worktree | `$ROOT_WORKTREE_PATH` | `setup-worktree-unix` in JSON, runs once per worktree |
70
+ | Claude | `pwd` inside worktree (the hook wrapper cd's in) | `$CLAUDE_PROJECT_DIR` (source repo, exposed inside the hook); the wrapper re-exports it as `ROOT_WORKTREE_PATH` | `WorktreeCreate` hook, runs once per worktree |
71
+
72
+ **Important about Claude Code**: do NOT use `SessionStart` for setup - it fires every session. Use the `WorktreeCreate` hook, which fires once when `claude --worktree` creates the worktree. The Claude wrapper script (`scripts/claude-worktree-create.sh`) is responsible for calling `git worktree add` itself, then handing off to `scripts/worktree-up.sh` inside the new worktree with `ROOT_WORKTREE_PATH` set. See [references/claude.md](references/claude.md).
73
+
74
+ If no env var yields a source checkout, fall back to a project-specific absolute path (e.g. `$HOME/Developer/saas/<repo>`). Ask the user during Step 1 if you cannot infer it.
75
+
76
+ ## `scripts/worktree-up.sh`
77
+
78
+ Setup must be **idempotent** - reruns are safe. Built from the user's Step 1 selections. Required behavior in order:
79
+
80
+ 1. `set -euo pipefail`.
81
+ 2. Resolve `WORKTREE_PATH` and `SOURCE_PATH`.
82
+ 3. `cd "$WORKTREE_PATH"`.
83
+ 4. If "Copy env files" selected: copy `.env`, `.env.local`, `.env.development.local` only when the source has them and the worktree does not.
84
+ 5. If "Install dependencies" selected: detect from lockfile and run the matching install.
85
+ 6. If "Isolated database" selected: build a DB name from `basename "$WORKTREE_PATH" | tr '/' '-'`, rewrite only `DATABASE_URL` (and any related vars) in the copied `.env`, create the DB if missing. Provide a reset escape hatch: `<PROJECT>_RESET_DB=1` drops and recreates.
86
+ 7. If "Codegen" selected: run the project's codegen command.
87
+ 8. Append any free-form project-specific steps from Step 1.
88
+
89
+ Reference template (adjust based on selections):
90
+
91
+ ```bash
92
+ #!/usr/bin/env bash
93
+ set -euo pipefail
94
+
95
+ WORKTREE_PATH="${CODEX_WORKTREE_PATH:-${CURSOR_WORKTREE_PATH:-$(pwd)}}"
96
+ SOURCE_PATH="${CODEX_SOURCE_TREE_PATH:-${ROOT_WORKTREE_PATH:-$HOME/Developer/saas/<repo>}}"
97
+
98
+ cd "$WORKTREE_PATH"
99
+
100
+ # Copy ignored env files.
101
+ # NOTE for Claude Code users: .worktreeinclude handles this natively. Prefer it
102
+ # over the cp loop when the project uses Claude's --worktree.
103
+ for f in .env .env.local .env.development.local; do
104
+ if [[ -f "$SOURCE_PATH/$f" && ! -f "$WORKTREE_PATH/$f" ]]; then
105
+ cp "$SOURCE_PATH/$f" "$WORKTREE_PATH/$f"
106
+ echo "copied $f"
107
+ fi
108
+ done
109
+
110
+ # Install deps
111
+ if [[ -f pnpm-lock.yaml ]]; then pnpm install
112
+ elif [[ -f bun.lock || -f bun.lockb ]]; then bun install
113
+ elif [[ -f yarn.lock ]]; then yarn install
114
+ elif [[ -f package-lock.json ]]; then npm install
115
+ fi
116
+
117
+ # Project-specific DB isolation and codegen go here.
118
+ ```
119
+
120
+ ## `scripts/worktree-down.sh`
121
+
122
+ Cleanup runs before the IDE destroys the worktree.
123
+
124
+ 1. `set -euo pipefail`.
125
+ 2. `cd "$WORKTREE_PATH"`.
126
+ 3. Read DB names from the worktree `.env`. **Never guess from branch names.**
127
+ 4. `dropdb --if-exists` per DB found, against a maintenance database.
128
+ 5. Remove copied env files.
129
+ 6. If env files or PostgreSQL tools are missing, print one short message and exit 0.
130
+
131
+ ```bash
132
+ #!/usr/bin/env bash
133
+ set -euo pipefail
134
+
135
+ WORKTREE_PATH="${CODEX_WORKTREE_PATH:-${CURSOR_WORKTREE_PATH:-$(pwd)}}"
136
+ cd "$WORKTREE_PATH"
137
+
138
+ if [[ ! -f .env ]]; then
139
+ echo "no .env in worktree, nothing to clean"
140
+ exit 0
141
+ fi
142
+
143
+ db_name=$(grep -E '^DATABASE_URL=' .env | sed -E 's|.*/([^/?]+).*|\1|' | head -n1 || true)
144
+ if [[ -n "${db_name:-}" ]] && command -v dropdb >/dev/null 2>&1; then
145
+ dropdb --if-exists -d postgres "$db_name" || true
146
+ fi
147
+
148
+ rm -f .env .env.local .env.development.local
149
+ ```
150
+
151
+ ## `scripts/dev.sh`
152
+
153
+ Pick a free port so multiple worktrees can run in parallel.
154
+
155
+ ```bash
156
+ #!/usr/bin/env bash
157
+ set -euo pipefail
158
+
159
+ WORKTREE_PATH="${CODEX_WORKTREE_PATH:-${CURSOR_WORKTREE_PATH:-$(pwd)}}"
160
+ cd "$WORKTREE_PATH"
161
+
162
+ port="${DEV_PORT_START:-3910}"
163
+ while lsof -nP -iTCP:"$port" -sTCP:LISTEN >/dev/null 2>&1; do
164
+ port=$((port + 1))
165
+ done
166
+
167
+ echo "Starting app on http://localhost:$port"
168
+ exec pnpm dev -p "$port" # adjust for the project package manager
169
+ ```
170
+
171
+ ## Standard Actions
172
+
173
+ Every project should expose these four actions through the IDE's own mechanism (see references). Wire them per IDE.
174
+
175
+ | Action | Command (typical) |
176
+ | :--------- | :------------------------------- |
177
+ | Dev | `scripts/dev.sh` |
178
+ | Typecheck | `pnpm ts` / `bun run typecheck` |
179
+ | Unit tests | `pnpm test:ci` / `bun test` |
180
+ | Lint | `pnpm lint:ci` / `bun run lint` |
181
+
182
+ Add `E2E` as an action only if the suite is cheap enough to run interactively.
183
+
184
+ ## Universal Guardrails
185
+
186
+ - Never commit secrets. Copying ignored env files into a local worktree is fine; logging them is not.
187
+ - Never drop a database whose name was guessed from a branch. Read it from the worktree `.env`.
188
+ - Never put fragile multi-line shell programs inside an IDE config file. Keep all logic in `scripts/`; the IDE config just calls those scripts.
189
+ - Never hardcode a dev port. Pick a free one starting from `${DEV_PORT_START:-3910}`.
190
+ - Setup must be idempotent. Provide a reset escape hatch via env var (`<PROJECT>_RESET_DB=1`).
191
+ - Print DB names and redacted hosts only.
192
+ - The scripts and IDE config must live on the source checkout / main branch, not only the current worktree, or future worktrees will have nothing to copy.
193
+ - **Never import data from a production source.** Any setup step that exports a database/deployment and replays it into the new worktree MUST reject any source ref containing `prod`/`production` and require an explicit override env var (`<PROJECT>_ALLOW_PROD_SOURCE=1`). Even a single mistaken `--replace-all` against the wrong source can nuke a teammate's dev environment or, worse, leak prod data into a feature branch. Default the source to `dev` and validate before each export.
194
+
195
+ ```bash
196
+ assert_dev_source() {
197
+ case "$1" in
198
+ prod|prod:*|prod/*|production|production:*|production/*)
199
+ echo "refusing prod source: $1" >&2; exit 1 ;;
200
+ *prod*|*production*)
201
+ [ "${ALLOW_PROD_SOURCE:-0}" = "1" ] || { echo "looks like prod: $1" >&2; exit 1; } ;;
202
+ esac
203
+ }
204
+ ```
205
+
206
+ - **Hook wrappers must survive a missing `/dev/tty`, a wrong default Node version, and CLI prompts.** See `references/claude.md` → "Hook Robustness" for the five concrete fixes.
207
+
208
+ ## Verification
209
+
210
+ After generating files:
211
+
212
+ ```bash
213
+ bash -n scripts/worktree-up.sh scripts/worktree-down.sh scripts/dev.sh
214
+ git status --short
215
+ ```
216
+
217
+ If Python 3.11+ is available, validate any generated TOML:
218
+
219
+ ```bash
220
+ python3 - <<'PY'
221
+ import tomllib
222
+ with open(".codex/environments/environment.toml", "rb") as f:
223
+ tomllib.load(f)
224
+ PY
225
+ ```
226
+
227
+ For JSON configs:
228
+
229
+ ```bash
230
+ python3 -c "import json; json.load(open('.cursor/worktrees.json'))"
231
+ python3 -c "import json; json.load(open('.claude/settings.json'))"
232
+ ```
233
+
234
+ ## IDE-Specific Linking
235
+
236
+ After the shared scripts are written, for each IDE selected in Step 2, load the matching reference file and apply only its linking config:
237
+
238
+ - **Claude Code** → [references/claude.md](references/claude.md) - `.claude/settings.json` SessionStart hook + custom slash commands as actions.
239
+ - **Cursor** → [references/cursor.md](references/cursor.md) - `.cursor/worktrees.json` setup keys.
240
+ - **Codex** → [references/codex.md](references/codex.md) - `.codex/environments/environment.toml` setup, cleanup, and actions.
241
+
242
+ If multiple IDEs were selected, generate `scripts/` once and then apply each reference in turn.
243
+
244
+ ## Examples
245
+
246
+ Working copies of every file this skill generates live under [examples/](examples/). Use them as the source-of-truth shape when writing into a real project. Adapt the project section (package manager, DB name prefix, codegen step) for the target repo.
247
+
248
+ ```text
249
+ examples/
250
+ ├── scripts/
251
+ │ ├── worktree-up.sh # pnpm + Postgres + Prisma reference
252
+ │ ├── worktree-down.sh # pnpm + Postgres reference
253
+ │ ├── dev.sh # free-port dev server reference
254
+ │ ├── claude-worktree-create.sh # Claude WorktreeCreate hook wrapper
255
+ │ └── claude-worktree-remove.sh # Claude WorktreeRemove hook wrapper
256
+ ├── claude/
257
+ │ ├── .worktreeinclude # native env-file copy list
258
+ │ ├── settings.json # WorktreeCreate + WorktreeRemove hooks
259
+ │ └── commands/ # optional slash-command actions
260
+ │ ├── dev.md
261
+ │ ├── typecheck.md
262
+ │ ├── test.md
263
+ │ └── lint.md
264
+ ├── cursor/
265
+ │ └── worktrees.json # setup-worktree-unix -> scripts/worktree-up.sh
266
+ └── codex/
267
+ └── environments/
268
+ └── environment.toml # setup, cleanup, four actions
269
+ ```
270
+
271
+ Read the relevant example before writing the file into the target project. Do not copy verbatim - the user's Step 1 selections determine which sections of `worktree-up.sh` survive.
@@ -0,0 +1,3 @@
1
+ .env
2
+ .env.local
3
+ .env.development.local
@@ -0,0 +1,5 @@
1
+ ---
2
+ description: Start the dev server on a free port
3
+ ---
4
+
5
+ Run `scripts/dev.sh` from the project root. Stream output until the dev server is listening, then return the URL.
@@ -0,0 +1,5 @@
1
+ ---
2
+ description: Run the linter
3
+ ---
4
+
5
+ Run the project's lint command (`pnpm lint:ci`, `bun run lint`, or equivalent). Report any violations.
@@ -0,0 +1,5 @@
1
+ ---
2
+ description: Run unit tests
3
+ ---
4
+
5
+ Run the project's unit test command (`pnpm test:ci`, `bun test`, or equivalent). Report failures with file:line references.
@@ -0,0 +1,5 @@
1
+ ---
2
+ description: Typecheck the project
3
+ ---
4
+
5
+ Run the project's typecheck command (`pnpm ts`, `bun run typecheck`, or equivalent based on the lockfile). Report any errors with file:line references.
@@ -0,0 +1,24 @@
1
+ {
2
+ "hooks": {
3
+ "WorktreeCreate": [
4
+ {
5
+ "hooks": [
6
+ {
7
+ "type": "command",
8
+ "command": "\"$CLAUDE_PROJECT_DIR\"/scripts/claude-worktree-create.sh"
9
+ }
10
+ ]
11
+ }
12
+ ],
13
+ "WorktreeRemove": [
14
+ {
15
+ "hooks": [
16
+ {
17
+ "type": "command",
18
+ "command": "\"$CLAUDE_PROJECT_DIR\"/scripts/claude-worktree-remove.sh"
19
+ }
20
+ ]
21
+ }
22
+ ]
23
+ }
24
+ }
@@ -0,0 +1,29 @@
1
+ # THIS IS AUTOGENERATED. DO NOT EDIT MANUALLY.
2
+ version = 1
3
+ name = "Project Worktree"
4
+
5
+ [setup]
6
+ script = "cd \"$CODEX_WORKTREE_PATH\"\nscripts/worktree-up.sh"
7
+
8
+ [cleanup]
9
+ script = "cd \"$CODEX_WORKTREE_PATH\"\nscripts/worktree-down.sh"
10
+
11
+ [[actions]]
12
+ name = "Dev"
13
+ icon = "tool"
14
+ command = "scripts/dev.sh"
15
+
16
+ [[actions]]
17
+ name = "Typecheck"
18
+ icon = "tool"
19
+ command = "pnpm ts"
20
+
21
+ [[actions]]
22
+ name = "Unit tests"
23
+ icon = "tool"
24
+ command = "pnpm test:ci"
25
+
26
+ [[actions]]
27
+ name = "Lint"
28
+ icon = "tool"
29
+ command = "pnpm lint:ci"
@@ -0,0 +1,3 @@
1
+ {
2
+ "setup-worktree-unix": "../scripts/worktree-up.sh"
3
+ }