Agentic handbook overhaul#119
Merged
Merged
Conversation
* add "idiomatic rust" to skills * add lychee.toml * address Hubert's comments
* Fix .invariants references to starter kit and plural dotfile name. Rename invariance-framework.md to invariants-framework.md, replace .invariance with .invariants across handbook/skills/llms.txt, point upstream links at boorich/.invariants-starter-kit and GitHub Pages landing, and replace invariance.html with a redirect to the hosted site. * Restore Peter's pointer-page structure. Keep deep-link map shape, inline-rules placeholder, and anchor-TBD rows; add only plural naming and starter kit URLs. * Link pointer page to starter kit policy sections. Replace TBD rows with anchors for naming, lifecycle, and versioning; keep PR-COMMENT.md local-only. * fix merge error * fix invariants links --------- Co-authored-by: Peter Kalambet <peter@kalambet.dev>
Serve llms.txt at handbook.chainsafe.io/llms.txt and redirect the bare domain to the README, reusing the existing Git-connected Pages project (deploys natively on push to main, previews per PR — no GH Action needed). - scripts/build-pages.sh assembles the public/ publish dir (copies the root llms.txt in; extensible for future build steps). Set as the Pages build command, output dir public/. - public/_redirects: / -> README (301). - public/_headers: serve /llms.txt as text/plain; charset=utf-8. - public/llms.txt is generated at build time, git-ignored; the root llms.txt stays the single source of truth. - Normalize handbook references to handbook.chainsafe.io/llms.txt and rewrite the discovery doc for the Pages Git-integration mechanism. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Deploying engineering-handbook with
|
| Latest commit: |
7bdb7bd
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://de0ce842.engineering-handbook-8f2.pages.dev |
| Branch Preview URL: | https://peter-agentic-handbook-overh.engineering-handbook-8f2.pages.dev |
Audited all 23 docs.canton.network deep links cited across the DAML
pages against the live docs; every topic→page citation still holds
except one dead link, plus two improvements surfaced by the audit.
- Remove dead m3-functional-programming link (developer.md): the page
is gone; its content was folded into Language Fundamentals, already
linked in the same row.
- Add m6-testing-upgrades ("Testing Upgrades") to the upgrades
references (developer.md table + prose, reviewer.md): existing but
previously unlinked page covering dpm upgrade-check, both-DAR CI
gating, and downgrade testing — load-bearing for the HARD FAIL
upgrade review tier.
- Soften the "Full API" claim on m3-testing (idioms.md): it's a
tutorial, not an API reference.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.invariantsframework (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 intoarchitect/developer/reviewerroles plus sharedidioms.mdandgotchas.md.skills/— 18 packaged Anthropic Skills (per-language architect/developer/reviewer, code review, PR author, research-plan-implement) authored viaskill-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
docusaurus.config.js,sidebars.js,babel.config.js,tsconfig.json,package.json,yarn.lock,src/,static/, and the olddocs/tree.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..github/CODEOWNERSfor 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-implementskill adapted from Boris Tane; the Forest AI policy originally adapted from Ghostty) is credited inNOTICEand inline, per Section 4(d) of the Apache 2.0 License.Review notes
AGENTS.mdandoperating-model/collaborator-statement.mdto understand the new contract model.README.md"How it's organized" is the fastest map of the new directory structure.CODEOWNERSand inline headers.Generated with Claude Code reviewed and edited by a human.