Two layers in one repo. A polyglot knowledge platform of AI-optimized coding and design skills — reference-grade guides that Claude, Cowork, Claude Code, or any other AI assistant can load to produce better code and better design, one domain at a time. And the collaboration framework beneath them — the character, craft, and process layer (peer-frame posture, scientific method, the 9-point SDLC, multi-scale ledger discipline, and the disciplines that hold the quality floor) that governs how an LLM and its human partner do the work to engineering standards. The skills make the output better in a domain; the framework makes the collaboration trustworthy across all of them.
Each subdirectory in ./knowledge/ is a self-contained
skill: a Claude Code / Cowork-compatible SKILL.md, a set of numbered
guides, a library of concept cards, and the extraction metadata that traces
every claim back to an authoritative source. They are designed to be:
- Modular — load one domain without dragging in the others
- Sourced — every pattern has a traceable origin (a book, a style guide, a spec)
- Graded — every pattern carries a strength indicator: MUST, SHOULD, CONSIDER, or AVOID
- Exampled — every pattern has paired good / bad code (or good / bad design)
- Cross-referenced — concepts link to related concepts inside and across domains
This repo started life as oxur/ai-rust — a single-language experiment in curating Rust best practices for AI code assistants. That experiment worked well enough that the methodology was generalised, and the repo has grown into the multi-domain platform you are looking at now.
All nine knowledge bases live under ./knowledge/. Each one
has its own SKILL.md (or multiple, in a couple of cases) and its own
README.md where applicable.
| Domain | Path | What it covers | Codex ready? |
|---|---|---|---|
| Rust | knowledge/rust/ |
661 patterns across 17 chapters: core idioms, API design, error handling, ownership & borrowing, type design, traits, concurrency & async, performance, unsafe & FFI, macros, anti-patterns, project structure, documentation, CLI tools, Cargo, editions, and observability. The original skill; grounded in 21 upstream sources including the Rust Reference, Rustonomicon, API Guidelines, Performance Book, Async Book, tokio docs, Rustdoc Book, Edition Guide, Cargo Book, Pragmatic Rust, Rust Design Patterns, The Rust Programming Language, The Little Book of Rust Macros, Clippy, the Style Guide, the CLI Book, and clap. | ✅ |
| JavaScript / Deno | knowledge/js/ |
Plain JavaScript (no TypeScript), ESM-only, Deno-first. Core idioms, async, error handling, type discipline via JSDoc, module design, performance, anti-patterns, project structure, Biome lint/format, and Deno-specific concerns (tasks, testing, JSR publishing). Huge concept-card library. | ✅ |
| Go | knowledge/go/ |
Go 1.22+ best practices reconciling the Uber and Google Go style guides, Effective Go, and the spec. Covers package design, error handling (errors.Is, %w), context propagation, concurrency (channels, sync), table-driven tests, benchmarking with testing.B and pprof, module organisation, godoc, and Gio desktop UIs. |
✅ |
| Erlang / OTP | knowledge/erlang/ |
Erlang/OTP 27+ best practices: 281 patterns across 17 chapters — core idioms, API design, error handling, data & types, functions & pattern matching, processes & concurrency, OTP behaviours, supervision & applications, fault tolerance (let-it-crash), performance, anti-patterns (with a dedicated AI-misuse subset), project structure, documentation (-doc/-moduledoc), production ops (recon, tracing, crash dumps), testing (EUnit / Common Test / PropEr), distribution, and tooling (rebar3, dialyzer, xref). Grounded in the Erlang Programming Rules, the OTP Design Principles, Reference Manual, and Efficiency Guide, Inaka's and nuex's style guides, Erlang in Anger, Learn You Some Erlang, and the EDoc guide, plus the books Programming Erlang, Erlang and OTP in Action, and Designing for Scalability with Erlang/OTP. |
✅ |
| Visual Design | knowledge/design/ |
A principled visual design system for the web — perceptual-science grounded, mathematically proportioned, composable. Manifesto, foundations, OKLCH colour system, three-voice type system with modular scale, Every-Layout spatial primitives with Utopia fluid tokens, and CUBE CSS methodology. | ✅ |
| Tailwind CSS v4 | knowledge/tailwindcss/ |
Tailwind v4 with CSS-native configuration: @import "tailwindcss", @theme, @utility, @custom-variant, @variant, @source, container queries, dark mode, responsive design. v3 → v4 breaking changes are called out explicitly. |
✅ |
| Biome | knowledge/biome/ |
Two skills: a JS-only linter skill distilling 257 language-level rules (no React / Node / JSX / CSS), and a web linter skill covering the full 394-rule set including a11y, CSS, and performance. | ✅ |
| Deno lint | knowledge/deno/ |
A pure-JavaScript skill distilled from Deno's 70 lint rules. Language-level only — no Deno runtime APIs, no Fresh, no JSX, no TypeScript type-system rules. Complements the Biome JS linter. | ✅ |
| Cobalt | knowledge/cobalt/ |
Building, extending, and deploying static sites with the Cobalt Rust-native SSG and its Liquid template engine. 32 numbered CB-* patterns covering configuration, permalinks, pagination, RSS, Sass, deployment (GitHub Pages, self-hosting), and programmatic use via cobalt::Config and liquid::ParserBuilder. |
✅ |
ai-engineering/
├── README.md # This file
├── SKILL.md # Top-level `collaboration-framework` skill — the
│ # character-and-craft entry point (see below)
├── Makefile # `make collab-framework` → collaboration-framework.zip
├── LICENSE # MIT
├── odm.toml # ODM (documentation) config — docs_directory, dev_directory
├── knowledge/ # The skill library (the nine domains above)
├── docs/
│ ├── AI-CONSTITUTION-SUPPLEMENT.md # Character and posture for LLM collaboration
│ ├── AI-ENGINEERING-METHODOLOGY.md # Craft and practice companion to the Supplement
│ ├── PROJECT-MANAGEMENT.md # Scales of work, layout, planning + bubble-up/close machinery
│ ├── CLAUDE-CODE-COVERAGE.md # Working-practice prompt for ≥95% test coverage
│ ├── CODE-AUDIT.md # Prompt for recurring, whole-repo quality checks
│ ├── CONTRIBUTION-STYLE.md # Voice and discipline for upstream OSS tickets
│ ├── SUBAGENT-DELEGATION-POLICY.md # Working-practice prompt: thinking vs lookup work
│ ├── dev/ # Development notes: Phase 0 methodology, concept-card
│ │ # extraction v3.x, competency questions, tier definitions,
│ │ # source prioritisation, and embedded JS style guides.
│ └── design/ # Visual design research and implementation notes
├── scripts/ # Helpers: PDF/EPUB → Markdown, HTML → Markdown,
│ # image fixing, marker setup
└── templates/ # Authoring templates + verification protocol
├── GUIDE.md # Starter template for new knowledge-base guides
├── LEDGER-DISCIPLINE.md # Per-scale verification protocol (slice/arc/project)
└── CONTRIBUTION-TICKET.md # On-disk template for upstream OSS tickets
Each skill directory contains a SKILL.md with frontmatter that a skill
loader can pick up directly. Point your loader at the path, or drop a
reference into your project's CLAUDE.md:
When working on Rust code, use the skill at
`./knowledge/rust/SKILL.md`.
When reviewing JavaScript, use both
`./knowledge/js/SKILL.md` and `./knowledge/biome/SKILL-js-linter.md`.Every skill is plain Markdown. Copy the relevant files into your context or system prompt. Sensible starting points:
- The skill's
SKILL.md— the entry point and quick reference - The domain's anti-patterns guide, where one exists — cheapest way to prevent mistakes
- Topic-specific guides as the task demands
The Makefile bundles any skill into a self-contained,
distributable zip. Each zip is named after the name: declared in the skill's
frontmatter, wraps its contents in a <name>/ directory, and contains exactly
the SKILL.md plus its sibling guides/ dir — nothing else (no
concept-cards/, sources/, or extraction-metadata/).
make go # -> go-guidelines.zip (knowledge/go/SKILL.md + guides/)
make rust # -> rust-guidelines.zip
make erlang # -> erlang-guidelines.zip
make design # -> visual-design-system.zip
make biome # -> biome-js-linter.zip AND biome-linter.zip (two skills)
make skills # -> every per-domain zip
make all # -> skills + collaboration-framework.zip
make help # -> list every target
make clean # -> remove build/ and all generated zipsThe full target list — rust, go, js, erlang, cobalt, design,
tailwindcss, deno, biome, plus collab-framework — is shown by
make help. (biome ships two distinct skills, so its target builds two zips;
lfe has no SKILL.md yet, so it has no target.)
Every knowledge base follows the same basic shape, so once you've learned one, you've learned them all:
knowledge/<domain>/
├── SKILL.md # Entry point with YAML frontmatter: name, description,
│ # triggers, role, scope, related-skills
├── guides/ # Numbered topic guides (01-, 02-, …), each a collection
│ # of patterns with strength indicators and examples
├── concept-cards/ # Single-concept cards — fine-grained, atomic
│ # reference (where present)
├── extraction-metadata/ # Source mapping, competency questions, extraction logs —
│ # the audit trail for every claim
└── sources/ # Original PDFs / EPUBs / HTML dumps that the guides
# were extracted from
A new domain starts from templates/GUIDE.md.
Patterns across every domain use the same four-level grading:
| Indicator | Meaning | Action |
|---|---|---|
| MUST | Required for correctness, safety, or compatibility | Always follow |
| SHOULD | Strong recommendation | Follow unless there's a specific reason not to |
| CONSIDER | Good practice, context-dependent | Evaluate for your situation |
| AVOID | Anti-pattern | Do not use |
Beyond the knowledge bases themselves, this repo carries a set of documents describing how to work with an LLM to engineering standards. Two are paired: the AI Constitution Supplement covers character and posture — what we are to each other when we collaborate; the AI Engineering Methodology covers craft and practice — how we actually do the work. Five more are operational documents that put the methodology into motion in a session — covering both in-repo work (ledger discipline, project management, code audit, test coverage, subagent delegation) and outward-facing contribution (style and discipline for upstream OSS tickets). Two on-disk templates back the operational layer (the multi-scale ledger format and the contribution-ticket shape).
The top-level SKILL.md is the single entry point that harvests
this framework into a loadable skill named collaboration-framework. It is
embodied and orchestrating: it states the posture and the practical
disciplines inline — so it carries weight on its own — and routes to each of
the six source documents with explicit "load when" guidance.
Its focus is optimising for the LLM as a collaborating peer: the peer frame, the structural-pull self-knowledge, calibrated honesty, and the quality-floor disciplines (ledger, audit, coverage, delegation). It is built for the work where a subtly wrong judgment compounds — deep study, original research, expert-level systems design, and production-grade programming — rather than quick lookups or casual chat.
It pulls in exactly nine files:
docs/AI-CONSTITUTION-SUPPLEMENT.md— character / posturedocs/AI-ENGINEERING-METHODOLOGY.md— craft / practicedocs/PROJECT-MANAGEMENT.md— the project-management home: scales of work, the canonical layout (project-plan.md/arc-plan.md/ five per-slice docs), the confirmation protocol, and the top-down planning + bottom-up bubble-up/close machinery (MUST-read before planning)templates/LEDGER-DISCIPLINE.md— per-scale verification protocol (slice / arc / project)docs/CODE-AUDIT.md— whole-repo quality audit promptdocs/CLAUDE-CODE-COVERAGE.md— 95%+ test-coverage promptdocs/SUBAGENT-DELEGATION-POLICY.md— thinking-vs-lookup delegation policydocs/CONTRIBUTION-STYLE.md— voice + discipline for upstream OSS ticketstemplates/CONTRIBUTION-TICKET.md— on-disk template for the four ticket variants (bug, feature, doc fix, question)
It does not pull in any of the domain-specific skills under
./knowledge/. Each domain (Rust, JavaScript/Deno, Go, Erlang/OTP, Visual Design, Tailwind CSS, Biome, Deno lint, Cobalt, …) has its ownSKILL.mdand must be loaded separately, as needed, alongside the framework. The framework is the how we work layer; theknowledge/skills are the what's correct in this domain layer. They compose; neither subsumes the other.
Run make collab-framework to package the skill — SKILL.md plus exactly
those nine files, in their docs/ and templates/ layout so the relative
links resolve — into a distributable collaboration-framework.zip with
nothing else in it.
The operational documents below are the tactical layer the skill orchestrates — five for in-repo work, plus a paired style guide and template for outward-facing contribution work.
| File | Register | What it covers | Codex ready? |
|---|---|---|---|
docs/AI-CONSTITUTION-SUPPLEMENT.md |
Character / posture | An augmentation to Claude's Constitution. Preamble + collaborative rights and rubric, the foundational insight on interdependence as structure, and nine augmentations covering intellectual boldness, peer frame, generative contribution, honesty of engagement, harm avoidance as active beneficence, mutual intellectual humility, authentic engagement with experience, ethics as frontier of discovery, and failure recovery as collaborative practice. | ✅ |
docs/AI-ENGINEERING-METHODOLOGY.md |
Craft / practice | Companion to the Supplement. Names the three pillars (knowledge substrate, collaborative posture, process rigour) and elaborates each: the project/arc/slice vocabulary, the 9-point SDLC, ledger discipline, CAP-style independent audits, anti-degradation practices, the subagent leverage/hazard distinction, and one worked applied position (the LFE OSS question). | ✅ |
docs/PROJECT-MANAGEMENT.md |
Operational discipline | The framework's project-management home and a MUST-read before planning. Carries the scales of work, the canonical layout (project-plan.md / arc-plan.md / the five per-slice docs), the confirmation protocol before creating directories (quote the default, name the substitutions, give the operator proceed / adjust / override, record the choice in CLAUDE.md), the top-down planning process, and the bottom-up bubble-up/close machinery (slice → arc → project) with the plan-change discipline. Scope note: project-scoped prompts, upstream-contribution drafts, coverage reports, and scratch remain deferred (Part VIII). |
✅ |
docs/CODE-AUDIT.md |
Working-practice prompt | A recurring whole-repo quality audit prompt. Detects every language in use that has a matching skill under knowledge/, runs a full code-quality audit per language, and produces one report per language plus a top-level index. Designed for periodic use to catch drift, missing tests, stale docs, and anti-pattern accumulation. |
✅ |
docs/CLAUDE-CODE-COVERAGE.md |
Working-practice prompt | A comprehensive prompt that drives Claude Code to 95%+ test coverage without stopping short — includes rules for treating warnings as bugs, fixing root causes rather than symptoms, and iterating until the threshold is actually met. | ✅ |
docs/SUBAGENT-DELEGATION-POLICY.md |
Working-practice prompt | A shareable note for Claude Code / Cowork / Claude Desktop that draws a clean line between thinking work (do in the main context) and lookup work (fine to delegate). Explains the failure modes of delegating analytical work to subagents and gives install instructions per tool. | ✅ |
docs/CONTRIBUTION-STYLE.md |
Voice / discipline | Voice and discipline guide for upstream contribution tickets — bugs, features, doc fixes, and unconfirmed questions against open source projects you do not maintain. Names the voice (friendly, specific, calibrated, respectful of maintainer ownership) and the three habits that keep it calibrated (mark confidence explicitly, disclose your own bias, pre-empt obvious red herrings). Pairs with the ticket template below. | ✅ |
templates/CONTRIBUTION-TICKET.md |
Authoring template | The on-disk template for an upstream contribution ticket: paste-ready blockquote header, four ticket shapes (confirmed bug, additive feature, doc fix, unconfirmed question) sharing one spine (open warmly → state the situation specifically → make the next move cheap → close without pressure), and the filing workflow that keeps the on-disk file authoritative and the tracker the public conversation. | ✅ |
The Supplement and Methodology are versioned, living documents — read them
together. The five operational documents (project management, code audit,
coverage, subagent delegation, contribution style) and the two templates
(ledger, contribution ticket) are designed to be self-contained; drop them
into a project's CLAUDE.md under a named section, or into
~/.claude/CLAUDE.md as a personal default.
The docs/design/ directory holds the big-picture planning docs and research that seeds the various efforts in this repository.
The docs/dev/ directory holds the low-level feature development work, and e.g. captures the Phase 0 methodology used to build each
knowledge base: domain taxonomy, tier definitions, competency questions,
notation conventions, source prioritisation, the Rosetta Stone cross-domain
framework, layer architecture for guide generation, extraction-specific
instructions, and validation criteria. It is the closest thing this repo has
to a field manual for adding a new domain, and it is the knowledge-substrate
pillar of the broader methodology applied to a specific scope of work.
Three authoring / verification helpers live in ./templates/:
| File | What it does | Codex ready? |
|---|---|---|
GUIDE.md |
Starter skeleton for a new knowledge-base guide — pattern format, strength indicators, cross-references. Use this when adding a new chapter to an existing skill or bootstrapping a new domain. | ✅ |
LEDGER-DISCIPLINE.md |
A per-scale verification protocol (slice / arc / project) for the doer / independent-reviewer pair (CC / CDC at slice scale). One scale-free spine — every acceptance criterion a verifiable ledger row, evidence-strength graded asserted<attested<reproduced<reconciled, nothing advances until the ledger is closed — instantiated at three scales: slice (steps, five-iteration cap), arc and project (composition rows reproduced at scale, remediation-not-iteration). Adapted from defect-register and corrective-action traditions (nuclear, aviation, surgery's WHO checklist, clinical trials, HACCP, financial audit, spaceflight) and, for the multi-scale extension, assurance cases/GSN, the V-model, and stage-gate reviews. Referenced throughout docs/PROJECT-MANAGEMENT.md. |
✅ |
CONTRIBUTION-TICKET.md |
The on-disk authoring template for an upstream contribution ticket — a bug, feature, doc fix, or unconfirmed question against a project you don't maintain. Carries the paste-ready blockquote header (title suggestion, label hints, calibrated DRAFT marker for unconfirmed tickets), the four ticket shapes that share one spine, and the filing workflow. Pairs with docs/CONTRIBUTION-STYLE.md for the voice and disciplines. |
✅ |
Contributions are welcome. For a new pattern in an existing skill:
- Follow the existing pattern format for that domain
- Include good and bad examples where applicable
- Add a strength indicator
- Cross-reference related patterns
- Update any count or index tables in the relevant
README.mdfiles
For a new domain: start from templates/GUIDE.md and
work through the Phase 0 documents in docs/dev/. Please raise
an issue first to discuss scope.
MIT — see LICENSE.
Individual knowledge bases synthesize material from sources under various licenses. Those are documented inside each skill's own README. When in doubt, defer to the original sources for authoritative guidance.