Using OpenSpec with Superpowers
Principle
OpenSpec governs durable change intent and current behavior. Superpowers governs execution. Keep one reviewed plan and one verification record with the active change; keep drafts and raw agent material isolated.
Preflight
- Read a project adapter skill when present; it supplies project checks and overrides generic defaults.
- Read the active change's artifacts and
openspec instructions before writing or implementing.
- Ensure the project has the
agentic-workflow schema. For a new project, inspect its conventions and obtain owner approval before installing or selecting the schema.
- Ensure
.agent-work/{research,reviews,plans,specs,prompts} exists in the current worktree. It must be ignored and must not be shared between worktrees.
Artifact boundary
| Durable and committed |
Ephemeral and ignored |
openspec/specs/ current behavior |
.agent-work/research/ |
| Active change proposal, delta specs, design, tasks |
.agent-work/prompts/ |
Active change plan.md and verify.md |
Draft plans, raw reviews, logs |
| ADRs with consequential rationale |
|
Do not create root-level agent plans or reviews outside an active change. Promote a reviewed implementation plan to the schema-managed plan.md; summarize acceptance evidence in verify.md.
Lifecycle
explore -> feature worktree -> proposal/specs/design/tasks -> plan
-> implement/test/reconcile -> verify -> sync -> human approval
-> merge -> archive -> cleanup
- Explore read-only when scope is uncertain.
- Create a feature worktree before creating a named change. Never implement on
main.
- Review all planning artifacts, including
plan.md, before implementation.
- Follow TDD, task-level review, and project verification during implementation.
- If discoveries alter intent, reconcile the active OpenSpec artifacts; do not silently make code the new specification.
- Before final review, validate against the change and sync delta specifications into
openspec/specs/.
- After merge, archive from the main worktree so only shipped changes enter history.
Decision rules
If a correction is clearly implied by accepted intent, update the active artifacts and record the rationale. Ask the owner before a consequential architectural choice, ambiguity in intended behavior, irreversible/destructive operation, security-sensitive action, merge, push, archive, or deleting non-ephemeral material.
Urgency never bypasses branch isolation, review of planning artifacts, testing, or the durable/ephemeral boundary.
Closeout
Complete verify.md with scenario coverage, commands/results, review conclusions, residual risks, and an explicit READY archive verdict. Before offering archive, inspect the active change and stop if verify.md is missing or its verdict is not READY; OpenSpec itself does not enforce this archive precondition. Never commit .agent-work/. Preserve the worktree until the owner chooses integration; then archive and clean it up with the project's supported worktree tool.
1---2name: using-openspec-superpowers3description: Use when starting, planning, implementing, reviewing, or closing a non-trivial OpenSpec change that needs durable specifications and disciplined agent execution.4license: MIT5---67# Using OpenSpec with Superpowers89## Principle1011OpenSpec governs durable change intent and current behavior. Superpowers governs execution. Keep one reviewed plan and one verification record with the active change; keep drafts and raw agent material isolated.1213## Preflight14151. Read a project adapter skill when present; it supplies project checks and overrides generic defaults.162. Read the active change's artifacts and `openspec instructions` before writing or implementing.173. Ensure the project has the `agentic-workflow` schema. For a new project, inspect its conventions and obtain owner approval before installing or selecting the schema.184. Ensure `.agent-work/{research,reviews,plans,specs,prompts}` exists in the current worktree. It must be ignored and must not be shared between worktrees.1920## Artifact boundary2122| Durable and committed | Ephemeral and ignored |23| --- | --- |24| `openspec/specs/` current behavior | `.agent-work/research/` |25| Active change proposal, delta specs, design, tasks | `.agent-work/prompts/` |26| Active change `plan.md` and `verify.md` | Draft plans, raw reviews, logs |27| ADRs with consequential rationale | |2829Do not create root-level agent plans or reviews outside an active change. Promote a reviewed implementation plan to the schema-managed `plan.md`; summarize acceptance evidence in `verify.md`.3031## Lifecycle3233```text34explore -> feature worktree -> proposal/specs/design/tasks -> plan35 -> implement/test/reconcile -> verify -> sync -> human approval36 -> merge -> archive -> cleanup37```3839- Explore read-only when scope is uncertain.40- Create a feature worktree before creating a named change. Never implement on `main`.41- Review all planning artifacts, including `plan.md`, before implementation.42- Follow TDD, task-level review, and project verification during implementation.43- If discoveries alter intent, reconcile the active OpenSpec artifacts; do not silently make code the new specification.44- Before final review, validate against the change and sync delta specifications into `openspec/specs/`.45- After merge, archive from the main worktree so only shipped changes enter history.4647## Decision rules4849If a correction is clearly implied by accepted intent, update the active artifacts and record the rationale. Ask the owner before a consequential architectural choice, ambiguity in intended behavior, irreversible/destructive operation, security-sensitive action, merge, push, archive, or deleting non-ephemeral material.5051Urgency never bypasses branch isolation, review of planning artifacts, testing, or the durable/ephemeral boundary.5253## Closeout5455Complete `verify.md` with scenario coverage, commands/results, review conclusions, residual risks, and an explicit `READY` archive verdict. Before offering archive, inspect the active change and stop if `verify.md` is missing or its verdict is not `READY`; OpenSpec itself does not enforce this archive precondition. Never commit `.agent-work/`. Preserve the worktree until the owner chooses integration; then archive and clean it up with the project's supported worktree tool.
jfear