Ultimate Framework

Ultimate is a local control plane for agentic software work. It combines the cloned framework repositories into one routing layer with phases, agents, artifacts, gates, and validation.

The runtime is intentionally thin: it validates the framework scaffold, explains which phase/agents/artifacts apply, and generates task packets. It does not automatically execute gstack, GSD, Ruflo, Huashu, Matt Pocock, or Superpowers commands.

Requirements

• Node.js 18+ for the npx launcher.
• Python 3.11+ for the runtime.
• Python dependencies:

python3 -m pip install pydantic pydantic-settings PyYAML

The npm launcher can check and install those runtime dependencies:

npx ultimate-framework doctor
npx ultimate-framework setup-python

For development checks:

python3 -m pip install pytest ruff mypy

Install Into A Project

From a published npm package:

npx ultimate-framework init --agent both

From this local checkout:

npx /Users/juresunic/Documents/Claude/Projects/ultimate-framework init --agent both

What init does:

• Copies the ultimate/ scaffold into the current project.
• Installs Claude slash command prompts into .claude/commands/ultimate/.
• Installs Codex slash command prompts into .codex/commands/ultimate/.
• Leaves existing files unchanged unless --force is provided.

The npx launcher sets ULTIMATE_SOURCE_ROOT to the installed package directory. That lets the runtime validate source framework references even when the target project only contains the copied ultimate/ scaffold.

The npm package intentionally includes the referenced source-framework folders so routes and validation keep provenance. The dry-run package is currently about 36 MB compressed.

Planning-with-files is included as source provenance: README, skill, templates, helper scripts, install/workflow docs, Codex hooks, and Claude plugin metadata are packaged so Ultimate routes can point to the real contracts. ultimate-framework init does not install or merge those hooks into target projects. Install planning-with-files separately when you want its lifecycle automation.

Superpowers is included as source provenance: bootstrap skill, core skills, harness plugin manifests, hooks, docs, tests, scripts, and assets are packaged so Ultimate can route to the actual planning, TDD, debugging, worktree, review, and finish-the-branch contracts. ultimate-framework init does not install Superpowers or activate its hooks; install Superpowers separately in the target harness when you want automatic skill triggering.

Options:

npx ultimate-framework init --agent claude
npx ultimate-framework init --agent codex
npx ultimate-framework init --agent none
npx ultimate-framework init --target /path/to/project --agent both
npx ultimate-framework init --agent both --force

Use The CLI

Run these commands from a project that contains ultimate/.

npx ultimate-framework validate
npx ultimate-framework status
npx ultimate-framework phase 5
npx ultimate-framework route ultimate:review-plan
npx ultimate-framework task-packet 5

If a runtime command reports missing Python dependencies, run:

npx ultimate-framework setup-python

Local checkout equivalents:

python3 -m ultimate_runtime validate
python3 -m ultimate_runtime status
python3 -m ultimate_runtime phase 5
python3 -m ultimate_runtime route ultimate:review-plan
python3 -m ultimate_runtime task-packet 5

When using the Python runtime directly from a different project, set ULTIMATE_SOURCE_ROOT to the checkout that contains the cloned source framework repositories:

ULTIMATE_SOURCE_ROOT=/Users/juresunic/Documents/Claude/Projects/ultimate-framework \
  python3 -m ultimate_runtime validate

The compatibility wrapper still works:

bash ultimate/scripts/validate-framework-doc.sh
bash ultimate/scripts/validate-framework-doc.sh status

Slash Commands

After init --agent both, use these command prompts in clients that read project slash command files.

Claude command files:

.claude/commands/ultimate/office-hours.md
.claude/commands/ultimate/plan.md
.claude/commands/ultimate/execute.md
.claude/commands/ultimate/review.md
.claude/commands/ultimate/ship.md
.claude/commands/ultimate/learn.md

Codex command files:

.codex/commands/ultimate/office-hours.md
.codex/commands/ultimate/plan.md
.codex/commands/ultimate/execute.md
.codex/commands/ultimate/review.md
.codex/commands/ultimate/ship.md
.codex/commands/ultimate/learn.md

The slash command prompts are deliberately small. Each command asks the agent to run npx ultimate-framework route ... and npx ultimate-framework task-packet ..., then follow the generated contract.

If a client does not support project slash command files, paste the relevant command prompt into the chat or run the CLI commands directly.

Core Workflow

Use the framework by moving through phases only as far as the work requires.

1. Bootstrap / Resume: npx ultimate-framework task-packet 0
2. Office Hours / Discovery: npx ultimate-framework task-packet 1
3. Research / Context Map: npx ultimate-framework task-packet 2
4. Spec / Product / Design: npx ultimate-framework task-packet 3
5. Grill Gate: npx ultimate-framework task-packet 4
6. Plan / Review Convergence: npx ultimate-framework task-packet 5
7. Execution: npx ultimate-framework task-packet 6
8. Review / Security / QA: npx ultimate-framework task-packet 7
9. Ship / Deploy / Canary: npx ultimate-framework task-packet 8
10. Retro / Learn: npx ultimate-framework task-packet 9

For a small task, you can skip expensive phases when the packet skip rule allows it. For non-trivial work, always use discovery/spec, grill, plan review, execution evidence, and verification.

Common Situations

New Feature

npx ultimate-framework route ultimate:office-hours
npx ultimate-framework task-packet 1
npx ultimate-framework route ultimate:plan
npx ultimate-framework task-packet 5
npx ultimate-framework route ultimate:execute
npx ultimate-framework task-packet 6
npx ultimate-framework route ultimate:qa
npx ultimate-framework task-packet 7

Use office hours to clarify the wedge and success criteria, then plan, execute with TDD, and QA user-visible flows.

Bug Fix

npx ultimate-framework route ultimate:diagnose
npx ultimate-framework route ultimate:execute
npx ultimate-framework task-packet 6
npx ultimate-framework route ultimate:verify

Create or identify the failing test first, fix narrowly, and record regression evidence.

UI Or Design Work

npx ultimate-framework route ultimate:design
npx ultimate-framework task-packet 3
npx ultimate-framework route ultimate:qa
npx ultimate-framework task-packet 7

Use Huashu for asset-first design and GSD/UI review for the contract. Browser or visual QA is required for user-visible UI.

AI / LLM Work

npx ultimate-framework task-packet 3
npx ultimate-framework route ultimate:security
npx ultimate-framework route ultimate:perf
npx ultimate-framework task-packet 7

Document prompts, fallback behavior, eval strategy, token/cost expectations, and safety checks before implementation.

Release

npx ultimate-framework route ultimate:ship
npx ultimate-framework task-packet 8
npx ultimate-framework route ultimate:deploy
npx ultimate-framework route ultimate:canary
npx ultimate-framework route ultimate:benchmark
npx ultimate-framework route ultimate:retro

Release work is not done until docs/changelog, PR body, deploy evidence, canary status, rollback criteria, and lessons are clear or explicitly out of scope.

Command Map

Important command routes:

ultimate:bootstrap
ultimate:office-hours
ultimate:research
ultimate:spec
ultimate:design
ultimate:grill
ultimate:plan
ultimate:review-plan
ultimate:autoplan
ultimate:execute
ultimate:diagnose
ultimate:code-review
ultimate:verify
ultimate:qa
ultimate:devex
ultimate:security
ultimate:cso
ultimate:perf
ultimate:benchmark
ultimate:guard
ultimate:ship
ultimate:deploy
ultimate:canary
ultimate:learn
ultimate:retro
ultimate:validate-framework

Inspect any command:

npx ultimate-framework route ultimate:review-plan

Development

Validate the current checkout:

python3 -m ruff check .
python3 -m ruff format --check .
python3 -m mypy ultimate_runtime
python3 -m pytest
python3 -m ultimate_runtime validate
node bin/ultimate-framework.js doctor
node bin/ultimate-framework.js status

Publish To Npm

The package name is ultimate-framework.

License metadata is SEE LICENSE IN LICENSE because the package bundles multiple source frameworks with their own licenses. Most bundled components are MIT-licensed; huashu-design/ is personal-use only and requires separate commercial authorization.

Before publishing:

npm whoami
npm pack --dry-run
python3 -m ruff check .
python3 -m ruff format --check .
python3 -m mypy ultimate_runtime
python3 -m pytest
python3 -m ultimate_runtime validate
node bin/ultimate-framework.js doctor
node bin/ultimate-framework.js status

Publish:

npm publish --access public

After publish, test from a clean directory:

mkdir /tmp/ultimate-framework-smoke
cd /tmp/ultimate-framework-smoke
npx ultimate-framework doctor
npx ultimate-framework init --agent both
npx ultimate-framework validate
npx ultimate-framework route ultimate:review-plan