# superpowers - Doramagic AI Context Pack > Purpose: pre-work context for the user's host AI. This pack does not prove that the project has been installed, run, or validated. ## Project - canonical_name: `obra/superpowers` - capability: An agentic skills framework & software development methodology that works. - expected_user_outcome: An agentic skills framework & software development methodology that works. ## Operating Boundaries - Do not claim that the project has been installed, run, called through an API, or used on local files unless separate evidence proves it. - Project facts must come from repo evidence, Claim Graph, or explicit source references. - When a capability is not verified, mark it as unverified instead of completing it as fact. - publish_status: `publishable` - blocking_gaps: none --- ## Doramagic Context Augmentation The following sections strengthen the repository context for a host AI. Human Manual data is a reading route, and pitfall notes become operating constraints. ## Human Manual Outline Usage rule: this is only a reading route and salience signal, not factual authority. Concrete claims must still return to repo evidence or Claim Graph. Host AI hard rules: - Do not treat page titles, section order, summaries, or importance values as factual project evidence. - When explaining the Human Manual outline, state that it is only a reading route or salience signal. - Capability, installation, compatibility, runtime state, and risk claims must cite repo evidence, source paths, or Claim Graph. - **Overview, Philosophy, and Installation**: importance `high` - source_paths: README.md, AGENTS.md, CLAUDE.md, GEMINI.md, RELEASE-NOTES.md - **Skills Library and Development Methodology**: importance `high` - source_paths: skills/using-superpowers/SKILL.md, skills/test-driven-development/SKILL.md, skills/test-driven-development/testing-anti-patterns.md, skills/systematic-debugging/SKILL.md, skills/systematic-debugging/root-cause-tracing.md - **Brainstorming, Planning, and Subagent-Driven Execution**: importance `high` - source_paths: skills/brainstorming/SKILL.md, skills/brainstorming/visual-companion.md, skills/brainstorming/spec-document-reviewer-prompt.md, skills/brainstorming/scripts/server.cjs, skills/brainstorming/scripts/helper.js - **Harness Runtime, Branch Lifecycle, and Operations**: importance `high` - source_paths: hooks/hooks.json, hooks/hooks-cursor.json, hooks/session-start, hooks/run-hook.cmd, docs/windows/polyglot-hooks.md ## Repo Inspection Evidence - repo_clone_verified: true - repo_inspection_verified: true - repo_commit: `6fd4507659784c351abbd2bc264c7162cfd386dc` - inspected_files: `README.md`, `package.json`, `docs/testing.md`, `docs/README.opencode.md`, `docs/plans/2025-11-22-opencode-support-implementation.md`, `docs/plans/2025-11-22-opencode-support-design.md`, `docs/plans/2026-01-17-visual-brainstorming.md`, `docs/plans/2025-11-28-skills-improvements-from-user-feedback.md`, `docs/windows/polyglot-hooks.md`, `docs/superpowers/plans/2026-01-22-document-review-system.md`, `docs/superpowers/plans/2026-03-23-codex-app-compatibility.md`, `docs/superpowers/plans/2026-02-19-visual-brainstorming-refactor.md`, `docs/superpowers/plans/2026-03-11-zero-dep-brainstorm-server.md`, `docs/superpowers/plans/2026-04-06-worktree-rototill.md`, `docs/superpowers/specs/2026-04-06-worktree-rototill-design.md`, `docs/superpowers/specs/2026-03-23-codex-app-compatibility-design.md`, `docs/superpowers/specs/2026-03-11-zero-dep-brainstorm-server-design.md`, `docs/superpowers/specs/2026-02-19-visual-brainstorming-refactor-design.md`, `docs/superpowers/specs/2026-01-22-document-review-system-design.md` Host AI hard rules: - Without repo_clone_verified=true, do not claim that the source code has been read. - Without repo_inspection_verified=true, do not write README, docs, or package-file conclusions as facts. - Without quick_start_verified=true, do not claim that the Quick Start path has run successfully. ## Doramagic Pitfall Constraints These rules come from Doramagic discovery, validation, or compilation findings. The host AI must treat them as operating constraints, not background notes. ### Constraint 1: Security or permission risk requires verification - Trigger: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - Host AI rule: Reproduce the official install and quickstart path in an isolated environment. - Why it matters: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | cevd_a8794497fd53411881056201b8d6df60 | https://github.com/obra/superpowers/issues/1581 - Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it. ### Constraint 2: Security or permission risk requires verification - Trigger: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - Host AI rule: Reproduce the official install and quickstart path in an isolated environment. - Why it matters: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | cevd_ab70f8b1398247c2832ed51625870194 | https://github.com/obra/superpowers/issues/601 - Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it. ### Constraint 3: Installation risk requires verification - Trigger: Developers should check this installation risk before relying on the project: Antigravity 2.0 support - Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: Antigravity 2.0 support. Context: Observed during installation or first-run setup. - Why it matters: Developers may fail before the first successful local run: Antigravity 2.0 support - Evidence: failure_mode_cluster:github_issue | fmev_3cd7252f6ca5743aa06793d8258fa9c7 | https://github.com/obra/superpowers/issues/1636 - Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it. ### Constraint 4: Installation risk requires verification - Trigger: Developers should check this installation risk before relying on the project: Feature Request: Hermes Agent harness support — make Superpowers skills available in native Hermes format - Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: Feature Request: Hermes Agent harness support — make Superpowers skills available in native Hermes format. Context: Observed when using python - Why it matters: Developers may fail before the first successful local run: Feature Request: Hermes Agent harness support — make Superpowers skills available in native Hermes format - Evidence: failure_mode_cluster:github_issue | fmev_38493ac5020594e127b9094db01ae917 | https://github.com/obra/superpowers/issues/1581 - Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it. ### Constraint 5: Installation risk requires verification - Trigger: Developers should check this installation risk before relying on the project: Pi Agent package - Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: Pi Agent package. Context: Observed during installation or first-run setup. - Why it matters: Developers may fail before the first successful local run: Pi Agent package - Evidence: failure_mode_cluster:github_issue | fmev_81abb08cf2718798d6bf3874d5ab48d6 | https://github.com/obra/superpowers/issues/1685 - Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it. ### Constraint 6: Installation risk requires verification - Trigger: Developers should check this installation risk before relying on the project: v5.0.4 - Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v5.0.4. Context: Observed when using node - Why it matters: Upgrade or migration may change expected behavior: v5.0.4 - Evidence: failure_mode_cluster:github_release | fmev_a66cfa915699950289e6adc9ba6aa7e3 | https://github.com/obra/superpowers/releases/tag/v5.0.4 - Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it. ### Constraint 7: Installation risk requires verification - Trigger: Developers should check this installation risk before relying on the project: v5.0.7 - Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v5.0.7. Context: Observed during installation or first-run setup. - Why it matters: Upgrade or migration may change expected behavior: v5.0.7 - Evidence: failure_mode_cluster:github_release | fmev_c82f72cff463c8cee7702417638522f8 | https://github.com/obra/superpowers/releases/tag/v5.0.7 - Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it. ### Constraint 8: Installation risk requires verification - Trigger: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - Host AI rule: Reproduce the official install and quickstart path in an isolated environment. - Why it matters: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | cevd_92f8a9266fce437abbce3b0e8ae92679 | https://github.com/obra/superpowers/issues/551 - Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it. ### Constraint 9: Installation risk requires verification - Trigger: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - Host AI rule: Reproduce the official install and quickstart path in an isolated environment. - Why it matters: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | cevd_dc7595e0517f44b4b8f034a3891be1ba | https://github.com/obra/superpowers/issues/1685 - Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it. ### Constraint 10: Installation risk requires verification - Trigger: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - Host AI rule: Reproduce the official install and quickstart path in an isolated environment. - Why it matters: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | cevd_1d7f3ffcaf6d457eaa212b6de6361956 | https://github.com/obra/superpowers/issues/1690 - Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.