git:20260910.f04b7b8 to git:20260910.4c09ccc

# AGENTS.md

This file is the shared cross-tool entry point for AI coding agents working on cladding (OpenAI Codex, Cursor, Cline, Aider, Continue, GitHub Copilot, Gemini CLI, JetBrains Junie, Windsurf, and other [agents.md](https://agents.md/) hosts). [`CLAUDE.md`](CLAUDE.md) is the Claude Code maintainer addendum; it does not replace this shared contract or `GOVERNANCE.md`.

## 1. Project

cladding is the reference implementation of the [Ironclad](https://github.com/qwerfunch/ironclad) standard. Multi-agent dev harness; 15 Iron Law stages; 41 drift detectors; polyglot toolchain (9 languages). Successor to harness-boot.

## 2. Setup

End-user install:

```

npm install -g cladding

```

Contributor install (clones the repo and pulls dev dependencies):

```

git clone https://github.com/qwerfunch/cladding && cd cladding && npm install

```

## 3. Verify before pushing

Run all four. The first three must pass cleanly; the fourth must be green (the 15-stage gate) on a clean working tree.

```

npm test

npm run typecheck

npm run lint

node bin/clad.mjs check

```

## 4. Code & comment style

Apply [Google Style Guides](https://google.github.io/styleguide/) for every language cladding supports, and the comment policy summarised below. The full per-language table and the six comment principles live in [`docs/code-style.md`](docs/code-style.md) — that's the SSoT; this section is the entry pointer.

Comment policy in one paragraph: *why* over *what*, full doc-tag set on every export (TSDoc / JSDoc / pydoc / rustdoc / godoc / Javadoc), spec linkage via `@see spec/features/F-NNN.yaml AC-NNN` or `@see ironclad-design/<section>.md` whenever a decision traces to an external source, explicit invariants when non-obvious, self-documenting code first, no TODO markers / no date-bound notes / no comments that paraphrase the code.

## 5. PR policy

Branch off `develop`, never `main`, and open ordinary PRs against `develop`. A release uses a `develop → main` PR merged with a merge commit, followed by the mandatory `main → develop` back-merge. Full contract: `GOVERNANCE.md` §3–4.3 and `CLAUDE.md`.

## 6. Agent personas

cladding ships five persona definitions under `src/agents/`. **Planning intents** (deciding scope · drafting acceptance criteria · drawing a roadmap) are planner-territory (the persona formerly named `librarian`) and surface through natural language to the host AI tool, not through a fixed CLI verb. Execution itself is no longer a cladding verb: 0.10.0 retired the headless loop, so `clad serve` publishes the spec and the gates over MCP and the host AI owns carrying an already-defined plan out.

Each file is markdown with a YAML frontmatter that declares two parallel keys:

- `tools:` — the Claude Code subagent tool enum.

- `capabilities:` — the provider-agnostic capability set (`read`, `write`, `edit`, `exec`, `dispatch`).

Non-Claude-Code hosts (Cursor, Cline, Continue, …) should map `capabilities:` onto their own permission model and ignore `tools:`.

## 7. Multi-host policy

cladding does **not** require an API key by default. The default agent dispatch mode is `host` — cladding runs inside the user's existing AI tool (Claude Code with the Max/Pro subscription, Cursor, Cline, Continue, generic-MCP, …) and the host environment handles the LLM call.

The only place cladding itself reads a provider key is the onboarding scan fallback: `src/cli/scan/dispatcher.ts` lazily requires `@anthropic-ai/sdk` with `ANTHROPIC_API_KEY` when no host sampling server is registered. Every other execution path is owned by the host AI. Full roadmap: `docs/multi-provider-roadmap.md`.

## 8. Soft Shell rule

User-facing output uses business language: feature titles ("Login flow"), stage names ("Drift", "UAT"), plain sentences. Internal identifiers (`F-NNN`, `AC-NNN`, `stage_X.Y`, `HUMAN_REQUIRED` and the rest of the halt enum) belong in the audit log and behind `--internal` / `--json` flags.

Convert every internal id at the user surface boundary via `src/ui/softShell.ts`: `featureLabel(featureId, spec)` and `gateLabel(stageId)`. Background: `ironclad-design/03-ux-routing.md` §1.2 and `docs/ux-routing-coverage.md`.

## 9. Where to look

- `GOVERNANCE.md` — sync policy, versioning, contributor policy, PR contract, v1.0 graduation criteria.

- `CONTRIBUTING.md` — first-PR walkthrough.

- `CODE_OF_CONDUCT.md`, `SECURITY.md` — community standards + private security reports.

- `docs/design/spec-0.2.md` — accepted 0.10.0 continuation router; read it, then load only the task-routed canonical file under `docs/design/spec-0.2/` (implementation is still pending).

- `docs/code-style.md` — per-language Google Style Guides table + comment policy in full.

- `docs/ux-routing-coverage.md` — applied-status of `ironclad-design/03-ux-routing.md` prescriptions.

- `docs/multi-provider-roadmap.md` — host vs sdk adapter model + adapter matrix + how to add one.

- `src/agents/` — five persona definitions.

- `spec/` — sharded SSoT (features × scenarios × architecture).

- `src/stages/detectors/README.md` — drift detector inventory + status policy.

- `conformance/` — contributor self-audit tool (`npm run conformance` after a dev install). The end-user install does not ship it; the L1–L4 conformance claim travels through release notes instead.