From spec-first
Executes work from plans, task packs, or prompts: triages input complexity, scans repos for patterns and tests, builds task lists, implements features while following conventions and maintaining quality.
npx claudepluginhub sunrain520/spec-firstThis skill uses the workspace's default tool permissions.
Execute work efficiently while maintaining quality and finishing features.
Executes coding tasks from plans, specs, or prompts: triages input, scans codebase for patterns/tests, assesses complexity, implements systematically to ship complete features with quality.
Executes coding tasks from plan documents or prompts: triages input complexity, builds task lists, implements systematically following patterns, verifies with tests. Use to ship complete features efficiently.
Executes development work from plans, tasks, or prompts with optional experimental Codex delegation for token-conserving code implementation. Beta of spec-work; manual invocation for delegation trials.
Share bugs, ideas, or general feedback.
Execute work efficiently while maintaining quality and finishing features.
This command takes a work document (plan, task pack, or specification) or a bare prompt describing the work, and executes it systematically. The focus is on shipping complete features by understanding requirements quickly, following existing patterns, and maintaining quality throughout.
When a CRG graph is available, use spec-first crg hook before-work --plan=<plan.md> --repo=<repo> before implementation, or spec-first crg hook before-work --task-pack=<tasks.md> --repo=<repo> when executing a derived task pack. If opened at a parent workspace root, first run spec-first crg workspace context --root=<workspace> --task="<task>"; require an explicit child repo choice from the advisory candidates before editing files or running repo-local hooks. For multi-child tasks, decompose into explicit sequential repo-local work runs; do not create one hidden combined workspace work-run. After implementation, use spec-first crg hook after-work --work-run=<id> --repo=<repo> or pass an explicit base with --since=<base>. Hook output is advisory context for comparing planned surface and actual blast radius; it must not override the plan or replace LLM judgment. If graph state is unavailable, continue with targeted direct repo reads and do not read old Stage-0 docs as fallback.
<input_document> #$ARGUMENTS </input_document>
Determine how to proceed based on what was provided in <input_document>.
Plan or task-pack document (input is a file path to an existing plan, task pack, or specification) → skip to Phase 1.
Bare prompt (input is a description of work, not a file path):
Scan the work area
Assess complexity and route
| Complexity | Signals | Action |
|---|---|---|
| Trivial | 1-2 files, no behavioral change (typo, config, rename) | Proceed to Phase 1 step 2 (environment setup), then implement directly — no task list, no execution loop. Apply Test Discovery if the change touches behavior-bearing code |
| Small / Medium | Clear scope, under ~10 files | Build a task list from discovery. Proceed to Phase 1 step 2 |
| Large | Cross-cutting, architectural decisions, 10+ files, touches auth/payments/migrations | Inform the user this would benefit from /spec:brainstorm or /spec:plan to surface edge cases and scope boundaries. Honor their choice. If proceeding, build a task list and continue to Phase 1 step 2 |
Read Plan and Clarify (skip if arriving from Phase 0 with a bare prompt)
Implementation Units, Work Breakdown, Requirements Trace, Files, Test Scenarios, or Verification, use those as the primary source material for executionTask Graph, Execution Waves, Task Cards, Validation Notes, and Regeneration Rules as the primary source material for executiontype: task-pack, generated_by: spec-write-tasks, status: derived, and mode: derivedsource_plan and treat that plan as the single source of truth for scope, requirements, and non-goalsspec_id from the task pack and source plan. If the task pack lacks spec_id, stop as missing identity; if both are present, they must match; if they mismatch, reject the task pack as wrong-chain handoff before implementationspec_id, treat task-pack identity as unverifiable weak trace and stop for executable task-pack handoff; ask to return to spec-plan to add plan frontmatter or rerun spec-write-taskssource_plan_hash is a concrete canonical source plan body sha256:<64-hex> hash, not pending-tooling, unknown, empty, or a draft markerspec-first tasks validate <task-pack-path> --json; if that tooling is unavailable, treat the task pack as unverifiable and stopTask Pack Contract JSON block; do not infer executable task structure from free-form Markdown task cardsspec-write-tasks from the source plan or return to spec-plan; do not silently fall back to executing stale task cardsstop_if; if triggered, stop and return to spec-plan or regenerate the task pack instead of expanding scope in placebefore-work --plan, before creating a work-run, and before creating the internal task tracker:
spec-write-tasks <plan-path>, and re-enter only after it returns deterministic handoff with semantic_posture: generated-this-run | reviewed-existingbefore-work --plan and the internal tracker, and do not prompt again in this work runExecution note on each implementation unit — these carry the plan's execution posture signal for that unit (for example, test-first or characterization-first). Note them when creating tasks.Deferred to Implementation or Implementation-Time Unknowns section — these are questions the planner intentionally left for you to resolve during execution. Note them before starting so they inform your approach rather than surprising you mid-taskScope Boundaries section — these are explicit non-goals. Refer back to them if implementation starts pulling you toward adjacent workExecution notestatus: active → completed flip at shipping (see references/shipping-workflow.md Phase 4 Step 2). Legacy plans may contain - [ ] / - [x] marks on unit headings — ignore them as state; per-unit completion is determined during execution by reading the current file state.Setup Environment
First, check the current branch:
current_branch=$(git branch --show-current)
default_branch=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
# Fallback if remote HEAD isn't set
if [ -z "$default_branch" ]; then
default_branch=$(git rev-parse --verify origin/main >/dev/null 2>&1 && echo "main" || echo "master")
fi
If already on a feature branch (not the default branch):
First, check whether the branch name is meaningful — a name like feat/crowd-sniff or fix/email-validation tells future readers what the work is about. Auto-generated worktree names (e.g., worktree-jolly-beaming-raven) or other opaque names do not.
If the branch name is meaningless or auto-generated, suggest renaming it before continuing:
git branch -m <meaningful-name>
Derive the new name from the plan title or work description (e.g., feat/crowd-sniff). Present the rename as a recommended option alongside continuing as-is.
Then ask: "Continue working on [current_branch], or create a new branch?"
If on the default branch, choose how to proceed:
Option A: Create a new branch
git pull origin [default_branch]
git checkout -b feature-branch-name
Use a meaningful name based on the work (e.g., feat/user-authentication, fix/email-validation).
Option B: Use a worktree (recommended for parallel development)
skill: git-worktree
# The skill will create a new branch from the default branch in an isolated worktree
Option C: Continue on the default branch
Recommendation: Use worktree if:
Create Task List (skip if Phase 0 already built one, or if Phase 0 routed as Trivial)
TaskCreate/TaskUpdate/TaskList in Claude Code, update_plan in Codex, or the equivalent on other harnesses) to break the plan into actionable tasksTask Cards and preserve task_id, dependencies, wave, files, test_focus, done_signal, and stop_ifspec_id, keep it as trace context for blockers, deferred-work notes, task summaries, and final verification when it helps distinguish related requirements/plan/task-pack artifacts. Do not treat it as execution state or completion statusExecution note into the task when presentPatterns to follow field before implementing — these point to specific files or conventions to mirrorVerification field as the primary "done" signal for that taskChoose Execution Strategy
After creating the task list, decide how to execute based on the plan's size and dependency structure:
| Strategy | When to use |
|---|---|
| Inline | 1-2 small tasks, or tasks needing user interaction mid-flight. Default for bare-prompt work — bare prompts rarely produce enough structured context to justify subagent dispatch |
| Serial subagents | 3+ tasks with dependencies between them. Each subagent gets a fresh context window focused on one unit — prevents context degradation across many tasks. Requires plan-unit metadata (Goal, Files, Approach, Test scenarios) |
| Parallel subagents | 3+ tasks that pass the Parallel Safety Check (below). Dispatch independent units simultaneously, run dependent units after their prerequisites complete. Requires plan-unit metadata |
Parallel Safety Check — required before choosing parallel dispatch:
Files: section (Create, Modify, and Test paths)config/routes.rb — using serial dispatch"). Serial subagents still provide context-window isolation without shared-directory write races.Even with no file overlap, parallel subagents sharing the orchestrator's working directory face git index contention (concurrent staging/committing corrupts the index) and test interference (concurrent test runs pick up each other's in-progress changes). Reliable isolation eliminates both; the shared-directory fallback constraints below mitigate them.
Host capability matrix
| Host path | Isolation model | Parallel overlap rule | Commit/test ownership |
|---|---|---|---|
Claude Code Agent with worktree isolation | Pass isolation: "worktree" and run_in_background: true; the harness creates a per-subagent worktree under .claude/worktrees/agent-<id> on its own branch. Verify .claude/worktrees/ is gitignored before relying on this. | Overlap is allowed only as a predicted merge conflict handled by the worktree-isolated post-batch flow. Log the predicted overlap before dispatch. | Subagents may stage, commit, and run their unit tests inside their own worktree branch. |
Claude Code Agent without worktree isolation, or any shared-directory subagent | Subagents write in the orchestrator's working directory. | Overlap is not safe. Downgrade overlapping units to serial. | Subagents must not stage, commit, or run the project test suite. |
Codex spawn_agent / forked workspace | Use Codex's fork workspace semantics when available. Do not pass or claim Claude's isolation: "worktree" parameter. | Prefer disjoint write sets. If files overlap, dispatch serially unless the harness provides an explicit diff/merge handoff you can inspect before integration. | The orchestrator owns final integration, staging, commits, and project-level verification. |
| No subagent support | Inline execution only. | Not applicable. | The current agent owns all work. |
Subagent dispatch uses your available subagent or task spawning mechanism. For each unit, give the subagent:
Shared-directory fallback constraints — apply when reliable isolation is unavailable:
git add), create commits, or run the project test suite. The orchestrator handles testing, staging, and committing after all parallel units complete."Permission mode: Omit the mode parameter when dispatching subagents so the user's configured permission settings apply. Do not pass mode: "auto" — it overrides user-level settings like bypassPermissions.
After each subagent completes (serial mode):
Files: listAfter all parallel subagents in a batch complete (worktree-isolated mode):
git merge --abort) and re-dispatch the conflicting unit serially against the now-merged tree — hand-resolving silently picks a side and discards one unit's intent. Predicted overlap from the Parallel Safety Check surfaces here as a conflict, not as silent data loss in shared-directory mode.git worktree unlock <absolute-path>git worktree remove <absolute-path>git branch -d <branch-name> (-d refuses to delete unmerged branches; if it fails, investigate before forcing)After all parallel subagents in a batch complete (shared-directory or fork-workspace handoff):
Files: lists). Subagents may create or modify files not anticipated during planning — this is expected, since plans describe what not how. A collision only matters when 2+ subagents in the same batch modified the same file. In a shared working directory, only the last writer's version survives — the other unit's changes to that file are lost. If a collision is detected: commit all non-colliding files from all units first, then re-run the affected units serially for the shared file so each builds on the other's committed workTask Execution Loop
For each task in priority order:
while (tasks remain):
- Mark task as in-progress
- Read any referenced files from the plan or discovered during Phase 0
- **If the unit's work is already present and matches the plan's intent** (files exist with the expected capability, or the unit's `Verification` criteria are already satisfied by the current code), the work has likely shipped on a prior branch or session. Verify it matches, mark the task complete, and move on. Do not silently reimplement.
- Look for similar patterns in codebase
- Find existing test files for implementation files being changed (Test Discovery — see below)
- Implement following existing conventions
- Add, update, or remove tests to match implementation changes (see Test Discovery below)
- Run System-Wide Test Check (see below)
- Run tests after changes
- Assess testing coverage: did this task change behavior? If yes, were tests written or updated? If no tests were added, is the justification deliberate (e.g., pure config, no behavioral change)?
- Mark task as completed
- Evaluate for incremental commit (see below)
When a unit carries an Execution note, honor it. For test-first units, write the failing test before implementation for that unit. For characterization-first units, capture existing behavior before changing it. For units without an Execution note, proceed pragmatically.
Guardrails for execution posture:
Test Discovery — Before implementing changes to a file, find its existing test files (search for test/spec files that import, reference, or share naming patterns with the implementation file). When a plan specifies test scenarios or test files, start there, then check for additional test coverage the plan may not have enumerated. Changes to implementation files should be accompanied by corresponding test updates — new tests for new behavior, modified tests for changed behavior, removed or updated tests for deleted behavior.
Test Scenario Completeness — Before writing tests for a feature-bearing unit, check whether the plan's Test scenarios cover all categories that apply to this unit. If a category is missing or scenarios are vague (e.g., "validates correctly" without naming inputs and expected outcomes), supplement from the unit's own context before writing tests:
| Category | When it applies | How to derive if missing |
|---|---|---|
| Happy path | Always for feature-bearing units | Read the unit's Goal and Approach for core input/output pairs |
| Edge cases | When the unit has meaningful boundaries (inputs, state, concurrency) | Identify boundary values, empty/nil inputs, and concurrent access patterns |
| Error/failure paths | When the unit has failure modes (validation, external calls, permissions) | Enumerate invalid inputs the unit should reject, permission/auth denials it should enforce, and downstream failures it should handle |
| Integration | When the unit crosses layers (callbacks, middleware, multi-service) | Identify the cross-layer chain and write a scenario that exercises it without mocks |
System-Wide Test Check — Before marking a task done, pause and ask:
| Question | What to do |
|---|---|
| What fires when this runs? Callbacks, middleware, observers, event handlers — trace two levels out from your change. | Read the actual code (not docs) for callbacks on models you touch, middleware in the request chain, after_* hooks. |
| Do my tests exercise the real chain? If every dependency is mocked, the test proves your logic works in isolation — it says nothing about the interaction. | Write at least one integration test that uses real objects through the full callback/middleware chain. No mocks for the layers that interact. |
| Can failure leave orphaned state? If your code persists state (DB row, cache, file) before calling an external service, what happens when the service fails? Does retry create duplicates? | Trace the failure path with real objects. If state is created before the risky call, test that failure cleans up or that retry is idempotent. |
| What other interfaces expose this? Mixins, DSLs, alternative entry points (Agent vs Chat vs ChatMethods). | Grep for the method/behavior in related classes. If parity is needed, add it now — not as a follow-up. |
| Do error strategies align across layers? Retry middleware + application fallback + framework error handling — do they conflict or create double execution? | List the specific error classes at each layer. Verify your rescue list matches what the lower layer actually raises. |
When to skip: Leaf-node changes with no callbacks, no state persistence, no parallel interfaces. If the change is purely additive (new helper method, new view partial), the check takes 10 seconds and the answer is "nothing fires, skip."
When this matters most: Any change that touches models with callbacks, error handling with fallback/retry, or functionality exposed through multiple interfaces.
Incremental Commits
After completing each task, evaluate whether to create an incremental commit:
| Commit when... | Don't commit when... |
|---|---|
| Logical unit complete (model, service, component) | Small part of a larger unit |
| Tests pass + meaningful progress | Tests failing |
| About to switch contexts (backend → frontend) | Purely scaffolding with no behavior |
| About to attempt risky/uncertain changes | Would need a "WIP" commit message |
Heuristic: "Can I write a commit message that describes a complete, valuable change? If yes, commit. If the message would be 'WIP' or 'partial X', wait."
If the plan has Implementation Units, use them as a starting guide for commit boundaries — but adapt based on what you find during implementation. A unit might need multiple commits if it's larger than expected, or small related units might land together. Use each unit's Goal to inform the commit message.
Commit workflow:
# 1. Verify tests pass (use project's test command)
# Examples: bin/rails test, npm test, pytest, go test, etc.
# 2. Stage only files related to this logical unit (not `git add .`)
git add <files related to this logical unit>
# 3. Commit with conventional message
git commit -m "feat(scope): description of this unit"
Handling merge conflicts: If conflicts arise during rebasing or merging, resolve them immediately. Incremental commits make conflict resolution easier since each commit is small and focused.
Note: Incremental commits use clean conventional messages without attribution footers. The final Phase 4 commit/PR includes the full attribution.
Parallel subagent mode: Commit ownership is split by isolation mode (see Phase 1 Step 4):
Follow Existing Patterns
Test Continuously
Simplify as You Go
After completing a cluster of related implementation units (or every 2-3 units), review recently changed files for simplification opportunities — consolidate duplicated patterns, extract shared helpers, and improve code reuse and efficiency. This is especially valuable when using subagents, since each agent works with isolated context and can't see patterns emerging across units.
Don't simplify after every single unit — early patterns may look duplicated but diverge intentionally in later units. Wait for a natural phase boundary or when you notice accumulated complexity.
If a simplify skill or equivalent capability is available, use it. Otherwise, review the changed files yourself for reuse and consolidation opportunities.
Figma Design Sync (if applicable)
For UI work with Figma designs:
Track Progress
spec_id only as artifact-chain trace context, not as execution progress. Use the IDs the plan supplies and do not invent ones it does not. This preserves traceability without burying signal under noise.When all Phase 2 tasks are complete and execution transitions to quality check, read references/shipping-workflow.md for the full shipping workflow: quality checks, code review, final validation, PR creation, and notification.
/spec:plan to reduce scope — don't invent session phases as a workaround. For bare-prompt input, Phase 0's Large routing already handles oversized work