Prism

Turn ambiguous software-change requests into durable, reviewable delivery.

Prism stores requirements, design, dependencies, approval, implementation, and
verification state in Beads. It ships as
three independent plugins, listed in their intended priority order.

Plugins

The plugins share Beads state but have separate manifests, skill inventories,
marketplace entries, and runtime ownership. Installing one does not implicitly
install either of the others.

1. Prism host

The primary prism plugin owns the type-aware router, the full Story lifecycle,
and the Epic lifecycle. It never selects Prism Light or Callee implicitly.

An explicit request to process all open Prism epics snapshots them once, orders
them by priority, creation time, and ID, advances each sequentially, and reports
every outcome.

2. Prism Callee

prism-callee runs Story or Epic work through the canonical
prism/* Callee agent pack. Specialized Role, Script,
Human, Sequential, Loop, and Router agents own phase-specific work.

Invoke the plugin with an ordinary request:

$prism-callee:lifecycle Add CSV export to the report page.

The host resolves Beads state and builds the internal route envelope before
calling Callee; users do not construct that protocol manually.
Before execution, the default Callee catalog must contain prism/lifecycle as
a Router plus the prism/story and prism/epic imported roots.

3. Prism Light

prism-light owns the concise host-only Story workflow. Its canonical skill is
named lifecycle; the flat alias remains prism-light.

Light is always explicit and is never selected by the primary Prism router.

Story lifecycle

flowchart TB
    I["Change intent"] --> S["Specify"]
    S --> G{"Ready for design?"}
    G -->|clarify| Q["Human clarification"]
    Q --> S
    G -->|ready| D["Design"]
    D --> B["Breakdown"]
    B --> H{"Human approval"}
    H -->|approved| A["Apply and review"]
    H -->|refine| D
    A --> V{"Verify"}
    V -->|pass| C["Verified change"]
    V -->|gap| S
    DB[("Beads state")]
    DB -.-> S
    DB -.-> D
    DB -.-> B
    DB -.-> H
    DB -.-> A
    DB -.-> V

Story phases are:

1. phase:story:specify
2. phase:story:design
3. phase:story:breakdown
4. phase:story:human
5. phase:story:apply
6. phase:story:verify

Epic lifecycle

flowchart TB
    I["Multi-Story initiative"] --> F["Frame"]
    F --> A["Architecture"]
    A --> R["Roadmap"]
    R --> P{"Epic approval"}
    P -->|approved| D["Deliver ready Stories sequentially"]
    P -->|refine architecture| A
    D --> V{"Validate integration and Epic outcomes"}
    V -->|pass| C["Closed Epic"]
    V -->|open child race| D
    V -->|roadmap gap| R
    V -->|architecture gap| A
    V -->|requirements gap| F
    DB[("Beads state")]
    DB -.-> F
    DB -.-> A
    DB -.-> R
    DB -.-> P
    DB -.-> D
    DB -.-> V

Epic phases are:

1. phase:epic:frame
2. phase:epic:architecture
3. phase:epic:roadmap
4. phase:epic:approval
5. phase:epic:delivery
6. phase:epic:validation

Prism evaluates Story and Epic child graphs qualitatively: coverage, cohesion,
reviewability, verification, and necessary acyclic dependencies matter. There
is no fixed child-count range. Epic children are Stories; Story children are
Tasks. Nested Epics and direct Epic Tasks are invalid.

The full host plugin presents Design summary → Task summary → Approval request
for Stories and Architecture summary → Story roadmap → Approval request for
Epics. It shows acceptance criteria only when the operator explicitly requests
the current item's criteria. Prism Light retains its concise approval contract.
Every Apply transition still requires explicit human authorization.

Quick start

Each public plugin accepts an ordinary request:

$prism:lifecycle Add CSV export to the report page.
$prism-callee:lifecycle Add CSV export to the report page.
$prism-light:lifecycle Add CSV export to the report page.

Run only the entrypoint for the workflow you installed and want to use.

Requirements

All three plugins require:

• bd (Beads)
• a supported host

Prism Callee additionally requires:

• callee 0.19.0 or a compatible Router-capable release
• the prism/* agent pack

Installation

Install plugins individually in priority order according to the workflows you
want to expose.

Codex

codex plugin marketplace add baldaworks/prism
codex plugin add prism@prism
codex plugin add prism-callee@prism
codex plugin add prism-light@prism

To refresh an existing Git marketplace snapshot, run
codex plugin marketplace upgrade prism, then repeat codex plugin add for
the plugins you use. Start a new thread after a plugin reinstall.

Claude Code

claude plugin marketplace add baldaworks/prism
claude plugin install prism@prism --scope user
claude plugin install prism-callee@prism --scope user
claude plugin install prism-light@prism --scope user

Grok Build

grok plugin install 'baldaworks/prism#plugins/prism' --trust
grok plugin install 'baldaworks/prism#plugins/prism-callee' --trust
grok plugin install 'baldaworks/prism#plugins/prism-light' --trust

GitHub Copilot CLI

copilot plugin marketplace add baldaworks/prism
copilot plugin install prism@prism
copilot plugin install prism-callee@prism
copilot plugin install prism-light@prism

Cursor

agent plugin marketplace add https://github.com/baldaworks/prism.git

Install prism, prism-callee, and prism-light independently from the
marketplace UI.

OpenCode and compatible flat-skill hosts

mkdir -p .opencode/skills
cp -a plugins/prism/prefixed-skills/prism-lifecycle .opencode/skills/
cp -a plugins/prism/prefixed-skills/prism-story .opencode/skills/
cp -a plugins/prism/prefixed-skills/prism-epic .opencode/skills/
cp -a plugins/prism-callee/prefixed-skills/prism-callee-lifecycle .opencode/skills/
cp -a plugins/prism-light/prefixed-skills/prism-light .opencode/skills/

To also expose the explicit slash invocations (/prism-lifecycle,
/prism-story, /prism-epic, /prism-callee-lifecycle, /prism-light) as
OpenCode commands, install the matching command files:

mkdir -p .opencode/commands
cp plugins/prism/prefixed-commands/prism-lifecycle.md .opencode/commands/
cp plugins/prism/prefixed-commands/prism-story.md .opencode/commands/
cp plugins/prism/prefixed-commands/prism-epic.md .opencode/commands/
cp plugins/prism-callee/prefixed-commands/prism-callee-lifecycle.md .opencode/commands/
cp plugins/prism-light/prefixed-commands/prism-light.md .opencode/commands/

Commands are optional thin wrappers: OpenCode loads skills on demand through its
skill tool, and each command only directs the agent to the matching skill while
forwarding your request.

Agent Plugins 1.0.0

Each plugin directory is also an Agent Plugins 1.0.0 package root:

Point an Agent Plugins-compatible client at the package root for the workflow
you want to expose. The standard defines package discovery, not installation,
marketplaces, or invocation syntax; use the selected client's own workflow for
those operations. Portable clients discover the canonical immediate-child
skills under each package's skills/ directory.

Install or update the Callee agents

This step is required only for prism-callee and direct Callee execution:

Initial import:

callee agent import baldaworks/prism \
  --path pack/callee/prism \
  --prefix prism

Update or repair an existing import:

callee agent import baldaworks/prism \
  --path pack/callee/prism \
  --prefix prism \
  --force

Validate the default catalog:

callee agent list | grep '^prism/'
callee agent view prism/lifecycle --json
callee agent view prism/story --json
callee agent view prism/epic --json
bd where

The lifecycle view must report kind Router. A Sequential lifecycle or a
missing Story/Epic root means the local import is stale; rerun the --force
command before using Prism Callee. --agent-root pack/callee is for repository
maintenance only and is not a runtime workaround.

Repository ownership

Canonical and flat host paths are behavioral mirrors:

• plugins/prism/skills/{lifecycle,story,epic} ↔ corresponding
  plugins/prism/prefixed-skills/prism-* trees
• plugins/prism-callee/skills/lifecycle ↔
  plugins/prism-callee/prefixed-skills/prism-callee-lifecycle
• plugins/prism-light/skills/lifecycle ↔
  plugins/prism-light/prefixed-skills/prism-light

Each OpenCode command in plugins/*/prefixed-commands/ is a thin wrapper whose
name matches the flat skill it loads (see the install steps above).

Validation

./scripts/validate-plugin-packaging.sh
./scripts/validate-lifecycle-ownership.sh
./scripts/validate-documentation.sh
./scripts/test-lifecycle-drift-detection.sh
./scripts/test-documentation-drift-detection.sh
./scripts/test-lifecycle-forward-contracts.sh
./scripts/test-callee-lifecycle-forward-contracts.sh

For repeatable PTY-backed Callee Human smoke tests:

./scripts/smoke-test-callee-human.sh questions
./scripts/smoke-test-callee-human.sh specify

Maintainer docs

• docs/architecture-spec.md — repository architecture specification
• docs/architecture-host-lifecycle.md — primary host router
• docs/architecture-story-lifecycle.md — full Story behavior
• docs/architecture-epic-lifecycle.md — Epic behavior
• docs/architecture-callee-lifecycle.md — Callee integration
• docs/architecture-light-lifecycle.md — Prism Light behavior
• docs/callee-lifecycle-smoke-test.md — PTY-backed Callee Human smoke tests
• docs/lifecycle-ownership.json — machine-checked ownership and integrity

Authority

• Only explicit human intent authorizes Apply.
• Prism never invents approval.
• Repository tasks are committed after successful verification; pushing and
  publishing require explicit human authority.

License

MIT — see LICENSE.