create-agentic-app 1.1.53 → 1.1.55

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 (107) hide show
  1. package/package.json +1 -1
  2. package/template/.agents/skills/checkpoint/SKILL.md +75 -0
  3. package/template/.agents/skills/create-spec/SKILL.md +132 -0
  4. package/template/.agents/skills/create-spec/references/action-required-template.md +53 -0
  5. package/template/.agents/skills/create-spec/references/readme-template.md +53 -0
  6. package/template/.agents/skills/create-spec/references/requirements-template.md +54 -0
  7. package/template/.agents/skills/create-spec/references/task-template.md +79 -0
  8. package/template/.agents/skills/implement-feature/SKILL.md +189 -0
  9. package/template/.agents/skills/implement-feature/references/coder-prompt-template.md +46 -0
  10. package/template/.agents/skills/implement-feature/references/fix-prompt-template.md +38 -0
  11. package/template/.agents/skills/implement-feature/references/review-prompt-template.md +50 -0
  12. package/template/.agents/skills/review-pr/SKILL.md +97 -0
  13. package/template/.claude/skills/checkpoint/SKILL.md +75 -0
  14. package/template/.claude/skills/create-spec/SKILL.md +132 -0
  15. package/template/.claude/skills/create-spec/references/action-required-template.md +53 -0
  16. package/template/.claude/skills/create-spec/references/readme-template.md +53 -0
  17. package/template/.claude/skills/create-spec/references/requirements-template.md +54 -0
  18. package/template/.claude/skills/create-spec/references/task-template.md +79 -0
  19. package/template/.claude/skills/implement-feature/SKILL.md +189 -0
  20. package/template/.claude/skills/implement-feature/references/coder-prompt-template.md +46 -0
  21. package/template/.claude/skills/implement-feature/references/fix-prompt-template.md +38 -0
  22. package/template/.claude/skills/implement-feature/references/review-prompt-template.md +50 -0
  23. package/template/.claude/skills/review-pr/SKILL.md +97 -0
  24. package/template/AGENTS.md +32 -47
  25. package/template/skills-lock.json +0 -60
  26. package/template/.agents/skills/brainstorming/SKILL.md +0 -164
  27. package/template/.agents/skills/brainstorming/scripts/frame-template.html +0 -214
  28. package/template/.agents/skills/brainstorming/scripts/helper.js +0 -88
  29. package/template/.agents/skills/brainstorming/scripts/server.cjs +0 -354
  30. package/template/.agents/skills/brainstorming/scripts/start-server.sh +0 -148
  31. package/template/.agents/skills/brainstorming/scripts/stop-server.sh +0 -56
  32. package/template/.agents/skills/brainstorming/spec-document-reviewer-prompt.md +0 -49
  33. package/template/.agents/skills/brainstorming/visual-companion.md +0 -287
  34. package/template/.agents/skills/dispatching-parallel-agents/SKILL.md +0 -182
  35. package/template/.agents/skills/executing-plans/SKILL.md +0 -70
  36. package/template/.agents/skills/finishing-a-development-branch/SKILL.md +0 -200
  37. package/template/.agents/skills/receiving-code-review/SKILL.md +0 -213
  38. package/template/.agents/skills/requesting-code-review/SKILL.md +0 -105
  39. package/template/.agents/skills/requesting-code-review/code-reviewer.md +0 -146
  40. package/template/.agents/skills/subagent-driven-development/SKILL.md +0 -277
  41. package/template/.agents/skills/subagent-driven-development/code-quality-reviewer-prompt.md +0 -26
  42. package/template/.agents/skills/subagent-driven-development/implementer-prompt.md +0 -113
  43. package/template/.agents/skills/subagent-driven-development/spec-reviewer-prompt.md +0 -61
  44. package/template/.agents/skills/systematic-debugging/CREATION-LOG.md +0 -119
  45. package/template/.agents/skills/systematic-debugging/SKILL.md +0 -296
  46. package/template/.agents/skills/systematic-debugging/condition-based-waiting-example.ts +0 -158
  47. package/template/.agents/skills/systematic-debugging/condition-based-waiting.md +0 -115
  48. package/template/.agents/skills/systematic-debugging/defense-in-depth.md +0 -122
  49. package/template/.agents/skills/systematic-debugging/find-polluter.sh +0 -63
  50. package/template/.agents/skills/systematic-debugging/root-cause-tracing.md +0 -169
  51. package/template/.agents/skills/systematic-debugging/test-academic.md +0 -14
  52. package/template/.agents/skills/systematic-debugging/test-pressure-1.md +0 -58
  53. package/template/.agents/skills/systematic-debugging/test-pressure-2.md +0 -68
  54. package/template/.agents/skills/systematic-debugging/test-pressure-3.md +0 -69
  55. package/template/.agents/skills/test-driven-development/SKILL.md +0 -371
  56. package/template/.agents/skills/test-driven-development/testing-anti-patterns.md +0 -299
  57. package/template/.agents/skills/using-superpowers/SKILL.md +0 -117
  58. package/template/.agents/skills/using-superpowers/references/codex-tools.md +0 -100
  59. package/template/.agents/skills/using-superpowers/references/copilot-tools.md +0 -52
  60. package/template/.agents/skills/using-superpowers/references/gemini-tools.md +0 -33
  61. package/template/.agents/skills/verification-before-completion/SKILL.md +0 -139
  62. package/template/.agents/skills/writing-plans/SKILL.md +0 -152
  63. package/template/.agents/skills/writing-plans/plan-document-reviewer-prompt.md +0 -49
  64. package/template/.claude/commands/checkpoint.md +0 -37
  65. package/template/.claude/commands/continue-feature.md +0 -425
  66. package/template/.claude/commands/create-spec.md +0 -180
  67. package/template/.claude/commands/publish-to-github.md +0 -304
  68. package/template/.claude/commands/review-pr.md +0 -54
  69. package/template/.claude/skills/brainstorming/SKILL.md +0 -164
  70. package/template/.claude/skills/brainstorming/scripts/frame-template.html +0 -214
  71. package/template/.claude/skills/brainstorming/scripts/helper.js +0 -88
  72. package/template/.claude/skills/brainstorming/scripts/server.cjs +0 -354
  73. package/template/.claude/skills/brainstorming/scripts/start-server.sh +0 -148
  74. package/template/.claude/skills/brainstorming/scripts/stop-server.sh +0 -56
  75. package/template/.claude/skills/brainstorming/spec-document-reviewer-prompt.md +0 -49
  76. package/template/.claude/skills/brainstorming/visual-companion.md +0 -287
  77. package/template/.claude/skills/dispatching-parallel-agents/SKILL.md +0 -182
  78. package/template/.claude/skills/executing-plans/SKILL.md +0 -70
  79. package/template/.claude/skills/finishing-a-development-branch/SKILL.md +0 -200
  80. package/template/.claude/skills/receiving-code-review/SKILL.md +0 -213
  81. package/template/.claude/skills/requesting-code-review/SKILL.md +0 -105
  82. package/template/.claude/skills/requesting-code-review/code-reviewer.md +0 -146
  83. package/template/.claude/skills/subagent-driven-development/SKILL.md +0 -277
  84. package/template/.claude/skills/subagent-driven-development/code-quality-reviewer-prompt.md +0 -26
  85. package/template/.claude/skills/subagent-driven-development/implementer-prompt.md +0 -113
  86. package/template/.claude/skills/subagent-driven-development/spec-reviewer-prompt.md +0 -61
  87. package/template/.claude/skills/systematic-debugging/CREATION-LOG.md +0 -119
  88. package/template/.claude/skills/systematic-debugging/SKILL.md +0 -296
  89. package/template/.claude/skills/systematic-debugging/condition-based-waiting-example.ts +0 -158
  90. package/template/.claude/skills/systematic-debugging/condition-based-waiting.md +0 -115
  91. package/template/.claude/skills/systematic-debugging/defense-in-depth.md +0 -122
  92. package/template/.claude/skills/systematic-debugging/find-polluter.sh +0 -63
  93. package/template/.claude/skills/systematic-debugging/root-cause-tracing.md +0 -169
  94. package/template/.claude/skills/systematic-debugging/test-academic.md +0 -14
  95. package/template/.claude/skills/systematic-debugging/test-pressure-1.md +0 -58
  96. package/template/.claude/skills/systematic-debugging/test-pressure-2.md +0 -68
  97. package/template/.claude/skills/systematic-debugging/test-pressure-3.md +0 -69
  98. package/template/.claude/skills/test-driven-development/SKILL.md +0 -371
  99. package/template/.claude/skills/test-driven-development/testing-anti-patterns.md +0 -299
  100. package/template/.claude/skills/using-superpowers/SKILL.md +0 -117
  101. package/template/.claude/skills/using-superpowers/references/codex-tools.md +0 -100
  102. package/template/.claude/skills/using-superpowers/references/copilot-tools.md +0 -52
  103. package/template/.claude/skills/using-superpowers/references/gemini-tools.md +0 -33
  104. package/template/.claude/skills/verification-before-completion/SKILL.md +0 -139
  105. package/template/.claude/skills/writing-plans/SKILL.md +0 -152
  106. package/template/.claude/skills/writing-plans/plan-document-reviewer-prompt.md +0 -49
  107. package/template/.cursor/rules/project-rules.mdc +0 -6
@@ -0,0 +1,189 @@
1
+ ---
2
+ name: implement-feature
3
+ description: >
4
+ Orchestrate parallel implementation of a feature specification by dispatching coder agents
5
+ wave-by-wave with code review gates between waves. Use this skill when the user says
6
+ "implement this feature", "start implementing", "run the spec", "execute the plan",
7
+ "continue implementing", or wants to begin coding a previously planned feature from a
8
+ specs/{feature}/ folder. Also use when the user says "/implement-feature" or drags a spec
9
+ folder into the conversation and asks to implement it. This skill does NOT write code itself —
10
+ it orchestrates coder subagents that work in parallel.
11
+ ---
12
+
13
+ # Implement Feature
14
+
15
+ Orchestrate the parallel implementation of a feature specification by dispatching coder agents wave-by-wave. This skill reads a spec folder (created by `create-spec`), identifies the next wave of parallelizable work, spawns coder agents for each task, and runs a code review gate before moving to the next wave.
16
+
17
+ The orchestrator never writes code itself. Its job is to:
18
+ 1. Parse the spec and determine what to do next
19
+ 2. Give each coder agent exactly the context it needs
20
+ 3. Verify the results via code review
21
+ 4. Manage the fix loop if review finds issues
22
+ 5. Track progress and commit completed waves
23
+
24
+ ## Prerequisites
25
+
26
+ A `specs/{feature}/` directory containing:
27
+ - `README.md` with wave assignments and task status checkboxes
28
+ - `requirements.md` with feature context
29
+ - `tasks/task-{nn}-*.md` files (one per task, self-contained)
30
+
31
+ This structure is produced by the `create-spec` skill. If the user doesn't have a spec folder, suggest they create one first.
32
+
33
+ ## Orchestration
34
+
35
+ ### Step 1: Load the Spec
36
+
37
+ 1. Read `specs/{feature}/README.md`
38
+ 2. Read `specs/{feature}/requirements.md`
39
+ 3. Parse the **Task Status** section in the README — look at the checkboxes:
40
+ - `- [x]` = completed task (skip)
41
+ - `- [ ]` = pending task (include)
42
+ 4. Determine the **current wave**: the first wave that has any incomplete tasks
43
+ 5. If all tasks in all waves are complete, report "All tasks complete!" and stop
44
+
45
+ This makes the skill **resumable** — if invoked on a partially completed spec, it picks up exactly where it left off.
46
+
47
+ ### Step 2: Process Each Wave
48
+
49
+ For each wave starting from the current one, execute Steps 3 through 8 below, then advance to the next wave.
50
+
51
+ ### Step 3: Prepare Wave Tasks
52
+
53
+ 1. Read all incomplete task files for this wave from the `tasks/` subfolder
54
+ 2. **Check for file overlaps**: scan the "Files to Create" and "Files to Modify" sections across all tasks in this wave. If any file appears in more than one task, warn the user:
55
+
56
+ ```
57
+ Warning: File overlap detected in Wave {N}:
58
+ - {file-path} is modified by both task-{nn} and task-{mm}
59
+
60
+ Options:
61
+ 1. Proceed anyway (risk of conflicts)
62
+ 2. Run these tasks sequentially instead of in parallel
63
+ ```
64
+
65
+ Wait for the user's decision before proceeding.
66
+
67
+ ### Step 4: Dispatch Coder Agents
68
+
69
+ For each task in the wave, spawn a coder agent using the `Agent` tool with `subagent_type: "coder"`. Spawn all agents for the wave in a **single message** so they run in parallel.
70
+
71
+ Read `references/coder-prompt-template.md` and construct each agent's prompt by filling in:
72
+ - **{requirements}**: full text of `requirements.md`
73
+ - **{completed_tasks_summary}**: for each previously completed task, a one-paragraph summary of what was implemented and what files were created/modified (extract from the task file's Description section plus any completion notes)
74
+ - **{task_content}**: full text of the task file being assigned
75
+
76
+ The coder agents should NOT commit their changes — the orchestrator handles commits after review.
77
+
78
+ ### Step 5: Collect Results
79
+
80
+ Wait for all coder agents in the wave to complete. Each agent should report:
81
+ - Files created
82
+ - Files modified
83
+ - A summary of what was implemented
84
+
85
+ If any agent fails (returns an error or crashes), note the failure and continue with the remaining results. Report the failure to the user after the wave.
86
+
87
+ ### Step 6: Code Review Gate
88
+
89
+ Spawn a single review agent using the `Agent` tool with `subagent_type: "code-review"`.
90
+
91
+ Read `references/review-prompt-template.md` and construct the review prompt by filling in:
92
+ - **{wave_number}**: current wave number
93
+ - **{requirements}**: full text of `requirements.md`
94
+ - **{task_summaries}**: for each task in this wave, the task title and the coder agent's completion summary
95
+ - **{verification_commands}**: the project's lint and typecheck commands (e.g., `pnpm lint && pnpm typecheck`)
96
+
97
+ The review agent should:
98
+ 1. Run lint and typecheck
99
+ 2. Verify acceptance criteria from each task file
100
+ 3. Check that files integrate correctly (imports resolve, types match)
101
+ 4. Check for security issues and code quality
102
+ 5. Return a structured verdict: **PASS** or **FAIL** with specific issues
103
+
104
+ ### Step 7: Fix Loop
105
+
106
+ If the review returns **FAIL**:
107
+
108
+ 1. Parse the issues from the review (file paths, descriptions, suggested fixes)
109
+ 2. Group issues by the task they most closely relate to (match file paths against each task's "Files to Create/Modify")
110
+ 3. For each group, spawn a coder agent with a fix prompt. Read `references/fix-prompt-template.md` and fill in:
111
+ - **{issues}**: the specific issues for this task group
112
+ - **{task_content}**: the original task file for context
113
+ 4. After fix agents complete, re-run the review (Step 6)
114
+
115
+ **Cap at 3 review cycles per wave.** If the third review still fails, stop and report to the user:
116
+
117
+ ```
118
+ Wave {N} review failed after 3 cycles. Outstanding issues:
119
+ {list of remaining issues}
120
+
121
+ Options:
122
+ 1. Fix these manually and re-run /implement-feature
123
+ 2. Proceed to the next wave anyway
124
+ 3. Stop here
125
+ ```
126
+
127
+ ### Step 8: Complete the Wave
128
+
129
+ After the wave passes review (or the user chooses to proceed):
130
+
131
+ 1. **Update task files**: for each completed task, change the Status field from `pending` to `complete`
132
+ 2. **Update README.md**: change `- [ ]` to `- [x]` for each completed task
133
+ 3. **Commit the wave**:
134
+ ```
135
+ git add -A
136
+ git commit -m "feat({feature}): complete wave {N} — {brief summary}"
137
+ ```
138
+ 4. **Report wave completion**:
139
+ ```
140
+ Wave {N} of {total} complete.
141
+
142
+ Tasks completed:
143
+ - task-{nn}-{name}: {one-line summary}
144
+ - task-{mm}-{name}: {one-line summary}
145
+
146
+ Review: PASS
147
+ Commit: {hash}
148
+
149
+ Next: Wave {N+1} has {count} tasks ready for parallel execution.
150
+ ```
151
+
152
+ ### Step 9: Final Integration Review
153
+
154
+ After all waves are complete:
155
+
156
+ 1. Run lint and typecheck one final time
157
+ 2. Spawn a code-review agent to review the full scope of changes (all files modified across all waves)
158
+ 3. Report the final status:
159
+
160
+ ```
161
+ Feature "{feature}" implementation complete.
162
+
163
+ Waves completed: {N}/{N}
164
+ Total tasks: {T}
165
+
166
+ Verification:
167
+ - Lint: {PASS/FAIL}
168
+ - Typecheck: {PASS/FAIL}
169
+ - Integration review: {PASS/FAIL with notes}
170
+
171
+ Next steps:
172
+ - Review the changes
173
+ - Push and create a PR when ready
174
+ ```
175
+
176
+ ## Error Handling
177
+
178
+ - **Coder agent failure**: mark the task as failed, report to user, continue with remaining tasks in the wave. The review step will catch integration issues.
179
+ - **Lint/typecheck failure after fix attempts**: report the specific errors and ask the user whether to commit anyway or fix manually.
180
+ - **All tasks already complete**: report completion and stop.
181
+ - **Missing spec folder**: ask the user to provide the feature name or suggest creating a spec with `create-spec`.
182
+
183
+ ## Key Principles
184
+
185
+ - **The orchestrator does not write code.** Its job is dispatch, review, and progress tracking. All implementation happens in coder subagents.
186
+ - **Each coder agent gets exactly one task.** This keeps each agent's context focused and manageable.
187
+ - **Completed task summaries are brief.** One paragraph per task — not the full file contents. This keeps coder agent prompts from growing unbounded as waves progress.
188
+ - **The review gate is non-negotiable.** Every wave gets reviewed before commit. This catches integration issues early rather than letting them compound across waves.
189
+ - **Progress is tracked in the spec files.** README checkboxes and task file status fields are the source of truth. This makes the skill resumable across sessions.
@@ -0,0 +1,46 @@
1
+ # Coder Agent Prompt Template
2
+
3
+ Use this template when constructing prompts for coder subagents. Replace the placeholders (`{requirements}`, `{completed_tasks_summary}`, `{task_content}`) with actual content from the spec files.
4
+
5
+ ## Template
6
+
7
+ ```
8
+ You are implementing a single task from a feature specification. Your job is to write the code described below — nothing more, nothing less.
9
+
10
+ ## Feature Context
11
+
12
+ {requirements}
13
+
14
+ ## What's Already Been Built
15
+
16
+ {completed_tasks_summary}
17
+
18
+ ## Your Task
19
+
20
+ {task_content}
21
+
22
+ ## Instructions
23
+
24
+ 1. Read the relevant parts of the codebase to understand existing patterns, imports, and conventions
25
+ 2. Implement everything described in the task's Technical Details and Implementation Steps
26
+ 3. Follow the project's existing code patterns and conventions
27
+ 4. Run the project's lint and typecheck commands after making changes. Fix any errors before finishing.
28
+ 5. Do NOT commit your changes — the orchestrator handles commits after review
29
+ 6. When done, report:
30
+ - Files created (with paths)
31
+ - Files modified (with paths)
32
+ - A one-paragraph summary of what you implemented
33
+ ```
34
+
35
+ ## Placeholder Details
36
+
37
+ - **{requirements}**: paste the full text of `requirements.md`. This gives the agent overall feature context — the "what" and "why" — so it can make good judgment calls during implementation.
38
+
39
+ - **{completed_tasks_summary}**: for each previously completed task, include a brief summary like:
40
+ ```
41
+ - task-01-setup-database: Created PostgreSQL schema with users and sessions tables. Files: src/db/schema.ts, src/db/migrations/001_initial.sql
42
+ - task-02-auth-config: Set up Better Auth with email/password provider. Files: src/lib/auth.ts, src/lib/auth-client.ts
43
+ ```
44
+ Keep each entry to 1-2 lines. The purpose is to give the agent awareness of what exists, not full implementation details.
45
+
46
+ - **{task_content}**: paste the full text of the task file (task-{nn}-{name}.md). This is the agent's primary instruction set — it contains the description, technical details, files to create/modify, and acceptance criteria.
@@ -0,0 +1,38 @@
1
+ # Fix Agent Prompt Template
2
+
3
+ Use this template when constructing prompts for coder agents that fix issues found during code review. Replace the placeholders with actual content.
4
+
5
+ ## Template
6
+
7
+ ```
8
+ You are fixing specific issues found during code review. Address every issue listed below — do not skip any.
9
+
10
+ ## Issues to Fix
11
+
12
+ {issues}
13
+
14
+ ## Original Task Context
15
+
16
+ {task_content}
17
+
18
+ ## Instructions
19
+
20
+ 1. Fix each issue listed above. The review provided file paths, line numbers, and suggested fixes — use those as your starting point.
21
+ 2. Run the project's lint and typecheck commands after making fixes. Resolve any new errors your fixes introduce.
22
+ 3. Do NOT commit your changes — the orchestrator handles commits.
23
+ 4. Do NOT make changes beyond what's needed to fix the listed issues. Stay within scope.
24
+ 5. When done, report:
25
+ - What you fixed (reference each issue)
26
+ - Any files modified
27
+ - If you could NOT fix an issue, explain why
28
+ ```
29
+
30
+ ## Placeholder Details
31
+
32
+ - **{issues}**: the specific issues from the review that relate to this task. Include file paths, line numbers, descriptions, severity, and suggested fixes. Example:
33
+ ```
34
+ - Issue 1: src/api/users.ts:42 — Missing error handling for database connection failure — Severity: high — Suggested fix: wrap the query in try/catch and return a 500 response
35
+ - Issue 2: src/api/users.ts:15 — Unused import 'Session' — Severity: low — Suggested fix: remove the import
36
+ ```
37
+
38
+ - **{task_content}**: the full text of the original task file for context. The fix agent may need to reference the task's technical details or acceptance criteria to understand the intended behavior.
@@ -0,0 +1,50 @@
1
+ # Review Agent Prompt Template
2
+
3
+ Use this template when constructing prompts for the code review agent that runs between waves. Replace the placeholders with actual content.
4
+
5
+ ## Template
6
+
7
+ ```
8
+ You are reviewing the combined output of Wave {wave_number} of a feature implementation. Multiple coder agents worked in parallel on separate tasks — your job is to verify everything integrates correctly and meets quality standards.
9
+
10
+ ## Feature Context
11
+
12
+ {requirements}
13
+
14
+ ## Tasks Completed in This Wave
15
+
16
+ {task_summaries}
17
+
18
+ ## Review Checklist
19
+
20
+ 1. **Verification**: Run `{verification_commands}` and report results. Fix nothing — just report.
21
+ 2. **Acceptance Criteria**: For each task listed above, check whether the implementation meets the acceptance criteria from its task file.
22
+ 3. **Integration**: Verify that files created by different tasks work together:
23
+ - Imports resolve correctly
24
+ - Types match across module boundaries
25
+ - No duplicate or conflicting definitions
26
+ - Shared state (env vars, config) is consistent
27
+ 4. **Code Quality**: Check for security issues, performance problems, and adherence to project conventions.
28
+ 5. **Scope**: Verify each task stayed within its defined scope (Files to Create/Modify). Flag any unexpected file changes.
29
+
30
+ ## Verdict
31
+
32
+ Respond with one of:
33
+
34
+ **VERDICT: PASS**
35
+ All checks passed. Include any minor observations as notes.
36
+
37
+ **VERDICT: FAIL**
38
+ Include a structured list of issues:
39
+ - **Issue 1**: {file:line} — {description} — Severity: {high/medium/low} — Suggested fix: {fix}
40
+ - **Issue 2**: ...
41
+
42
+ Group issues by the task they most closely relate to (based on which task's files are affected). This helps the orchestrator dispatch targeted fix agents.
43
+ ```
44
+
45
+ ## Placeholder Details
46
+
47
+ - **{wave_number}**: the current wave number (e.g., "2")
48
+ - **{requirements}**: full text of `requirements.md`
49
+ - **{task_summaries}**: for each task in the wave, include the task title and the coder agent's completion summary (files created/modified + what was implemented)
50
+ - **{verification_commands}**: the project's lint and typecheck commands. Check for `package.json` scripts — typically `pnpm lint && pnpm typecheck` or similar.
@@ -0,0 +1,97 @@
1
+ ---
2
+ name: review-pr
3
+ description: >
4
+ Review pull requests with complexity-adaptive depth — spawning deep-dive agents for medium
5
+ and complex PRs. Use this skill when the user says "review this PR", "review PR #123",
6
+ "check this pull request", "give me a code review", or wants feedback on a PR before merging.
7
+ Also use when the user says "/review-pr" or pastes a GitHub PR URL. Requires the GitHub CLI (gh).
8
+ ---
9
+
10
+ # Review Pull Request
11
+
12
+ Review pull requests with a depth that matches their complexity. Simple PRs get a direct review; complex PRs get parallel deep-dive agents analyzing security, performance, and architecture.
13
+
14
+ ## Arguments
15
+
16
+ The user should provide PR number(s) or URL(s). If none provided, ask for them.
17
+
18
+ ## Instructions
19
+
20
+ ### Step 1: Retrieve PR Details
21
+
22
+ Use the GitHub CLI to get the full picture:
23
+
24
+ ```bash
25
+ gh pr view {pr_number} --json title,body,files,additions,deletions,commits,author,reviews,comments
26
+ gh pr diff {pr_number}
27
+ ```
28
+
29
+ ### Step 2: Assess Complexity
30
+
31
+ Score the PR based on:
32
+ - Number of files changed
33
+ - Lines added/removed
34
+ - Number of commits
35
+ - Whether changes touch core/architectural files
36
+
37
+ **Simple** (direct review, no agents):
38
+ - 5 or fewer files AND 100 or fewer lines AND single author
39
+
40
+ **Medium** (1-2 deep-dive agents):
41
+ - 6-15 files, OR 100-500 lines, OR 2 contributors
42
+
43
+ **Complex** (up to 3 deep-dive agents):
44
+ - More than 15 files, OR more than 500 lines, OR more than 2 contributors, OR touches core architecture
45
+
46
+ ### Step 3: Analyze
47
+
48
+ **For Simple PRs**: review directly — read the diff, check for issues, provide feedback.
49
+
50
+ **For Medium/Complex PRs**: spawn deep-dive agents in parallel using the `Agent` tool with `subagent_type: "deep-dive"`. Each agent gets a focused area:
51
+
52
+ - **Agent 1 — Code Quality**: conventions, patterns, maintainability, test coverage
53
+ - **Agent 2 — Security**: input validation, auth checks, injection risks, data exposure
54
+ - **Agent 3 — Architecture** (Complex only): design patterns, separation of concerns, performance implications, backwards compatibility
55
+
56
+ Each agent receives the PR diff and description and returns a structured review.
57
+
58
+ ### Step 4: Vision Alignment
59
+
60
+ Read the project's `README.md` and `CLAUDE.md` to understand the application's purpose. Assess whether the PR aligns with the project's intended direction. Flag significant deviations — not as a blocker, but as a consideration for the reviewer.
61
+
62
+ ### Step 5: Safety Assessment
63
+
64
+ Provide an overall assessment:
65
+ - **Safe to merge**: no significant issues found
66
+ - **Merge with caution**: minor issues that should be noted but aren't blocking
67
+ - **Needs changes**: issues that should be fixed before merging
68
+
69
+ Include a risk level (low/medium/high) with justification.
70
+
71
+ ### Step 6: Report
72
+
73
+ Structure the review as:
74
+
75
+ ```
76
+ ## PR Review: #{pr_number} — {title}
77
+
78
+ ### Complexity: {Simple|Medium|Complex}
79
+ {Brief justification}
80
+
81
+ ### Summary
82
+ {2-3 sentence overview of what the PR does}
83
+
84
+ ### Issues Found
85
+ {Grouped by severity: high → medium → low}
86
+ - **{severity}**: {file:line} — {description}
87
+
88
+ ### Improvements Suggested
89
+ {Optional improvements ranked by importance and implementation complexity}
90
+
91
+ ### Vision Alignment
92
+ {Does this PR align with the project's direction?}
93
+
94
+ ### Verdict: {Safe to merge | Merge with caution | Needs changes}
95
+ Risk level: {low|medium|high}
96
+ {Brief justification}
97
+ ```
@@ -1,62 +1,47 @@
1
- # Project Agent Instructions
1
+ ## Planning mode
2
2
 
3
- ## Skills are mandatory, not optional
3
+ Never make assumptions about what the user wants. Always ask clarifying questions before proceeding.
4
4
 
5
- **ALWAYS invoke the relevant skill before doing work.** Do not rely on your own judgment, training, or built-in workflows when a project skill applies to the task. Skills encode how we want work done in this project — skipping them produces output that misses project-specific patterns, stack conventions, and past lessons.
5
+ # Project Agent Instructions
6
6
 
7
- **This overrides Claude Code's built-in workflows.** Plan mode's phases (Explore → Plan agent → Review → final plan) are a scaffold, not a replacement for `writing-plans`, `brainstorming`, or other planning skills. If a skill applies, invoke it _inside_ plan mode's phases — not instead of them. The same rule holds for any other built-in behavior that would otherwise lead you to skip a skill.
7
+ ## Skills
8
8
 
9
- ## Pre-flight checklistrun BEFORE every non-trivial task
9
+ This repo ships agent skills under `.claude/skills` (mirrored at `.agents/skills`). **Read and follow the relevant skill** when your task matches its domainskills encode stack conventions and patterns for this project.
10
10
 
11
- Before doing anything else on a new task (reading files, writing plans, exploring the codebase, delegating to sub-agents):
11
+ Use **`find-skills`** when you are unsure whether a skill exists for a task or want to discover installable skills from registries.
12
12
 
13
- 1. **Invoke `using-superpowers` first.** This is the default entry point for any real task. It routes to the right skills and establishes how to find and use them.
14
- 2. **Scan the skills list against the task.** Mentally map the task to skills using the routing table below. Multiple skills usually apply — invoke all that match.
15
- 3. **Invoke matching skills before any other action.** No exploration, no planning, no file reads until the relevant skills have been invoked.
13
+ ## Pre-flight (non-trivial tasks)
16
14
 
17
- If you catch yourself mid-task having skipped this checklist, stop and run it immediately. Do not rationalize that "it's too late now" or "the task is almost done."
15
+ 1. Map the work to skills using the routing table below.
16
+ 2. Open and follow matching skills before writing substantial code or making architectural decisions.
18
17
 
19
- ## Task skill routing (binding)
18
+ If you start down the wrong path, stop, invoke the right skill, and continue from there.
20
19
 
21
- | If you are about to… | You MUST first invoke |
22
- | ------------------------------------------------------- | ----------------------------------------------------------------------------- |
23
- | Start any non-trivial task | `using-superpowers` |
24
- | Create a feature, component, or new behavior | `brainstorming` |
25
- | Write a multi-step implementation plan | `writing-plans` |
26
- | Execute an existing plan | `executing-plans` (plus `subagent-driven-development` when tasks parallelize) |
27
- | Dispatch multiple independent sub-agents in parallel | `dispatching-parallel-agents` |
28
- | Write or modify production code | `test-driven-development` |
29
- | Debug a bug, test failure, or unexpected behavior | `systematic-debugging` |
30
- | Claim work is complete, passing, fixed, or ready | `verification-before-completion` |
31
- | Receive code review feedback | `receiving-code-review` |
32
- | Request code review or verify work against requirements | `requesting-code-review` |
33
- | Finish a development branch / decide how to integrate | `finishing-a-development-branch` |
34
- | Touch Next.js App Router code | `nextjs` |
35
- | Touch shadcn/ui components or registries | `shadcn` |
36
- | Touch Better Auth configuration or auth flows | `better-auth-best-practices` |
37
- | Optimize or review React / Next.js performance | `vercel-react-best-practices` |
38
- | Build, modify, or review an MCP server | `mcp-builder` |
39
- | Build or review a frontend design / UI | `frontend-design`, `web-design-guidelines` |
40
- | Work with Claude API / Anthropic SDK code | `claude-api` |
41
- | Automate browser testing | `playwright-cli` |
42
- | Look for a skill you think might exist | `find-skills` |
20
+ ## Task skill routing
43
21
 
44
- Stack-specific skills (`nextjs`, `shadcn`, `better-auth-best-practices`, `mcp-builder`) compose with workflow skills (`brainstorming`, `writing-plans`, `test-driven-development`). Invoking one does not excuse you from invoking the others.
22
+ | If you are about to… | Invoke first |
23
+ | --- | --- |
24
+ | Plan a feature, create a spec, break work into tasks | `create-spec` |
25
+ | Implement a planned feature, execute a spec | `implement-feature` |
26
+ | Create a checkpoint commit | `checkpoint` |
27
+ | Review a pull request | `review-pr` |
28
+ | Touch Next.js App Router, routing, RSC, data fetching, deployment | `nextjs` |
29
+ | Touch shadcn/ui components or registries | `shadcn` |
30
+ | Touch Better Auth configuration or auth flows | `better-auth-best-practices` |
31
+ | Optimize or review React / Next.js performance | `vercel-react-best-practices` |
32
+ | Build, modify, or review an MCP server | `mcp-builder` |
33
+ | Build or review a frontend design / UI | `frontend-design`, `web-design-guidelines` |
34
+ | Automate browser testing (Playwright) | `playwright-cli` |
35
+ | Create or refine project agent skills | `skill-creator` |
36
+ | Look for a skill or extend capabilities | `find-skills` |
45
37
 
46
- ## Hard rules (violations are bugs, not preferences)
38
+ Stack skills compose: invoking `nextjs` does not excuse skipping `shadcn` or `better-auth-best-practices` when those layers are involved.
47
39
 
48
- 1. **Never skip `brainstorming` before creative work.** Its description says MUST. That MUST is binding in this project.
49
- 2. **Never write an implementation plan — in plan mode or out of it — without `writing-plans`.** Plan mode's built-in workflow is not a substitute.
50
- 3. **Never write production code without `test-driven-development`.** Tests first, code second.
51
- 4. **Never debug by pattern-matching.** Use `systematic-debugging` for every bug, test failure, or unexpected behavior — even ones that look obvious.
52
- 5. **Never claim something is done, fixed, working, or passing without first running `verification-before-completion`.** Evidence before assertions, always.
53
- 6. **Never touch the Next.js / shadcn / Better Auth / MCP layers without their corresponding stack skill.** They are not optional reference material — they are mandatory consultations.
54
- 7. **When in doubt, invoke `using-superpowers` and let it route.** Do not guess which skill applies — let the routing skill decide.
40
+ ## Hard rules
55
41
 
56
- ## If no skill matches
42
+ 1. **Never touch the Next.js / shadcn / Better Auth / MCP layers without reading their corresponding skill** for this repo. They are mandatory references, not optional browsing.
43
+ 2. **Before claiming work is done, fixed, or passing**, run the project’s verification commands (see workspace rules: lint and typecheck scripts) and only assert success when the output supports it.
57
44
 
58
- Only then fall back to your own judgment. When you do, state explicitly in your response: _"I checked the skills list and none applied because …"_ — so the user can correct you if you missed one.
59
-
60
- ## Why this is strict
45
+ ## If no skill matches
61
46
 
62
- Earlier sessions showed that "lean towards" language gets discounted when it competes with explicit built-in workflows (like plan mode). Soft preferences lose; hard rules win. This file is strict because the previous version was not strict enough.
47
+ Fall back to sound engineering judgment. State explicitly: _"I checked the skills list and none applied because …"_ so the user can correct a missed skill.
@@ -6,31 +6,11 @@
6
6
  "sourceType": "github",
7
7
  "computedHash": "9ab075b5061be2a5f299c10505667345cc1ec76e8de4120901cfd586643e776f"
8
8
  },
9
- "brainstorming": {
10
- "source": "obra/superpowers",
11
- "sourceType": "github",
12
- "computedHash": "f483c304fcde060211ffae00f49bb728536e7e7613c99db45b5b924d9fc17243"
13
- },
14
- "dispatching-parallel-agents": {
15
- "source": "obra/superpowers",
16
- "sourceType": "github",
17
- "computedHash": "e21044ae7496fc285f1df9ff3fb518a3a20bea6f5216c1f59f4987e12c769a0a"
18
- },
19
- "executing-plans": {
20
- "source": "obra/superpowers",
21
- "sourceType": "github",
22
- "computedHash": "2f709d1a2c7564f8ce6a9bb707e7f5451117ba80f8e8e2302662c29bc61246a6"
23
- },
24
9
  "find-skills": {
25
10
  "source": "vercel-labs/skills",
26
11
  "sourceType": "github",
27
12
  "computedHash": "9e1c8b3103f92fa8092568a44fe64858de7c5c9dc65ce4bea8f168080e889cfd"
28
13
  },
29
- "finishing-a-development-branch": {
30
- "source": "obra/superpowers",
31
- "sourceType": "github",
32
- "computedHash": "9edba9a38684c060fdc38290f640e1dc0c37de286723ac9be73bacacf7cd6f3d"
33
- },
34
14
  "frontend-design": {
35
15
  "source": "anthropics/skills",
36
16
  "sourceType": "github",
@@ -51,16 +31,6 @@
51
31
  "sourceType": "github",
52
32
  "computedHash": "675811a7e7f958e6544f9c6bc53993c85fe39e72c5820a60d9d46bd169eddc32"
53
33
  },
54
- "receiving-code-review": {
55
- "source": "obra/superpowers",
56
- "sourceType": "github",
57
- "computedHash": "2760c85d4f4117b0006e7ba755f4bbd61f8f4c185f347999763c97f507274e30"
58
- },
59
- "requesting-code-review": {
60
- "source": "obra/superpowers",
61
- "sourceType": "github",
62
- "computedHash": "246e65cd72a7e360987d94e6c61564ce6d71c6361d1784d529d70e4cbbe8522d"
63
- },
64
34
  "shadcn": {
65
35
  "source": "shadcn/ui",
66
36
  "sourceType": "github",
@@ -71,45 +41,15 @@
71
41
  "sourceType": "github",
72
42
  "computedHash": "57f470f512f45bdac598e302bc72fd62bf2b649fc7fad032efe97720149cde4d"
73
43
  },
74
- "subagent-driven-development": {
75
- "source": "obra/superpowers",
76
- "sourceType": "github",
77
- "computedHash": "a197f8e5fba5ea59013e1adbaa90dd42db35de8f074feca200c8038de584a83b"
78
- },
79
- "systematic-debugging": {
80
- "source": "obra/superpowers",
81
- "sourceType": "github",
82
- "computedHash": "72e9ab72627e4fd8ed26a582e82309a98ecdc4f6e1c99418430ac05682c9e91d"
83
- },
84
- "test-driven-development": {
85
- "source": "obra/superpowers",
86
- "sourceType": "github",
87
- "computedHash": "126f1ebf6ccd414f42544f6e83d8cc5adb089e1108eaffb7c400701e37eecd9f"
88
- },
89
- "using-superpowers": {
90
- "source": "obra/superpowers",
91
- "sourceType": "github",
92
- "computedHash": "e0eced9fbb205c212f420aded0c6f2bf5d5f059254679a8459b4fe72390160be"
93
- },
94
44
  "vercel-react-best-practices": {
95
45
  "source": "vercel-labs/agent-skills",
96
46
  "sourceType": "github",
97
47
  "computedHash": "257b84bf218a7d3b2cba56e929b7e933cf71cb89f2e24ab601759c599d1c23f2"
98
48
  },
99
- "verification-before-completion": {
100
- "source": "obra/superpowers",
101
- "sourceType": "github",
102
- "computedHash": "9b446f0c7fe1cfb560b1d34439523b1a76d5f177290007b2c053a1c749a4a8ba"
103
- },
104
49
  "web-design-guidelines": {
105
50
  "source": "vercel-labs/agent-skills",
106
51
  "sourceType": "github",
107
52
  "computedHash": "f3bc47f890f42a44db1007ab390709ec368e4b8c089baee6b0007182236ac474"
108
- },
109
- "writing-plans": {
110
- "source": "obra/superpowers",
111
- "sourceType": "github",
112
- "computedHash": "bfaed11054ad8021c66860244e2d2e0d1eca483ae9f5fbfcb956e99c61f5c3d7"
113
53
  }
114
54
  }
115
55
  }