Menu
Research-backed rebaselining. Revises design, plan, or in-progress work while preserving completed scope and approval lineage.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Specwright health check. Validates shared config, anchor docs, workflow and session state, commands, gates, and hooks. May backfill shipped PR metadata when it can prove the mapping safely.
Detects project stack and existing guardrails, then interactively configures deterministic quality checks across session, commit, push, and CI/CD layers.
Initializes Specwright in a project. Detects stack, asks about practices, creates constitution and charter, configures quality gates and hooks.
Shows current Specwright state for this worktree, the attached work, repo-wide active works, gate results, and lock status. Supports --reset, --cleanup, and --repair {unitId}.
Periodic codebase health check. Analyzes architecture, complexity, consistency, and debt across the full codebase. Produces persistent findings in AUDIT.md.
TDD implementation of one work unit. Delegates test writing to the tester agent and implementation to the executor agent. Commits per task.
| name | sw-pivot |
| description | Research-backed rebaselining. Revises design, plan, or in-progress work while preserving completed scope and approval lineage. |
| argument-hint | [reason for pivot] |
| allowed-tools | ["Read","Write","Edit","Bash","Glob","Grep","Task"] |
Research-backed rebaselining for the selected work. Capture preserved scope,
understand what changed, classify the pivot, revise the affected open work via
architect, and hand back to /sw-plan or /sw-build as appropriate. Applies
protocols/decision.md for all decisions. Revisions auto-applied and recorded
in decisions.md; the revised artifact set is the contract.
{worktreeStateRoot}/session.json — selected work for this worktree{repoStateRoot}/work/{selectedWork.id}/workflow.json — selected work state,
active unit, tasksCompleted, tasksTotal, and work/unit pathsdesign.md, context.md, assumptions.md,
decisions.md, integration-criteria.md when presentspec.md, plan.md, context.md{workArtifactsRoot}/{selectedWork.id}/approvals.md — durable approval ledger for design and unit lineageintegration-criteria.md when structural pivots stale the current
criteriaworkflow.json — pivot classification, active state, and
affected remaining work updateddecisions.md — pivot decisions recordedPre-condition (LOW freedom):
Resolve the selected work from the current worktree session. Valid entry states
are planning, building, and verifying. Reject designing,
shipping, and shipped with explicit guidance: use /sw-design change
request flow for designing, and start a fresh work or normal ship/fix flow
for shipping or shipped. If another live top-level worktree owns the
selected work, STOP with explicit adopt/takeover guidance.
Snapshot (LOW freedom): Read the selected work's completed and open scope. Present preserved baseline scope versus delta scope before proposing any mutation.
Classification (MEDIUM freedom): Classify the request before mutation:
task-pivot — execution detail changed but design and unit boundaries remain validunit-pivot — current or future unit scope changed, but work-level design intent still holdswork-pivot — design path changed, scope expanded, or the architecture must be rebaselinedPivot input (MEDIUM freedom):
If argument provided, use it as the pivot reason. If no argument, infer from
conversation context per protocols/decision.md DISAMBIGUATION.
Research-first analysis (MEDIUM freedom):
For unit-pivot and work-pivot, run a bounded research pass before revision.
Prefer existing tracked artifacts first, recent retro evidence second, and
fresh external research only when the pivot changes an external contract.
Capture the synthesized findings in work context rather than requiring the user
to restate them.
Revise (HIGH freedom for architect, LOW freedom for mutation):
Delegate to specwright-architect per protocols/delegation.md. Completed
tasks and shipped units are immutable baseline scope. Architect may revise
remaining tasks, affected remaining-unit artifacts, or work-level design
artifacts depending on pivot class. If architect proposes rewriting completed
criteria or shipped scope: reject and re-delegate (max 2 attempts). If the
pivot would invalidate shipped scope anyway, STOP and escalate to a fresh
/sw-design work instead of rewriting history.
Apply (MEDIUM freedom):
Auto-apply the classified revision. task-pivot may revise the active unit
task list; unit-pivot may regenerate affected remaining-unit artifacts and
integration-criteria.md; work-pivot may revise work-level design artifacts
plus affected remaining units. Update the selected work's workflow.json,
record preserved baseline scope versus delta scope in decisions.md, and
mutate only the selected work's workflow state. Never rewrite unrelated active
works. Use revision-chain updates for work-level artifacts instead of creating
parallel design trees.
State handling (LOW freedom):
Do not create a new persisted pivoting workflow status. sw-pivot runs
inside planning, building, or verifying; if active or affected unit
artifacts change, the touched work returns to building. If only future units
change and the active unit remains valid, preserve the active unit's current
state.
Approval lineage (LOW freedom):
If the pivot changes work-level or unit-level artifacts, the corresponding
design or unit-spec approval lineage becomes stale against the revised
artifact set. Use protocols/approvals.md and the shared approval helper
implemented in adapters/shared/specwright-approvals.mjs to assess and
preserve that stale lineage rather than erasing it. Surface compact stale
reasons such as missing-entry, artifact-set-changed, missing-lineage,
expired, and superseded. Never fabricate a replacement APPROVED entry
during /sw-pivot; the next human-triggered /sw-build records the
replacement approval that supersedes the stale lineage.
Closeout summary (LOW freedom):
Before the stage handoff, summarize the preserved completed scope, delta scope
introduced by the pivot, affected units or tasks, whether the active unit was
reset to building, and any stale approval reasons (missing-entry,
artifact-set-changed, missing-lineage, expired, superseded). The
closeout must make scope preservation explicit instead of implying a
remaining-tasks-only rewrite.
Stage boundary (LOW freedom):
Follow protocols/stage-boundary.md. After apply: STOP with the appropriate
handoff — "Run /sw-plan." for planning-state work-pivots that revise the
work-level design before unit decomposition, and "Run /sw-build." otherwise.
protocols/stage-boundary.md -- scope and handoffprotocols/decision.md -- autonomous decision framework (scope assessment)protocols/state.md -- workflow state updatesprotocols/approvals.md -- approval lineage invalidation and stale-state handlingprotocols/delegation.md -- architect delegationprotocols/git.md -- branch context| Condition | Action |
|---|---|
Status not planning, building, or verifying | STOP with the stage-appropriate guidance for /sw-design or a fresh follow-up work |
| Selected work owned by another live top-level worktree | STOP with explicit adopt/takeover guidance |
No open scope remains (only applicable in building or verifying) | STOP: "Run /sw-verify" |
| Architect modifies completed criteria or shipped scope | Reject, re-delegate (max 2) |
| Requested pivot would rewrite shipped scope | STOP and escalate to a fresh /sw-design work |
| Compaction during pivot | Read the selected work's workflow.json, check if revision was applied |