Orpheum

orpheum is a scenario catalog and Rust CLI for applying reusable AI-assisted SDLC workflows to real projects.

This repository now has two closely related responsibilities:

• maintain the canonical catalog of scenarios, roles, workflows, artifacts, and checks
• provide the orpheum CLI that resolves that catalog into lightweight project-local orchestration state under .orpheum/

The goal is not to build a heavyweight autonomous orchestrator. The goal is to make AI-assisted delivery more repeatable: explicit scenario selection, explicit artifact expectations, explicit checks, and a small, machine-readable control surface that an agent can use inside an ordinary project repo.

What Orpheum Is

At a high level, Orpheum has three layers:

1. Catalog layer: this repository contains the reusable SDLC building blocks.
2. Session layer: the CLI applies a selected scenario into a target project and creates a local .orpheum/ control directory.
3. Project output layer: durable deliverables live in the target project, not in Orpheum.

In practice, that means:

• humans and agents can inspect available scenarios with the CLI
• a scenario can be applied to a project without copying the whole catalog into it
• prompts, state, and checks are derived from machine-readable metadata rather than prose scraping

Current CLI Surface

The Rust workspace lives at the repo root and currently ships these v1 commands:

• orpheum init
• orpheum scenario list
• orpheum scenario show <id>
• orpheum scenario apply <id>
• orpheum status
• orpheum prompt current
• orpheum check run
• orpheum doctor

All implemented commands support --json.

The CLI is intentionally metadata-first. It resolves scenarios from YAML frontmatter embedded in catalog Markdown files under:

• scenarios
• roles
• workflows
• artifacts
• checks

Catalog-dependent commands can locate the catalog in three ways:

• --catalog <path>
• ORPHEUM_CATALOG=<path>
• runtime discovery from the current working directory or executable location when you are working from the Orpheum repo itself

Commands like init, status, and prompt current are project-local and do not require catalog loading.

If you are wiring Orpheum into a local agent workflow, use the dedicated consumer guide:

• docs/agent-usage.md

Quick Start

Build and run the CLI from this repository:

cargo run -p orpheum -- scenario list

Initialize a consumer project for local agents:

cargo run -p orpheum -- init

Inspect a scenario:

cargo run -p orpheum -- scenario show project-planning

Apply a scenario to a target project:

cargo run -p orpheum -- scenario apply project-planning --project /path/to/project

After applying a scenario, the target project gets a small .orpheum/ control surface:

• .orpheum/ACTIVE.md
• .orpheum/session.json
• .orpheum/scenario.json
• .orpheum/state.json
• .orpheum/prompts/current.md
• .orpheum/logs/checks.json

From the target project root, you can then run:

orpheum init

orpheum status

orpheum prompt current

orpheum check run

orpheum doctor

orpheum init installs or refreshes a project-local skill at .codex/skills/orpheum/SKILL.md so local agents have an explicit Orpheum usage contract. If a .gitignore already exists, init also adds .orpheum/ when that entry is missing.

Default SDLC Scenario Chain

The current standard path through the catalog is:

1. Project Discovery
2. Project Planning
3. Delivery Slice Planning
4. Implementation and Release Prep
5. Review Remediation Loop when bounded remediation is needed
6. Verification And Release Gate when a distinct final downstream gate is needed
7. Release Feedback To Reprioritization

For security-sensitive or approval-sensitive work, use Secure Delivery / Secure Feature Lifecycle instead of the standard chain when those concerns need to shape the work end to end.

For designing and hardening scenarios themselves, see Scenario Implementation.

Repository Structure

• crates/orpheum-cli contains the orpheum binary and command-line interface.
• crates/orpheum-core contains catalog loading, dependency resolution, session management, prompt generation, checks, and doctor logic.
• scenarios contains reusable multi-role SDLC scenarios.
• roles contains reusable role packages.
• workflows contains reusable role-owned workflow definitions.
• artifacts contains reusable artifact definitions and templates.
• checks contains validation patterns used by roles and scenarios.
• notes contains design notes, sourcing notes, and other durable working context.
• skills contains vendored or locally maintained skills used by the catalog.

Metadata Contract

The CLI does not infer dependencies from prose at runtime.

Instead, the canonical catalog files carry YAML frontmatter that provides the machine-readable contract for:

• scenario dependencies
• workflow inputs and outputs
• role default workflows and skills
• artifact output paths and attached checks
• check execution mode and target artifacts

That frontmatter is the integration contract the CLI relies on. The surrounding Markdown remains the human-facing explanation.

Validation Model

The v1 check engine is intentionally narrow. It currently supports:

• artifact presence checks
• required heading checks

orpheum check run records results in .orpheum/logs/checks.json and mirrors summarized status back into .orpheum/state.json.

Product Specification Convention

When this repository defines product behavior, it should prefer Allium over ad hoc prose requirements unless there is a clear reason not to.

That preference still applies even though Orpheum now has a working CLI. The catalog should continue to optimize for reusable structure, explicit reasoning, and durable operating conventions.

Development Notes

• Workspace root: Cargo.toml
• Binary crate: crates/orpheum-cli/Cargo.toml
• Core crate: crates/orpheum-core/Cargo.toml
• CLI integration tests: crates/orpheum-cli/tests/cli.rs

Useful commands:

cargo fmt

cargo test

cargo run -p orpheum -- doctor --json

orpheum doctor will report catalog or project-health issues, including whether .orpheum/ is ignored in the target project.