create-agentic-app 1.1.54 → 1.1.55

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agentic-app",
-  "version": "1.1.54",
+  "version": "1.1.55",
   "description": "Scaffold a new agentic AI application with Next.js, Better Auth, and AI SDK",
   "type": "module",
   "bin": {

package/template/.agents/skills/checkpoint/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: checkpoint
+description: >
+  Create a comprehensive checkpoint commit with detailed analysis of all changes. Use this skill
+  when the user says "checkpoint", "commit everything", "save my progress", "create a commit",
+  or wants to stage and commit all current changes with a well-crafted message. Also use when
+  the user says "/checkpoint" or asks to snapshot current work. This skill stages all changes
+  and creates a descriptive commit — it does not push.
+---
+
+# Checkpoint Commit
+
+Create a comprehensive checkpoint commit that captures all current changes with a detailed, well-structured commit message.
+
+## Instructions
+
+### Step 1: Analyze Changes
+
+Run these commands to understand the full picture:
+
+1. `git status` — see all tracked and untracked files
+2. `git diff` — see detailed changes in tracked files
+3. `git diff --cached` — see already-staged changes
+4. `git log -5 --oneline` — understand this repo's commit message style
+
+### Step 2: Stage Everything
+
+Stage all changes — tracked modifications, deletions, and new untracked files:
+
+```bash
+git add -A
+```
+
+### Step 3: Craft the Commit Message
+
+Write a commit message following the project's existing conventions (observed from `git log`). Structure:
+
+- **First line**: clear, concise summary in imperative mood (50-72 chars)
+  - Use conventional commit prefixes where the project uses them: `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`, etc.
+- **Body** (separated by blank line): detailed description including:
+  - What changes were made (key modifications)
+  - Why these changes were made (purpose/motivation)
+  - Important technical details or decisions
+  - Breaking changes or migration notes if applicable
+- **Footer**: co-author attribution
+
+### Step 4: Commit
+
+Create the commit using a heredoc for proper formatting:
+
+```bash
+git commit -m "$(cat <<'EOF'
+{first line}
+
+{body}
+
+Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+### Step 5: Report
+
+Display:
+- The commit hash and message summary
+- Files changed count
+- Insertions/deletions summary
+
+## Important
+
+- Stage and commit everything — do not skip files unless they are clearly sensitive (`.env`, credentials)
+- If the repo has no git history, run `git init` first
+- Make the commit message descriptive enough that someone reading `git log` understands what was accomplished
+- Follow the project's existing commit conventions (check the log first)
+- Do not push — only commit locally

package/template/.agents/skills/create-spec/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: create-spec
+description: >
+  Create a structured feature specification with self-contained task files organized into
+  parallel execution waves. Use this skill when the user says "create a spec", "plan this feature",
+  "write up an implementation plan", "break this into tasks", or after any planning conversation
+  where the user wants to capture decisions as actionable spec files. Also use when the user
+  says "/create-spec" or wants to decompose a feature into work items that agents can implement
+  independently. This skill produces local spec files under specs/{feature}/ — no GitHub integration.
+---
+
+# Create Feature Specification
+
+Transform a planning conversation into a structured spec folder that enables parallel agent implementation. The spec breaks a feature into self-contained task files — each one detailed enough that a coder agent can pick it up cold and implement it without reading anything else.
+
+The key insight: implementation plans that live in a single file are either too large for a context window or too shallow for independent execution. By splitting into one file per task with full context in each, we enable multiple agents to work in parallel while keeping each agent's context focused.
+
+## When to Use
+
+- After a planning conversation where requirements and technical details have been discussed
+- When the user asks to create a spec, plan a feature, or break work into tasks
+- When the user wants to prepare work for parallel agent implementation
+
+## Instructions
+
+### Step 1: Gather Requirements
+
+If the conversation already contains planning context (requirements discussed, technical decisions made, architecture outlined), extract all of it. Review the entire conversation to ensure nothing is lost — the spec is the single source of truth, and anything not captured here disappears.
+
+If no planning conversation exists, interview the user:
+- What does this feature do and why does it matter?
+- What are the acceptance criteria?
+- What technical constraints or decisions have been made?
+- What files, APIs, schemas, or patterns are involved?
+
+### Step 2: Name the Feature
+
+Choose a kebab-case name that clearly identifies the feature (e.g., `add-user-auth`, `migrate-to-postgres`, `dashboard-redesign`). This becomes the folder name under `specs/`.
+
+### Step 3: Decompose into Tasks
+
+Break the implementation into atomic tasks. Each task should:
+- Be completable in a single coding session by one agent
+- Have a clear, specific scope (one concern per task)
+- Produce working, testable code when complete
+- Not overlap in files modified with other tasks in the same wave
+
+Think carefully about granularity. Too coarse and agents can't work in parallel. Too fine and the overhead of context-switching between tasks dominates. A good task typically creates or modifies 1-5 files around a single concern.
+
+Do NOT include testing tasks (unit tests, e2e tests) unless the user explicitly asks for them.
+
+### Step 4: Build the Dependency Graph
+
+For each task, identify:
+- **What it depends on**: which tasks must complete before this one can start
+- **What depends on it**: which tasks are blocked until this one finishes
+
+Tasks with no dependencies form Wave 1. Tasks whose dependencies are all in Wave 1 form Wave 2. And so on. All tasks within a wave can execute in parallel.
+
+When assigning waves, verify that tasks within the same wave do not modify overlapping files. If two tasks in the same wave would touch the same file, move one to a later wave — parallel agents on the same branch cannot safely modify the same file.
+
+### Step 5: Create the Spec Folder
+
+Create the following structure at `specs/{feature-name}/`:
+
+```
+specs/{feature-name}/
+├── README.md
+├── requirements.md
+├── action-required.md
+└── tasks/
+    ���── task-01-{name}.md
+    ├── task-02-{name}.md
+    └── ...
+```
+
+Read the templates in `references/` before writing each file:
+- `references/readme-template.md` — for the README (dependency graph, wave table, status tracking)
+- `references/task-template.md` — for each task file (self-contained with all context)
+- `references/requirements-template.md` ��� for the requirements document
+- `references/action-required-template.md` — for manual human steps
+
+Task files are numbered with zero-padded two-digit prefixes in topological order: Wave 1 tasks first, then Wave 2, etc. Within a wave, order is arbitrary but stable.
+
+### Step 6: Write Self-Contained Task Files
+
+This is the most important step. Each task file is the **only thing** a coder agent will read before implementing. It must contain everything the agent needs:
+
+- **Description**: what to build and why it matters in context
+- **Dependency context**: what prior tasks produce that this task needs (summarized in prose, not just filenames). The agent should not need to read other task files.
+- **Technical details**: CLI commands, code snippets, schemas, file paths, env vars, API endpoints — every implementation-specific detail from the planning conversation
+- **Files to create/modify**: explicit list with purpose for each
+- **Acceptance criteria**: specific, verifiable conditions
+
+Review each task file with fresh eyes: could an agent who has never seen the planning conversation implement this correctly using only this file? If not, add what's missing.
+
+### Step 7: Extract Manual Actions
+
+Identify any steps that require human action (account creation, API key setup, DNS configuration, environment variables, third-party service registration, etc.). Write these to `action-required.md` grouped by timing (Before/During/After implementation). If none exist, note "No manual steps required."
+
+### Step 8: Report to User
+
+After creating the spec, display:
+
+```
+Feature specification created at specs/{feature-name}/
+
+Files created:
+- README.md (dependency graph, {N} waves, {T} tasks)
+- requirements.md
+- action-required.md
+- tasks/ ({T} task files)
+
+Wave breakdown:
+- Wave 1: {count} tasks (parallel) — {brief description}
+- Wave 2: {count} tasks (parallel) — {brief description}
+- ...
+
+Next steps:
+1. Review action-required.md for tasks you need to complete manually
+2. Review the requirements and task files
+3. Use /implement-feature to start parallel implementation
+```
+
+## Critical Rules
+
+- Every task file must be fully self-contained — this is the entire point of the spec structure. A coder agent reading only that file must know exactly what to do.
+- Capture ALL technical details from the planning conversation. The spec is the single source of truth — CLI commands, schemas, code snippets, file paths, env vars, API endpoints. Anything not captured here is lost.
+- Tasks within the same wave must not modify overlapping files. Parallel agents on the same branch cannot safely touch the same files.
+- Keep tasks atomic — one concern per task. If a task has more than 5-7 files to modify, consider splitting it.
+- Do not create testing tasks unless the user explicitly asks for them.
+- Number task files in topological order (wave 1 first, then wave 2, etc.) for easy scanning.

package/template/.agents/skills/create-spec/references/action-required-template.md

@@ -0,0 +1,53 @@
+# Action Required Template
+
+Use this structure for the action-required.md at the root of each spec folder. This file captures manual steps that require human action and cannot be automated by agents.
+
+## Template (when manual steps exist)
+
+```markdown
+# Action Required: {Feature Name}
+
+Manual steps that must be completed by a human. These cannot be automated.
+
+## Before Implementation
+
+- [ ] **{Action}** — {Brief reason why this is needed}
+- [ ] **{Action}** — {Brief reason}
+
+## During Implementation
+
+- [ ] **{Action}** — {Brief reason}
+
+## After Implementation
+
+- [ ] **{Action}** — {Brief reason}
+
+---
+
+> These tasks are also referenced in context within the relevant task files.
+```
+
+## Template (when no manual steps exist)
+
+```markdown
+# Action Required: {Feature Name}
+
+No manual steps required for this feature. All tasks can be implemented automatically.
+```
+
+## Common Manual Steps
+
+- Account creation (third-party services, OAuth apps)
+- API key generation and setup
+- Environment variable configuration
+- DNS or domain settings
+- Billing or subscription setup
+- Third-party service registration (webhooks, integrations)
+- Certificate provisioning
+- Access permissions or IAM roles
+
+## Key Points
+
+- Group actions by timing: before, during, and after implementation. This helps the user know when they need to act.
+- Keep descriptions brief — one line explaining what to do and why.
+- Also reference these manual steps in the relevant task files so agents know to pause or skip that part.

package/template/.agents/skills/create-spec/references/readme-template.md

@@ -0,0 +1,53 @@
+# README Template
+
+Use this structure for the README.md at the root of each spec folder. The README serves as the orchestration index — the `implement-feature` skill reads it to determine wave order, task assignments, and completion status.
+
+## Template
+
+```markdown
+# {Feature Name}
+
+## Overview
+
+{One paragraph summary of what the feature does and why it exists.}
+
+## Quick Links
+
+- [Requirements](./requirements.md) — full requirements and acceptance criteria
+- [Action Required](./action-required.md) — manual steps needing human action
+
+## Dependency Graph
+
+​```mermaid
+graph TD
+    task-01-name["01: Task Title"]
+    task-02-name["02: Task Title"]
+    task-03-name["03: Task Title"]
+    task-01-name --> task-03-name
+    task-02-name --> task-03-name
+​```
+
+## Waves
+
+| Wave | Tasks | Description |
+|------|-------|-------------|
+| 1 | task-01, task-02 | {Brief description of what this wave accomplishes} |
+| 2 | task-03 | {Brief description} |
+
+## Task Status
+
+### Wave 1
+- [ ] [task-01-{name}](./tasks/task-01-{name}.md) — {One-line title}
+- [ ] [task-02-{name}](./tasks/task-02-{name}.md) — {One-line title}
+
+### Wave 2
+- [ ] [task-03-{name}](./tasks/task-03-{name}.md) — {One-line title}
+```
+
+## Key Points
+
+- The **Dependency Graph** uses Mermaid syntax (widely rendered in GitHub, VS Code, etc.). Each node shows the task number and title for quick reference.
+- The **Waves** table provides a scannable overview of what runs in parallel.
+- The **Task Status** section uses markdown checkboxes that the `implement-feature` skill updates as tasks complete. The orchestrator parses these to determine which wave to resume from.
+- Links to task files use relative paths pointing into the `tasks/` subfolder.
+- Tasks without dependencies have no incoming arrows in the graph — these form Wave 1.

package/template/.agents/skills/create-spec/references/requirements-template.md

@@ -0,0 +1,54 @@
+# Requirements Template
+
+Use this structure for the requirements.md at the root of each spec folder.
+
+## Template
+
+```markdown
+# Requirements: {Feature Name}
+
+## Summary
+
+{What the feature does and why it exists — 2-3 paragraphs covering the problem, the solution, and the expected outcome.}
+
+## Goals
+
+- {Goal 1}
+- {Goal 2}
+- {Goal 3}
+
+## Non-Goals
+
+{Explicitly out of scope — things that might seem related but are not part of this feature.}
+
+- {Non-goal 1}
+- {Non-goal 2}
+
+## Acceptance Criteria
+
+{High-level criteria for the entire feature. Individual task files have their own granular criteria.}
+
+- [ ] {Criterion 1}
+- [ ] {Criterion 2}
+- [ ] {Criterion 3}
+
+## Assumptions
+
+{Things assumed to be true that could affect implementation if they turn out to be false.}
+
+- {Assumption 1}
+- {Assumption 2}
+
+## Technical Constraints
+
+{Architecture decisions, technology choices, or constraints that affect all tasks.}
+
+- {Constraint 1}
+- {Constraint 2}
+```
+
+## Key Points
+
+- The requirements doc provides **overall feature context** that each coder agent receives alongside its task file. Keep it focused on the "what" and "why" — individual task files handle the "how."
+- Non-goals are important: they prevent agents from over-building. If search functionality is out of scope, say so — otherwise a well-meaning agent might add it.
+- Acceptance criteria here are feature-level (the whole thing works end-to-end). Task-level criteria live in each task file.

package/template/.agents/skills/create-spec/references/task-template.md

@@ -0,0 +1,79 @@
+# Task File Template
+
+Use this structure for each task file in the `tasks/` subfolder. Each task file must be **fully self-contained** — a coder agent reading only this file should know exactly what to implement, why, and how.
+
+## Template
+
+```markdown
+# Task {nn}: {Title}
+
+## Status
+
+pending
+
+## Wave
+
+{N}
+
+## Description
+
+{2-5 sentences describing what this task accomplishes and why it matters in the context of the overall feature. Include enough context that an agent unfamiliar with the planning conversation understands the purpose.}
+
+## Dependencies
+
+**Depends on:** {Comma-separated list of task filenames, or "None (Wave 1)"}
+**Blocks:** {Comma-separated list of task filenames, or "None"}
+
+**Context from dependencies:** {Prose summary of what the dependency tasks produce that this task needs. For example: "task-01-setup-database.md creates the PostgreSQL schema with users and sessions tables. This task builds the API routes that query those tables." This is what makes each file self-contained — the agent does not need to read other task files to understand its inputs.}
+
+## Files to Create
+
+- `path/to/new-file.ts` — {Brief purpose}
+- `path/to/another-file.ts` — {Brief purpose}
+
+## Files to Modify
+
+- `path/to/existing-file.ts` — {What changes and why}
+
+## Technical Details
+
+{All implementation-specific details from the planning conversation. This section is the single source of truth. Include:}
+
+### Implementation Steps
+
+1. {Step-by-step instructions with enough detail for independent implementation}
+2. {Include CLI commands where relevant: `pnpm add package-name`}
+3. {Include code snippets for non-obvious patterns}
+
+### Code Snippets
+
+{Key type definitions, schemas, configuration blocks, or patterns that the implementer needs. Use fenced code blocks with language tags.}
+
+### Environment Variables
+
+{If applicable:}
+- `VAR_NAME` — {Purpose and example value}
+
+### API Endpoints
+
+{If applicable:}
+- `METHOD /path` — {Request/response shape}
+
+## Acceptance Criteria
+
+- [ ] {Criterion 1 — specific and verifiable}
+- [ ] {Criterion 2}
+- [ ] {Criterion 3}
+
+## Notes
+
+{Any additional context, edge cases, warnings, or architectural decisions relevant to this task. Omit this section if there's nothing to add.}
+```
+
+## Key Points
+
+- The **Status** field is updated by the `implement-feature` skill: `pending` → `in-progress` → `complete`.
+- The **Dependencies** section includes prose context (not just filenames) so the agent understands its inputs without reading other files. This is the most important part of making task files self-contained.
+- **Files to Create** and **Files to Modify** make the task's scope explicit. Tasks in the same wave should not overlap on these lists.
+- **Technical Details** captures everything from the planning conversation — CLI commands, schemas, code snippets, file paths, env vars, API endpoints. If it was discussed during planning and is relevant to this task, it belongs here.
+- **Acceptance Criteria** should be specific enough that completion can be verified objectively (by a code review agent or a human).

package/template/.agents/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.