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 hosts). 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 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

Requires Node ≥ 20 to develop — the test runner and linter need it. The published tool itself runs on Node ≥ 16.

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 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 — 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.