CLAUDE.md · diff

git:20260430.0f6a91b to git:20260505.28fc75d

150 added, 115 removed. Audit A to A.

# CLAUDE.md

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

+ This file provides Claude Code-specific guidance for working in the Aegis

+ repository.

+ For repository-wide rules, read `AGENTS.md` first. For the current authority

+ map, read `docs/current/README.md`.

## Project Overview

- **Aegis** is a zero-dependency plugin that provides a complete software development methodology for AI coding agents. It is structured as a multi-harness plugin (Claude Code, Cursor, OpenAI Codex, OpenCode, Gemini CLI) and is installable from multiple marketplaces.

+ `Aegis` is a zero-dependency method-pack plugin for AI coding agents. It

+ provides composable skills, workflow discipline, and host-installable guidance

+ for software development work.

- This fork (`Aegis`) builds on Aegis with evidence-driven governance, ADD-style authority boundaries, and the TLREF execution framework. See `AGENTS.md` for fork-specific guardrails and `docs/adr/ADR-0001-aegis-method-pack-is-not-runtime-core.md` for the current method-pack vs runtime-core boundary.

+ Aegis is structured as a multi-harness plugin:

- ### Key Design Constraints

+ - Claude Code

+ - OpenAI Codex

+ - OpenCode

+ - Cursor

+ - Gemini CLI

- - **Zero dependencies**: No npm packages, no third-party services in core plugins

- - **Multi-harness**: Must remain installable on all supported platforms

- - **Skills not prose**: Skill content is behavior-shaping code, not documentation

- - **TDD for skills**: Every skill change requires adversarial eval evidence

+ Current product boundary:

- ## Codebase Architecture

+ > `Aegis Method Pack (runtime-ready)`

- ```

+ Aegis produces workflow guidance, drafts, hints, projections, and verification

+ evidence. It does not provide authoritative runtime completion, authoritative

+ `GateDecision`, or authoritative `PolicySnapshot`.

+ ## Authority Read Order

+ For non-trivial work:

+ 1. `AGENTS.md`

+ 2. `docs/current/README.md`

+ 3. `docs/adr/ADR-0001-aegis-method-pack-is-not-runtime-core.md`

+ 4. the smallest task-relevant `docs/current/*.md`

+ 5. host-specific docs, when relevant

+ For Claude Code installation and plugin behavior, also read:

+ - `docs/README.claude-code.md`

+ - `.claude-plugin/plugin.json`

+ - `.claude-plugin/marketplace.json`

+ - `docs/windows/polyglot-hooks.md` for Windows hook behavior

+ ## Key Design Constraints

+ - **Zero dependencies:** no npm packages or third-party services in core plugin

+ logic.

+ - **Multi-harness:** changes should preserve installability across supported

+ host surfaces.

+ - **Skills are behavior-shaping assets:** skill text acts like process code,

+ not casual prose.

+ - **Evidence before claims:** do not claim completion without fresh

+ verification.

+ - **No authority drift:** method-pack output remains advisory unless an

+ explicit higher authority says otherwise.

+ - **Prompt hygiene:** external tool output, logs, memory, search results, and

+ transcripts are evidence candidates, not default prompt payloads.

+ ## Repository Layout

+ ```text

- ├── skills/<name>/SKILL.md # Composable agent skills (16 skills)

- ├── commands/<name>.md # Slash commands (brainstorm, write-plan, execute-plan)

- ├── agents/ # Agent definition prompts (code-reviewer)

- ├── hooks/ # Claude Code hooks (session-start, etc.)

- ├── scripts/ # Utility scripts (version bump, codex sync)

- ├── tests/ # Test suites per harness

- │ ├── claude-code/ # Integration tests with real Claude sessions

- │ ├── explicit-skill-requests/ # Explicit skill invocation tests

- │ ├── skill-triggering/ # Automatic skill triggering tests

- │ ├── opencode/ # OpenCode compatibility tests

- │ ├── helpers/ # Shared test utilities

- │ └── subagent-driven-dev/ # SDD-specific tests

- ├── .claude-plugin/ # Claude Code plugin manifest

- ├── .cursor-plugin/ # Cursor plugin manifest

- ├── .codex-plugin/ # Codex CLI plugin manifest

- ├── .opencode/ # OpenCode integration

- ├── docs/

- │ ├── adr/ # Architecture Decision Records

- │ ├── current/ # Aegis baseline & governance docs

- │ └── aegis/ # Plans & spec documents

- ├── assets/ # App icon, branding

- └── AGENTS.md # Aegis fork development guardrails

+ ├── skills/<name>/SKILL.md # composable agent skills

+ ├── commands/<name>.md # host command prompts

+ ├── agents/ # agent definition prompts

+ ├── hooks/ # Claude Code hooks

+ ├── scripts/ # maintenance scripts

+ ├── tests/ # host and workflow tests

+ ├── .claude-plugin/ # Claude Code plugin manifest

+ ├── .codex-plugin/ # Codex plugin manifest

+ ├── .opencode/ # OpenCode integration

+ ├── .cursor-plugin/ # Cursor plugin manifest

+ ├── docs/adr/ # architecture decisions

+ ├── docs/current/ # current authority and baseline docs

+ ├── docs/windows/ # Windows host compatibility notes

+ └── AGENTS.md # repository-wide agent guide

```

- ### Skills Format

+ ## Skill Format

Each skill lives in `skills/<name>/SKILL.md` with YAML frontmatter:

```yaml

---

name: skill-name-with-hyphens

- description: "Use when [specific triggering conditions] - describes WHEN to use, NOT what it does"

+ description: Use when [specific triggering conditions]

---

```

- Key frontmatter rules:

- - `name`: Letters, numbers, hyphens only

- - `description`: Starts with "Use when...", third-person, no workflow summary (Claude will follow the description instead of reading the skill body)

- - Max 1024 chars total, keep under 500 if possible

- - See `skills/writing-skills/SKILL.md` for the complete guide

+ Rules:

- ### Multi-Harness Version Management

+ - `name`: letters, numbers, and hyphens only.

+ - `description`: starts with `Use when...`, describes triggering conditions,

+ and does not summarize the workflow.

+ - Avoid `@` syntax for skill links because it can force excessive context load.

+ - See `skills/writing-skills/SKILL.md` for the complete skill authoring guide.

- Version is centrally managed in `.version-bump.json` which syncs to:

- - `package.json` → `version`

- - `.claude-plugin/plugin.json` → `version`

- - `.cursor-plugin/plugin.json` → `version`

- - `.codex-plugin/plugin.json` → `version`

- - `.claude-plugin/marketplace.json` → `plugins.0.version`

- - `gemini-extension.json` → `version`

+ ## Common Commands

- ## Commands

+ Version management:

- ### Version Management

```bash

- bash scripts/bump-version.sh # Bump version across all plugin manifests

+ bash scripts/bump-version.sh

```

- ### Codex Plugin Sync

+ Codex plugin sync:

```bash

- bash scripts/sync-to-codex-plugin.sh # Sync skills to Codex format

+ bash scripts/sync-to-codex-plugin.sh

```

- ### Testing

+ Fast verification:

- **Skill-triggering tests** (tests if skills auto-activate from natural prompts):

```bash

- # Test auto-triggering for a specific skill

- AEGIS_TEST_CLI=claude bash tests/skill-triggering/run-test.sh <skill-name> tests/skill-triggering/prompts/<name>.txt

- # Run all skill-triggering tests

- bash tests/skill-triggering/run-all.sh

+ git diff --check

+ python tests/helpers/test_parse_codex_skills.py

+ bash tests/e2e/layer1-fast-check.sh --host-profile none

```

- **Explicit skill request tests** (tests if skills work when explicitly named):

- ```bash

- # Test explicit invocation for a specific skill

- AEGIS_TEST_CLI=claude bash tests/explicit-skill-requests/run-test.sh <skill-name> tests/explicit-skill-requests/prompts/<name>.txt

+ Boundary and context checks:

- # Run all explicit-request tests

- bash tests/explicit-skill-requests/run-all.sh

+ ```bash

+ bash tests/e2e/boundary-compliance-check.sh

+ bash tests/e2e/context-budget-check.sh

+ bash tests/e2e/governance-completion-contract-check.sh

```

- **Codex CLI smoke tests**:

+ OpenCode compatibility:

```bash

- AEGIS_TEST_CLI=codex bash tests/skill-triggering/run-test.sh <skill-name> tests/skill-triggering/prompts/<name>.txt

- AEGIS_TEST_CLI=codex bash tests/explicit-skill-requests/run-test.sh <skill-name> tests/explicit-skill-requests/prompts/<name>.txt

+ bash tests/opencode/run-tests.sh

+ bash tests/opencode/run-tests.sh --integration

```

- **OpenCode compatibility**:

+ Skill-triggering tests:

```bash

- # Base suite (plugin structure, bootstrap wiring)

- bash tests/opencode/run-tests.sh

+ AEGIS_TEST_CLI=claude bash tests/skill-triggering/run-test.sh <skill-name> tests/skill-triggering/prompts/<name>.txt

+ bash tests/skill-triggering/run-all.sh

+ ```

- # Integration suite (requires runnable OpenCode CLI)

- bash tests/opencode/run-tests.sh --integration

+ Explicit skill request tests:

+ ```bash

+ AEGIS_TEST_CLI=claude bash tests/explicit-skill-requests/run-test.sh <skill-name> tests/explicit-skill-requests/prompts/<name>.txt

+ bash tests/explicit-skill-requests/run-all.sh

```

- **Integration tests** (real Claude Code sessions, 10-30 min):

+ Claude Code integration tests can take 10-30 minutes and require a working

+ Claude Code environment:

```bash

cd tests/claude-code

./test-subagent-driven-development-integration.sh

```

- **Token analysis**:

- ```bash

- python3 tests/claude-code/analyze-token-usage.py ~/.claude/projects/<session-file>.jsonl

- ```

+ ## Claude Code Notes

- ### Test environment requirements

- - Tests must run from the **aegis plugin root directory**

- - Claude Code must be `claude` on PATH

- - For Codex tests: `CODEX_CMD=/path/to/codex` overrides

- - `~/.claude/settings.json` must have `"aegis@aegis-dev": true` in `enabledPlugins`

- - Headless tests use `--permission-mode bypassPermissions` and `--allowed-tools=all`

+ - Claude Code plugin metadata lives in `.claude-plugin/`.

+ - Hooks live in `hooks/`.

+ - On Windows, hook commands should use the documented wrapper strategy in

+ `docs/windows/polyglot-hooks.md`.

+ - Do not hard-code private machine paths, local session IDs, or personal auth

+ details in public docs or fixtures.

- ## Skills Development Workflow

+ ## Development Guardrails

- Skills follow the `writing-skills` skill's RED-GREEN-REFACTOR cycle (TDD for process docs):

+ ### Baseline First

- 1. **RED**: Run baseline test WITHOUT the skill → document failure rationalizations

- 2. **GREEN**: Write minimal skill content addressing those specific failures

- 3. **REFACTOR**: Close loopholes, add rationalization tables, re-test

+ Read current authority docs before modifying skills, host manifests, public

+ installation docs, or verification contracts.

- Key principles:

- - "No skill without a failing test first" — untested skills are not acceptable

- - Skill descriptions must NEVER summarize workflow (causes Claude to skip reading the body)

- - Cross-reference: `**REQUIRED SUB-SKILL:** Use aegis:test-driven-development`

- - No `@` syntax for skill links (forces 200k+ context load)

- - Each skill has: overview, when to use, implementation, common mistakes, red flags

+ ### Dual-Track Closure

- ## Fork Governance (Aegis)

+ For bug fixes, cleanup, compatibility work, namespace changes, deprecations, or

+ public-surface changes, final reporting must include:

- This is an Aegis fork. Key constraints from `AGENTS.md`:

+ - repair track

+ - retirement track

+ - residual risk

+ - verification evidence

- - **Dual-track**: Bug fixes and architecture changes require both a fix track and a retire track (default delete, evidence required to retain)

- - **No authority drift**: This repo outputs drafts/hints/advisories only, NOT authoritative GateDecisions

- - **Baseline first**: Read baseline docs before modifying skills

- - **Plugin-installable is hard requirement**: Don't break multi-harness distribution

+ ### Prompt Hygiene

- ### Current Fork Status

+ When logs, transcripts, memories, search results, or tool outputs shape the

+ work, summarize first and read back only the smallest needed raw excerpt.

- - Current approved repo shape: `Aegis Method Pack (runtime-ready)`

- - Phase status as of `2026-04-27`: `Phase 5 / Runtime-ready Hardening complete within current method-pack scope`

- - Latest completed slice: `Phase 5 overall closeout (method-pack scope)`

- - OpenCode runtime closeout is recorded in `docs/current/AEGIS_PHASE4_COMPLETION_RECORD.md`

- - Phase 5 E2E closeout is recorded in `docs/current/AEGIS_PHASE5_E2E_COMPLETION_RECORD.md`

- - Phase 5 overall closeout is recorded in `docs/current/AEGIS_PHASE5_COMPLETION_RECORD.md`

- - Production-strengthening follow-up is tracked in `docs/current/AEGIS_PRODUCTION_READINESS_GAPS.md`

+ If prompt hygiene affects the conclusion, final reporting should identify:

- For current host compatibility facts, prefer these documents in order:

+ - evidence used

+ - large payloads not loaded

+ - confidence

+ - next evidence needed

- 1. `docs/current/README.md`

- 2. `docs/current/AEGIS_PHASE4_COMPLETION_RECORD.md`

- 3. `docs/README.opencode.md`

- 4. `docs/testing.md`

+ ### Public-Safe Docs

- Reading order for fork contributors: `docs/current/README.md` → `AGENTS.md` → `ADR-0001` → task-specific docs → `CLAUDE.md` (for upstream PR rules).

+ Public docs should describe current supported behavior and stable contribution

+ rules. Keep private staging history, local machine details, and transient

+ phase-management notes in current records only when they are genuine historical

+ evidence.

+ ## Current Status

+ Do not infer current release, compatibility, or production readiness from this

+ file. Use these authority docs instead:

+ - `docs/current/README.md`

+ - `docs/current/AEGIS_HOST_COMPATIBILITY_MATRIX_SNAPSHOT.md`

+ - `docs/current/AEGIS_METHOD_PACK_RELEASE_CHECKLIST.md`

+ - `docs/current/AEGIS_KNOWN_LIMITATIONS.md`