Agentic handbook overhaul

[kalambet]

Agentic handbook overhaul

Rebuilds the ChainSafe Engineering Handbook from a Docusaurus/GitBook documentation site into a flat, agent-first handbook written for both humans browsing on GitHub and AI agents consuming it via MCP / llms.txt.

Why

The premise of the rewrite: engineering practices are a competitive asset, AI agents are now first-class users of those practices, and the handbook should be authored for both audiences. The old site was a human-only Docusaurus build; this PR drops the web-app tooling and reorganizes the content into a structure agents can load as context and humans can read directly.

What changed

New structure

• operating-model/ — the operator/agent contract: collaborator statement, gates & escalation, model & tool selection, MCP/llms.txt, memory conventions.
• invariants/ — engineering invariants, the .invariants framework (deep-linked, not duplicated), and agent-era invariants.
• workflows/ — PR authoring, code review, repo & CI setup, testing & QA, infrastructure & DevOps, incident response, release & deploy, OneFlow.
• languages/ — per-ecosystem guidance (Go, Rust, TypeScript, Solidity, Daml, Python, Zig), each split into architect / developer / reviewer roles plus shared idioms.md and gotchas.md.
• skills/ — 18 packaged Anthropic Skills (per-language architect/developer/reviewer, code review, PR author, research-plan-implement) authored via skill-creator.
• references/ — attribution, sources, contributors.
• career/ — career ladders, 360-review cadence, and people-process reference (moved out of the engineering core).

New top-level guiding documents

• VISION.md — company mission, vision, values.
• PRINCIPLES.md — General Engineering Principles (ten principles).
• AGENTS.md / CLAUDE.md — agent entrypoint: read-order, escalation rules, operator contract.
• README.md — rewritten as the human entrypoint.
• llms.txt, NOTICE — agent discovery and third-party attribution.

Tooling

• Removed the Docusaurus stack: docusaurus.config.js, sidebars.js, babel.config.js, tsconfig.json, package.json, yarn.lock, src/, static/, and the old docs/ tree.
• Added link checking via lychee (lychee.toml, .lycheecache, .github/workflows/link-check.yml), a skills-sync check (scripts/check-skills-sync.sh, .github/workflows/skills-sync.yml), and a skill-description tuning workflow.
• Updated .github/CODEOWNERS for the new layout.

Scale

169 files changed (+11,063 / −15,082). The deletions are almost entirely the removed Docusaurus build and the migrated GitBook content; the additions are the new agent-first content and skills.

Attribution

Third-party content (the chainsafe-research-plan-implement skill adapted from Boris Tane; the Forest AI policy originally adapted from Ghostty) is credited in NOTICE and inline, per Section 4(d) of the Apache 2.0 License.

Review notes

• Start with AGENTS.md and operating-model/collaborator-statement.md to understand the new contract model.
• README.md "How it's organized" is the fastest map of the new directory structure.
• Content was aggregated from existing org practices with original authors credited via CODEOWNERS and inline headers.

Generated with Claude Code reviewed and edited by a human.