Pandoscope

Agentic engineering instrument: high-level commands that let any AI agent run a Pandoscope-powered project as a self-improving software factory. It stamps templates, installs skills, orchestrates build, review, and memory, and hardens itself by turning every failure into a regression test.

Install

Every surface delivers the same Python implementation at the same version (see docs/releasing.md):

uvx pandoscope --help   # Python (uv)
npx pandoscope --help   # Node — a launcher shim that bootstraps uv

Agent-native: install the repository as a Claude Code plugin to get the pandoscope-stamp skill:

/plugin marketplace add pandoscope/pandoscope
/plugin install pandoscope@pandoscope

Commands

pandoscope stamp [DIRECTORY]

Render the agentic-engineering-template scaffold into a project directory (wraps copier copy).

pandoscope stamp my-project \
  -d agentic_project_name="My Project" \
  -d agentic_repo_owner=me \
  --defaults

pandoscope compose

Compose the session-time reinset from a SessionStart hook (skills#179, skills#195, waybill#1). The composer detects the harness facts. It reads the waybill order. It writes the answers file at $REINSET_ANSWERS (default ~/.claude/reinset/<session_id>.yml). It renders ~/.claude/CLAUDE.md from the role's profile. The package ships profiles under src/pandoscope/reinset/profiles/. The composer prefers a same-named file under meta/reinset/profiles/ in the session root; that file replaces the shipped one whole.

The order is the only receiver. The Routine fires when a pull request opens on the waybill repository from a branch order/<name>. The harness sets CCR_TRIGGER_REPO and CCR_TRIGGER_HEAD_REF in the environment. It also checks out the pull request head. The checkout puts waybill/orders/<name>.yml on disk. That file names the role, the pull request under work and the tickets, and for a reviewer the pass and model tier. The composer reads that file and sets the role. For a reviewer it appends the review task to CLAUDE.md. The task is the whole of skills/original/thread-ledger/review/<pass>.md. The composer renders it as a Jinja template from the order and the pull request's clone. An undefined variable is a composer error. Before rendering, the composer switches that clone to the review branch claude/review-<pass>-<model_tier>-pr<n> at the pull request head. It renders findings.schema.json, beside the pass file, as the variable findings_contract. A pass file that uses the variable candidates gets the hits of the prose check on the lines the pull request adds, or none. The prose check is skills/original/writing-prose/check.sh. The composer runs the check. The reviewer never runs it. Without an order the composer sets the role general and renders the loud UNCONFIGURED state. The Routine's saved prompt is one orientation sentence. Every Routine saves the same sentence. It tells the model that the hooks composed its role and task into CLAUDE.md. Never run the composer from a model turn: the hook is the caller.

The composer installs the role's bundle. It copies each skill that the profile names into ~/.claude/skills. It looks in meta/reinset/skills/<name> first, then in the skills clone's original/ and derived/, then in a clone's vendored .agents/skills/<name>. Each copy carries a marker file. The next pass replaces a marked copy whole. The composer refuses a directory without the marker. It removes marked skills that the role no longer names. It then renders the profile's hooks to $REINSET_HOOKS (default ~/.claude/reinset/hooks.json). The CLI captures hook registration at startup, so the environment registers one dispatcher per event. The dispatcher reads this file at every fire.

The composer writes the following keys to the answers file: detected (harness facts), resolved (harness, environment, role, principal, model), order (path, role, pass, model tier, pull request number, tickets; null without an order), errors, installed (the skills the role's bundle copied) and hooks (the hooks rendered to $REINSET_HOOKS).

The composer validates the order against a strict schema (src/pandoscope/reinset/schemas/order.json). The schema rejects unknown keys. It requires role. It requires id to equal the file name. It takes pull_request as owner/repo#n. It takes tickets as a list of the same form. It takes checkouts as a map from owner/repo to a ref. For a reviewer it also requires pass and model_tier, both lowercase. When the order does not validate against the schema, the composer reports an error that names every violated field. The session therefore never runs on a half-read order.

SESSION_ROOT=/home/user pandoscope compose

pandoscope order check FILE...

Validate waybill order files against the schema that the composer uses. The command prints every violation with its field. It exits 1 when any file fails. Waybill's pull request checks run it. A broken order therefore turns red before anyone fires on it.

More commands land as the tool grows.

Glossary

Ubiquitous language lives in docs/glossary/, one file per term. Resolve a term and its transitive dependencies with uvx disambiguate <term>.

• The instrument: Pandoscope
• The actors: Principal, Pando, Pando cell, Org, Reinset
• Building blocks: Pandoscope template, Org genome, Template stamp, Agent session
• Memory: Memory repo, Decision-memory, Session-memory, Evidence-memory, Decision record, Preference set, Record contract
• Decisions: Grilling