Alchemy

Alchemy

Command entrypoint for the adaptive A.L.C.H.E.M.Y. gate system. Requirements qualification spans the Minimum gate without adding letters to the acronym. Keep the default response terse: resume from the latest trustworthy decision, route to the smallest useful stage set, state the verdict, and name the next action.

1. Command Grammar

Invoke as /alchemy <alias> <subject> in Claude Code or $alchemy <alias> <subject> in Codex; the alias is optional. Natural language is equivalent: do some alchemy, run alchemy on this, use alchemy, and give this an alchemy pass all request adaptive dispatch on the active subject.

The subject is the invocation arguments. Where commands expand arguments, $ARGUMENTS is that string; if it is empty or literally unexpanded, use the surrounding request text. A natural phrase with no explicit subject uses the active request or most recent unresolved task; never ask the user to restate context already in the conversation or worktree. ?, help, --help, or an empty command with no active subject returns only this table.

left, out, and down form the DevOps improvement triad, outside the seven-gate sequence: run a triad move only when the user names it. During /alchemy Y, recommend out or down when the bottleneck is manual toil or bespoke implementation, but do not run them unless the user asks.

Dispatch Preflight

Classify before reading any sibling skill body. Make dispatch the first observable checkpoint: decide from the request, already-loaded context, skill metadata, and the latest trustworthy decision artifacts; do not scan the repository or open sibling bodies merely to choose a dispatch. After emitting the dispatch, inspect only the artifacts and skills the route selects.

Do not run every gate by default: only explicit full language selects FULL, and Alchemy FULL is a traversal dispatch, not a gate's analysis mode. Do not convert uncertainty into FULL; select the smallest plausible route, state the uncertain signal, and stop at the first missing prerequisite.

Gate and triad aliases are authoritative: use only that core gate or triad move, even when the subject mentions subsystem boundaries, and expand the core route only for explicit full, all, audit, walk the gates, or complete alchemy. Focused aliases never silently run requirements qualification. If a focused gate lacks a prerequisite, report the missing decision artifact and stop at that gate unless the user asked for a broader pass. The prerequisites:

• Gate E remains blocked until Gate 3 records final acceptance; a MOVE, SPLIT, MERGE, or INTRODUCE-BOUNDARY first runs the bounded L candidate → C measurement → L acceptance handshake, re-entering L once.
• Gate E also waits for a passing readiness decision in a full pass.
• Gate Y runs in iteration 2, the iteration after the increment ships, from its stable, measured baseline, unless the request is explicitly about an existing bottleneck.

ADAPTIVE, FULL, and audit read the route in §2 before selecting stages.

Companion Skill Routing

Alchemy owns the core qualification and gate route, not every task domain. From skill metadata and project instructions, select any non-Alchemy skill whose trigger independently matches the subject, and read only the selected companion bodies. A project profile may require companions for its domain, stack, UX, security, accessibility, API, release, or evidence rules; never hard-code project-specific companion names into this generic skill.

• When the subject decides where a fact, decision, or document belongs — a proposed document, a decision record, an architecture note, a status page, or a documentation-tree audit — select zero-copy-requirements. It names the artifact that owns the question; push-out prunes prose already covered by an executable source, and requirements-traceability anchors evidence once the location exists. None of the three is a qualification stage, gate, or acronym letter.
• When an advisory, drift, abandonment, license change, or end-of-life date names an owned dependency, select dependency-lifecycle; it classifies the bump, and only a contract-preserving bump is SKIP.
• When a risk survives verification into production, or alerts or telemetry are under review, select observability-design.
• When infrastructure is chosen, inherited, or questioned, select infrastructure-fit.
• test-strategy and evolutionary-database-design are two-pass companions that bracket A/L/C/E; the route in §2 orders their passes.
• SKIP skips only the Alchemy core; it never suppresses a matching companion. DIRECT keeps the core route focused while allowing independently triggered companions.
• Report companions explicitly. Use None when no companion trigger matches.

Execution Strategy

Execution is a second decision after dispatch, never a fifth dispatch: it decides whether one agent or several carry out the selected route, and the user never names agents. SKIP and DIRECT run single-agent and never load orchestration. ADAPTIVE, FULL, and audit select multi-agent only when the work changes or audits code and at least two parts are independent — different subsystems, disjoint files, no ordering between them — or a high-risk change (security, public contract, persisted shape) needs a reviewer that did not write it. Count every agent: one writer and one independent reviewer is multi-agent. The number of gates or skills on the route is never a reason. Stay single-agent and say why when neither holds, when the project's alchemy-workspace.json sets execution.multi_agent to off, or when the runtime cannot launch agents. On multi-agent, load alchemy-orchestrate before the first stage that changes or audits code; it plans, launches, verifies, and gates the agents.

Change Primitives

Every stage describes change with four primitives: a Subsystem is where change lands, an Aspect is which dimension is touched, an Increment is what changes, and an Iteration admits, realizes, and measures one increment. Each sibling names its own term as a specialization of exactly one and never redefines them; references/change-primitives.md defines them and maps each sibling term. Decomposition and aspect extraction are different cuts: decomposition splits one subsystem into several; extraction pulls one aspect out of several subsystems into one mechanism. A design that models an aspect as a subsystem, or copies its mechanism per subsystem, has confused the two.

2. Adaptive Requirements Qualification

textCopy code
Requirements Grounding, when evidence or meaning is absent or stale
→ M — Minimum
→ Requirements Topology, when relationships are non-trivial
→ Implementation Readiness
→ A — Architecture → L → C → E → H → Y

Qualification stages are conditional and never become acronym letters. Before selecting stages for ADAPTIVE, FULL, or audit, read references/adaptive-route.md: routing rules, decision hand-offs, the gate table, the Gate 3–4 handshake, the two-pass companion order, core directives, the pre-flight checklist, and the retrospective order. SKIP and DIRECT never need it.

Read references/failure-modes.md when a run's result looks wrong, an audit shows a symptom, or a trail has an unexplained skip; route the recovery to the named stage instead of rerunning every gate.

3. Output Contract

Default output for a single-gate or simple routed request:

Copy code
Dispatch:   <SKIP | DIRECT | ADAPTIVE | FULL>
Core route: <None | M | A | L | C | E | H | Y | left | out | down | ordered set>
Companions: <None | task-matched skills>
Execution:  <single-agent | multi-agent> — <independence or risk fact>
Verdict:    Proceed | Redesign | Drop | Defer
Reason:     <one or two lines>
Next:       <one concrete action>

For SKIP, emit this compact output alone with Core route: None; do not load a core sibling merely to justify the skip.

Multi-stage runs, non-trivial design/refactor passes, audits, and explicit requests for detail emit one combined decision trail in execution order, including every stage used and every conditional stage skipped:

Then state:

Copy code
Scope:          <subsystem / service / refactor / PR>
Mode:           Design | Refactor | Audit
Dispatch:       SKIP | DIRECT | ADAPTIVE | FULL
Companions:     <None | task-matched skills>
Execution:      single-agent | multi-agent
Blocking stage: <first non-passing qualification decision or gate, or None>
Decision:       Proceed | Redesign | Drop | Defer
Verification:   <commands, lint rules, tests, or Not run + reason>

Lead any run that reaches a verdict with the four report blocks the root instruction file defines, What I found, Why it matters, Do this first, and What I did not check, then emit the records unchanged: the trail and scope block, then each stage that ran in execution order, with the decision record its skill's output contract defines. The trail summarizes stages; it never replaces a stage's record. When implementing changes, add the normal coding summary after the verdict.

4. Discipline

• Skipped stages require a one-line rationale. A skip without one is a defect and an over-engineering risk for the next audit.
• Natural language stays adaptive. "Do some alchemy" never means FULL without explicit full-traversal language.
• Load each stage when the route reaches it. Read a stage's or companion pass's SKILL.md only once every stage before it has passed, never ahead. A blocking decision in the route's hand-off table ends the route for that candidate: the stages after it stay unloaded and appear in the trail as Not run with that decision as the reason. Only candidates with a passing decision continue.
• Claim only what ran. Core route and the trail name a stage's decision only when its SKILL.md was read in this task; a selected stage that did not run appears in the trail as Not run with the reason.
• When a gate is consistently skipped across tasks, that's a signal for continuous-improvement to update THIS skill — not paper over with case-by-case reminders.