Forge

Forge — Ideas Into Designs & Implementation

Overview

Turn ideas into fully formed designs through collaborative dialogue, then orchestrate implementation via bob (autonomous executor agent). Uses a two-phase approach: Design Team explores approaches with dual challengers (Claude + Codex) and UX advocate, then bob handles all execution — work package decomposition, team orchestration via agent-teams, verification, and delivery.

Every design and implementation decision must account for real human behaviour — how end users actually see, navigate, and interact with the product.

• Forge invokes the component-contract-mapping skill at Step 8a to produce the map.
• Forge signs it with HMAC-SHA256 using .forge/session.key (per spec section 7.4).
• The signed payload MUST include map_hash, map_revision, forge_session_id, and signed_at.
• Missing or unsigned map = refuse to spawn bob. No workarounds. No "we'll add it later".
• Pure refactoring / single-file bugfixes with no new components are exempt.

Checklist

You MUST create a task for each item and complete in order:

1. Explore project context — read PROJECT.md (architecture map, components, integration edges) and relevant COMPONENT.md files FIRST. Check history.md (if >400 lines, head+tail only — older context lives in history/INDEX.md), session_control.md. Invoke project-documentation to ensure all docs exist (creates PROJECT.md + COMPONENT.md stubs if missing). If a wiki exists for the project (CWD contains .wiki/ OR ~/.wiki-registry.yaml lists this project), use Tier 1 access: Grep the wiki's wiki/ directory for prior decisions, research, and ADRs on the task topic. Include any findings in shared_context as a "Prior Wiki Knowledge" section so design agents can reference existing decisions. Also run python3 ~/.claude/skills/_meta/scan_hard_rules.py (plain mode) to scan CLAUDE.md (global + project-local) for hard-rule directives and diff against ~/.claude/skills/_meta/hard-rules-checklist.md. If any are flagged as potentially missing, surface them to the user with a 1-line summary and ask: "add to checklist / wire into a skill / apply ad-hoc / ignore?" — do NOT silently skip. This is idempotent with the SessionStart hook but catches cases where forge is invoked from a subagent, after cd, or in sessions where the hook didn't run.

   Dependency currency check (advisory only, MEDIUM+ tasks): if any manifest is present at the project root (pyproject.toml, package.json, Cargo.toml, go.mod, Gemfile, pom.xml), invoke dep-currency-check to populate shared_context.dependency_health. Run it advisory-only — forge Step 1 NEVER fails on its exit code; blocking enforcement lives at bob's WP boundary, the G_DEP_CURRENCY gate, and pre-commit hooks. Skip for TRIVIAL/SIMPLE tasks (latency budget). Pattern:

   if find "$PWD" -maxdepth 4 \( -name 'pyproject.toml' -o -name 'package.json' -o -name 'Cargo.toml' -o -name 'go.mod' -o -name 'Gemfile' -o -name 'pom.xml' \) 2>/dev/null | grep -q .; then
     PYTHONPATH="$HOME/.claude/skills/dep-currency-check" python3 -m dep_currency_check "$PWD" \
       --format json --severity high --quiet \
       --output "/tmp/forge-dep-currency-${FORGE_SESSION_ID:-default}.json" 2>&1 || true
   fi
   

   The || true is mandatory — Step 1 MUST NOT fail. Read the JSON if present, include dependency_health in shared_context. See ~/.claude/skills/dep-currency-check/references/integration-forge.md for the full payload shape + skip rules.

2. Offer visual companion (if topic involves visual questions) — see Visual Companion section. This is its own message, not combined with clarifying questions.

3. Ask clarifying questions — one at a time, understand purpose/constraints/success criteria. If the request describes multiple independent subsystems, flag and decompose first (see Large Project Decomposition). Founder-intent routing: if the request is "I have a startup idea" / "generate ideas" / "validate my idea" / "what should I build" / any pre-execution founder / innovator / inventor intent — route to the founder skill FIRST (not forge directly). Founder owns pre-execution (ideation, validation, business model, GTM); forge owns execution. Founder will hand back at the Scope→Launch gate with a populated forge_brief when the venture is ready for build. See founder/references/forge-handshake.md for the full contract.

Explicit founder handoff: If the spawn prompt or user message includes came_from_founder: true with a venture_brief_path, read that file and use its forge_brief block as the pre-clarified task statement:

• forge_brief.problem -> the design challenge (skip "what are we building?" questions)
• forge_brief.success_criteria -> pass to design agents as constraints
• forge_brief.non_goals -> pass as explicit scope boundaries
• forge_brief.complexity_hint -> seed Step 4 complexity assessment
• forge_brief.open_questions -> ask ONLY these in Step 3 (skip all other questions)
• ideas_considered / assumptions / experiments -> include as "Prior founder exploration" in shared_context for all design agents

If came_from_founder is absent or false, proceed with normal forge flow. Forge NEVER reads .founder/venture-brief.yaml at session start -- only on explicit handoff.

Explicit avengers handoff: If the spawn prompt or user message includes came_from_avengers: true with an avengers_brief_path, read that file and use its avengers_brief block as the pre-clarified task statement (mirrors came_from_founder; the avengers build path enters forge HERE at Step 3 intake, then flows through forge's own Step 4–9 gates — classification, contract map, spec review, bob):

• avengers_brief.problem -> the design challenge (skip "what are we building?" questions)
• avengers_brief.constraints -> passed to design agents as constraints
• avengers_brief.success_criteria -> passed to design agents as constraints
• avengers_brief.ruled_out_approaches -> non-goals + hard "do not explore" signals (each carries which seat killed it; same treatment as the founder phase-2 rule)
• avengers_brief.recommended_direction -> seed front-runner for Step 6 exploration (advisory, NEVER locked — design agents may reject it)
• avengers_brief.dissent[] -> surfaced verbatim to the user during Step 7 presentation (never summarized away)
• avengers_brief.confidence -> input to Step 4 complexity assessment (high+narrow MAY downgrade team size; low/speculative FORCES full exploration)
• avengers_brief.deliberation_record -> listed as a prior-exploration reference in shared_context (path, never inlined)

avengers_brief.contract_map_signed and avengers_brief.bob_ready are mechanically always-false — avengers NEVER signs a contract map or marks anything bob-ready; forge owns those gates. If either is true in the brief, treat the brief as malformed and re-clarify with the user.

If came_from_avengers is absent or false, proceed with normal forge flow. Forge NEVER reads an avengers session directory at session start -- only on explicit handoff. Recursion guard: a forge-convened avengers session (forge itself invoked avengers for design exploration, carrying forge_session_id) MUST NOT emit a brief back into forge — see the Step 6 recursion-guard note. 4. Assess complexity — determine design exploration team size needed 4b. Check tool availability via env-adoption manifest — Read ~/.claude/state/inventory.json for tool availability and $XDG_RUNTIME_DIR/env-adoption/session-*.json for session capabilities. If the inventory is missing or stale (>24h), run bash ~/.claude/skills/env-adoption/scripts/probe.sh check first (completes in <3s). Branch on capabilities:

• capabilities.codex_challenger = true: Codex available, use /codex:setup or delegate directly.
• capabilities.agy_analyst = true: agy available, use a direct agy --sandbox -p "..." < /dev/null Bash call (read-only analyst, #157; < /dev/null is MANDATORY — without it agy blocks on stdin in non-TTY shells and hangs to timeout, #135).
• capabilities.triple_model = true: all three models available for maximum coverage.

The manifest is cached for the session — do not re-probe on every use. If Codex/agy unavailable, note the gap explicitly but continue with what's available. See env-adoption skill for full schema. 5. Skill gap check — identify skills needed, check if they exist (see Skill Gap Detection) 5b. Hard rules checkpoint — read ~/.claude/skills/_meta/hard-rules-checklist.md DESIGN PHASE + CROSS-MODEL sections. Verify: Codex parallel for MEDIUM/COMPLEX? Performance expectations asked? Gap detection done? 6. Phase 1: Design Exploration — spawn design exploration team OR do single-agent exploration 7. Present design — in sections, get user approval after each section 7b. Freeze the design skeleton (UI designs only) — after the user approves the HTML mockup and BEFORE Step 8a signing: invoke skeleton-extractor then visual-architect. See "UI designs — design-skeleton freeze (Step 2.5)" under Visual Companion. 8. Write design doc — save to docs/plans/YYYY-MM-DD-<topic>-design.md 8a. Generate & sign contract map (if design introduces components) — invoke component-contract-mapping skill, run G2 validation, sign via HMAC (see Contract Map Generation) 8b. Spec review — run spec self-review checklist, then dispatch reviewer subagent (see Spec Review) 8c. User reviews spec — ask user to review spec file before proceeding. Wait for approval. 8d. Hard rules checkpoint — read ~/.claude/skills/_meta/hard-rules-checklist.md EXECUTION PHASE section before spawning bob. 9. Spawn bob — pass design doc path and shared context (see Execution Method Selection) 10. Wait for bob — bob handles decomposition, orchestration, verification autonomously 11. Final integration — collect execution results, verify, present to user

Complexity Assessment

Before spawning any design exploration team, assess complexity:

Adaptive Checklist

Skill Gap Detection

After assessing complexity, identify what domain skills agents will need:

Follow gap-detection protocol at ~/.claude/skills/research-for-skills/gap-detection.md

Step 4b: Orchestration tier (S055 — feature-detected)

Before Step 6, decide HOW design exploration runs. This is a fast-path choice, never a dependency — the documented main path (Step 6B below) completes with ZERO orchestration primitives.

• Read bash ~/.claude/skills/env-adoption/scripts/probe.sh get capabilities.workflow_tool (the ONLY capability API — never inline-probe, never raw jq) AND confirm the live context via probe.sh context (must be main-loop). The decision rule, restated: can_orchestrate = capabilities.workflow_tool AND context == main-loop. See env-adoption/references/context-detection.md — capabilities.* alone NEVER authorizes orchestration (session files are shared with subagents).
• If both true (Step 6A fast path): the main loop MAY run the design-tournament saved workflow (parallel approach/challenge/converge fan-out that returns a DRAFT synthesis + a script-computed disagreement matrix). The converge DECISION, all user questions/approvals, and the design-doc write STAY inline in forge (Workflow Boundary, below). External challengers are PRE-LAUNCHED inline by forge and passed as transcripts (agy is UNREACHABLE from workflow stages — WP-2 live finding).
• Else (Step 6B portable, canonical): run the existing design exploration team inline (Phase 1 below). This is byte-identical to the prior forge flow. Codex/Copilot/VS Code/older-Claude hosts always take this path.

Step 6A fast path — design-tournament workflow (optional, main-loop only)

When the orchestration tier (Step 4b) selected the fast path: invoke Workflow({name: "design-tournament", args: {...}}) with run_started_at, run_label, brief_path+brief_sha256, shared_context_path+shared_context_sha256, approaches[], consultants[], consultant_cmds{}, ui_facing, budget_tokens, transcript_dir, external_transcripts[] (pre-launched), models{}. The workflow returns a design-synthesis.v1 DRAFT + the disagreement matrix; forge presents it section-by-section and OWNS the converge decision. Budget floor: if the budget cannot cover ≥2 approaches + 1 challenger + synthesis, the workflow returns status: INCOMPLETE with zero synthesis — an under-budget tournament looks unfinished, not polished. Shed ladder (documented, never silent): codex approach-explorer → agy analyst → approach agents above the minimum 2; NEVER shed the Claude challenger or UX-when-ui_facing. Spend is reported observe-only (#147 design half — no enforcement). On ANY fast-path failure, fall back to Step 6B (byte-identical, portable).

Step 6B: Design exploration team (portable, canonical) — Phase 1

Recursion guard (avengers ↔ forge): forge MAY convene avengers in design-exploration mode as an adjunct to the approach team. When it does, forge passes its forge_session_id in the avengers came_from block. A forge-convened avengers session is depth-capped and its build path is BLOCKED: it returns a decision (forced), never a forge_brief, so it cannot emit a came_from_avengers handoff back into forge (which forge itself started). This prevents infinite forge→avengers→forge recursion. Forge already pays for its own challengers; a convened avengers is for contention, not a second build gate.

Step 1: Understanding (Lead Only)

The lead handles all user interaction:

• Check current project state (files, docs, recent commits)
• Ask questions one at a time (prefer multiple choice)
• Focus on: purpose, constraints, success criteria
• Performance expectations (ask if task creates/modifies endpoints, queries, UI, or batch processes):
  • "Expected concurrency / data volume?"
  • "Latency requirements? (e.g., p95 < 200ms)"
  • "Is this on a hot path?"
  • "Existing performance budgets to respect?"
• Runtime / observability branch (ask once, not a full questionnaire): "Does this change runtime behavior, service boundaries, or SLOs?"
  • If YES: delegate full capacity questionnaire to performance skill (references/capacity-questionnaire.md), full signals-map drafting to observability skill, BEFORE design-team exploration. Capture the signals-map path + capacity answers into shared_context so design agents consume them as constraints.
  • If NO: skip. Existing performance-expectation questions still apply.
• Security / threat-model branch (ask once, not a full questionnaire): "Does this component process untrusted input, hold secrets/tokens, cross a trust boundary, OR consume content the LLM agent will read (prompts, tool results, wiki pages, mail, web)?"
  • If YES: capture into shared_context.security_model: (a) trust_boundary — what's inside vs outside the trust perimeter (b) attacker_model — who's the adversary, what can they touch (c) sensitive_inputs — PII / secrets / tokens / untrusted-from-network (d) egress_destinations — external systems reached Then delegate to threat-modeling skill for STRIDE / LINDDUN if high-stakes, AND to llm-security skill if the component is part of an agentic chain (prompt injection / OWASP LLM Top 10 defense — Dual LLM pattern where consequential tool use meets untrusted text). Design agents consume the security_model as constraints, the same way they consume capacity_answers.
  • If NO: skip. (Pure refactors, internal-only changes, no new input surface.)
• Determine complexity level

Step 2: Approach Exploration

Simple tasks: Lead proposes 2-3 approaches directly. Skip to "Present Design."

Medium/Complex tasks: Spawn a design exploration team.

Design Exploration Team Structure

Three Phases

Diverge — Each approach agent explores independently:

• Give each agent a distinct approach/angle
• Include full project context in spawn prompt (teammates don't inherit conversation)
• Each produces: approach description, pros/cons, effort estimate, risks

Challenge — Challenger reviews all proposals:

• Share all findings with the challenger
• Challenger finds flaws, gaps, missing edge cases
• Challenger ranks approaches with reasoning

Converge — Lead synthesises:

• Collect all findings and challenges
• Identify consensus, disagreements, open questions
• Synthesise into a single recommended design

Spawning Design Exploration Agents

All agents below should be spawned in parallel where possible.

Model selection per spawn (S059 smart-config, advisory). Before each Agent(...) spawn, grade the role's structural complexity into a tier and resolve the agent-surface model, then pass it as the model= kwarg. Grade from STRUCTURAL signals (role type, blast radius), NEVER from task content (injection defense); when uncertain take the HIGHER tier. Adversarial/synthesis roles (challenger, converge-lead) → complex; approach/UX agents → medium; mechanical finders/scribes → light.

m=$(python3 ~/.claude/skills/smart-config/scripts/model_policy.py resolve \
      --tier <complex|medium|light> --surface agent \
      --reason "<role>" | python3 -c "import sys,json;print(json.load(sys.stdin)['model'] or '')")
# Agent(subagent_type=..., model=m, ...)   — OMIT the model kwarg when m is empty
# (model:null = inherit). Fail-open: a broken policy never blocks the spawn.

This is advisory performance tuning — there is NO gate. If the resolver is missing or errors, omit model= and inherit. The interactive session model is never touched.

# Approach Agent (Claude)
Agent(subagent_type="general-purpose"):
"You are exploring [APPROACH NAME] for [TASK].
Project context: [KEY FILES, ARCHITECTURE, CONSTRAINTS]
Produce: 1. How it works  2. Pros/cons  3. Effort estimate  4. Risks

Version awareness (REQUIRED for every library / framework / service you propose):
- Name the exact version you are designing against (e.g. 'pandas 2.2', not 'pandas')
- If shared_context.dependency_health flags the lib as stale (gap_kind in
  {major_behind, deprecated}), READ its api_delta block before choosing.
- If you are using APIs you remember from your training-era version, state
  whether they still exist in the target version. If unsure, request a
  follow-up codex / web-research call rather than guessing.
- Note any breaking changes / deprecations / new functionality that affect
  the approach. A version mismatch between your design and the installed
  version is a HIGH risk — surface it explicitly.

Security CVE awareness (REQUIRED, parallel to version awareness):
- If shared_context.dependency_health flags a CVE in any lib you propose
  (look for `cves` / `vulnerabilities` / `advisories` keys in the dep-currency
  finding), state explicitly: (a) the CVE id, (b) whether you're proposing an
  upgrade past the fixed version OR a mitigation (input filter, sandbox,
  removal of the vulnerable code path), (c) why the mitigation is acceptable
  if you're NOT upgrading. Designing against a known-vulnerable version
  without acknowledging the CVE is a HIGH risk and will be flagged in review.
- If shared_context.security_model exists (set by Step 1 security branch),
  treat its attacker_model / sensitive_inputs / egress_destinations as
  constraints. A design that ignores them is structurally wrong, not just
  insecure. Examples: trust_boundary='public API' means your approach MUST
  include input validation at the boundary; sensitive_inputs containing
  tokens/secrets means your approach MUST address storage hardening.
- For agentic components (LLM consuming untrusted text + having tools):
  reference Dual LLM architecture (Quarantined LLM processes untrusted data
  without tool access, Privileged LLM uses only symbolic vars) as the
  default-safe pattern. Deviations need explicit justification."

# UX Agent (for UI-facing work)
# subagent_type MUST be one that exists on this host. Verify against the available
# agent-type list before spawning — a nonexistent type does NOT fail loudly, it
# silently degrades, and the specialist runs without its intended role. (S073: this
# line named `multi-platform-apps:ui-ux-designer`, which was never installed —
# `enabledPlugins` contains only `superpowers` — so every UI-facing forge cycle had
# been falling back silently.)
Agent(subagent_type="general-purpose"):
"You are the UX advocate for [TASK].
Invoke the `ux-reviewer` skill first (and `audience-experience-design` when the task
is design-before-build rather than review-after-build).
Evaluate every approach through: user journey, visual hierarchy,
cognitive load, mobile ergonomics, trust/emotion, accessibility.
Rank approaches by real-world usability."

# Claude Challenger Agent
Agent(subagent_type="general-purpose"):
"You are the devil's advocate for [TASK].
Invoke the `challenger` skill first.
Find flaws in EVERY proposal including UX findings.
Rank approaches with reasoning."

Spawning Codex Agents (ALWAYS — in parallel with Claude agents)

Check Codex availability first (step 4b). If unavailable, skip Codex agents and note the gap.

CHECK AVAILABILITY FIRST. The /codex:* commands come from a Codex plugin, which is a separate thing from the codex CLI. Having the CLI does NOT mean you have the commands. Verify the plugin is in enabledPlugins (~/.claude/settings.json) — or that the commands exist under ~/.claude/commands/ — before using this path. If it is absent, go straight to raw codex exec below; that path is fully capable and needs only the CLI. (S073: on this host enabledPlugins contains only superpowers, so every /codex:* invocation documented here was unavailable while raw codex exec worked normally.)

Preferred when available: Codex plugin commands (structured output, job tracking, resume capability):

# Codex Challenger — use /codex:adversarial-review for design challenge
# Run via Skill("codex:adversarial-review") or invoke the command:
/codex:adversarial-review --background look for scalability, security, maintainability issues and rank approaches

# Codex Research — use /codex:rescue for independent exploration
/codex:rescue --background "Explore approaches for [TASK]. Context: [KEY FILES, ARCHITECTURE, CONSTRAINTS]. Produce top 2-3 approaches with pros/cons, effort, risks."

# Check status of background jobs
/codex:status
# Retrieve results when done
/codex:result [job-id]

Fallback: Raw codex exec (for parallel batch tasks or custom briefs). STDIN RULE (#155): the agy stdin rule applies to codex exec exactly the same — close stdin (< /dev/null) on every headless argv-prompt invocation or it hangs to timeout in background shells:

CODEX_WORK=$(mktemp -d /tmp/codex-XXXXXXXXXX)

# Codex Challenger (runs simultaneously with Claude challenger)
cat > "$CODEX_WORK/brief-challenger.md" << 'BRIEF'
# Challenger Review Brief
## Context
[TASK DESCRIPTION + KEY CONSTRAINTS]
Project files at: [PROJECT_DIR]
## Your Role
You are a devil's advocate / challenger. Find flaws in EVERY approach.
Focus on: scalability, security, maintainability, edge cases, operational complexity.
For each issue: Severity (critical/moderate/minor), What's wrong, Why it matters, How to fix.
Rank overall design: strong / acceptable / needs-rework / reject.
BRIEF

timeout 600 codex exec --ephemeral -C "$PROJECT_DIR" -s read-only \
  -o "$CODEX_WORK/challenger.md" \
  "Read $CODEX_WORK/brief-challenger.md and execute the challenger review." < /dev/null || echo "CODEX_TIMEOUT: Codex did not respond within 600s" > "$CODEX_WORK/challenger.md" &

# Codex Second Opinion / Approach Explorer (independent perspective)
timeout 600 codex exec --ephemeral -C "$PROJECT_DIR" -s read-only \
  -o "$CODEX_WORK/approach.md" \
  "You are exploring approaches for [TASK].
Context: [KEY FILES, ARCHITECTURE, CONSTRAINTS]
Produce your top 2-3 recommended approaches with:
1. How it works  2. Pros/cons  3. Effort estimate  4. Risks
Be opinionated — recommend the best approach and explain why." < /dev/null || echo "CODEX_TIMEOUT: Codex did not respond within 600s" > "$CODEX_WORK/approach.md" &

# Codex Research (when task needs up-to-date info; web search is automatic — no flag)
timeout 600 codex exec --ephemeral --skip-git-repo-check \
  -o "$CODEX_WORK/research.md" \
  "Research current best practices for [TECHNOLOGY/PATTERN] as of 2026.
Latest versions, known limitations, community adoption, alternatives." < /dev/null || echo "CODEX_TIMEOUT: Codex did not respond within 600s" > "$CODEX_WORK/research.md" &

wait  # Wait for all Codex tasks to complete

When to use plugin vs raw exec: Plugin commands are preferred for single challenger/research tasks (structured output, job tracking). Use raw codex exec when running 3+ parallel tasks in a batch or when custom brief files with skill injection are needed.

Spawning Antigravity (agy) Analyst (MEDIUM+ — in parallel with Claude and Codex agents)

Check agy availability first: command -v agy. If unavailable, skip and note the gap.

agy -p returns plain text on stdout — the lead parses the text reply, not JSON fields. Raise --print-timeout above the 5m default for long analyses. Append a served_by probe line to the prompt and capture it — self-reported model identity is unreliable.

STDIN RULE (root-caused 2026-06-05, #135): headless agy MUST have stdin closed or piped — < /dev/null on every call. agy reads non-TTY stdin until EOF before the model call; in background/harness shells stdin never EOFs, so agy hangs forever producing 0 bytes and --print-timeout never fires (it only guards the print phase). Also wrap in a shell timeout.

Prompt size is NOT a factor (verified: 30-char prompt hung; 11KB prompt with < /dev/null answered in 9s).

SANDBOX RULE (S052 rogue-commit incident, #157): the agy analyst is a READ-ONLY role — ALWAYS invoke it with --sandbox. agy has write/shell/git tools by default; in S052 an un-sandboxed "analyst" auto-authored and git-committed broken code mid-design (HARD-GATE violation). Codex is unaffected (it already runs -s read-only). FLAG ORDER (root-caused 2026-07-02): --sandbox and every other flag BEFORE -p, prompt LAST — agy -p --sandbox "X" silently runs UN-sandboxed with the literal prompt --sandbox and discards "X" (agy then improvises from implicit memory — the "does work instead of consulting" failure mode). Scope caveat (verified 2026-07-02, 1.0.15): --sandbox constrains shell/git only, NOT native file writes — prefer piping content over --add-dir on a writable repo, open the prompt with "Advisory only — do not modify any files; answer on stdout", and run git status --short afterwards if a repo was exposed.

# Antigravity (agy) Analyst — independent third-model analysis
timeout 600 agy --sandbox -p "You are an analyst for [TASK].
Project context: [KEY FILES, ARCHITECTURE, CONSTRAINTS]
Analyze: 1. Architecture trade-offs  2. Scalability limits  3. Security surface
4. What approaches work best at scale for this pattern?
Be specific and cite real-world precedents where possible.
At the very end print one line: SERVED_BY=<model-id-you-are-running-as>." < /dev/null

# For codebase context, add the relevant paths to the workspace with --add-dir:
# CAUTION: --sandbox does NOT gate native file writes into --add-dir trees — prefer piping;
# if you must --add-dir a writable repo, run `git status --short` afterwards and revert strays.
timeout 600 agy --sandbox --add-dir [PATHS] -p "Advisory only — do not modify any files; answer on stdout.
Review the codebase at [PATHS] for [TASK].
Focus on: cross-cutting concerns, hidden coupling, N+1 patterns, missing error boundaries." < /dev/null

# For multi-methodology brainstorming (frame the methodology in the prompt itself):
timeout 600 agy --sandbox -p "Brainstorm approaches for [TASK] using the Six Thinking Hats methodology —
work through White (facts), Red (intuition), Black (caution), Yellow (benefits),
Green (alternatives), and Blue (process) in turn, then summarise." < /dev/null

When to use agy vs Codex: agy is a useful independent third model for architecture analysis, codebase review (add paths with --add-dir), and multi-methodology brainstorming. Codex excels at focused code review, devil's advocate challenger work, and prototype exploration.

Converging Triple-Model Findings

When collecting results, the lead MUST:

1. Read Claude challenger output AND Codex challenger output ($CODEX_WORK/challenger.md) AND agy analyst output
2. Read Codex approach exploration ($CODEX_WORK/approach.md)
3. Identify where models agree (high confidence) vs disagree (needs deeper analysis)
4. Flag disagreements to the user: "Claude, Codex, and agy disagree on X — here are all perspectives"
5. Weight all model findings equally — each has different blind spots and strengths
6. agy findings that cite real-world precedents — flag these as evidence (and verify per Stage 1.5)

Codex Escalation (When Claude Is Stuck)

When Claude agents fail to solve a problem after 2+ attempts or enter circular reasoning:

Primary: Use /codex:rescue (managed job with resume capability):

/codex:rescue "Claude agents are stuck on [PROBLEM]. Tried: [APPROACHES]. Blocker: [ISSUE]. Need a fresh approach — challenge the assumptions that led to the dead end."

Fallback: Raw codex exec (for custom briefs):

CODEX_WORK=$(mktemp -d /tmp/codex-XXXXXXXXXX)

cat > "$CODEX_WORK/escalation-brief.md" << 'BRIEF'
# Escalation: Claude agents are stuck on [PROBLEM]

## What was tried
[LIST APPROACHES THAT FAILED AND WHY]

## The specific blocker
[DESCRIBE THE EXACT ISSUE]

## Project context
[KEY FILES, ARCHITECTURE]

## What we need
A fresh approach to solve this. Don't repeat what was already tried.
Think differently — challenge the assumptions that led to the dead end.
BRIEF

timeout 600 codex exec --ephemeral -C "$PROJECT_DIR" -s read-only \
  -o "$CODEX_WORK/escalation-result.md" \
  "Read $CODEX_WORK/escalation-brief.md and provide a fresh solution." < /dev/null || echo "CODEX_TIMEOUT: Codex did not respond within 600s" > "$CODEX_WORK/escalation-result.md"

Escalation Termination

Max escalation chain: Claude 2 attempts -> Codex 1 attempt -> user.

If Codex escalation also fails or times out:

1. Present the problem to the user with ALL attempted approaches
2. Include what Claude tried, what Codex tried, and why both failed
3. Ask the user for direction
4. Do NOT retry automatically. Do NOT loop back to Claude.

Step 3: Present Design

After convergence:

• Present design in sections scaled to complexity
• Ask after each section: "Does this look right so far?"
• Cover: architecture, components, data flow, error handling, testing approach, performance considerations
• Always include a UX section for UI-facing work
• If came_from_avengers: surface the avengers_brief.dissent[] entries verbatim in the presentation — attributed to the seat, with each entry's trip-wire. Do NOT summarize or drop them; the user judges the design with the deliberation's dissent in view (mirrors the founder minority-report surfacing).
• Be ready to revise based on user feedback

Step 4: Write Design Doc

• Save to docs/plans/YYYY-MM-DD-<topic>-design.md
• Update history.md and index.md
• Shut down design exploration team (if created)

Contract Map Generation (Step 8a)

Step 8a.0: Emit + corroborate the classification artifact (S042 / #115)

BEFORE deciding whether to build a map, forge MUST write .forge/classification.json (schema contract-classification.v1) — the recorded classification that travels with the cycle, analogous to the signed contract map. This closes the bare-Contract map: N/A hole at the producer side (not just bob's front door).

The artifact states:

• introduces_components: "yes" | "no"
• reason_code: a value from the closed enum {skill_text, doc_only, direct_bugfix, refactor, self_contained_meta_helper, sidecar_telemetry, agent_text, existing_component_extension} — NOT free-text (free-text reasons are a loophole).
• design_doc, planned_globs, evidence (confirmed_positives / negatives / prose_only).

Forge may hand-write it, or derive a default via the helper:

python3 ~/.claude/skills/_meta/classify_emit.py "<project_root>" \
  --design-doc "<design-doc-path>" --classified-by forge_design \
  --files-from "<planned-file-touch-list>"

Then forge locally runs G_CLASSIFY to fail-fast at design time (catch a misclassification before bob is ever spawned):

python3 ~/.claude/skills/_meta/gates.py G_CLASSIFY "<project_root>" \
  --design-doc "<design-doc-path>" \
  --asserted "<N/A if introduces_components==no, else provided>" \
  --files-from "<planned-file-touch-list>"

• Exit 0 → classification corroborated; proceed.
• Exit 2 → the scan contradicts the artifact (named signals). Fix the design/classification before continuing; do NOT hand bob a false N/A.
• Exit 3 → ambiguous; resolve with the user before spawning bob.

The artifact is a CLAIM the gate re-derives and corroborates — never trusted (the threat model includes a buggy/drifting producer). existing_component_extension makes the Ship-of-Theseus case (appending component logic into existing allowed files) a declarable, checkable category rather than a silent dodge.

Step 8a.1+: Build the signed contract map (component cycles only)

When a design introduces components (new services, modules, APIs, integration points), forge MUST produce a signed contract map BEFORE invoking the spec review (Step 8b) and before spawning bob.

Pure refactors, bugfixes, and single-file changes with no new components are exempt.

Step 8a.1: Invoke component-contract-mapping

Invoke the component-contract-mapping skill with:

1. The draft design doc path
2. Relevant PROJECT.md and COMPONENT.md paths
3. The user's spoken intent from design dialogue

The skill will:

1. Extract components from the design discussion
2. Define types dictionary with semantic_type per field (from the v1 18-type registry)
3. Write progress/contract-map.yaml (single writer — only ever written here)
4. Run G2 validation locally by invoking python -m gates G2 progress/contract-map.yaml
5. Auto-render a markdown table into the design doc
6. Request forge to sign the map

If G2 validation fails, fix the design doc (not the YAML — the skill rewrites it from the design doc). Re-invoke the skill. Bob will refuse to execute without a valid signed contract map.

Step 8a.2: Emit session material and sign

Forge is responsible for the session material and the signing payload.

# Create session material once per forge session (idempotent)
mkdir -p .forge
[[ -f .forge/session-id ]] || uuidgen > .forge/session

…(truncated)