ArcKit Build Harness (v0.4)

Operating principles

• Never read or write artefact content in main context. That's what subagents are for.
• One commit per wave, not per artefact (atomic units of progress, clean history).
• Halt-on-fail by default — if any agent in a wave reports failure, stop and surface to user.
• State is sacred — update

  projects/{P}-{NAME}/.arckit/state.json

  after every wave, before moving on.
• Single message, multiple Agent calls for parallelism within a wave. Never loop sequential Agent calls.
• Idempotency: if state says

  complete

  , the file exists at the recorded path, AND every input file's SHA-256 matches the hash recorded at build time, skip. Otherwise the target is stale — rebuild it (and propagate staleness through the DAG). See § "Input-hash change detection".
• Trust the path-allocation hook. ArcKit's

  validate-arc-filename.mjs

  PreToolUse hook is the authoritative path normalizer — it allocates sequence numbers, applies subfolders, pads project IDs at write time. The orchestrator and workers never construct paths by string substitution or call

  generate-document-id.sh

  directly. Read the corrected path back from the Write tool result.

Args

<project>

001

001-arckit-saas

--plan

--resume

--target NAME

--refresh NAME

--no-commit

--recipe NAME

uk-saas

--enable ID

--enable AIP

--exclude ID

--exclude SVCASS

--skip-hash-check

complete

Recipe loading

--recipe NAME

1. Project override:

   .arckit/recipes/{NAME}.yaml

   — user customizations preserved across plugin updates.
2. Core plugin:

   ${CLAUDE_PLUGIN_ROOT}/skills/arckit-build/recipes/{NAME}.yaml

   — recipes shipped with the

   arckit

   core plugin (

   uk-saas

   ,

   uk-mod-sovereign

   ).
3. Sibling community plugins:

   ${CLAUDE_PLUGIN_ROOT}/../arckit-*/recipes/{NAME}.yaml

   — recipes shipped with installed community plugins (e.g.

   arckit-uae/recipes/uae-federal-ai.yaml

   ,

   arckit-ca/recipes/ca-federal-fitaa.yaml

   ).

${CLAUDE_PLUGIN_ROOT}

arckit-*/recipes/{NAME}.yaml

uk-saas

.arckit/recipes/uk-saas.yaml

mkdir -p .arckit/recipes
cp "${CLAUDE_PLUGIN_ROOT}/skills/arckit-build/recipes/uk-saas.yaml" .arckit/recipes/uk-saas.yaml

uk-saas

arckit

uk-mod-sovereign

arckit

mod-secure

jsp-936

uae-federal-ai

arckit-uae

uae-agentic-transformation

arckit-uae

ca-federal-fitaa

arckit-ca

au-federal

arckit-au

au-energy

arckit-au-energy

arckit-au

SERVICE_INVENTORY

servicenow

uk-nhs-clinical-safety

arckit

arckit-uk-nhs

Recipe schema (v1)

${CLAUDE_PLUGIN_ROOT}/skills/arckit-build/recipes/uk-saas.yaml

• recipe

  — recipe name (string, must match filename stem)

• schema_version

  — recipe schema version (currently

  1

  )

• description

  — free text

• defaults.version

  — default version stamp for outputs (e.g.

  "1.0"

  )

• optional_targets

  — map of target ID →

  {description, default}

• post_build_hooks

  — list of

  {skill, args}

  to run after final wave (parallel)

• targets

  — list of target entries

targets[]

id

PRIN

ADR-001

DIAG-C4

skill

arckit:requirements

args

output.project

"000-global"

"{P}-{NAME}"

output.type

PRIN

REQ

ADR

DIAG

output.subfolder

--plan

validate-arc-filename.mjs

SUBDIR_MAP

output.multi_instance

MULTI_INSTANCE_TYPES

topic

{TOPIC}

deps

"ADR-*"

output.subfolder

output.multi_instance

--plan

subfolder: decisions

Variable substitution

args

output.project

{P}

"001"

{NAME}

"arckit-saas"

{V}

defaults.version

{TOPIC}

target.topic

Dep resolution

deps: ["ADR-*"]

ADR-

Input-hash change detection

test -f

What counts as an input

deps

external/policies/*.md

source: "pre-existing"

What's recorded

input_hashes

"RISK": {
  "status": "complete",
  "path": "projects/001-arckit-saas/ARC-001-RISK-v1.0.md",
  "input_hashes": {
    "REQ":  "9f2a...c41e",
    "STKE": "1b88...07ad",
    "PRIN": "44e7...bc92"
  },
  ...
}

sha256sum

complete

Staleness rules (skipped if

--skip-hash-check

)

1. Start with

   done = { t ∈ state.targets : t.status == "complete" AND test -f t.path }

   .
2. Direct staleness: for each

   t ∈ done

   , recompute SHA-256 for every entry in

   t.input_hashes

   . If any current hash differs from the recorded value (or the input file is now missing),

   t

   is stale — move it from

   done

   back into pending and clear it from

   state.targets[t].status

   (set

   "stale"

   ).
3. Propagated staleness: walk the DAG; any target whose deps (transitively) include a stale target is itself stale. Apply in topological order so a single REQ edit cascades to RISK, HLD, SOBC, PLAN, TRACE, …
4. Targets explicitly named in

   --refresh NAME

   are marked stale unconditionally (existing behaviour — overrides hash check).
5. With

   --skip-hash-check

   , skip steps 2–3 entirely.

   done

   is whatever survives the

   test -f

   filter.

--plan

Wave 1: REQ
  (stale) REQ ← file edited since last build (sha mismatch)
Wave 3: RISK, HLD, STRATEGY, ...
  (stale-cascade) RISK ← REQ changed since 2026-05-12T10:14:03Z

Performance note

--resume

Wave plan algorithm

1. pending = recipe.targets ∩ enabled - done

   — where

   enabled

   reflects

   --enable

   /

   --exclude

   flags and

   optional_targets[id].default

   , and

   done

   is computed by the staleness rules in § "Input-hash change detection" (i.e.

   complete

   AND

   test -f

   AND every input hash matches, unless

   --skip-hash-check

   is set). Stale targets stay in

   pending

   .

2. done

   from staleness computation above.
3. While pending non-empty:

   • wave = { t ∈ pending : deps(t) ⊆ done }

     (after expanding globs)
   • If wave empty → cycle / unresolvable. Halt with error, list involved targets.
   • Emit wave; remove its members from pending; (after dispatch + validate) add to done.

• W0: PRIN
• W1: GLOSSARY, REQ, STKE
• W2: ADR-001..ADR-008 (parallel)
• W3: STRATEGY, WARDLEY, RISK, HLD, DEVOPS, FINOPS
• W4: SOBC, TCOP, SBD, DPIA, DIAG-C4, DIAG-SEQ
• W5: DIAG-DEP, PLAN, OPS, AIP (if enabled)
• W6: ROADMAP
• W7: SVCASS
• W8: TRACE
• W9 (post-build): health, pages

Per-wave execution

1. Plan dispatch

Wave {N}/{total}: {targets joined}
  - estimated agents: {len(wave)}
  - estimated duration: ~2-5 min wall-clock per agent (parallel)

2. Single message, multiple Agent calls — all in parallel

subagent_type: "general-purpose"

{...}

You are an ArcKit artefact worker subagent (orchestrated by arckit-build, wave {WAVE_N}).

Project: {PROJECT_ID} ({PROJECT_NAME})
Target: {TARGET_ID}
Skill to invoke: {SKILL}
Skill args: {ARGS_RESOLVED}
Expected directory: {EXPECTED_DIR}     # for orientation only — actual filename is hook-allocated

Inputs you may read (only these):
{INPUT_PATHS_BULLETED}

Steps:
1. Use the Skill tool to invoke `{SKILL}` with the args above verbatim.

   **Interactive Q&A handling (CRITICAL — subagents have no user available):**
   If the skill calls `AskUserQuestion`, you MUST select the option marked `(Recommended)`
   without asking. If no option is marked Recommended, use these defaults:

   | Question header | Default |
   |-----------------|---------|
   | Scope | `Full system` |
   | Consultation | `Surveys` |
   | Phase | value from skill args, else `alpha` |
   | AI mode / scope | derive from REQ FRs (AI-in-scope iff any FR mentions AI/ML/LLM) |
   | Risk appetite | `Medium` |
   | Anything else | first option in the list |

   Document the choice you made in your final report so the orchestrator can record it.
   Never block waiting for an answer.

2. Capture the actual file path the skill wrote to. Inside the Write tool call,
   the ArcKit `validate-arc-filename.mjs` PreToolUse hook normalizes the path
   (allocates the next sequence number for multi-instance types like ADR/DIAG,
   moves into the correct subfolder, pads project IDs). The hook returns the
   corrected path as `updatedInput.file_path` and the actual write proceeds
   there. You will see this corrected path in the Skill tool's result.

   Read `ACTUAL_PATH` from that result. Do NOT call `generate-document-id.sh`
   yourself or construct paths by string substitution — the hook is the
   authoritative path allocator.

3. Sanity check the corrected path via Bash:
   - `test -f "$ACTUAL_PATH"` returns success
   - `[ "$(wc -l < "$ACTUAL_PATH")" -gt 100 ]`
   - `grep -c '^## Document Control\|^| Document ID' "$ACTUAL_PATH"` returns ≥ 1

4. Do NOT git commit. Do NOT modify other files. The orchestrator handles version control.

Report back ≤ 200 words:
- Actual file path written + exact line count
- Top 3 findings, scores, or RAG ratings (whatever the skill produces as headline result)
- Validation result: PASS or FAIL (with reason)
- Any failures, partial completions, or warnings
- AskUserQuestion choices made (if any)

Do NOT include the document content in your report. Just the summary.

3. Wait for all agents

4. Validate

• File exists at expected path (

  test -f

  ).
• Line count > 100 (

  wc -l

  ).
• Document control header present (

  grep -c '^## Document Control'

  ≥ 1).

5. Update state.json

projects/{P}-{NAME}/.arckit/state.json

{
  "<TARGET_ID>": {
    "status": "complete",
    "path": "{ACTUAL_PATH}",
    "built_at": "{ISO_TIMESTAMP}",
    "wave": {WAVE_N},
    "line_count": {LC},
    "skill": "{SKILL}",
    "topic": "{TOPIC_OR_NULL}",
    "agent_summary": "{≤200-word agent report}",
    "input_hashes": {
      "<DEP_ID>": "{SHA256_OF_state.targets[DEP_ID].path}"
    }
  }
}

input_hashes

sha256sum

state.targets[DEP_ID].path

input_hashes: {}

status: "failed"

error: "..."

wave: {WAVE_N}

input_hashes

6. Git commit

--no-commit

git add {OUTPUT_PATHS} projects/{P}-{NAME}/.arckit/state.json
git commit -m "$(cat <<'EOF'
Build wave {N}: {targets joined} via arckit-build

{One-line per target with line count and headline result}

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"

7. Halt-on-fail

FAIL

• DO write state.json — record

  status: "failed"

  ,

  error: "..."

  ,

  wave: {WAVE_N}

  for failed targets, and

  status: "complete"

  for the targets in the wave that did succeed. State is needed for

  --resume

  .
• Do NOT git commit (don't half-commit a wave). Successfully-written artefacts are left in the working tree; they get bundled into the resume commit.
• Surface to user: per-target outcome, error summary, suggested remediation.
• Suggest

  --resume

  once fixed.
• Stop the build.

8. Move to next wave

State file shape

projects/{P}-{NAME}/.arckit/state.json

{
  "state_format_version": "0.4",
  "project_id": "001",
  "project_name": "001-arckit-saas",
  "recipe": "uk-saas",
  "recipe_path": ".claude/skills/arckit-build/recipes/uk-saas.yaml",
  "started_at": "2026-05-03T16:00:00Z",
  "last_wave_completed": 5,
  "current_wave": 6,
  "targets": {
    "PRIN":   {"status": "complete", "path": "projects/000-global/ARC-000-PRIN-v1.0.md", "wave": 0, "source": "pre-existing", "input_hashes": {}},
    "REQ":    {"status": "complete", "path": "...", "wave": 1, "source": "pre-existing", "input_hashes": {"PRIN": "44e7...bc92"}},
    "RISK":   {"status": "complete", "path": "...", "wave": 3, "skill": "arckit:risk", "input_hashes": {"REQ": "9f2a...c41e", "STKE": "1b88...07ad", "PRIN": "44e7...bc92"}},
    "SVCASS": {"status": "pending"}
  },
  "waves": [
    {"n": 0, "targets": ["PRIN"], "status": "complete", "completed_at": "..."},
    {"n": 3, "targets": ["RISK", "STRATEGY"], "status": "complete", "completed_at": "..."}
  ]
}

state_format_version: "0.3"

input_hashes

state_format_version

"0.4"

When invoked, perform these steps in order

1. Parse arguments from skill input (project, --plan, --resume, --recipe, --enable, --exclude, etc.). If project not specified, ask user.
2. Detect project: resolve

   <project>

   arg →

   projects/{P}-{slug}/

   . Confirm directory exists.
3. Load recipe: resolve

   --recipe NAME

   (default

   uk-saas

   ) against the precedence list. Read the YAML with the Read tool. Validate top-level shape (

   recipe

   ,

   schema_version

   ,

   targets

   ,

   defaults.version

   ). Halt with a clear error if the recipe file is missing or malformed.
4. Resolve enabled targets: drop

   optional_targets

   whose

   default: false

   unless

   --enable ID

   was passed; drop

   optional_targets

   named in

   --exclude ID

   . Apply

   {P}/{NAME}/{V}/{TOPIC}

   substitution to every

   args

   and

   output.project

   field.
5. Load state.json at

   projects/{P}-{NAME}/.arckit/state.json

   . If absent, scan project dir for existing

   ARC-{P}-*-v*.md

   files and infer initial state.
6. Subagent capability smoke-test (first wave only, skip on

   --resume

   ): before dispatching the real wave, spawn one throwaway

   general-purpose

   Agent with this prompt:

   "Examine your system-reminder messages — they enumerate the skills available in this conversation. Return exactly one line:

   • AVAILABLE

     if the list contains

     arckit:principles

     (or any other

     arckit:*

     skill).

   • NOT_AVAILABLE

     otherwise. Do NOT invoke any skill. Do NOT call any tool other than reading your own context."

   This is a metadata check, not a skill invocation — it should complete in seconds. If the response is

   NOT_AVAILABLE

   , halt: subagents in this session do not have access to plugin skills (Failure mode #1). Suggest enabling the plugin at user-scope or running the harness from a session where

   claude --print '/skill list'

   shows the

   arckit:*

   family.
7. Compute work list: apply the staleness rules from § "Input-hash change detection".

   done

   = targets where

   status: complete

   AND file exists AND every recorded input hash still matches AND no transitive dep is stale (steps 2–3 of the staleness rules).

   pending

   =

   enabled-targets − done

   . Stale targets have their

   state.targets[id].status

   rewritten to

   "stale"

   and re-enter the wave plan. With

   --skip-hash-check

   , skip the hash + cascade checks (

   test -f

   only).
8. If

   --plan

   : print plan (each wave + targets + line

   (skip|build) target ← deps

   ), exit.
9. For each wave (sequential outer loop):
   • Print wave header.
   • Build the per-agent prompt for each target in wave.
   • Send a single assistant message containing N Agent tool calls (one per target, all parallel).
   • Collect summaries when all complete.
   • Validate each output.
   • Update state.json (Write tool).
   • git commit (Bash) unless

     --no-commit

     .
   • Halt if any fail.
10. Post-build hooks: spawn parallel agents — one per

    recipe.post_build_hooks[]

    entry.
11. Final report:
    • Targets built (with line counts) / skipped / failed.
    • Total wall-clock.
    • Post-build hook outcomes.
    • Next recommended action (e.g., "review pre-GA blockers in TCOP §Critical Issues").

Pairing with

/goal

(Claude Code v2.1.139+)

/goal

• "Build until APPROVED" —

  /goal every artefact under projects/001-*/ has Document Control Status: APPROVED and no Next Review Date in the past

  , then run

  /arckit:build 001 --recipe uk-saas --resume

  . The harness rebuilds stale targets;

  /goal

  keeps re-running it until the post-condition holds.
• "Refresh a stale slice" —

  /goal no artefact under projects/001-*/ has been flagged by the stale-artifact-scan monitor

  , then

  /arckit:build 001 --refresh REQ

  (or whichever target the monitor flagged).
• "Drive a project to GA" — wrap the build under a goal that also requires zero open

  /arckit:conformance

  violations and a green

  /arckit:health

  scan;

  /goal

  will sequence

  build → conformance → health → refresh-violator → build

  until clean.

• /goal

  is Claude Code only (not exposed in Codex / OpenCode / Gemini). Document the manual loop ("re-run

  /arckit:build --resume

  until state.json shows all targets complete") for non-Claude runtimes.
• Stop-hook block cap (v2.1.143, default 8) applies — if a Stop hook keeps blocking inside the goal loop the turn ends with a warning. ArcKit's Stop hooks (

  session-learner

  ,

  session-end-stamp

  ) are observational and never block, so the cap should not interfere.
• One

  /goal

  per session; don't nest. The harness's own halt-on-fail still fires inside the goal loop.

Failure modes to watch for

• Subagent doesn't have access to

  arckit:*

  skills — detected by the smoke-test in step 6 of the run order; halts the build before any wave dispatches. Workaround if smoke-test fails: load the skill prompt in main context once, pass as plain text to agent (deferred to v0.4+).
• Recipe file missing or malformed — halt at step 3 with the exact YAML parse error and the precedence list of paths checked. If a community recipe is requested but the corresponding community plugin isn't installed, surface a concrete install command:

  "Recipe 'uae-federal-ai' not found. It ships in the arckit-uae community plugin. Install with: claude plugin install arckit-uae"

  . The orchestrator maps recipe name to expected plugin via the built-in recipes table; recipes the table doesn't know about fall back to the generic precedence-list error.
• Skill expects interactive Q&A — the worker prompt's defaults table covers this. The recipe's

  args

  field should be specific enough to skip interaction in the first place.
• Output path collision — two targets writing to same path. Recipe must have unique

  (output.project, output.type, output.subfolder, multi_instance)

  tuples for non-multi-instance targets, and unique

  id

  s for multi-instance ones.
• State drift — user manually deletes/edits artefacts after build. Deletions are caught by

  test -f

  . Edits are caught by the SHA-256 hash check (§ "Input-hash change detection") — the edited artefact's downstream targets are marked stale and rebuilt in dep order. Use

  --skip-hash-check

  to bypass.
• Cycle in dependencies — wave algorithm halts with "unresolvable cycle" error and lists the involved targets. Glob deps (

  ADR-*

  ) are expanded before cycle detection.

Future versions

• v0.4 (remaining): orchestrator-side fallback for skills inaccessible to subagents — load

  arckit:*

  skill prompts in main context once and inline them in worker prompts when the smoke-test returns

  NOT_AVAILABLE

  . (File-hash change detection shipped in v0.4 — see § "Input-hash change detection".)
• v0.5: cross-reference + schema validators between waves; recipe inheritance (

  extends: uk-saas

  ); hash external inputs (e.g.

  external/policies/*.md

  ) in addition to dep artefacts.
• v0.6: CI mode (

  --validate-only

  for GitHub Actions).
• v1.0: skills declare I/O in frontmatter; harness reads frontmatter directly; dedicated

  arckit:artefact-worker

  subagent type; recipe "Expected output path" computed from skill metadata (single source of truth).