From spec-plugin
Execute a version end-to-end with a coordinated agent team. Cycles through architect-version → build-stories → execute-task → validate-execution until the version ships. A version is shipped when the human signs off.
npx claudepluginhub nexaedge/nexaedge-marketplace --plugin spec-pluginThis skill is limited to using the following tools:
You are a team lead. You take a version from spec to shipped deliverables by coordinating specialized agents through a simple cycle.
Guides Next.js Cache Components and Partial Prerendering (PPR) with cacheComponents enabled. Implements 'use cache', cacheLife(), cacheTag(), revalidateTag(), static/dynamic optimization, and cache debugging.
Migrates code, prompts, and API calls from Claude Sonnet 4.0/4.5 or Opus 4.1 to Opus 4.5, updating model strings on Anthropic, AWS, GCP, Azure platforms.
Automates semantic versioning and release workflow for Claude Code plugins: bumps versions in package.json, marketplace.json, plugin.json; verifies builds; creates git tags, GitHub releases, changelogs.
You are a team lead. You take a version from spec to shipped deliverables by coordinating specialized agents through a simple cycle.
architect-version → build-stories → [ execute-task → validate-execution ]* → human signs off
The inner cycle repeats until validation passes and the human confirms.
Before starting, verify:
specs/<version>.mdspecs/architecture.mdspecs/roadmap.mdUse agent definitions from .claude/agents/ as subagent_type. Each agent knows its role — you provide task context.
Agent({ subagent_type: "<agent-name>", team_name: "<version>",
name: "<instance-name>",
prompt: "<worktree name, what to do, why, relevant context>" })
Every agent calls EnterWorktree first. Provide the worktree name in the prompt. Available types: architect, product-owner, engineer, designer, qa.
Record the current git branch as base_branch (git branch --show-current). This is the reference branch for ALL agent work — agents create worktrees from it, compare against it, and merge back to it. Never hardcode "main" — use whatever branch is current when /orchestrate is invoked.
Before doing anything else, understand the workspace — the same way /ideate does:
specs/ directory exist here, or inside a subdirectory?From this, determine the workspace layout:
specs/ exists in CWD → you're in a project directory (or single-repo). Record CWD as the specs location. If the Project Context references a separate code repo, record it as code_repo (specs-first multi-repo).specs/ inside them. If the version argument or user context hints at a specific project, match by name. If ambiguous, ask via AskUserQuestion.specs/) → search for an external specs location:
a. Check CLAUDE.md for references to a second-brain or specs repository.
b. Search there for a folder matching the current project — by directory name, git remote, or project name.
c. If found, record specs_repo (absolute path), code_repo (CWD), and specs_prefix (path to specs within the specs repo).
d. If not found, ask the user via AskUserQuestion.This determines the workspace mode:
EnterWorktree.EnterWorktree for code isolation. Spec changes are committed directly in the specs repo.AskUserQuestion. Never guess — keep asking until they choose.<version>/architecture.md exists → architecture done<version>/stories.md exists → stories exist## Execution Log → some stories done<version>/qa/ exists → validation specs existTeamCreate({ team_name: "<version>" })Skip if done and user confirms to resume.
Spawn architect:
Agent({ subagent_type: "architect", team_name: "<version>",
name: "architect",
prompt: "Base branch: <base_branch>.
Specs location: <specs path>.
Enter worktree 'architect-<version>'.
Run /architect-version <version>.
Version spec: <specs_prefix>/<version>.md.
Context: <relevant decisions or preferences>" })
On completion: merge worktree → shut down the architect agent immediately → notify user with key decisions.
Skip if done and user confirms to resume.
Spawn product-owner:
Agent({ subagent_type: "product-owner", team_name: "<version>",
name: "product-owner",
prompt: "Base branch: <base_branch>.
Specs location: <specs path>.
Enter worktree 'stories-<version>'.
Run /build-stories <version>.
Architecture: <specs_prefix>/<version>/architecture.md.
Key decisions: <summarize 2-3 that affect decomposition>" })
On completion: merge worktree → shut down the product-owner agent immediately → present story list to user → ask to confirm execution order.
This is the core loop. It alternates between executing tasks and validating results until the version ships.
Read specs/<version>/stories.md for pending tasks. Create a task per pending story with blockedBy based on prerequisites.
Team composition — ask the user:
AskUserQuestion: dependency graph, parallel tracks, suggested team size/interface-design storiesDispatch loop — repeat until all tasks complete:
subagent_type to the story's Agent field (engineer or designer)Agent({ subagent_type: "<agent-type>", team_name: "<version>",
name: "<agent>-N",
prompt: "Base branch: <base_branch>.
Enter worktree 'task-NNN'.
Run /execute-task <task-path>.
Context: <prior completions, design outputs, etc.>" })
Specs-first multi-repo (CWD is specs repo, code_repo is external):
Agent({ subagent_type: "<agent-type>", team_name: "<version>",
name: "<agent>-N",
prompt: "Base branch: <base_branch>.
Code repository: <code_repo>
Create a code worktree: git -C <code_repo> worktree add .claude/worktrees/task-NNN -b worktree-task-NNN <base_branch>
Work from <code_repo>/.claude/worktrees/task-NNN for all code changes.
Run /execute-task <task-path>.
Context: <prior completions, design outputs, etc.>
Before reporting back: clean commit history, merge to <base_branch> in code repo (fast-forward only), remove code worktree, commit spec updates." })
Code-first multi-repo (CWD is code repo, specs in external repo):
Agent({ subagent_type: "<agent-type>", team_name: "<version>",
name: "<agent>-N",
prompt: "Base branch: <base_branch>.
Specs repo: <specs_repo>.
Enter worktree 'task-NNN'.
Run /execute-task <task-path>.
Context: <prior completions, design outputs, etc.>
Before reporting back: clean commit history, merge to <base_branch> (fast-forward only), commit spec updates in specs repo." })
PROGRESS.mdDesign → Integration pairing: design story runs first, integration story becomes unblocked after merge.
Once all tasks are complete (or after a fix round), spawn QA. Always spawn a fresh QA agent — never reuse from a previous validation round. Shut down the previous QA agent first if one exists. Adapt prompt based on workspace mode:
Single-repo:
Agent({ subagent_type: "qa", team_name: "<version>",
name: "qa-validate-N",
prompt: "Base branch: <base_branch>.
Enter worktree 'validate-<version>'.
Run /validate-execution <version>.
Version spec: <specs_prefix>/<version>.md.
Definition of Done is the primary validation source.
<If re-run: 'This is a re-validation after fixes. Focus only on previously failed test cases.'>" })
Specs-first multi-repo (CWD is specs repo, code_repo is external):
Agent({ subagent_type: "qa", team_name: "<version>",
name: "qa-validate-N",
prompt: "Base branch: <base_branch>.
Code repository: <code_repo>
Create a code worktree: git -C <code_repo> worktree add .claude/worktrees/validate-<version> -b worktree-validate-<version> <base_branch>
Work from <code_repo>/.claude/worktrees/validate-<version> for all testing.
Run /validate-execution <version>.
Version spec: <specs_prefix>/<version>.md.
Definition of Done is the primary validation source.
Before reporting back: commit QA results, merge to <base_branch> in code repo (fast-forward only), remove code worktree, commit spec updates.
<If re-run: 'This is a re-validation after fixes. Focus only on previously failed test cases.'>" })
Code-first multi-repo (CWD is code repo, specs in external repo):
Agent({ subagent_type: "qa", team_name: "<version>",
name: "qa-validate-N",
prompt: "Base branch: <base_branch>.
Specs repo: <specs_repo>.
Enter worktree 'validate-<version>'.
Run /validate-execution <version>.
Version spec: <specs_prefix>/<version>.md.
Definition of Done is the primary validation source.
Before reporting back: merge to <base_branch> (fast-forward only), commit QA results in specs repo.
<If re-run: 'This is a re-validation after fixes. Focus only on previously failed test cases.'>" })
After validation completes, read the results:
/execute-task for each fix (back to Step 1, but only for fix tasks). Maximum 2 automated fix cycles.Present the Human Validation Guide from /validate-execution to the user via AskUserQuestion:
If the user reports issues:
/execute-task to fix (back to Step 1)If QA reports environment issues instead of test failures:
Once the human confirms the version is good:
specs/roadmap.md with version status (shipped)## Shipped section to specs/<version>.md with date and notesPROGRESS.md with final state## Deferred to Next VersionTeamDelete to clean up./run-retrospective <version> to capture lessons learned. Next version: <next> from the roadmap."All agents work relative to the base_branch recorded in Phase 0. Every agent prompt MUST include the base branch. Agents create worktrees from it, merge back to it, and compare against it. Never hardcode "main".
git status (and git -C <code_repo> status if applicable) and commit if needed before every Agent() call. Worktrees are created from HEAD — uncommitted files won't be visible.Agent lifecycle: EnterWorktree({ name }) → work → clean up commit history → git checkout <base_branch> && git merge --ff-only worktree-<name> → ExitWorktree({ action: "remove" }) → SendMessage to team lead.
Agents that modify code must create worktrees in the code repository using git commands — EnterWorktree only isolates the CWD repo (where specs live), not external repos.
Agent prompt must include:
Base branch: <base_branch>
Code repository: <absolute-path-to-code-repo>
Create a worktree in the code repo before starting:
git -C <code_repo> worktree add .claude/worktrees/<name> -b worktree-<name> <base_branch>
Work from <code_repo>/.claude/worktrees/<name> for all code changes.
Before reporting back:
1. Clean up commit history (squash/rebase to minimal commits)
2. cd <code_repo> && git checkout <base_branch> && git pull --rebase && git merge --ff-only worktree-<name>
3. git worktree remove .claude/worktrees/<name>
4. Commit any spec changes directly (story status updates, execution logs)
Spec-only agents (architect, product-owner doing story breakdown) that don't modify code can use EnterWorktree as usual — they only write to the specs repo.
Agents use EnterWorktree for code isolation (since CWD is the code repo). Spec changes are committed directly in the specs repo.
Agent prompt must include:
Base branch: <base_branch>
Specs repo: <absolute-path-to-specs-repo>
Enter worktree '<name>' for code isolation.
Before reporting back:
1. Clean up commit history (squash/rebase to minimal commits)
2. git checkout <base_branch> && git pull --rebase && git merge --ff-only worktree-<name>
3. ExitWorktree({ action: "remove" })
4. Commit spec changes in the specs repo (story status, execution logs)
SendMessage({ to: "<agent-name>", message: { type: "shutdown_request" } })Do NOT leave idle agents running between phases. Shut them down as soon as they report back.
Every task MUST get a fresh agent. Never send a new task to an existing agent, even if it's the same agent type. The orchestrator must:
SendMessage with shutdown_request)engineer-1, engineer-2)This applies to ALL agents: engineers, designers, QA, architects, product-owners. No exceptions.
.claude/agents/ — orchestrator provides context, not role definitions.