@pzy560117/opensuper 0.2.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rpamis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,362 @@
+<p align="center">
+  <a href="https://github.com/pzy560117/opensuper/blob/main/img/title-log.png">
+    <picture>
+      <source srcset="https://github.com/pzy560117/opensuper/blob/main/img/title-log.png">
+      <img src="https://github.com/pzy560117/opensuper/blob/main/img/title-log.png" alt="OpenSuper logo">
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/pzy560117/opensuper/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/pzy560117/opensuper/actions/workflows/ci.yml/badge.svg" /></a>
+  <a href="https://www.npmjs.com/package/@pzy560117/opensuper"><img alt="npm version" src="https://img.shields.io/npm/v/%40pzy560117%2Fopensuper?style=flat-square" /></a>
+  <a href="https://www.npmjs.com/package/@pzy560117/opensuper"><img alt="npm download count" src="https://img.shields.io/npm/dm/%40pzy560117%2Fopensuper?style=flat-square&label=Downloads/mo" /></a>
+  <a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" /></a>
+</p>
+
+# @pzy560117/opensuper
+
+```
+ ██████╗ ██████╗ ███╗   ███╗███████╗████████╗
+██╔════╝██╔═══██╗████╗ ████║██╔════╝╚══██╔══╝
+██║     ██║   ██║██╔████╔██║█████╗     ██║
+██║     ██║   ██║██║╚██╔╝██║██╔══╝     ██║
+╚██████╗╚██████╔╝██║ ╚═╝ ██║███████╗   ██║
+ ╚═════╝ ╚═════╝ ╚═╝     ╚═╝╚══════╝   ╚═╝
+```
+
+> 中文版：[README-zh.md](README-zh.md)
+> [B站视频介绍 ](https://www.bilibili.com/video/BV1y4Gi6CEo1/?spm_id_from=333.1387.homepage.video_card.click&vd_source=d22726fe6b108647dbebf1c5d8817377)
+
+**OpenSpec + Superpowers dual-star development workflow** — one command from idea to archive.
+
+OpenSpec handles **WHAT** (outlines, proposals, spec lifecycle, archiving). Superpowers handles **HOW** (technical design, planning, execution, wrap-up). OpenSuper chains both into a five-phase automated pipeline.
+
+## Why OpenSuper
+
+OpenSpec excels at managing requirements, creating proposals, managing Spec lifecycles, and archiving, but its proposals and tasks lack the detail of Superpowers brainstorming.
+
+Superpowers generates Spec documents after brainstorming, but these documents typically lack stateful design — after completing requirements, Specs only have tasks checked off in the document, and Agents even forget to check them off. This causes the Agent to re-examine documents and project code to verify on resumption, wasting many tokens.
+
+**OpenSuper combines the strengths of both**, integrating the core workflow into 5 phases
+
+The main entry `/opensuper` supports current Spec state detection, suitable for long tasks — after completing and closing CC midway, just `/opensuper continue` and OpenSuper will automatically read the active Spec (lists multiple for selection), dynamically identify which phase is currently executing, and continue.
+
+## Install
+
+```bash
+npm install -g @pzy560117/opensuper
+```
+
+## Quick Start
+
+```bash
+cd your-project
+opensuper init
+```
+
+`opensuper init` will:
+
+1. Prompt you to select AI platforms (auto-detects existing configs)
+2. Choose install scope: project-level (current directory) or global (home directory)
+3. Select language for OpenSuper skills: English or 中文
+4. Install [OpenSpec](https://github.com/Fission-AI/OpenSpec) skills
+5. Install [Superpowers](https://github.com/obra/superpowers) skills
+6. Deploy OpenSuper skills (in your chosen language) to selected platforms
+7. Create `docs/superpowers/specs/` and `docs/superpowers/plans/` working directories
+
+> [!TIP]
+> update version
+>
+> `opensuper update` or `npm install -g @pzy560117/opensuper@latest` to get the latest features and fixes.
+
+## Screenshots
+
+<p align="center">
+  <img src="https://github.com/pzy560117/opensuper/blob/main/img/runner.png" alt="runner">
+</p>
+
+<p align="center">Auto-install OpenSpec & Superpowers, one-click dev environment setup</p>
+<p align="center">Multi-phase Skill entry, auto-detects current Spec stage, auto-triggers core flow, manual review at key nodes</p>
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opensuper init [path]` | Initialize OpenSuper workflow |
+| `opensuper status [path]` | Show active changes, task progress, and next workflow command |
+| `opensuper doctor [path]` | Diagnose project/global OpenSuper installation health |
+| `opensuper update [path]` | Update the npm package and installed OpenSuper skills |
+| `opensuper --help` | Show help |
+| `opensuper --version` | Show version |
+
+### init Options
+
+| Option | Description |
+|--------|-------------|
+| `--yes` | Non-interactive mode, auto-select detected platforms |
+| `--skip-existing` | Skip already installed components |
+| `--overwrite` | Overwrite already installed components |
+| `--json` | Output structured JSON |
+
+When multiple existing components are found on the same platform, interactive init offers one bulk choice: overwrite all, skip all, or choose per component.
+
+### status Options
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Output active changes with `nextCommand` |
+
+### doctor Options
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Output structured diagnostic results |
+| `--scope <scope>` | Diagnose `auto`, `project`, or `global` scope (default: `auto`) |
+
+### update Options
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Output npm and skill update results as JSON |
+| `--language <lang>` | Override detected skill language (`en`, `zh`) |
+| `--scope <scope>` | Update only `global` or `project` scope |
+
+## Supported Platforms
+
+`opensuper init` supports 28 AI coding platforms:
+
+| Platform | Skills Dir | Platform | Skills Dir |
+|----------|-----------|----------|-----------|
+| Claude Code | `.claude/` | Cursor | `.cursor/` |
+| Codex | `.codex/` | OpenCode | `.opencode/` |
+| Windsurf | `.windsurf/` | Cline | `.cline/` |
+| RooCode | `.roo/` | Continue | `.continue/` |
+| GitHub Copilot | `.github/` | Gemini CLI | `.gemini/` |
+| Amazon Q Developer | `.amazonq/` | Qwen Code | `.qwen/` |
+| Kilo Code | `.kilocode/` | Auggie | `.augment/` |
+| Kiro | `.kiro/` | Lingma | `.lingma/` |
+| Junie | `.junie/` | CodeBuddy | `.codebuddy/` |
+| CoStrict | `.cospec/` | Crush | `.crush/` |
+| Factory Droid | `.factory/` | iFlow | `.iflow/` |
+| Pi | `.pi/` | Qoder | `.qoder/` |
+| Antigravity | `.agent/` | Bob Shell | `.bob/` |
+| ForgeCode | `.forge/` | Trae | `.trae/` |
+
+## Skills
+
+After `opensuper init`, three groups of skills are installed to the selected platform's `skills/` directory:
+
+### OpenSuper Skills
+
+| Skill | Description |
+|-------|-------------|
+| `/opensuper` | Main entry — auto-detects phase and dispatches to sub-commands |
+| `/opensuper-open` | Phase 1: Open a change (proposal, design, task breakdown) |
+| `/opensuper-design` | Phase 2: Deep design (brainstorming, Design Doc) |
+| `/opensuper-build` | Phase 3: Plan and build (implementation plan, code commits) |
+| `/opensuper-verify` | Phase 4: Verify and finish (testing, verification report) |
+| `/opensuper-archive` | Phase 5: Archive (delta spec sync, status annotation) |
+| `/opensuper-hotfix` | Preset: Quick bug fix (skips brainstorming) |
+| `/opensuper-tweak` | Preset: Small change (skips brainstorming and full plan) |
+
+### Guard & Automation Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `opensuper-guard.sh` | Phase transition guard — validates exit conditions, `--apply` auto-updates `.opensuper.yaml` |
+| `opensuper-archive.sh` | One-command archive — validates state, syncs specs, moves to archive, updates status |
+| `opensuper-yaml-validate.sh` | Schema validator — validates `.opensuper.yaml` structure and field values |
+| `opensuper-state.sh` | Unified state management — init/set/get/check/scale, agents' exclusive YAML interface |
+
+### OpenSpec Skills
+
+Spec lifecycle management: propose, explore, sync, verify, archive, and more.
+
+### Superpowers Skills
+
+Development methodology: brainstorming, TDD, subagent-driven development, code review, plan writing, and more.
+
+## Workflow
+
+```
+/opensuper
+  ↓ auto-detect
+/opensuper-open  -->  /opensuper-design  -->  /opensuper-build  -->  /opensuper-verify  -->  /opensuper-archive
+(OpenSpec)         (Superpowers)       (Superpowers)       (Both)           (OpenSpec)
+
+/opensuper-hotfix (preset path, skips brainstorming)
+  open  -->  build  -->  verify  -->  archive
+
+/opensuper-tweak (preset path, skips brainstorming and full plan)
+  open  -->  lightweight build  -->  light verify  -->  archive
+```
+
+### Five Phases
+
+| Phase | Command | Owner | Artifacts |
+|-------|---------|-------|-----------|
+| 1. Open | `/opensuper-open` | OpenSpec | proposal.md, design.md, tasks.md |
+| 2. Deep Design | `/opensuper-design` | Superpowers | Design Doc, delta spec |
+| 3. Plan & Build | `/opensuper-build` | Superpowers | Implementation plan, code commits |
+| 4. Verify & Finish | `/opensuper-verify` | Both | Verification report, branch handling |
+| 5. Archive | `/opensuper-archive` | OpenSpec | delta→main spec sync, archive |
+
+### Core Principles
+
+- **Brainstorming is non-skippable** — every change must go through deep design (except hotfix/tweak)
+- **Delta specs are living documents** — freely editable during Phase 3, synced at archive
+- **Keep tasks.md in sync** — check off each task as completed
+- **Commit frequently** — one commit per task, message reflects design intent
+- **Verify before archive** — `/opensuper-verify` must pass before `/opensuper-archive`
+
+### State Management
+
+OpenSuper uses a decoupled state architecture with separate YAML files:
+
+| File | Owner | Purpose |
+|------|-------|---------|
+| `.openspec.yaml` | OpenSpec | Spec lifecycle, change metadata |
+| `.opensuper.yaml` | OpenSuper | Workflow phase, execution mode, verification status |
+
+**Key Fields in `.opensuper.yaml`:**
+
+```yaml
+workflow: full
+phase: build
+design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
+plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
+build_mode: subagent-driven-development
+isolation: branch
+verify_mode: light
+verify_result: pending
+verification_report: docs/superpowers/reports/YYYY-MM-DD-change-verify.md
+branch_status: pending
+verified_at: null
+archived: false
+```
+
+In full workflow, `build_mode` and `isolation` may temporarily be `null` at init time, but they must be resolved before `build → verify`. `direct` is allowed by default only for hotfix/tweak; full workflow requires `direct_override: true`. Projects can configure `build_command` / `verify_command` in the change or repo root, and guard will run those commands first and print failure output.
+
+All states and execution phases are updated via scripts, and **each phase verifies that tasks are truly completed before exiting — conditions are met before the phase exits and state is updated**. Compared to recording complex state management mechanisms in Skills, the script approach strongly guarantees the reliability of core state transitions, correctness of YAML files, and convenience of breakpoint recovery — Agents only need to use OpenSuper's built-in commands to read state and know the current Spec's situation.
+
+### Reliability Features
+
+OpenSuper ensures agent execution reliability through automated state transitions:
+
+1. **Entry Verification** — Each phase validates preconditions before execution
+   - Checks file existence, state consistency, and phase transitions
+   - Outputs `[HARD STOP]` with actionable suggestions if validation fails
+
+2. **Automated State Transitions** — `opensuper-guard.sh --apply` updates `.opensuper.yaml` automatically
+   - All phase transitions (design → build → verify → archive) use `guard --apply`
+   - No manual state editing required — eliminates write-verification errors
+   - `opensuper-state.sh` is the agents' exclusive interface for state operations
+   - Guard and archive scripts use `opensuper-state.sh` internally for state management
+
+3. **Schema Validation** — `opensuper-yaml-validate.sh` ensures data integrity
+   - Validates required and optional fields
+   - Validates enum values, including `direct_override`
+   - Validates referenced file paths exist
+   - Detects unknown/typos fields
+
+4. **Build Decision Enforcement** — Guard and state transitions both block skipped build choices
+   - `isolation` must be `branch` or `worktree`
+   - `build_mode` must be selected before leaving build
+   - Full workflow `build_mode: direct` requires `direct_override: true`
+
+5. **Verification Evidence** — Guard enforces proof before phase advance
+   - `verify-pass` transition requires `verification_report` pointing to an existing report file
+   - `branch_status` must be `handled` before verify can pass
+   - Guard checks `verification_report exists` and `branch_status=handled` as hard prerequisites
+   - Prevents false phase advances when verification or branch handling was skipped
+
+6. **Archive Automation** — `opensuper-archive.sh` handles the full archive flow in one command
+   - Validates entry state, syncs delta specs to main specs
+   - Annotates design doc and plan frontmatter
+   - Moves change to archive directory and updates `archived: true`
+   - Supports `--dry-run` for preview
+
+**Security**: Path traversal protection on all change name inputs
+
+## Project Structure
+
+```
+your-project/
+├── .claude/skills/              # Platform skills dir (OpenSuper + OpenSpec + Superpowers)
+│   ├── opensuper/SKILL.md
+│   │   └── scripts/
+│   │       ├── opensuper-guard.sh       # Phase transition guard (--apply auto-updates state)
+│   │       ├── opensuper-archive.sh     # One-command archive automation
+│   │       ├── opensuper-yaml-validate.sh # Schema validator
+│   │       └── opensuper-state.sh       # Unified state management (init/set/get/check/scale)
+│   ├── opensuper-*/SKILL.md
+│   ├── openspec-*/SKILL.md
+│   └── brainstorming/SKILL.md
+├── openspec/                    # OpenSpec — WHAT
+│   ├── config.yaml
+│   └── changes/
+│       └── <name>/
+│           ├── .openspec.yaml       # OpenSpec state
+│           ├── .opensuper.yaml          # OpenSuper workflow state (decoupled)
+│           ├── proposal.md
+│           ├── design.md
+│           ├── specs/<capability>/spec.md
+│           └── tasks.md
+└── docs/superpowers/            # Superpowers — HOW
+    ├── specs/                   # Design documents
+    └── plans/                   # Implementation plans
+```
+
+## What You'll Learn
+
+Many excellent Skill projects exist in the current Skill market, but they generally have preference issues — users may only like some features. For example, when using both OpenSpec and Superpowers, one might only use OpenSpec's Spec management capabilities, but prefer Superpowers' TDD-driven approach for coding.
+
+Long-term Skill users know these capabilities can be freely combined, but exactly how to do so still requires real practice. The OpenSuper project can serve as a reference:
+
+- **How to reliably trigger nested Skills** — Not letting the Agent rely on document descriptions to perform "look-alike Skill trigger" operations (like writing files based on Skill descriptions), but truly triggering Skills (key feature: Skill trigger prints on CC). OpenSuper will trigger many capabilities from OpenSpec and Superpowers — how is this Prompt written?
+
+- **How to make combined Skills multi-phase auto-flow** — Not relying on manual intervention. OpenSuper's 5-phase flow automatically triggers Skills for core processes except necessary user selections, while the **state machine mechanism** also ensures state transition reliability.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, commit conventions, PR process, and guidance for adding platforms or skills.
+
+```bash
+# Clone
+git clone https://github.com/pzy560117/opensuper
+cd opensuper
+
+# Install dependencies
+pnpm install
+
+# Dev mode (watch)
+pnpm dev
+
+# Build
+pnpm build
+
+# Test (unit + coverage)
+pnpm test
+pnpm test:coverage
+pnpm test:shell         # bats shell tests
+
+# Lint & format
+pnpm lint
+pnpm format
+```
+
+See [CHANGELOG.md](CHANGELOG.md) for version history and updates.
+
+## Security
+
+- Pre-publish scan for API keys, secrets, tokens, and private keys
+- `.npmignore` prevents source code and config files from entering the npm package
+- `.gitignore` covers secrets, credentials, IDE configs, and more
+
+## License
+
+[MIT](LICENSE.md)
+
+## Reference
+[LINUX DO - 新的理想型社区](https://linux.do/)

package/assets/manifest.json

@@ -0,0 +1,21 @@
+{
+  "version": "0.2.6",
+  "skills": [
+    "opensuper/SKILL.md",
+    "opensuper/scripts/opensuper-guard.sh",
+    "opensuper/scripts/opensuper-state.sh",
+    "opensuper/scripts/opensuper-archive.sh",
+    "opensuper/scripts/opensuper-yaml-validate.sh",
+    "opensuper-open/SKILL.md",
+    "opensuper-design/SKILL.md",
+    "opensuper-build/SKILL.md",
+    "opensuper-verify/SKILL.md",
+    "opensuper-archive/SKILL.md",
+    "opensuper-hotfix/SKILL.md",
+    "opensuper-tweak/SKILL.md"
+  ],
+  "languages": [
+    { "id": "en", "name": "English", "skillsDir": "skills" },
+    { "id": "zh", "name": "中文", "skillsDir": "skills-zh" }
+  ]
+}

package/assets/skills/opensuper/SKILL.md

@@ -0,0 +1,268 @@
+---
+name: opensuper
+description: "OpenSuper — OpenSpec + Superpowers dual-star development workflow. Start with /opensuper for automatic phase detection and dispatch to subcommands. Five phases: open → design → build → verify → archive."
+---
+
+# OpenSuper — OpenSpec + Superpowers Dual-Star Development Workflow
+
+OpenSpec and Superpowers orbit the same goal like a binary star system. OpenSpec handles WHAT, Superpowers handles HOW.
+
+```
+OpenSpec handles WHAT  — outline, proposal, spec lifecycle, archive
+Superpowers handles HOW — technical design, planning, execution, closing
+```
+
+**Core principle: brainstorming cannot be skipped. Every change must undergo deep design (except hotfix and tweak presets).**
+
+---
+
+## Decision Core
+
+Agents need only read this section for decision-making. Refer to the Reference Appendix as needed.
+
+### Automatic Phase Detection
+
+**Step 0: Active Change Discovery**
+
+1. Run `openspec list --json` to get all active changes
+
+| Active changes | User input | Behavior |
+|----------------|------------|----------|
+| None | any | → Invoke `/opensuper-open` |
+| Exactly 1 | `/opensuper <description>` | → **Ask**: continue this change or create a new change |
+| Multiple | `/opensuper <description>` | → **Ask**: continue existing or create new; if continuing, list changes for selection |
+| Exactly 1 | `/opensuper` with no description | → Auto-select, enter Step 1 |
+| Multiple | `/opensuper` with no description | → List changes for user selection |
+
+<IMPORTANT>
+When the user chooses "create a new change", **must invoke `/opensuper-open`**. Do not call `/opsx:new` directly.
+`/opensuper-open` performs dual initialization: OpenSpec artifacts plus `.opensuper.yaml` state.
+Calling `/opsx:new` directly leaves `.opensuper.yaml` missing and breaks later phase detection.
+</IMPORTANT>
+
+**Preset detection**:
+- User describes as bug fix / hotfix + meets hotfix conditions → directly invoke `/opensuper-hotfix`
+- User describes as copy, config, docs, prompt or small non-bug adjustment + meets tweak conditions → directly invoke `/opensuper-tweak`
+
+**Step 1: Read `.opensuper.yaml` state metadata**
+
+Prefer reading `openspec/changes/<name>/.opensuper.yaml`. If not available, fall back to `openspec status --change "<name>" --json`, `tasks.md`, and `docs/superpowers/` file checks.
+
+**Resume rules**:
+- On every context resume, rerun Step 0 and Step 1; do not trust conversation history for phase detection
+- If `phase: build`, read the next unchecked task from tasks.md and continue
+- If `phase: verify` and `verify_result: fail`, first run `bash "$OPENSUPER_STATE" transition <name> verify-fail`, then invoke `/opensuper-build`
+- If `phase: open` but proposal/design/tasks are complete, run `bash "$OPENSUPER_GUARD" <change-name> open --apply` to repair state, then continue detection
+- If `phase: archive`, only invoke `/opensuper-archive`; after archive succeeds, the change moves to the archive directory, so do not run guard against the old active directory
+
+**Step 2: Phase Determination** (check in order, first match wins)
+
+1. `archived: true` or change moved to archive → Workflow complete
+2. `verify_result: pass` and `archived` is not `true` → Invoke `/opensuper-archive`
+3. `verify_result: fail` → run `bash "$OPENSUPER_STATE" transition <name> verify-fail`, then invoke `/opensuper-build`
+4. `phase: verify` or tasks.md all checked → Invoke `/opensuper-verify`
+5. `phase: build` or has Design Doc but plan/execution incomplete → Invoke `/opensuper-build`
+6. `phase: design` or has change but no Design Doc → Invoke `/opensuper-design`
+7. `phase: open` or active change exists but `.opensuper.yaml` is missing → Invoke `/opensuper-open`
+8. No active change → Invoke `/opensuper-open`
+
+If metadata conflicts with file state, use verifiable file state as source of truth and correct `.opensuper.yaml` before continuing.
+
+### Preset Upgrade Criteria
+
+**hotfix → full** (upgrade if any condition met):
+- Change involves **3+ files**
+- Architecture changes (new modules, new interfaces, new dependencies)
+- Database schema changes
+- Fix introduces new public API
+- Fix scope exceeds a single function/module
+
+**tweak → full** (upgrade if any condition met):
+- Change involves **5+ files**
+- Cross-module coordination required
+- **5+** new test cases needed
+- Config item additions or deletions (not value changes)
+
+### Error Handling Quick Reference
+
+| Scenario | Handling |
+|----------|----------|
+| `openspec list --json` fails | Check if openspec is installed, prompt user to run `openspec init` |
+| Sub-skill unavailable | Stop workflow, prompt to install or enable the corresponding skill |
+| `.opensuper.yaml` malformed or missing | Use file state as source of truth, correct with `bash $OPENSUPER_STATE set` then continue |
+| Build/test fails | Return to build phase for fixes, do not enter verify |
+| Incomplete change directory structure | Fill missing files according to `opensuper-open` artifact requirements |
+
+### Phase Transitions
+
+<IMPORTANT>
+A single `/opensuper` invocation starts from the detected phase and advances to the next phase when exit conditions are met.
+
+Flow chain: open → design → build → verify → archive
+
+**Continuous execution requirement**: starting from the detected phase, the agent must automatically continue through all later phases without waiting for another user command, except at explicit decision points. After a phase completes, immediately enter the next phase.
+
+Nodes requiring user participation:
+1. Confirm design approach during brainstorming
+2. Select execution mode during build phase
+3. Decide to fix or accept deviation when verify fails
+4. Choose branch handling method for finishing-branch
+5. Encounter upgrade conditions (hotfix/tweak → full workflow)
+
+Agents should not skip these decision points; other unambiguous phase transitions can proceed automatically.
+</IMPORTANT>
+
+---
+
+## Subcommand Quick Reference
+
+| Command | Phase | Owner | Artifacts |
+|---------|-------|-------|-----------|
+| `/opensuper-open` | 1. Open | OpenSpec | proposal.md, design.md, tasks.md |
+| `/opensuper-design` | 2. Deep Design | Superpowers | Design Doc, delta spec |
+| `/opensuper-build` | 3. Plan and Build | Superpowers | Implementation plan, code commits |
+| `/opensuper-verify` | 4. Verify and Close | Both | Verification report, branch handling |
+| `/opensuper-archive` | 5. Archive | OpenSpec | delta→main spec sync, design doc markup, archive |
+| `/opensuper-hotfix` | Preset path | Both | Quick fix (skip brainstorming) |
+| `/opensuper-tweak` | Preset path | Both | Small change (skip brainstorming and full plan) |
+
+```
+/opensuper
+  ↓ Auto-detect
+/opensuper-open ──→ /opensuper-design ──→ /opensuper-build ──→ /opensuper-verify ──→ /opensuper-archive
+  (OpenSpec)      (Superpowers)     (Superpowers)     (Both)          (OpenSpec)
+
+/opensuper-hotfix (preset, skip brainstorming)
+  open ──→ build ──→ verify ──→ archive
+    ↑ If upgrade triggered → supplement Design Doc → return to full workflow
+
+/opensuper-tweak (preset, skip brainstorming and full plan)
+  open ──→ lightweight build ──→ light verify ──→ archive
+    ↑ If upgrade triggered → supplement Design Doc → return to full workflow
+```
+
+---
+
+## Reference Appendix
+
+### .opensuper.yaml Field Reference
+
+```yaml
+workflow: full
+phase: build
+design_doc: docs/superpowers/specs/YYYY-MM-DD-topic-design.md
+plan: docs/superpowers/plans/YYYY-MM-DD-feature.md
+build_mode: subagent-driven-development
+isolation: branch
+verify_mode: light
+verify_result: pending
+verification_report: null
+branch_status: pending
+verified_at: null
+archived: false
+```
+
+| Field | Meaning |
+|-------|---------|
+| `workflow` | `full`, `hotfix`, or `tweak` |
+| `phase` | Current phase: `open`, `design`, `build`, `verify`, `archive` |
+| `design_doc` | Associated Superpowers Design Doc path, can be empty |
+| `plan` | Associated Superpowers Plan path, can be empty |
+| `build_mode` | Selected execution mode, can be empty |
+| `isolation` | `branch` or `worktree`, workspace isolation method. Full workflow init may leave this as `null`, but only until `/opensuper-build` Step 3; hotfix/tweak default to `branch` |
+| `verify_mode` | `light` or `full`, can be empty |
+| `verify_result` | `pending`, `pass`, or `fail` |
+| `verification_report` | Verification report file path; must point to an existing file before verify can pass |
+| `branch_status` | `pending` or `handled`; set to `handled` after branch handling completes |
+| `verified_at` | Verification pass time, can be empty |
+| `archived` | Whether change is archived |
+
+Optional fields:
+
+| Field | Meaning |
+|-------|---------|
+| `direct_override` | `true`/`false`. Full workflow may use `build_mode: direct` only when this is explicitly `true` |
+| `build_command` | Project build command. Guard runs this first and prints failure output |
+| `verify_command` | Project verification command. Verify guard runs this first; if absent, it falls back to the build command |
+
+State-machine hard constraints:
+- Before `build → verify`, `isolation` must be `branch` or `worktree`
+- Before `build → verify`, `build_mode` must be selected
+- `build_mode: direct` is allowed by default only for `hotfix` / `tweak`; full workflow requires `direct_override: true`
+- These constraints are enforced by both `opensuper-guard.sh build --apply` and `opensuper-state.sh transition <name> build-complete`
+
+### Script Location
+
+OpenSuper scripts are distributed in `opensuper/scripts/`. **Do not hardcode paths** — locate once, cache in env vars:
+
+```bash
+OPENSUPER_SEARCH_ROOTS=("." "$HOME/.claude/skills" "$HOME/.codex/skills" "$HOME/.cursor/skills")
+OPENSUPER_GUARD="${OPENSUPER_GUARD:-$(find "${OPENSUPER_SEARCH_ROOTS[@]}" -path '*/opensuper/scripts/opensuper-guard.sh' -type f -print -quit 2>/dev/null)}"
+OPENSUPER_STATE="${OPENSUPER_STATE:-$(find "${OPENSUPER_SEARCH_ROOTS[@]}" -path '*/opensuper/scripts/opensuper-state.sh' -type f -print -quit 2>/dev/null)}"
+OPENSUPER_ARCHIVE="${OPENSUPER_ARCHIVE:-$(find "${OPENSUPER_SEARCH_ROOTS[@]}" -path '*/opensuper/scripts/opensuper-archive.sh' -type f -print -quit 2>/dev/null)}"
+
+if [ -z "$OPENSUPER_GUARD" ] || [ -z "$OPENSUPER_STATE" ] || [ -z "$OPENSUPER_ARCHIVE" ]; then
+  echo "ERROR: OpenSuper scripts not found. Ensure the opensuper skill is installed." >&2
+  echo "Expected path pattern: */opensuper/scripts/opensuper-*.sh under project or platform skill directories" >&2
+  return 1
+fi
+```
+
+**Auto state update**: Guard supports `--apply` flag, automatically updating `.opensuper.yaml` state fields after checks pass:
+
+```bash
+bash "$OPENSUPER_GUARD" <change-name> <phase> --apply
+```
+
+`--apply` delegates to `opensuper-state transition`. Use these semantic events when state changes need to be expressed directly:
+
+```bash
+bash "$OPENSUPER_STATE" transition <change-name> open-complete
+bash "$OPENSUPER_STATE" transition <change-name> design-complete
+bash "$OPENSUPER_STATE" transition <change-name> build-complete
+bash "$OPENSUPER_STATE" transition <change-name> verify-pass
+bash "$OPENSUPER_STATE" transition <change-name> verify-fail
+bash "$OPENSUPER_STATE" transition <archive-name> archived
+```
+
+**Archive script**: Complete all archive steps in one command:
+
+```bash
+bash "$OPENSUPER_ARCHIVE" <change-name>
+```
+
+After loading opensuper, agents should run the three variable assignments above once, then reuse `$OPENSUPER_GUARD`, `$OPENSUPER_STATE`, `$OPENSUPER_ARCHIVE` throughout the session.
+
+### File Structure
+
+```
+openspec/                              # OpenSpec — WHAT
+├── config.yaml
+├── changes/
+│   ├── <name>/                        # Active change
+│   │   ├── .openspec.yaml
+│   │   ├── .opensuper.yaml
+│   │   ├── proposal.md                # Why + What
+│   │   ├── design.md                  # High-level architecture decisions
+│   │   ├── specs/<capability>/spec.md # Delta capability spec
+│   │   └── tasks.md                   # Task checklist
+│   └── archive/YYYY-MM-DD-<name>/     # Archived
+└── specs/<capability>/spec.md         # Main specs (overwritten from delta at archive)
+
+docs/superpowers/                      # Superpowers — HOW
+├── specs/YYYY-MM-DD-<topic>-design.md # Design doc (technical RFC, mark status at archive)
+└── plans/YYYY-MM-DD-<feature>.md      # Implementation plan (file header contains change association metadata)
+```
+
+### Best Practices
+
+1. **brainstorming cannot be skipped** — Every change must undergo deep design (except hotfix and tweak)
+2. **delta spec is a living document** — Freely modify during phase 3, sync at archive
+3. **Keep tasks.md in sync** — Check off each completed task
+4. **Commit frequently** — One commit per task, message reflects design intent
+5. **Verify before archive** — Execute `/opensuper-archive` only after `/opensuper-verify` passes
+6. **Classify incremental updates** — Small edits, medium brainstorming, large new changes
+7. **Plan must associate with change** — File header contains `change:` and `design-doc:` metadata
+8. **Archive closure** — design doc and plan must mark `archived-with` status
+9. **Modifying existing features** — Just open a new change
+10. **Preset has limits** — Switch to full workflow promptly when hotfix/tweak meet upgrade conditions