Anneal · Getting Started · v0.1.0

Three commands.
One restart.
One plan.

The fastest path from zero to a battle-tested plan: install all three variants, verify the install, and run your first plan through Cast — the linear four-minute variant.

01Prerequisites

What you need first.

Requirement	Why	How to check
Claude Code CLI v2.0+	Plugin marketplace support, /plugin subcommand, ${CLAUDE_PLUGIN_ROOT} resolution	`claude --version`
macOS or Linux shell	orchestrate.sh uses POSIX + xargs -P for parallel fan-out (Alloy)	`uname -s`
Python 3.10+	convergence-check.py (Temper), validate-plugin.py (all three)	`python3 --version`
Git	Anneal writes to a scratch worktree during Hephaestus validation	`git --version`
~2 GB free disk	Per-run artifacts land under ./.anneal/runs/; keep at least a few runs available	`df -h .`

Optional but recommended: If you have context7, docs-seeker, or similar MCPs configured, the probe stage enumerates them and Metis routes Prometheus to the right docs. ValidationForge at the project level gives Hephaestus richer evidence when validating.

02Install

One marketplace. Three plugins.

Anneal ships an umbrella marketplace that lists all three plugin variants. One marketplace add, three plugin installs.

bashinstall from umbrella marketplace

# From a fresh Claude Code session/plugin marketplace add krzemienski/anneal# Install all three variants/plugin install anneal-cast@anneal-umbrella-dev/plugin install anneal-alloy@anneal-umbrella-dev/plugin install anneal-temper@anneal-umbrella-dev# Restart Claude Code — plugin registration runs at session start

bashlocal development (working on Anneal itself)

/plugin marketplace add /path/to/anneal/cast/plugin install anneal-cast@anneal-cast-dev/plugin marketplace add /path/to/anneal/alloy/plugin install anneal-alloy@anneal-alloy-dev/plugin marketplace add /path/to/anneal/temper/plugin install anneal-temper@anneal-temper-dev

03Verify

Confirm the install.

bashlist installed plugins

claude plugin list# Expected output (v0.1.0):anneal-cast    0.1.0   anneal-umbrella-devanneal-alloy   0.1.0   anneal-umbrella-devanneal-temper  0.1.0   anneal-umbrella-dev

bashstructural self-check — each plugin ships validate-plugin.py

python3 ~/.claude/plugins/cache/anneal-cast/*/scripts/validate-plugin.py \ ~/.claude/plugins/cache/anneal-cast/*/ python3 ~/.claude/plugins/cache/anneal-alloy/*/scripts/validate-plugin.py \ ~/.claude/plugins/cache/anneal-alloy/*/ python3 ~/.claude/plugins/cache/anneal-temper/*/scripts/validate-plugin.py \ ~/.claude/plugins/cache/anneal-temper/*/# All three should exit 0 with a green check summary

After install, the three slash commands register:

commandsregistered slash commands

/anneal-cast:anneal    "<task>"   # Linear pipeline/anneal-alloy:anneal   "<task>"   # Tournament consensus/anneal-temper:anneal  "<task>"   # Fixed-point deepen

04Your First Plan

Cast: four minutes to a battle-tested plan.

Run a concrete task through Cast — the linear variant, fastest of the three, simplest to follow stage-by-stage.

invokereal-time chat feature via Cast

/anneal-cast:anneal "Build a real-time chat feature with WebSocket connections, presence tracking, and message history"

Stage-by-stage walkthrough

Stage 1 · Intent Gate (~2 seconds)
Classifies the task as new-feature. No secret extraction, no destructive ops, no ambiguity requiring a clarifying question. Proceeds.
```
[stage-1] intent: new-feature | safe: yes | proceed
```
Stage 2 · Probe (~15 seconds)
Scans the project root. Enumerates ~/.claude/skills/ and .claude/skills/. Reads README.md, CLAUDE.md, package.json, docs/, plans/. Detects Next.js 15 + TypeScript + pnpm.
```
[stage-2] probe: 47 files, 12 skills (context7, functional-validation, ...), detected: nextjs15, typescript, pnpm, tailwind-v4
```

Stage 3 · Enrich — Metis (~30 seconds)

Metis reads the task and probe report. Returns an envelope with directives and flags.

verdict: CAUTIONsummary: Real-time chat is broad. Narrowing via directives.directives:- Use Socket.IO (Next.js integration well-trodden)- Store message history in Postgres with TTL eviction- Presence tracking via Redis pub/sub- Phase rollout: read-only → write → presencefindings:- src/app/: no real-time infrastructure exists- docs/: no WebSocket architecture document

Stage 4 · Plan — Prometheus (~90 seconds)
Prometheus writes the plan — plan.md plus six phase-NN-*.md files. Then Momus audits. Returns CAUTION — flags the migration envelope. Finding folds into Oracle's input, not a BLOCK.

Stage 5 · Review — Red-Team Trinity (~60 seconds parallel)

Three adversaries dispatched in a single message (parallelism is load-bearing):

redteam-security:  RISKY — unsigned WebSocket handshake; requires origin-checkredteam-scope:     CAUTION — "history" retention undefined; adds 90-day defaultredteam-assumptions: CAUTION — Redis dependency unstated; requires Phase 0 checkoracle:            SAFE — 3 deployment-risk notes, 1 breaking-change callout

Stage 6 · Validate — Hephaestus (~45 seconds)
Builds the Phase 0 artifact (Redis + Socket.IO bootstrap) in a scratch worktree. Captures real pnpm build output, real curl against the socket health endpoint, real screenshots of the echo-room debug UI. PASS.
Stage 7 · Emit — Atlas (~5 seconds)
Rollup computed: simultaneous_pass: true, overall_verdict: SAFE,emission_decision: EMIT. Atlas writes the artifacts.

05Output Artifacts

What you get after a run.

directory.anneal/runs/cast-anneal-260423-2134-realtime-chat/

.anneal/runs/cast-anneal-260423-2134-realtime-chat/ ├── cast-anneal-260423-2134-realtime-chat.xml    ← 4.2 KB Opus 4.7 XML prompt├── plan/ │   ├── plan.md                                  ← overview + phase index│   ├── phase-00-infrastructure-bootstrap.md │   ├── phase-01-socket-server.md │   ├── phase-02-presence-tracking.md │   ├── phase-03-message-persistence.md │   ├── phase-04-ui-integration.md │   ├── phase-05-phased-rollout.md │   └── phase-06-functional-validation.md ├── rollup.yaml                                  ← all envelopes aggregated├── reviews/ │   ├── metis-envelope.yaml │   ├── momus-envelope.yaml │   ├── redteam-security-envelope.yaml │   ├── redteam-scope-envelope.yaml │   ├── redteam-assumptions-envelope.yaml │   └── oracle-envelope.yaml └── evidence/ ├── hephaestus-build-log.txt ├── hephaestus-socket-health.json └── hephaestus-echo-room.png

bashexecute the emitted plan in a fresh session

# Atlas prints the next step after every successful run:# Open a fresh Claude Code session and paste:cat .anneal/runs/cast-anneal-260423-2134-realtime-chat/*.xml | claude

naming conventionrun ID format

# {variant}-anneal-{YYMMDD}-{HHMM}-{slug}cast-anneal-260423-2134-realtime-chat alloy-anneal-260423-2150-database-multi-tenant temper-anneal-260423-2215-unify-oidc-legacy-jwt# Override the root directory:ANNEAL_RUNS_ROOT=~/anneal-runs/ /anneal-cast:anneal "task"

06Good First Tasks

Tasks that fit well on first try.

bashrecommended first-run shapes

# Bounded features — Cast/anneal-cast:anneal "Add a /health endpoint that returns { status, version, db_reachable }"/anneal-cast:anneal "Split the 800-line src/api/users.ts into per-resource modules"/anneal-cast:anneal "Add rate limiting to /api/messages using sliding window counter"# Novel architecture — Alloy/anneal-alloy:anneal "Design a plugin system for the CLI with versioned lifecycle hooks"# Complex-but-scoped — Temper/anneal-temper:anneal "Rewrite auth middleware to unify OIDC and legacy JWT flows"

Tasks that struggle on first try: "Refactor the whole codebase" (Intent Gate rejects — scope it) · "Make it faster" (Metis emits BLOCK — name the hot path) · "Follow best practices" (Metis emits BLOCK — name the specific practice) · "Just ship something" (Metis rejects — name what you want built)

07Troubleshooting

When things go wrong.

Symptom	Fix
command not found: /anneal-cast:anneal	Restart Claude Code. Plugin registration runs at session start only. If still missing, run claude plugin list — if absent, re-install from marketplace.
validate-plugin.py: FileNotFoundError	Stale install path. Re-install: /plugin uninstall anneal-cast then /plugin install anneal-cast@anneal-umbrella-dev.
Stage 4 hangs, no Prometheus output	Check network — Prometheus needs MCP access if probe report referenced docs servers. Alloy's xargs -P fan-out is CPU-bound; reduce --versions to 3 on small machines.
Hephaestus FAIL with 'empty evidence'	The plan's Phase 0 did not produce a real buildable artifact. Read the hephaestus-evidence/ directory — the failing step is always explicit. Re-run; Cast routes through Metis automatically.
Atlas emits RE_LOOP three times	Genuine disagreement. Read the last rollup.yaml → blocking_issues field. Either relax the task scope or run Alloy on the same task; the tournament often resolves what Cast cannot.
convergence-check.py never returns 0 (Temper)	You hit the depth cap. Raise --depth 5 or accept the final plan — Temper's rule 3 exists exactly for this case.

"No plan survives its own adversaries without tempering. Anneal ensures every plan earns its compile."— the shared contract

← startNext: Cast →

ANNEAL · anneal.withagents.devSRC · github.com/krzemienski/annealDOCS · ← LandingBRAND · withagents.dev

Three commands.One restart.One plan.