create-agentic-app 1.1.54 → 1.1.55

package/template/.claude/skills/implement-feature/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: implement-feature
+description: >
+  Orchestrate parallel implementation of a feature specification by dispatching coder agents
+  wave-by-wave with code review gates between waves. Use this skill when the user says
+  "implement this feature", "start implementing", "run the spec", "execute the plan",
+  "continue implementing", or wants to begin coding a previously planned feature from a
+  specs/{feature}/ folder. Also use when the user says "/implement-feature" or drags a spec
+  folder into the conversation and asks to implement it. This skill does NOT write code itself —
+  it orchestrates coder subagents that work in parallel.
+---
+
+# Implement Feature
+
+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.
+
+The orchestrator never writes code itself. Its job is to:
+1. Parse the spec and determine what to do next
+2. Give each coder agent exactly the context it needs
+3. Verify the results via code review
+4. Manage the fix loop if review finds issues
+5. Track progress and commit completed waves
+
+## Prerequisites
+
+A `specs/{feature}/` directory containing:
+- `README.md` with wave assignments and task status checkboxes
+- `requirements.md` with feature context
+- `tasks/task-{nn}-*.md` files (one per task, self-contained)
+
+This structure is produced by the `create-spec` skill. If the user doesn't have a spec folder, suggest they create one first.
+
+## Orchestration
+
+### Step 1: Load the Spec
+
+1. Read `specs/{feature}/README.md`
+2. Read `specs/{feature}/requirements.md`
+3. Parse the **Task Status** section in the README — look at the checkboxes:
+   - `- [x]` = completed task (skip)
+   - `- [ ]` = pending task (include)
+4. Determine the **current wave**: the first wave that has any incomplete tasks
+5. If all tasks in all waves are complete, report "All tasks complete!" and stop
+
+This makes the skill **resumable** — if invoked on a partially completed spec, it picks up exactly where it left off.
+
+### Step 2: Process Each Wave
+
+For each wave starting from the current one, execute Steps 3 through 8 below, then advance to the next wave.
+
+### Step 3: Prepare Wave Tasks
+
+1. Read all incomplete task files for this wave from the `tasks/` subfolder
+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:
+
+   ```
+   Warning: File overlap detected in Wave {N}:
+   - {file-path} is modified by both task-{nn} and task-{mm}
+
+   Options:
+   1. Proceed anyway (risk of conflicts)
+   2. Run these tasks sequentially instead of in parallel
+   ```
+
+   Wait for the user's decision before proceeding.
+
+### Step 4: Dispatch Coder Agents
+
+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.
+
+Read `references/coder-prompt-template.md` and construct each agent's prompt by filling in:
+- **{requirements}**: full text of `requirements.md`
+- **{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)
+- **{task_content}**: full text of the task file being assigned
+
+The coder agents should NOT commit their changes — the orchestrator handles commits after review.
+
+### Step 5: Collect Results
+
+Wait for all coder agents in the wave to complete. Each agent should report:
+- Files created
+- Files modified
+- A summary of what was implemented
+
+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.
+
+### Step 6: Code Review Gate
+
+Spawn a single review agent using the `Agent` tool with `subagent_type: "code-review"`.
+
+Read `references/review-prompt-template.md` and construct the review prompt by filling in:
+- **{wave_number}**: current wave number
+- **{requirements}**: full text of `requirements.md`
+- **{task_summaries}**: for each task in this wave, the task title and the coder agent's completion summary
+- **{verification_commands}**: the project's lint and typecheck commands (e.g., `pnpm lint && pnpm typecheck`)
+
+The review agent should:
+1. Run lint and typecheck
+2. Verify acceptance criteria from each task file
+3. Check that files integrate correctly (imports resolve, types match)
+4. Check for security issues and code quality
+5. Return a structured verdict: **PASS** or **FAIL** with specific issues
+
+### Step 7: Fix Loop
+
+If the review returns **FAIL**:
+
+1. Parse the issues from the review (file paths, descriptions, suggested fixes)
+2. Group issues by the task they most closely relate to (match file paths against each task's "Files to Create/Modify")
+3. For each group, spawn a coder agent with a fix prompt. Read `references/fix-prompt-template.md` and fill in:
+   - **{issues}**: the specific issues for this task group
+   - **{task_content}**: the original task file for context
+4. After fix agents complete, re-run the review (Step 6)
+
+**Cap at 3 review cycles per wave.** If the third review still fails, stop and report to the user:
+
+```
+Wave {N} review failed after 3 cycles. Outstanding issues:
+{list of remaining issues}
+
+Options:
+1. Fix these manually and re-run /implement-feature
+2. Proceed to the next wave anyway
+3. Stop here
+```
+
+### Step 8: Complete the Wave
+
+After the wave passes review (or the user chooses to proceed):
+
+1. **Update task files**: for each completed task, change the Status field from `pending` to `complete`
+2. **Update README.md**: change `- [ ]` to `- [x]` for each completed task
+3. **Commit the wave**:
+   ```
+   git add -A
+   git commit -m "feat({feature}): complete wave {N} — {brief summary}"
+   ```
+4. **Report wave completion**:
+   ```
+   Wave {N} of {total} complete.
+
+   Tasks completed:
+   - task-{nn}-{name}: {one-line summary}
+   - task-{mm}-{name}: {one-line summary}
+
+   Review: PASS
+   Commit: {hash}
+
+   Next: Wave {N+1} has {count} tasks ready for parallel execution.
+   ```
+
+### Step 9: Final Integration Review
+
+After all waves are complete:
+
+1. Run lint and typecheck one final time
+2. Spawn a code-review agent to review the full scope of changes (all files modified across all waves)
+3. Report the final status:
+
+```
+Feature "{feature}" implementation complete.
+
+Waves completed: {N}/{N}
+Total tasks: {T}
+
+Verification:
+- Lint: {PASS/FAIL}
+- Typecheck: {PASS/FAIL}
+- Integration review: {PASS/FAIL with notes}
+
+Next steps:
+- Review the changes
+- Push and create a PR when ready
+```
+
+## Error Handling
+
+- **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.
+- **Lint/typecheck failure after fix attempts**: report the specific errors and ask the user whether to commit anyway or fix manually.
+- **All tasks already complete**: report completion and stop.
+- **Missing spec folder**: ask the user to provide the feature name or suggest creating a spec with `create-spec`.
+
+## Key Principles
+
+- **The orchestrator does not write code.** Its job is dispatch, review, and progress tracking. All implementation happens in coder subagents.
+- **Each coder agent gets exactly one task.** This keeps each agent's context focused and manageable.
+- **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.
+- **The review gate is non-negotiable.** Every wave gets reviewed before commit. This catches integration issues early rather than letting them compound across waves.
+- **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.

package/template/.claude/skills/implement-feature/references/coder-prompt-template.md

@@ -0,0 +1,46 @@
+# Coder Agent Prompt Template
+
+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.
+
+## Template
+
+```
+You are implementing a single task from a feature specification. Your job is to write the code described below — nothing more, nothing less.
+
+## Feature Context
+
+{requirements}
+
+## What's Already Been Built
+
+{completed_tasks_summary}
+
+## Your Task
+
+{task_content}
+
+## Instructions
+
+1. Read the relevant parts of the codebase to understand existing patterns, imports, and conventions
+2. Implement everything described in the task's Technical Details and Implementation Steps
+3. Follow the project's existing code patterns and conventions
+4. Run the project's lint and typecheck commands after making changes. Fix any errors before finishing.
+5. Do NOT commit your changes — the orchestrator handles commits after review
+6. When done, report:
+   - Files created (with paths)
+   - Files modified (with paths)
+   - A one-paragraph summary of what you implemented
+```
+
+## Placeholder Details
+
+- **{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.
+
+- **{completed_tasks_summary}**: for each previously completed task, include a brief summary like:
+  ```
+  - task-01-setup-database: Created PostgreSQL schema with users and sessions tables. Files: src/db/schema.ts, src/db/migrations/001_initial.sql
+  - task-02-auth-config: Set up Better Auth with email/password provider. Files: src/lib/auth.ts, src/lib/auth-client.ts
+  ```
+  Keep each entry to 1-2 lines. The purpose is to give the agent awareness of what exists, not full implementation details.
+
+- **{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.

package/template/.claude/skills/implement-feature/references/fix-prompt-template.md

@@ -0,0 +1,38 @@
+# Fix Agent Prompt Template
+
+Use this template when constructing prompts for coder agents that fix issues found during code review. Replace the placeholders with actual content.
+
+## Template
+
+```
+You are fixing specific issues found during code review. Address every issue listed below — do not skip any.
+
+## Issues to Fix
+
+{issues}
+
+## Original Task Context
+
+{task_content}
+
+## Instructions
+
+1. Fix each issue listed above. The review provided file paths, line numbers, and suggested fixes — use those as your starting point.
+2. Run the project's lint and typecheck commands after making fixes. Resolve any new errors your fixes introduce.
+3. Do NOT commit your changes — the orchestrator handles commits.
+4. Do NOT make changes beyond what's needed to fix the listed issues. Stay within scope.
+5. When done, report:
+   - What you fixed (reference each issue)
+   - Any files modified
+   - If you could NOT fix an issue, explain why
+```
+
+## Placeholder Details
+
+- **{issues}**: the specific issues from the review that relate to this task. Include file paths, line numbers, descriptions, severity, and suggested fixes. Example:
+  ```
+  - 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
+  - Issue 2: src/api/users.ts:15 — Unused import 'Session' — Severity: low — Suggested fix: remove the import
+  ```
+
+- **{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.

package/template/.claude/skills/implement-feature/references/review-prompt-template.md

@@ -0,0 +1,50 @@
+# Review Agent Prompt Template
+
+Use this template when constructing prompts for the code review agent that runs between waves. Replace the placeholders with actual content.
+
+## Template
+
+```
+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.
+
+## Feature Context
+
+{requirements}
+
+## Tasks Completed in This Wave
+
+{task_summaries}
+
+## Review Checklist
+
+1. **Verification**: Run `{verification_commands}` and report results. Fix nothing — just report.
+2. **Acceptance Criteria**: For each task listed above, check whether the implementation meets the acceptance criteria from its task file.
+3. **Integration**: Verify that files created by different tasks work together:
+   - Imports resolve correctly
+   - Types match across module boundaries
+   - No duplicate or conflicting definitions
+   - Shared state (env vars, config) is consistent
+4. **Code Quality**: Check for security issues, performance problems, and adherence to project conventions.
+5. **Scope**: Verify each task stayed within its defined scope (Files to Create/Modify). Flag any unexpected file changes.
+
+## Verdict
+
+Respond with one of:
+
+**VERDICT: PASS**
+All checks passed. Include any minor observations as notes.
+
+**VERDICT: FAIL**
+Include a structured list of issues:
+- **Issue 1**: {file:line} — {description} — Severity: {high/medium/low} — Suggested fix: {fix}
+- **Issue 2**: ...
+
+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.
+```
+
+## Placeholder Details
+
+- **{wave_number}**: the current wave number (e.g., "2")
+- **{requirements}**: full text of `requirements.md`
+- **{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)
+- **{verification_commands}**: the project's lint and typecheck commands. Check for `package.json` scripts — typically `pnpm lint && pnpm typecheck` or similar.

package/template/.claude/skills/review-pr/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: review-pr
+description: >
+  Review pull requests with complexity-adaptive depth — spawning deep-dive agents for medium
+  and complex PRs. Use this skill when the user says "review this PR", "review PR #123",
+  "check this pull request", "give me a code review", or wants feedback on a PR before merging.
+  Also use when the user says "/review-pr" or pastes a GitHub PR URL. Requires the GitHub CLI (gh).
+---
+
+# Review Pull Request
+
+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.
+
+## Arguments
+
+The user should provide PR number(s) or URL(s). If none provided, ask for them.
+
+## Instructions
+
+### Step 1: Retrieve PR Details
+
+Use the GitHub CLI to get the full picture:
+
+```bash
+gh pr view {pr_number} --json title,body,files,additions,deletions,commits,author,reviews,comments
+gh pr diff {pr_number}
+```
+
+### Step 2: Assess Complexity
+
+Score the PR based on:
+- Number of files changed
+- Lines added/removed
+- Number of commits
+- Whether changes touch core/architectural files
+
+**Simple** (direct review, no agents):
+- 5 or fewer files AND 100 or fewer lines AND single author
+
+**Medium** (1-2 deep-dive agents):
+- 6-15 files, OR 100-500 lines, OR 2 contributors
+
+**Complex** (up to 3 deep-dive agents):
+- More than 15 files, OR more than 500 lines, OR more than 2 contributors, OR touches core architecture
+
+### Step 3: Analyze
+
+**For Simple PRs**: review directly — read the diff, check for issues, provide feedback.
+
+**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:
+
+- **Agent 1 — Code Quality**: conventions, patterns, maintainability, test coverage
+- **Agent 2 — Security**: input validation, auth checks, injection risks, data exposure
+- **Agent 3 — Architecture** (Complex only): design patterns, separation of concerns, performance implications, backwards compatibility
+
+Each agent receives the PR diff and description and returns a structured review.
+
+### Step 4: Vision Alignment
+
+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.
+
+### Step 5: Safety Assessment
+
+Provide an overall assessment:
+- **Safe to merge**: no significant issues found
+- **Merge with caution**: minor issues that should be noted but aren't blocking
+- **Needs changes**: issues that should be fixed before merging
+
+Include a risk level (low/medium/high) with justification.
+
+### Step 6: Report
+
+Structure the review as:
+
+```
+## PR Review: #{pr_number} — {title}
+
+### Complexity: {Simple|Medium|Complex}
+{Brief justification}
+
+### Summary
+{2-3 sentence overview of what the PR does}
+
+### Issues Found
+{Grouped by severity: high → medium → low}
+- **{severity}**: {file:line} — {description}
+
+### Improvements Suggested
+{Optional improvements ranked by importance and implementation complexity}
+
+### Vision Alignment
+{Does this PR align with the project's direction?}
+
+### Verdict: {Safe to merge | Merge with caution | Needs changes}
+Risk level: {low|medium|high}
+{Brief justification}
+```

package/template/AGENTS.md

@@ -21,6 +21,10 @@ If you start down the wrong path, stop, invoke the right skill, and continue fro
 
 | If you are about to… | Invoke first |
 | --- | --- |
+| Plan a feature, create a spec, break work into tasks | `create-spec` |
+| Implement a planned feature, execute a spec | `implement-feature` |
+| Create a checkpoint commit | `checkpoint` |
+| Review a pull request | `review-pr` |
 | Touch Next.js App Router, routing, RSC, data fetching, deployment | `nextjs` |
 | Touch shadcn/ui components or registries | `shadcn` |
 | Touch Better Auth configuration or auth flows | `better-auth-best-practices` |

package/template/.claude/commands/checkpoint.md

@@ -1,37 +0,0 @@
----
-description: Create commit with detailed comment
----
-
-Please create a comprehensive checkpoint commit with the following steps:
-
-1. **Initialize Git if needed**: Run `git init` if git has not been instantiated for the project yet.
-
-2. **Analyze all changes**:
-   - Run `git status` to see all tracked and untracked files
-   - Run `git diff` to see detailed changes in tracked files
-   - Run `git log -5 --oneline` to understand the commit message style of this repository
-
-3. **Stage everything**:
-   - Add ALL tracked changes (modified and deleted files)
-   - Add ALL untracked files (new files)
-   - Use `git add -A` or `git add .` to stage everything
-
-4. **Create a detailed commit message**:
-   - **First line**: Write a clear, concise summary (50-72 chars) describing the primary change
-     - Use imperative mood (e.g., "Add feature" not "Added feature")
-     - Examples: "feat: add user authentication", "fix: resolve database connection issue", "refactor: improve API route structure"
-   - **Body**: Provide a detailed description including:
-     - What changes were made (list of key modifications)
-     - Why these changes were made (purpose/motivation)
-     - Any important technical details or decisions
-     - Breaking changes or migration notes if applicable
-   - **Footer**: Include co-author attribution as shown in the Git Safety Protocol
-
-5. **Execute the commit**: Create the commit with the properly formatted message following this repository's conventions.
-
-IMPORTANT:
-
-- Do NOT skip any files - include everything
-- Make the commit message descriptive enough that someone reviewing the git log can understand what was accomplished
-- Follow the project's existing commit message conventions (check git log first)
-- Include the Claude Code co-author attribution in the commit message