# Build

> Use when starting any feature development, building new functionality, implementing a design, or going from idea to working code. Triggers on "build", "implement", "add feature", or any task requiring design-through-execution.

- **Type:** Skill
- **Install:** `agentstack add skill-raddue-crucible-build`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [raddue](https://agentstack.voostack.com/s/raddue)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [raddue](https://github.com/raddue)
- **Source:** https://github.com/raddue/crucible/tree/main/skills/build

## Install

```sh
agentstack add skill-raddue-crucible-build
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Build

## Overview

All subagent dispatches use disk-mediated dispatch. See `shared/dispatch-convention.md` for the full protocol.

All subagent returns use the Ledger Return Protocol. Every subagent returns exactly one Evidence Receipt per `shared/return-convention.md`; the orchestrator applies the two-tier receipt linter (Tier 1 structural + Tier 2 witness verification — full grammar in the shared convention) to every Task return before acting on the declared VERDICT. The linter is a deterministic runtime tool: orchestrators MUST run `python3 scripts/rcpt_verify.py --tier2 --strict --root  --ledger /receipt-ledger.jsonl ` on every received receipt before acting on its VERDICT, and apply the shared convention's in-context pseudocode ONLY as the fallback when the tool is unavailable (`--strict` hard-FAILs only resolvable paths; an unresolvable bare basename is UNVERIFIABLE, never a false FAIL). A lint failure is treated as structurally `BLOCKED`.

The orchestrator maintains a per-run Invariant Cairn at `~/.claude/projects//memory/cairn/cairn-.md` per `shared/cairn-convention.md`. See the `## Cairn (Layer 3)` section below for build-specific phase definitions, terminal condition, and mandatory-invariant categories.

End-to-end development pipeline: interactive design, autonomous planning with adversarial review, team-based execution with per-task code and test review. One command, idea to completion.

**Announce at start:** "I'm using the build skill to run the full development pipeline."

**Session index event:** At startup, if session indexing is active (session index path discoverable via glob), emit a `skill_start` event to the outbox: `{"ts":"","seq":0,"type":"skill_start","summary":"Starting /build for ","detail":{"skill":"build","goal":""}}`. See `skills/shared/session-index-convention.md` for the outbox pattern.

**Guiding principle:** Quality over velocity. This pipeline produces correct, well-integrated, maintainable output — even if slower. Parallel execution is available for independent work, but sequential with quality gates is the default.

## Mock Dispatch Mode (eval-gate)

This mode exists for the `skills/build/evals/` eval-gate harness. It is enabled **iff** `CRUCIBLE_BUILD_EVAL_MOCK_DIR` is set in the environment. Production runs MUST leave this variable unset, in which case this mode is a no-op and the orchestrator behaves exactly as if this section were not present.

**Env-var contract.** Three variables, all consumed only when `CRUCIBLE_BUILD_EVAL_MOCK_DIR` is set:

- `CRUCIBLE_BUILD_EVAL_MOCK_DIR=` — directory of canned subagent return receipts. Filenames follow `-.md` with fallback `.md` (e.g. `1-plan-writer.md`, then `plan-writer.md`). Missing mock → halt immediately with a clear error; no silent fallthrough.
- `CRUCIBLE_BUILD_EVAL_MODE=feature|refactor` — pre-set answer to the Mode Detection prompt. When present, the orchestrator skips the AskUserQuestion call in Mode Detection and uses this value.
- `CRUCIBLE_BUILD_EVAL_USER_INPUT_DIR=` — directory of canned user-input turns, named `turn-.md`. Each AskUserQuestion call (other than Mode Detection, which uses `CRUCIBLE_BUILD_EVAL_MODE`) consumes the next sequential turn. If the next turn-file is missing, halt before proceeding — this is the b4 fixture's design: build correctly stops when it needs input it does not have.

**Substitution rule (defined ONCE here; referenced from intercept sites below):** at every dispatch site, the dispatch file is STILL written to the normal dispatch dir (trace integrity preserved). Only the Task/Agent tool invocation is replaced — instead of invoking the tool, read `$CRUCIBLE_BUILD_EVAL_MOCK_DIR/-.md` (or `.md`) and treat its contents as the subagent's return receipt. Apply the normal receipt linter and manifest sweep as if the receipt had come from a live agent.

**Boundary behavior.** `MockNotFound` / `MockUserInputMissing` errors raised by the mock loader halt the build run with a clear stderr message. They do not silently fall through. The eval-gate harness detects these halts via on-disk artifacts (absent phase-handoff manifests, pipeline-active marker still at the original phase) — the harness does NOT catch these exceptions across the build-runtime boundary.

**Pointer reminders.** Sections that reference these env vars (Mode Detection, Phase 1 Step 2 / 2.5 / 3, Phase 2 Step 1 / 2, Phase 3 Step 3) contain short inline pointers back to this section. The substitution rule is defined here only; the pointers exist so a reader scanning a dispatch site doesn't need to re-derive the contract.

**See also:** `skills/build/evals/README.md` for harness usage; `skills/shared/dispatch-convention.md` for the dispatch-file protocol the substitution rule preserves.

## Cairn (Layer 3)

The orchestrator maintains an Invariant Cairn per `shared/cairn-convention.md`. Build-specific bindings:

- **Phase mapping.** The build pipeline's four phases (1 Design, 2 Plan, 3 Execute, 4 Completion) map 1:1 to cairn phases. Mid-phase sub-stages (e.g. Phase 3 Wave N, Phase 4 gate rounds) do NOT get their own cairn phase counter — they are internal to the owning phase and contribute a single LEDGER line when the owning phase completes.
- **Phase transitions.** At every 1→2, 2→3, 3→4 transition, the orchestrator: (a) writes any correctness-critical phase-N invariants, (b) appends the phase-N LEDGER line with `dispatches=/receipts=/verdict=`, (c) single atomic Write advancing PHASE to phase N+1. Uses the phase handoff manifest (`handoff-N-to-M.md`) as input evidence for the invariants.
- **Terminal phase.** Phase 4 sealing — after finish-skill completes and the pipeline-active marker is deleted. At terminal sealing, delete `active-run.md`; leave `cairn-.md` in place.
- **Mandatory-invariant categories for build.** Each phase-exit MUST capture:
  - **Design exit:** the one-sentence architectural commitment, plus any RED-flag constraint surfaced by red-team that later phases must preserve.
  - **Plan exit:** the task list's load-bearing dependencies (e.g. "Task 3 unblocks Tasks 5-7; T2 review tier"); any non-obvious refactoring risk.
  - **Execute exit:** every `noticed-not-touching` entry that is correctness-critical for a future task or for post-merge review; every test-gap finding that the run chose to leave uncovered.
  - **Completion exit:** acceptance-test outcome; siege dispatch decision + outcome; any skipped gate with `Acknowledged: true`.
- **Reconciliation on phase entry.** Runs the full Reconciliation Pass (5 rules) against `receipt-ledger.jsonl` and the in-context Tripwire Manifest. Rule 1 local-repair is authorized for trailing-receipts-in-current-phase LEDGER under-count only.
- **Composition with Phase Handoff Manifest.** The cairn and the existing Phase Handoff Manifest overlap in intent but not in scope: the handoff manifest is a per-transition snapshot of inputs for the next phase; the cairn is the cumulative load-bearing state across the whole run. Both are maintained; neither replaces the other. On Recovery Protocol invocation, the orchestrator reads the cairn first (authoritative for load-bearing state) then the most recent handoff manifest (authoritative for current-phase inputs).

## Tripwire Manifest Sweep (Layer 2)

Starting with convention **v1.1**, every subagent returns a receipt carrying `TRIPWIRE:`, `SUPERSEDES:`, and (if the subagent dispatched children) `TRIPWIRE-CHILD:` lines. The full grammar and predicate vocabulary live in `shared/return-convention.md`. This section defines how the orchestrator uses them.

**Manifest:** After each Task return (post-lint), append one line to the in-context manifest:

```
  /    TRIPWIRE:   [SUPERSEDED_BY=]  [keys=::,…]  [files=:,…]
```

Extract `keys=` and `files=` discriminators at insertion time (severity-max, `*-count` CLAIM keys namespaced by skill; EDIT/WROTE paths with first 6 hex of post-edit hash). Truncate each list at 8; overflow becomes `more=` and forces mandatory fire on `peer-dispatch-disagrees`.

**Sweep (the dispatch-loop clause):** The orchestrator MAY NOT dispatch the next subagent until it has:

1. Applied Layer 1 two-tier linter to the just-returned receipt. Lint failure → re-dispatch, DO NOT sweep.
2. Appended the manifest entry.
3. Processed `SUPERSEDES:` — marked each cited predecessor `SUPERSEDED_BY=`.
4. Evaluated self-checks (verdict=FAIL, exec-exit!=0, suspicion>=N-self) on the new receipt — no Read needed.
5. Evaluated forward-checks against every active (not `SUPERSEDED_BY=*`) prior manifest entry, over the union of that entry's `TRIPWIRE` and `TRIPWIRE-CHILD` predicate sets:
   - `claims-touch(glob)` / `wrote(glob)` / `read(glob)` — path-glob match against the new receipt's TRACE or CLAIMS citations.
   - `suspicion>=N` — new receipt's SUSPICION ≥ N.
   - `peer-dispatch-disagrees()` — same-skill, same-target, discriminator mismatch (evaluated via manifest `keys=`/`files=`; `more=` overflow → mandatory fire).
   - `always` — fires unconditionally.
6. For each firing predicate on manifest entry M, `Read` M's full receipt from disk and narrate the re-read: *"tripwire `` on  fired from ; re-read M."*
7. Only then dispatch the next subagent.

**Supersession fix-flow.** A fix-agent dispatched after a FAIL receipt normally supersedes that FAIL. Its receipt MUST cite the FAIL's hash-prefix in `SUPERSEDES:` and in at least one CLAIM `from=#…`, AND its WITNESS must be `kind ∈ {exec, grep}` with `ran=TRACE#N` (not SKIPPED/UNRUNNABLE). Tier-2 then verifies the witness — supersession only survives if the original failure no longer reproduces.

**Mandatory-work declarations for build's subagent types** (add to each dispatch template's `## Return Format` section):

- Implementer (feature): `run-tests`, `apply-edits`.
- Implementer (refactor, atomic): `run-blast-radius-tests`, `apply-edits`.
- Reviewer (code / test): `read-artifact`, `emit-findings`.
- Cleanup agent: `read-diff`, `emit-recommendation`.
- Plan writer / plan reviewer: `read-design`, `emit-artifact`.
- Acceptance-test writer / test-gap writer / adversarial tester: `run-tests`, `emit-tests`.

## Communication Requirement (Non-Negotiable)

**Between every agent dispatch and every agent completion, output a status update to the user.** This is NOT optional — the user cannot see agent activity without your narration.

Every status update must include:
1. **Current phase** — Which pipeline phase you're in
2. **What just completed** — What the last agent reported
3. **What's being dispatched next** — What you're about to do and why
4. **Task checklist** — Current status of all tasks (pending/in-progress/complete)

**After compaction:** If you just experienced context compaction, re-read the task list from disk and output current status before continuing. Do NOT proceed silently.

**Examples of GOOD narration:**
> "Phase 3, Task 4 complete. Reviewer found 2 Important issues — dispatching implementer to fix. Tasks: [1] ✓ [2] ✓ [3] ✓ [4] fixing [5-8] pending"

> "Phase 2 complete. Plan passed review with 0 issues on round 2. Dispatching innovate on the plan."

**This requirement exists because:** Long-running autonomous pipelines can run for hours. Without narration, the user sees nothing but a spinner. They can't assess progress, can't decide whether to intervene, and can't learn from the pipeline's decisions.

## Pipeline Discipline (Non-Negotiable)

NEVER skip quality gate steps. Every artifact must pass its quality gate before proceeding to the next phase. No exceptions, no shortcuts.

**BLOCK semantics:** Phase transitions are gated. You CANNOT proceed from Phase 1→2, 2→3, or 3→4 without the gate for that phase passing. If a gate fails, fix the issues and re-run the gate. Do not silently skip a gate because "it looks fine" or "we already reviewed it."

**If you find yourself about to skip a gate:** STOP. Re-read this section. The gate exists because skipping it has caused real production incidents and hours of wasted time. Run the gate.

## Anti-Rationalization Table — build

| Rationalization | Rebuttal | Rule |
|---|---|---|
| "This task is small/simple/trivial, the quality gate would just find nits." | Small changes have the same bug density per line as large ones. QG has never run on a Crucible artifact without finding at least one real issue. | Run the quality gate on every phase artifact, regardless of size. |
| "Phase N looks fine, I can skip the gate and move on." | Self-assessment of artifact quality is exactly the bias the gate exists to counter. "Looks fine" is the failure mode, not a pass criterion. | Phase transitions are BLOCKED without a verified PASS verdict marker for the prior phase. |
| "The fix agent addressed the findings, so the gate is done." | Fixing is not passing. Fix rounds routinely introduce new issues or incompletely resolve old ones. A clean verification round is required. | The gate is only complete after a fresh red-team round returns 0 Fatal, 0 Significant. |
| "The user said 'looks good' / 'move on' — that's approval to skip the gate." | General feedback is not skip approval. Only an unambiguous instruction that explicitly references the gate counts. | Require literal `SKIP GATE` (or equivalent explicit phrase) before recording `Status: SKIPPED`. |
| "I can fix this one finding myself instead of dispatching a fix agent." | Orchestrator-applied fixes conflate coordination with remediation and bypass the fix journal. Every fix — even trivial — goes through a fix agent. | Orchestrator never edits the artifact directly; always dispatch the fix agent. |
| "Innovate/red-team seem redundant on top of the quality gate, I'll skip them." | They are not redundant. Innovate is divergent; red-team is adversarial; QG is iterative remediation. Skipping any one of them is a documented regression (`feedback_never_skip_gates`). | Run innovate and red-team on every artifact, every time. |
| "I'll just finish the task list and narrate at the end." | Long-running autonomous pipelines are invisible without narration. Silent runs prevent the user from intervening or learning. | Narrate before every dispatch and after every completion — non-negotiable. |

## Gate Ledger Protocol

Tamper-evident audit trail for phase transitions and gate verdicts. This is defense-in-depth — it raises the cost of gate-skipping from zero to nonzero by requiring structured state to be maintained and verified. An external enforcement hook (`gate-ledger-guard.sh`) provides mechanical enforcement by blocking unauthorized PASS writes.

**File location:** `~/.claude/projects//memory/build-gate-ledger.md`

**Relationship to pipeline-status.md:** pipeline-status.md is ambient user awareness (overwritten at every narration point). build-gate-ledger.md is the gate verdict audit trail (updated per phase as gates pass). Both are needed; neither replaces the other.

### PipelineID Generation

At pipeline start, generate a PipelineID via `date -u +build-%Y%m%d-%H%M%S`. This ID:
- Is persisted in the ledger header
- Is passed to quality-gate invocations as `pipeline_id`
- Is used by the enforcement hook to cross-check verdict markers
- Is unique per build run (timestamp-based)

### Ledger Format

```
# Build Gate Ledger
Run: 
PipelineID: 
Goal: 
Mode: 

## Phase 1: Design
Status: NOT_STARTED

## Phase 2: Plan
Status: NOT_STARTED

## Phase 3: Execute
Status: NOT_STARTED

## Phase 4: Completion
Status: NOT_STARTED
```

**Format constraints:**
- One key-value pair per line: `Key: value`
- Fixed key names: `Status`, `Gate`, `Artifact`, `Tasks`, `Reason`, `Acknowledged`, `PipelineID`
- Status values: `NOT_STARTED`, `IN_PROGRESS`, `PASS`, `COMPLETE`, `FAIL`, `SKIPPED`, `INFERRED`
- Phase headers are `## Phase N: Name` — always 4 phases, always in order
- No prose, no paragraphs, no nested structure

### Ledger Initialization

Runs during build startup, after mode detection but before Phase 1 begins:

1. Check for existing ledger at canonical path
2. If found: run Run Isolation checks (see below)
3.

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [raddue](https://github.com/raddue)
- **Source:** [raddue/crucible](https://github.com/raddue/crucible)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** yes

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-raddue-crucible-build
- Seller: https://agentstack.voostack.com/s/raddue
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.