openspec-superpower-change is an explicit-entry engineering change gate shared across Codex, Pi, Antigravity CLI, and Grok CLI. It connects repository-local rules, OpenSpec change contracts, Superpowers execution discipline, built-in /autoloop verification & read-only review, and evidence-based completion into one proportional workflow.
Ordinary questions, standalone read-only reviews, and everyday unconstrained edits bypass this Router. When work is explicitly routed here—or touches runtime control flow, public contracts, security, persistence, migrations, or workflow routing—the gate scales ceremony proportionally across four lanes instead of forcing a single heavy linear process.
Interactive terminal blueprint (with animated orthogonal signal paths): docs/diagrams/workflow-lanes.html
| Lane | When to use | Execution & review posture |
|---|---|---|
| 1. Compact Direct Change | Low-risk local edits, typos/docs/config, or a three-condition localized bugfix (failing-then-passing regression test, no external contract change, bounded local diff) | One-line Gate 0, minimum edit, targeted required checks, focused inline diff/self-review; no standalone Plan, Preflight, or status.md |
2. Daily /autoloop Closed-Loop |
Feature/bugfix slices backed by docs/req/*.md + 验收标准 (or active OpenSpec change / session-distilled contract) |
autoloop_ctl.py match / init-req → minimal edit → autoloop_ctl.py run (host process-group verify + deterministic vetoes + isolated agy-readonly-review, up to 2 auto-repair rounds) |
| 3. OpenSpec-Backed Implementation | New capabilities, public API/schema/migration, security, persistence, routing, or workflow lifecycle changes | Domain Context Check when ambiguous → openspec validate <id> --strict → stop for explicit approval → direct Four Hard Anchors execution (or Plan + bounded Preflight) → cohesive slices → distinct Review → learning closeout → fresh final verify/Review & archive |
| 4. External Handoff & Session Resume | Multi-window recovery, compaction handoff, or explicitly delegated external-agent execution | Lazy docs/agent-collab/<change-id>/status.md (local schema-6 subset with stage-specific strict reviewer bindings, or full external schema-6 Handoff + schema-2 evidence manifests); read-only scripts/next_action.py --status |
- Explicit-only entry & anti-drift locks: Loads only on explicit OpenSpec/change-gate/routing requests,
迭代优化skill, or archive/distill requests. Records Gate 0 with an explicit task lock (VERIFY|DIAGNOSE|FIX|REVIEW), enforces a two-failure circuit breaker on the same slice, and continues authorized same-scope work (including delegated reviews) without asking for repetitive confirmation. - Four Hard Anchors plan-anchored execution: When approved OpenSpec
design.mdandtasks.mdalready define allowed/forbidden scope,path:linetargets, cohesive batches, and exact verification commands, they serve directly as the executable Plan—eliminating duplicate Superpowers plans, standalone local Preflight JSONs, and intermediatered-green.json/native-green.jsonsprawl in favor of inline RED-to-GREEN proof. - Built-in
/autoloop&pre-mrdeterministic gate: Zero-arg requirement matching (or automatic session distillation viainit-req), isolated verification process groups (start_new_session=True+os.killpgon timeout/SIGTERM), pre-reviewer failure short-circuit, positive-count-exempted zero-test veto, fast-mode high-risk path escalation (-high+ 5-lens conditional hunt checklist), credential/PEM redaction, non-collapsingfailure_signature, portable merge-aware commit hygiene, and workspace-fingerprint-verifiedagy-readonly-review. - Schema-6 role-first authority & four-CLI parity: Treats Codex, Pi, Antigravity CLI, and Grok CLI as equally eligible assigned executors/reviewers. Product names grant no authority; only the bound Codex
control-plane/control-plane-highinstance and contract own routing, evidence acceptance, canonical state, archive, and completion decisions. Current external Handoffs use schema 6 plus schema-2 evidence manifests; frozen schema-4/5 records remain read-only legacy audit history. - Cross-window session resume & read-only next-action query: Lazy
docs/agent-collab/<change-id>/status.mdcheckpoints bind verified source fingerprints (excludingCHANGELOG.md, ledgers, and historical reports), support stage-specific strict local reviewer bindings (implementation-review/final-review), isolate rare blocked-context amendments intoreferences/resume-context-amendments.mdbehind theCOLD_PATH_STARTmarker, and exposescripts/next_action.py --statusas an advisory read-only state transition query. - Project document ownership & 4-tier mechanical learning ladder: Respects existing project directory conventions before falling back to purpose subdirectories (default engineering invariant target:
docs/engineering/engineering-invariants.md), and prioritizes durable learning by mechanical strength: (1) SSoT / dead-code removal → (2) static validators/types naming the replacement → (3) behavior regression tests → (4) prose guidance last. - Transactional four-target runtime sync & bounded self-evolution: Allowlisted schema-v2 scoped synchronization across Codex, Pi (
${PI_CODING_AGENT_DIR}/skills&APPEND_SYSTEM.md), Antigravity CLI, and Grok CLI (withgrok inspect --json), mode-0600transaction receipts, target-local rollback, managed governance block v6 (CCG-001..CCG-016), and a single-round迭代优化skillloop tracked indocs/iteration/. - Claim-to-Test Relevance Gate & specialist Review: Binds every test command to current acceptance and demonstrated blast radius (
OUT_OF_SCOPE_PREEXISTING_DEBTfor unrelated frozen-baseline failures), and routes explicit backend proposal/design audits to read-onlybackend-architecture-review.
Interactive terminal blueprint: docs/diagrams/autoloop-flow.html
# 1. Auto-match pending docs/req/*.md or active OpenSpec change (chaining its test commands)
python3 scripts/autoloop_ctl.py match --cwd "$PWD"
# 2. If unmatched, persist requirement & acceptance criteria distilled from the session
python3 scripts/autoloop_ctl.py init-req \
--cwd "$PWD" --slug "<slug>" --title "<title>" \
--summary "<scope & non-goals>" --cmd "<verify command>" --accept "<criteria>"
# 3. Run default fast closed-loop (medium reasoning; auto-escalates to -high + 5-lens hunt on .sql/auth/security/migration/rename src)
python3 scripts/autoloop_ctl.py run --cwd "$PWD"
# 4. Run strict pre-MR signoff (three-dot net diff, 2MB patch cap, merge-aware commit check, 5 conditional hunt lenses, high reasoning)
python3 scripts/autoloop_ctl.py run \
--cwd "$PWD" --base-ref "origin/<target_branch>" \
--commit-msg-file /private/tmp/commit_msg.txt --review-profile pre-mrKey runtime guardrails enforced by scripts/gov_runner.py, scripts/autoloop_ctl.py, and scripts/check_commit_text.py (macOS Python 3.9.6 & launchd compatible):
- Process-group isolation & short-circuit: Runs
verify_commandin a dedicated session (start_new_session=True), kills the entire tree viaos.killpg(..., SIGKILL)on timeout orSIGTERM, maps missing/non-executable commands to127/126(setup_or_env_error), and short-circuits before launching the reviewer CLI on any non-zero exit or deterministic veto. - Deterministic pre-reviewer vetoes: Rejects
pre-mrwithout--base-ref, unresolvable--base-ref, patches exceeding2,000,000bytes (truncated=true), clean worktrees with zero net diff, zero-testexit 0runs (exempted when any chained module reports a positive test count), and secret/hygiene failures incheck_commit_text.py(exempting standardMerge:commits from Conventional Commit syntax while retaining secret scanning and applyingprofile_cfgto the first non-merge commit). - Redacted non-collapsing diagnostics & exact verdict anchoring: Masks compound secret keys (
access_token,DB_PASSWORD,OPENAI_API_KEY),Bearer/Basic/Tokenauth, password-only URLs (redis://:pwd@host), raw tokens, and full/truncated PEM private keys without swallowing trailing error lines; computes a 16-hexfailure_signatureacross test IDs and normalized error/finding lines (stopping auto-repair immediately on two identical consecutive signatures); and enforces exact-line anchoredAUTOLOOP_VERDICT: PASSplus zero workspace mutation acrossagy-readonly-review.
The built-in, default-off governed-caveman-lite profile makes ordinary Router prose concise while keeping professional full sentences. Enable it for the current conversation with OpenSpec 精简模式:<任务> (or send OpenSpec 精简模式 before the task), and disable it with OpenSpec 正常模式.
The profile changes presentation only. It does not require an external Caveman skill, does not persist beyond the current conversation, and never compresses away governance fields, approvals, evidence, critical commands, or security and safety text.
| Capability | Responsibility | Owned By |
|---|---|---|
| Local project rules | Repository constraints, review artifacts, handoff rules, commit conventions | Project AGENTS.md / local docs |
| Project knowledge | Domain glossary, engineering invariants, ADRs, candidate provenance, regression enforcement | CONTEXT.md, docs/engineering/engineering-invariants.md (default), docs/adr/, Candidate Cards, tests/validators |
| OpenSpec | Single authoritative change contract, requirements, scenarios, approval state, Four Hard Anchors | openspec/ |
| Superpowers | Phase-selected planning, TDD, systematic debugging, verification discipline | Superpowers skills via references/superpowers-adapter.md |
Daily /autoloop gate |
Zero-arg requirement match/distill, host verification, deterministic vetoes, isolated read-only AGY review | scripts/autoloop_ctl.py, scripts/gov_runner.py, scripts/check_commit_text.py, references/autoloop-req-acceptance.md, references/autoloop-review-hunt.md |
| Step Evidence Gate | Business-slice evidence profiles (compact, standard, strict) and inline RED-to-GREEN proof |
references/step-evidence-gate.md |
| Completion Contract | Single Router-owned whole-task success, stop, evidence, learning, reconciliation, sync, and authority contract | references/completion-contract.md |
| Continuity & Resume | Lazy status.md checkpoints, stage-specific strict reviews, cold-path amendments, read-only transition query |
references/approved-implementation-workflow.md, references/resume-context-amendments.md, scripts/next_action.py |
| Companion & Specialist Reviews | Standalone prompt/diff review & Handoff-backed batch review; explicit read-only backend architecture audits | codex-brief-antigravity-review; backend-architecture-review |
| openspec-superpower-change | Entry gate, proportional routing, risk classification, approval/evidence boundaries, self-evolution | This skill (SKILL.md) |
| Mode | Use When | File Changes? |
|---|---|---|
| Review-only | Assess architecture, OpenSpec need, authorization, risk, or completion evidence | No |
| Backend architecture Review | Explicit backend proposal/design audit (boundaries, contracts, transactions, performance, over-design) | No |
| Discovery First | Domain terms, actors, lifecycle, or boundaries remain unclear after inspecting code/docs | Glossary / context only |
| OpenSpec proposal | New capability, public behavior, API/schema/migration, security, persistence, or workflow changes | Proposal artifacts only |
| Approved implementation | Concrete OpenSpec change-id is explicitly approved |
Yes (Four Hard Anchors or Plan + Preflight) |
| Direct Change | Low-risk local edits, docs/config/tests, or three-condition localized bugfix restoration | Yes, scoped |
/autoloop closed-loop |
Requirement doc (docs/req/*.md) + acceptance criteria verification & independent read-only review |
Yes, gated by govpi |
| Self-Evolution | Modifying this skill, its references, scripts, validators, or sync rules (迭代优化skill) |
Yes, Patch/Minor/Major gated |
Gate 0 (recorded before state-changing edits, commands, or proposals; compressed to one line for obvious compact local work) states: active mode, task (VERIFY | DIAGNOSE | FIX | REVIEW), references read, OpenSpec decision and reason, selected Superpowers methods (or none), risk/evidence profile (compact | standard | strict), next action, and whether user confirmation is required.
- Bounded Plan Preflight (when a separate Plan/Brief is needed outside Four Hard Anchors / compact Direct Change): at most one
FULL_PREFLIGHTplus one terminalFOCUSED_RECHECKby the same independent reviewer instance on unchanged protected boundaries; non-convergence routes toCONTROL_PLANE_ADJUDICATION. - Project Learning Layers: Two independent correction/Review signals—or one high-severity security, integrity, data-loss, or false-PASS event, or an explicit archive-and-distill request—require durable promotion before fresh final verification (
CONTEXT.mdfor glossary only, project guidance defaulting todocs/engineering/engineering-invariants.md,docs/adr/NNNN-slug.mdfor hard-to-reverse trade-offs,docs/learning-candidates/YYYY-MM-DD-<slug>.mdfor provenance, and deterministic tests/validators following the 4-tier mechanical ladder). - Workflow Baseline (2026-07-30): Evaluated Schemes A/B/C and retained Scheme C (OpenSpec + Superpowers +
codex-brief-antigravity-review) for cross-project/cross-stack governance with traceable dependency upgrades rather than blind auto-tracking; see the full evaluation and independent Review.
.
├── SKILL.md
├── references/
│ ├── request-modes.md
│ ├── direct-change-rule.md
│ ├── openspec-decision-rule.md
│ ├── proposal-workflow.md
│ ├── approved-implementation-workflow.md # hot trunk + COLD_PATH_START resume tail
│ ├── resume-context-amendments.md # cold-path blocked-context/rebind rules
│ ├── autoloop-req-acceptance.md # zero-arg /autoloop closed-loop spec
│ ├── autoloop-review-hunt.md # 5 conditional read-only hunt lenses
│ ├── step-evidence-gate.md
│ ├── completion-contract.md
│ ├── superpowers-adapter.md
│ ├── handoff-contract.md
│ ├── agent-capability-routing.md
│ ├── confirmation-lease.md
│ ├── local-instruction-checkpoint.md
│ ├── learning-candidate-pipeline.md
│ ├── project-learning-closeout.md # includes Project Document Ownership
│ ├── response-patterns.md
│ ├── self-evolution-rule.md
│ ├── skill-iteration-loop.md # bounded 迭代优化skill protocol
│ ├── sync-checklist.md
│ ├── cross-cli-sync.md
│ ├── cross-cli-portable-manifest.json
│ └── shared-global-governance.md # managed block v6 (CCG-001..CCG-016)
├── scripts/
│ ├── autoloop_ctl.py # match / init-req / run / status / ensure
│ ├── gov_runner.py # host-side isolated verifier & reviewer runner
│ ├── check_commit_text.py # portable commit & added-diff hygiene gate
│ ├── next_action.py # read-only advisory transition query
│ ├── validate_core_gates.py # core governance, handoff & resume validator
│ ├── validate_cross_cli_sync.py # 4-CLI transactional plan/apply/verify-all
│ ├── build_codex_plugin.py # Codex plugin distribution generator
│ ├── build_skillsmp_adapter.py # SkillsMP compatibility adapter generator
│ └── validate_distribution.py # package, plugin & adapter validator
├── distribution/codex-plugin/ # generated Codex plugin distribution
├── skills/openspec-superpower-change/ # generated SkillsMP catalog adapter
├── templates/ # OpenSpec, evidence, req & candidate templates
├── tests/ # 500+ stdlib unit, sync, distribution & runner tests
└── docs/
├── diagrams/ # terminal-flow-diagram HTML blueprints & 2x PNGs
├── iteration/ # BACKLOG.md, CURRENT.md, LOG.md, upstream-notes.md
├── distribution.md
└── workflow.md
The repository root is the canonical Agent Skill source. Copy or link into your runtime skills directory:
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
cp -R openspec-superpower-change "${CODEX_HOME:-$HOME/.codex}/skills/openspec-superpower-change"See Distribution and installation for Agent Skills/GitHub, skills.sh, SkillsMP, Pi/npm, and Codex plugin paths. Rebuild generated adapters from the canonical source with python3 scripts/build_codex_plugin.py . and python3 scripts/build_skillsmp_adapter.py .. Third-party search refresh is asynchronous and is not guaranteed by generation, installation, or npm publication.
Run static, distribution, and test validation after editing the skill:
/usr/bin/python3 -m py_compile scripts/*.py
"${PYTHON_BIN:-python3}" "${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-creator/scripts/quick_validate.py" .
PYTHONDONTWRITEBYTECODE=1 python3 scripts/validate_core_gates.py .
PYTHONDONTWRITEBYTECODE=1 python3 scripts/validate_distribution.py .
PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tests -vCurrent governed status uses schema 6 with an immutable Reviewer Assignment. Validate its schema-2 evidence manifests, read-only next-action transitions, or project session resume checkpoints with:
# Full external Handoff status (+ --previous-status mandatory for complete)
PYTHONDONTWRITEBYTECODE=1 python3 scripts/validate_core_gates.py . \
--status /project/docs/agent-collab/<change-id>/status.md \
--artifact-root /project
# Read-only advisory next-action query
PYTHONDONTWRITEBYTECODE=1 python3 scripts/next_action.py \
--status /project/docs/agent-collab/<change-id>/status.md
# Local/external project session resume checkpoint
PYTHONDONTWRITEBYTECODE=1 python3 scripts/validate_core_gates.py . \
--resume-status /project/docs/agent-collab/<change-id>/status.md \
--artifact-root /projectEach referenced artifact embeds a schema-2 evidence manifest that binds its role/result/change/batch/attempt/source fingerprint plus assigned product, instance, role, and capability profile. Before a transition introduces new evidence, validate a proposed status from outside the project with --previous-status /project/docs/agent-collab/<change-id>/status.md; this is mandatory for complete. Replace the one canonical status only after PASS, and do not persist a second marker block in the project.
Frozen schema-4/schema-5 records are legacy audit/drain inputs only. Inventory them separately; never pass them to current --status validation or migrate them into schema 6:
PYTHONDONTWRITEBYTECODE=1 python3 scripts/validate_core_gates.py . \
--legacy-inventory-root /project \
--legacy-inventory-output /private/tmp/legacy-drain.jsonquick_validate.py requires PyYAML; set PYTHON_BIN accordingly. The project validator and test suite exercise the dependency-free fallback. Portable core-skill changes must additionally run scripts/validate_cross_cli_sync.py (plan → per-target apply/verify/verify-discovery/commit-target → verify-all) across Codex, Pi, Antigravity CLI, and Grok CLI (grok inspect --json), plus scripts/autoloop_ctl.py ensure when gov_runner.py or check_commit_text.py changes.
Use openspec-superpower-change review-only mode. Read local rules, inspect this implementation plan, and report whether it requires OpenSpec. Do not modify files.
Use Direct Change mode. Confirm this is a three-condition localized bugfix, add a failing-then-passing regression test, make the smallest fix, and report evidence.
/autoloop
Use backend-architecture-review for a read-only Review of this backend proposal. Inspect the actual project code and report only material boundary, contract, transaction, performance, stability, or over-design findings.
Continue the approved task from its canonical Plan/Status/Handoff state. Do not restart completed work, create a second ledger, or expand scope without a new decision.
- Update both
README.mdandREADME_cn.md(and any affected blueprints underdocs/diagrams/) for every published repository change so user-visible behavior, flows, validation, and compatibility stay aligned. - Do not weaken approval gates, evidence gates, or completion-claim rules.
- When OpenSpec
design.mdandtasks.mddefine the Four Hard Anchors, they serve as the executable Plan; require a separate Superpowers plan only when those execution anchors are absent, and never use Superpowers planning to bypass OpenSpec approval. - Do not let
CONTEXT.mdreplace OpenSpec proposal artifacts, and do not let required project learning remain only in chat or prose when deterministic enforcement is practical. - Do not sync runtime and open-source copies with directory-level overwrites; use
references/sync-checklist.mdandscripts/validate_cross_cli_sync.py. - Do not complete verified-but-unreviewed work or claim OpenSpec closure with unreconciled tasks or missing post-archive strict validation.
MIT. See LICENSE.

