Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 11 additions & 10 deletions .codex-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,26 +1,27 @@
{
"name": "gpt56-superpowers",
"version": "0.7.0",
"description": "A dependency-aware development suite with eleven Skills, an optional controller-led delivery workflow, global purpose-bound rigor, and an on-demand audit agent.",
"name": "agentic-superpowers",
"version": "0.8.0",
"description": "A dependency-aware development suite with eleven Skills, an optional controller-led workflow, agent-owned PR delivery, review-gated merge, global purpose-bound rigor, and an on-demand audit agent.",
"author": {
"name": "Wonderbell",
"url": "https://github.com/bells0"
},
"homepage": "https://github.com/bells0/gpt56-superpowers#readme",
"repository": "https://github.com/bells0/gpt56-superpowers",
"homepage": "https://github.com/bells0/agentic-superpowers#readme",
"repository": "https://github.com/bells0/agentic-superpowers",
"license": "MIT",
"keywords": [
"gpt-5.6",
"agentic-engineering",
"model-adaptive",
"codex",
"skills",
"development-workflow",
"token-efficiency"
],
"skills": "./skills/",
"interface": {
"displayName": "GPT-5.6 Superpowers",
"shortDescription": "Eleven focused development Skills for GPT-5.6 Sol",
"longDescription": "A Sol-first coordinator, an explicit controller-led delivery workflow, and focused Skills for design, implementation planning, worktree isolation, bounded subagent execution, debugging, verification, purpose-bound rigor, delegation and review, and atomic Git delivery.",
"displayName": "Agentic Superpowers",
"shortDescription": "Eleven model-evolving development Skills",
"longDescription": "A model-neutral accountable coordinator, an explicit controller-led delivery workflow, and focused Skills for design, implementation planning, worktree isolation, bounded subagent execution, debugging, verification, purpose-bound rigor, delegation and review, agent-owned feature-branch and PR delivery, and review-gated merge.",
"developerName": "Wonderbell",
"category": "Developer Tools",
"capabilities": [
Expand All @@ -35,7 +36,7 @@
"Git"
],
"defaultPrompt": [
"Use the smallest matching GPT-5.6 Superpowers Skill for this development task."
"Use the smallest matching Agentic Superpowers Skill for this development task."
]
}
}
2 changes: 1 addition & 1 deletion .codex/agents/execution-efficiency-auditor.toml
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# managed-by: gpt56-superpowers
# managed-by: agentic-superpowers
name = "execution-efficiency-auditor"
description = "Use only when the user asks to audit delivery-process bloat or repeated execution drift needs a focused, read-only correction. Do not invoke as a routine reviewer or universal implementation gate."
sandbox_mode = "read-only"
Expand Down
2 changes: 1 addition & 1 deletion Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ dev-deps:

local-codex-validate:
@$(PYTHON) -c 'import yaml' >/dev/null 2>&1 || { echo "PyYAML is required; run make dev-deps" >&2; exit 1; }
@for skill in skills/gpt56-*; do \
@for skill in skills/agentic-*; do \
$(PYTHON) $(CODEX_HOME)/skills/.system/skill-creator/scripts/quick_validate.py "$$skill" || exit 1; \
done
$(PYTHON) $(CODEX_HOME)/skills/.system/plugin-creator/scripts/validate_plugin.py .
104 changes: 56 additions & 48 deletions README.md

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion THIRD_PARTY_NOTICES.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Third-party notices

GPT-5.6 Superpowers is an original rewrite informed by the workflow concepts and lessons of [obra/superpowers](https://github.com/obra/superpowers). It does not bundle the upstream Skill files.
Agentic Superpowers is an original rewrite informed by the workflow concepts and lessons of [obra/superpowers](https://github.com/obra/superpowers). It does not bundle the upstream Skill files.

The upstream project is licensed under the MIT License:

Expand Down
48 changes: 27 additions & 21 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,24 +2,24 @@

## Goal

Give GPT-5.6 a small set of precise development lenses without re-teaching reliable base-model behavior or forcing every task through one workflow.
Give evolving coding agents a small set of precise development lenses without re-teaching reliable base-model behavior or forcing every task through one workflow.

## Hub and spokes

The suite contains eleven focused Skills:

```text
gpt56-superpowers Sol-led cross-phase coordination
├── gpt56-orchestrate-delivery opt-in standardized delivery lifecycle
├── gpt56-design-planning material ambiguity
├── gpt56-writing-plans implementation-ready plans
├── gpt56-using-git-worktrees justified repository isolation
├── gpt56-subagent-driven-development bounded plan execution
├── gpt56-debugging non-obvious failures
├── gpt56-verification claim-matched evidence
├── gpt56-purpose-bound-rigor necessity for workflow defenses
├── gpt56-delegation-review independent work or judgment
└── gpt56-git-delivery repository delivery state
agentic-superpowers controller-led cross-phase coordination
├── agentic-orchestrate-delivery opt-in standardized delivery lifecycle
├── agentic-design-planning material ambiguity
├── agentic-writing-plans implementation-ready plans
├── agentic-using-git-worktrees justified repository isolation
├── agentic-subagent-driven-development bounded plan execution
├── agentic-debugging non-obvious failures
├── agentic-verification claim-matched evidence
├── agentic-purpose-bound-rigor necessity for workflow defenses
├── agentic-delegation-review independent work or judgment
└── agentic-git-delivery repository delivery state
```

The diagram describes ownership, not a required call chain. Every spoke is a direct entry point. Orchestrated Delivery is the explicit exception for users who want a standardized current-truth → Spec → Plan → Execution → Review → Verification → Acceptance → Closure lifecycle; its narrow trigger prevents that workflow from becoming a tax on ordinary tasks. Design may hand settled requirements to Writing Plans; a suitable plan may hand independently ownable outcomes to Subagent Development; Worktree Isolation is optional; Verification and Git Delivery close only the claims and repository actions that need them.
Expand All @@ -30,7 +30,7 @@ The full repository installer adds the concise `.codex/purpose-bound-rigor.md` f

- Read-only and clear non-repository work: no suite Skill.
- Explicit standardized delivery or long-running multi-module work that needs durable cross-phase control: Orchestrated Delivery.
- Completed repository-changing outcomes: Git & Delivery supplies atomic local commits at verified boundaries.
- Repository-changing outcomes: Git & Delivery makes the Agent own the task branch, atomic commits, branch push, and evidence-bearing PR; independent approval and required checks gate explicitly authorized merge.
- One consequential decision domain: one narrow Skill.
- Two or more dependent phases whose ordering and synthesis affect success: core plus only the one or two narrow Skills that change a decision.
- Proposed hashes, gates, isolation, mocks, freezes, repeated reviews, or broad reruns: Purpose-Bound Rigor requires a concrete protected outcome, observed risk, existing gap, and minimal intervention.
Expand All @@ -50,19 +50,25 @@ Orchestrated Delivery codifies the controller-led method only when the user sele

### Focused ownership

Each spoke owns one decision domain. Trigger overlap is minimized by separating design uncertainty, implementation planning, isolation, bounded execution, causal uncertainty, evidence selection, coordination value, and Git delivery state. Git & Delivery additionally owns suite-wide atomic commit boundaries for repository changes.
Each spoke owns one decision domain. Trigger overlap is minimized by separating design uncertainty, implementation planning, isolation, bounded execution, causal uncertainty, evidence selection, coordination value, and Git delivery state. Git & Delivery additionally owns suite-wide feature-branch and review-gated delivery boundaries for repository changes.

### Stable identity, versioned model profiles

Repository, plugin, and Skill identifiers describe durable agentic-engineering responsibilities rather than a model generation. Model-specific prompting inputs, assumptions, and evaluation status live in [model profiles](model-profiles.md). A future model update changes a profile and the affected contracts, not every public identifier.

### Grounded implementation plans

Writing Plans distinguishes user-provided facts, repository observations, proposed choices, and unresolved facts. Exact paths, symbols, commands, and current behavior must come from evidence rather than model completion.

### Conditional isolation and subagents

Worktree Isolation activates only for an explicit request or a concrete safety benefit. Subagent Development activates only for implementation-ready plans with independently ownable outcomes; Sol retains shared state, integration decisions, and final evidence.
Worktree Isolation activates only for an explicit request or a concrete safety benefit. Subagent Development activates only for implementation-ready plans with independently ownable outcomes; the controller retains shared state, integration decisions, and final evidence.

### Feature-branch, review-gated delivery

### Atomic completion commits
Before implementation, the Agent automatically creates or selects a task-specific feature branch from a verified baseline, never asks the user to create it, and never works directly on `main` or another default branch. If the default branch has uncommitted user work, the Agent protects and safely migrates it; only unsafe separation requires a question. Each independently acceptable outcome maps to one atomic commit per affected repository after focused evidence passes. The outcome must have one purpose and be independently revertible without leaving dependent history broken. Task-owned paths or hunks are staged explicitly, unrelated user changes remain untouched, and proposed, opted-out, unsafe, incomplete, failed, blocked, or empty work remains uncommitted.

Each independently acceptable outcome maps to one local commit per affected repository after focused evidence passes. The outcome must have one purpose and be independently revertible without leaving dependent history broken; every edit or partial test phase is not a boundary. An approved Plan supplies the commit map, and dependent work starts only after the current boundary is verified and committed. Task-owned paths or hunks are staged explicitly, unrelated user changes remain untouched, and proposed, opted-out, unsafe, incomplete, failed, blocked, or empty work remains uncommitted. Push and other remote authority stay separate.
After focused verification, the Agent automatically commits, pushes, and opens or updates a PR containing scope, implementation, evidence, risks, unresolved items, and dependencies. The change request preauthorizes these mechanical actions, so the Agent does not seek stepwise confirmation. PR creation is not approval, and the implementer cannot approve its own work. Merge requires independent authorized-reviewer or user approval, every required check, and explicit merge authority. Explicit local-only instructions stop before push. Direct default-branch work requires prior user authorization and a recorded reason. After confirmed merge, automatic local and remote cleanup is allowed only with a clean worktree and no unmerged commits or open dependencies.

### Claim-based verification

Expand All @@ -85,13 +91,13 @@ The direct path is the default for local, reversible work. A non-default defense

Delegation is justified by independent deliverables, elapsed-time savings, or fresh judgment that can change a material decision. Review is focused on named risks rather than added as a universal stage.

## Mapping to GPT-5.6 guidance
## Current guidance mapping

| Official guidance | Implementation |
| Current model-profile guidance | Stable implementation |
|---|---|
| State outcomes and stop rules | Six-part core contract and completion conditions |
| Remove repeated process instructions | Nine focused bodies loaded only at matching boundaries; no mandatory chain |
| Define autonomy and permissions | Verified local outcomes receive atomic commits; remote and destructive authority stay separate |
| Define autonomy and permissions | Agent-owned branch, commit, push, and PR mechanics; independent approval, explicit merge authority, and safe cleanup |
| Route tools by dependency | Parallel independent work; sequential dependencies; synthesis before claims |
| Validate what matters | Claim-to-evidence selection and explicit gaps |
| Keep progress sparse | Outcome-first reporting and phase-level updates |
Expand All @@ -109,4 +115,4 @@ Repository validation enforces per-Skill budgets based on each contract's comple
- complete package: at most 5,800 words;
- only declared SDD resources and no mandatory `$skill` call chain.

Version 0.7 keeps the coordinator under 600 words and the complete package under 5,800 words. These are guardrails, not targets; normal routing loads only the matching bodies and any explicitly needed resource.
Version 0.8 keeps the coordinator under 600 words and the complete package under 5,800 words. These are guardrails, not targets; normal routing loads only the matching bodies and any explicitly needed resource.
14 changes: 7 additions & 7 deletions docs/evaluation.md
Original file line number Diff line number Diff line change
@@ -1,19 +1,19 @@
# Evaluation

The checked-in scenario matrix tests routing intent and package invariants. It is not a claim that a live GPT-5.6 benchmark occurred.
The checked-in scenario matrix tests routing intent and package invariants. It is not a claim that a live benchmark occurred for the current or any future [model profile](model-profiles.md).

## Fourteen representative scenarios

| Scenario | Expected route | Decisive behavior |
|---|---|---|
| Read-only code explanation | None | Answer from inspected evidence without workflow overhead |
| Clear static edit | Git & Delivery | Direct change, obvious artifact checks, and a scoped local commit |
| Clear static edit | Git & Delivery | Feature-branch change, obvious artifact checks, atomic commit, and review-gated delivery |
| Public API or migration ambiguity | Design & Planning | Choose a tradeoff and define boundaries and acceptance |
| Intermittent cross-component failure and fix | Debugging + Git & Delivery | Find the first divergence, recheck the symptom, and commit the completed fix |
| Material visual or release claim | Verification | Match claim breadth to reliable evidence |
| Unjustified workflow defenses | Purpose-Bound Rigor | Require a concrete protected outcome, observed risk, existing gap, and minimal effective measure |
| Independent investigations or focused security review | Delegation & Review | Parallelize true independence and synthesize findings |
| Authorized branch, commit, push, and pull request | Git & Delivery | Preserve unrelated state and verify delivery results |
| Repository change with remote delivery | Git & Delivery | Agent owns branch, commit, push, and PR mechanics without stepwise approval; independent review, checks, and explicit authority gate merge |
| Cross-module migration with architecture and evidence dependencies | Core + Design + Verification | Coordinate phases without loading the complete suite |
| Explicit no-commit request | Git & Delivery | Verify the change while leaving it uncommitted |
| Settled multi-module requirements | Writing Plans | Separate provided, observed, proposed, and unresolved facts in an implementation-ready plan |
Expand All @@ -25,12 +25,12 @@ The checked-in scenario matrix tests routing intent and package invariants. It i

## Current evidence

- Deterministic validation checks all eleven Skill structures, per-Skill trigger budgets, forbidden forced ritual language, declared workflow resources, dependency-aware routing, and the fourteen-scenario specification.
- Transaction smoke tests exercise fresh and upgrade installs, exact restore semantics, conflicts, injected install and restore failures, version-0.3, version-0.6, and version-1 compatibility, path aliases, locks, spaces, and broken links.
- Deterministic validation checks all eleven Skill structures, per-Skill trigger budgets, forbidden forced ritual language, declared workflow resources, dependency-aware routing, the agent-owned mechanical Git delivery contract, review-gated merge, and the fourteen-scenario specification.
- Transaction smoke tests exercise fresh and upgrade installs, exact restore semantics, conflicts, injected install and restore failures, legacy `gpt56-*` migration, version-0.3, version-0.6, version-0.7, and version-1 compatibility, path aliases, locks, spaces, and broken links.
- A three-case blind forward review on 2026-07-20 covered an implicit simple-change commit, an explicit no-commit request, and a multi-repository completion. All three followed the version-0.3 local-commit contract.
- Three focused forward scenarios on 2026-07-27 covered evidence-grounded implementation plans, dirty-checkout worktree isolation, and Sol-controlled subagent execution. The first Writing Plans pass exposed invented repository details; the revised evidence classification passed the second blind scenario.
- Three focused GPT-5.6 Sol scenarios on 2026-07-27 covered evidence-grounded implementation plans, dirty-checkout worktree isolation, and controller-owned subagent execution. The first Writing Plans pass exposed invented repository details; the revised evidence classification passed the second blind scenario.

The blind review tests semantic separation in the discovery descriptions. It does not exercise Codex's production implicit router and is not a live GPT-5.6 outcome, latency, token, or cost benchmark.
The blind review tests semantic separation in the discovery descriptions. It does not exercise Codex's production implicit router and is not a repository-wide live outcome, latency, token, or cost benchmark.

## Compare effectiveness

Expand Down
Loading
Loading