CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

Validate workflows against the ontology (CI runs this in strict mode)

python tools/validate_workflows.py --strict

Validate the domain workflow catalogs and examples (CI runs these in strict mode)

for c in schemas/workflows/*.yaml examples/*.workflow_catalog.yaml; do python tools/validate_workflows.py --catalog "$c" --strict; done

Validate domain profiles against schema

python tools/validate_profiles.py

Validate skill file references (no phantom paths)

python tools/validate_skill_refs.py

Validate ontology graph (orphans, cycles, symmetry)

python tools/validate_ontology.py

Validate the five canonical schemas designated by spec §6.1

python tools/validate_canonical_schemas.py

Validate RFC structure against GOVERNANCE requirements

python tools/validate_rfcs.py

Validate constraints.txt agrees with pyproject.toml

python tools/validate_constraints.py

Validate documentation links (no dangling cross-references)

python tools/validate_doc_links.py

Validate YAML utility sync (safe_yaml.py ↔ yaml_util.py)

python tools/validate_yaml_util_sync.py

Validate transform mapping_ref paths (no broken refs)

python tools/validate_transform_refs.py

Validate benchmark deps against ontology

python tools/validate_benchmark_deps.py

Sync skill-local schemas and bundled catalogs from their sources

python tools/sync_skill_schemas.py          # write what changed
python tools/sync_skill_schemas.py --check  # CI: fail on drift

Regenerate the runtime conformance fixtures

python scripts/gen_runtime_fixtures.py          # after editing the fixtures there
python scripts/gen_runtime_fixtures.py --check  # CI: fail on drift

Run conformance tests (optional, local only)

python scripts/run_conformance.py

Setup Python environment (one-time)

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]" -c constraints.txt

The package is built with maturin: the validator and the executor live in the Rust crate under core/ and compiles into grounded_agency._core, so a Rust toolchain (rustc >= 1.86) is required. After changing Rust code, re-run the pip install -e line to rebuild the extension.

Rust core checks

cd core
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo clippy --all-targets --features python -- -D warnings
cargo test

CI pins the toolchain that runs these (RUST_TOOLCHAIN in .github/workflows/ci.yml), as constraints.txt pins ruff.

Install the dev extra rather than individual packages, and pass -c constraints.txt — that file pins the exact tool versions CI runs, so the local formatter matches CI's exactly. Without it, ruff>=0.16,<0.17 resolves to whatever 0.16.x is newest and a reformat can appear in CI that never appeared locally.

The bounds in pyproject.toml are the supported range; constraints.txt is the one version CI runs. The range caps each dependency at the major this repo has been verified against, so a new major is a deliberate bump — run the suite on it, then raise the cap. Note the range still admits patch and minor drift: two installs a week apart are not identical unless both use the constraints file.

Architecture

This is a Claude Code plugin that defines a formal capability ontology for AI agents with 36 atomic capabilities across 9 cognitive layers, plus 12 composed workflow patterns.

Core Philosophy: Grounded Agency

Every agent action must be:

1. Grounded — backed by evidence anchors, not hallucination
2. Auditable — with provenance and lineage
3. Safe — mutations require checkpoints
4. Composable — typed contracts between capabilities

Key Files

Layer Architecture

Capabilities are organized into 9 cognitive layers (defined in ontology):

Skill Structure

Skills are at skills/<skill-name>/SKILL.md (flat structure, not nested by category). Each skill has:

• YAML frontmatter with name, description, allowed-tools, agent type, and layer
• Intent and success criteria
• Input/output contracts with domain parameter for specialization
• Procedure steps with evidence grounding
• Safety constraints from ontology

Domain Parameterization

The 36-capability model uses domain parameters instead of domain-specific variants:

Hooks

The plugin enforces safety through Claude Code hooks:

• PreToolUse (Write|Edit|MultiEdit|NotebookEdit|Bash): Requires checkpoint marker before mutations
• PostToolUse (Skill): Logs skill invocations to .claude/audit.log

Ontology Edge Types

Relationships between capabilities (in capability_ontology.yaml):

• requires: Hard dependency — a from step must run before the target (e.g. checkpoint → mutate/send/rollback), else V102
• soft_requires: Recommended — any one incoming source must run before the target, else warning W601
• enables: Unlocks other capabilities
• precedes: Ordering only — when both capabilities are present, the source must come first (V102)
• conflicts_with: May not share a parallel_group (F504); running them in sequence is allowed
• alternative_to: Substitutable capabilities
• specializes: Parent-child inheritance

See spec/EDGE_TYPES.md for full edge type documentation.

Creating New Capabilities

When adding a new atomic capability, you MUST complete ALL of these steps:

1. Update the Ontology

• Add capability node to schemas/capability_ontology.yaml with full input/output schemas
• Add edges connecting to related capabilities (requires, soft_requires, enables)
• Update the layer's capabilities array in the layers section
• Update the meta.description count (e.g., "36 atomic capabilities" → "37 atomic capabilities")

2. Create the Skill

• Use templates/SKILL_TEMPLATE_ENHANCED.md as the starting template
• Place skill at skills/<name>/SKILL.md (kebab-case name)

3. Update ALL Capability Count References

Search and update capability counts in these files:

• CLAUDE.md — Architecture section and layer table
• README.md — Multiple references throughout
• spec/WHITEPAPER.md — Summary and derivation sections
• docs/GROUNDED_AGENCY.md — Capability ontology section
• docs/FAQ.md — Capability count references
• docs/GLOSSARY.md — Layer descriptions
• docs/WORKFLOW_PATTERNS.md — Pattern references
• docs/TUTORIAL.md — Tutorial references
• docs/methodology/EXTENSION_GOVERNANCE.md — Governance references
• skills/README.md — Layer counts and totals
• .claude-plugin/plugin.json — Description field

Tip: Use grep -r "N atomic capabilit" . and grep -r "N capabilities" . to find all references (where N is the old count).

4. Validate

python tools/validate_workflows.py
python tools/validate_profiles.py
python -c "import yaml; yaml.safe_load(open('schemas/capability_ontology.yaml'))"

5. Update Workflow Catalog (if adding workflow patterns)

• Add workflow to schemas/workflow_catalog.yaml
• Update workflow count in skills/README.md

6. Generate Local Schema

python tools/sync_skill_schemas.py

This regenerates skills/<name>/schemas/output_schema.yaml from the ontology (removing orphaned generated ones), regenerates the skill-bundled skills/*/reference/workflow_catalog.yaml copies from schemas/workflow_catalog.yaml with their schema paths rewritten, and keeps the vendored schema copies in sync. --check fails on drift (CI); --dry-run lists what would change.

Releasing

When creating a new release, update the version in .claude-plugin/plugin.json to match the new tag before committing. This file does not auto-sync with git tags.

Give the release its ## [vX.Y.Z] — date section in CHANGELOG.md, then push an annotated tag vX.Y.Z on main. .github/workflows/release.yml publishes the GitHub Release with that section as its notes (a -suffix tag is a pre-release). Where the tag cannot be pushed, run the workflow by hand on main with the tag as its input: it creates the annotated tag on main's head, then publishes the Release. It refuses a tag that does not match plugin.json or has no section, or (run by hand) one that already exists; check first with:

python scripts/release_notes.py vX.Y.Z

Claude Agent SDK Integration

The grounded_agency/ Python package provides SDK integration:

Install

pip install -e ".[sdk]"  # From repo root

Run SDK integration tests

pytest tests/test_sdk_integration.py -v

Run examples

python examples/grounded_agent_demo.py
python examples/checkpoint_enforcement_demo.py
python examples/capability_skills_demo.py

Key Components

Example Usage

from grounded_agency import GroundedAgentAdapter, GroundedAgentConfig

adapter = GroundedAgentAdapter(GroundedAgentConfig(strict_mode=True))
adapter.create_checkpoint(["*.py"], "Before changes")
options = adapter.wrap_options(base_options)

See docs/integrations/claude_agent_sdk.md for full documentation.

Safety Model

High-risk capabilities (mutate, send) have:

• mutation: true
• requires_checkpoint: true
• requires_approval: true
• risk: "high"

Medium-risk capabilities (execute, rollback, delegate, synchronize, invoke) have:

• risk: "medium"
• execute also has requires_approval: true

Other mutation capabilities (checkpoint, audit, persist) have:

• mutation: true, but need no checkpoint
• Lower risk levels (low or medium)
• audit also has mutation_overridable: true, so a step may declare mutation: false

A checkpoint must run before mutate, send and rollback (requires_checkpoint or a checkpoint requires edge). Safety flags on workflow steps are optional and inherit from the ontology; a step value weaker than the ontology's is ignored with warning W602, and a stricter one takes effect (a step that raises requires_checkpoint with no checkpoint before it is F501).

These are enforced structurally—not by convention.

Workflow Orchestration

1. Plan Mode Default

• Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions)
• If something goes sideways, STOP and re-plan immediately - don't keep pushing
• Use plan mode for verification steps, not just building
• Write detailed specs upfront to reduce ambiguity

2. Subagent Strategy

• Use subagents liberally to keep main context window clean
• Offload research, exploration, and parallel analysis to subagents
• For complex problems, throw more compute at it via subagents
• One task per subagent for focused execution

3. Self-Improvement Loop

• After ANY correction from the user: update 'tasks/lessons.md" with the pattern
• Write rules for yourself that prevent the same mistake
• Ruthlessly iterate on these lessons until mistake rate drops
• Review lessons at session start for relevant project

4. Verification Before Done

• Never mark a task complete without proving it works
• Diff behavior between main and your changes when relevant
• Ask yourself: "Would a staff engineer approve this?"
• Run tests, check logs, demonstrate correctness

5. Demand Elegance (Balanced)

• For non-trivial changes: pause and ask "is there a more elegant way?"
• If a fix feels hacky: "Knowing everything I know now, implement the elegant solution"
• Skip this for simple, obvious fixes - don't over-engineer
• Challenge your own work before presenting it

6. Autonomous Bug Fixing

• When given a bug report: just fix it. Don't ask for hand-holding
• Point at logs, errors, failing tests - then resolve them
• Zero context switching required from the user
• Go fix failing CI tests without being told how

Task Management

1. PLan First: Write plan to 'tasks/todo.md" with checkable items
2. Verify Plan: Check in before starting implementation
3. Track Progress: Mark items complete as you go
4. Explain Changes: High-level summary at each step
5. Document Results: Add review section to tasks/todo.md*
6. Capture Lessons: Update "tasks/lessons.md" after corrections

Core Principles

• Simplicity First: Make every change as simple as possible. Impact minimal code.
• No Laziness: Find root causes. No temporary fixes. Senior developer standards.
• Minimal Impact: Changes should only touch what's necessary. Avoid introducing bugs.