27 added, 27 removed. Audit A to A.
# AGENTS.md — ARIA
## What This Is
ARIA (Applied Reasoning and Insight Architecture) — an active knowledge and development discipline plugin for Codex. Three pillars: a five-phase knowledge lifecycle (capture → govern → promote → apply → refresh), decision discipline (Rule 22 enforcement at every edit), and codebase & task mapping (/codemap for repo traces, /stitch for cross-repo contract binding, /distill for task spec shaping). The "Applied" framing emphasizes the apply phase: trusted knowledge actively shapes the next decision via /context, /rules, /codemap, /stitch, /distill, and Rule 22 — not just stored and recalled.
**Repository:** GitHub (`mikeprasad/aria-knowledge`) — **public repo**
- ## Cowork Port (plugin-Codex-cowork/)
+ ## Claude Cowork Port (plugin-claude-cowork/)
- The Codex Cowork port lives at `plugin-Codex-cowork/` — consolidated into this repo in v2.20.0 (2026-05-24) from the previously standalone `mikeprasad/aria-cowork` (last standalone release: v1.1.0, 2026-05-19). **Current cowork release: v1.1.3** (2026-05-25, coordinated with aria-knowledge v2.20.2 — wrapup/handoff spec fixes: closing-heading labeling correction + auto-mode extract-always-runs invariant). Prior coordinated cowork release: v1.1.2 (with aria-knowledge v2.20.1 — ADR-094 §Part 1/2/3 gate UX revision). Both ports share the user's `~/Projects/knowledge/` folder and write to the same canonical config (`aria-config.md`) under an additive-only schema (per ADR-002). Edits to shared surfaces — `aria-config.md` field names, `template/rules/` content, `working-rules.md` rule numbering — must preserve cross-port compatibility. 26 skills (24 distinct + 2 aliases). Cowork-specific authoring constraints documented in `knowledge/guides/Codex/cowork-plugin-validation.md`. **Cowork-specific release constraint**: aria-cowork release.sh enforces a 9000-char hard cap on summed SKILL.md description chars (empirical install-fail at 9233, documented v0.2.1 + v1.0.0); v2.20.1's trailing-parenthetical port-id uses a short form on cowork (`(Cowork variant — namespaced-only.)` ~36 chars) versus Code's verbose form (~96 chars), with the full ADR-094 narrative in the Runtime Gate body where no cap applies.
+ The Claude Cowork port lives at `plugin-claude-cowork/` — consolidated into this repo in v2.20.0 (2026-05-24) from the previously standalone `mikeprasad/aria-cowork` (last standalone release: v1.1.0, 2026-05-19). **Current cowork release: v1.1.3** (2026-05-25, coordinated with aria-knowledge v2.20.2 — wrapup/handoff spec fixes: closing-heading labeling correction + auto-mode extract-always-runs invariant). Prior coordinated cowork release: v1.1.2 (with aria-knowledge v2.20.1 — ADR-094 §Part 1/2/3 gate UX revision). Both ports share the user's `~/Projects/knowledge/` folder and write to the same canonical config (`aria-config.md`) under an additive-only schema (per ADR-002). Edits to shared surfaces — `aria-config.md` field names, `template/rules/` content, `working-rules.md` rule numbering — must preserve cross-port compatibility. 26 skills (24 distinct + 2 aliases). Cowork-specific authoring constraints documented in `knowledge/guides/claude/cowork-plugin-validation.md`. **Cowork-specific release constraint**: aria-cowork release.sh enforces a 9000-char hard cap on summed SKILL.md description chars (empirical install-fail at 9233, documented v0.2.1 + v1.0.0); v2.20.1's trailing-parenthetical port-id uses a short form on cowork (`(Cowork variant — namespaced-only.)` ~36 chars) versus Code's verbose form (~96 chars), with the full ADR-094 narrative in the Runtime Gate body where no cap applies.
- **Bidirectional feature flow (since v0.3.0 / v2.17.0):** Features may originate in either port and port to the other; plugin-Codex remains the schema source-of-truth (output formats, knowledge-folder conventions, archive structures). v0.3.0's `/handoff brief` and `/intake doc` modes are the first cowork-originated features ported into aria-knowledge. See plugin-Codex-cowork ADR-014 for the architectural rationale.
+ **Bidirectional feature flow (since v0.3.0 / v2.17.0):** Features may originate in either port and port to the other; plugin-claude-code remains the schema source-of-truth (output formats, knowledge-folder conventions, archive structures). v0.3.0's `/handoff brief` and `/intake doc` modes are the first cowork-originated features ported into aria-knowledge. See plugin-claude-cowork ADR-014 for the architectural rationale.
- **Bare-slash ownership (ADR-094, v2.19.1):** When both ports are loaded in the same session (most common in Codex Desktop), 24 colliding skill names (`/handoff`, `/wrapup`, `/extract`, `/intake`, etc.) deterministically resolve to **plugin-Codex** as canonical owner. plugin-Codex-cowork's variants are namespaced-only (`/aria-cowork:handoff`, etc.). Each colliding skill carries a Runtime Gate in its body that surfaces a notification when invoked from the wrong runtime (Bash-availability is the fingerprint). The gate applies even in `auto` modes — auto's "implicit-yes" rule is suspended for the runtime-mismatch check per ADR-094 §Part 3. Edits affecting cross-port compatibility (description prepend conventions, gate clause text, anti-trigger language) should preserve this ownership rule. Full design: [`~/Projects/knowledge/projects/aria/decisions/094-bare-slash-canonical-owner-and-dual-runtime-gate.md`](../../knowledge/projects/aria/decisions/094-bare-slash-canonical-owner-and-dual-runtime-gate.md).
+ **Bare-slash ownership (ADR-094, v2.19.1):** When both ports are loaded in the same session (most common in Claude Desktop), 24 colliding skill names (`/handoff`, `/wrapup`, `/extract`, `/intake`, etc.) deterministically resolve to **plugin-claude-code** as canonical owner. plugin-claude-cowork's variants are namespaced-only (`/aria-cowork:handoff`, etc.). Each colliding skill carries a Runtime Gate in its body that surfaces a notification when invoked from the wrong runtime (Bash-availability is the fingerprint). The gate applies even in `auto` modes — auto's "implicit-yes" rule is suspended for the runtime-mismatch check per ADR-094 §Part 3. Edits affecting cross-port compatibility (description prepend conventions, gate clause text, anti-trigger language) should preserve this ownership rule. Full design: [`~/Projects/knowledge/projects/aria/decisions/094-bare-slash-canonical-owner-and-dual-runtime-gate.md`](../../knowledge/projects/aria/decisions/094-bare-slash-canonical-owner-and-dual-runtime-gate.md).
## Project Structure
```
aria/
├── README.md ← GitHub-facing intro
├── LICENSE ← CC BY-NC-SA 4.0
├── CHANGELOG.md ← Version history
├── AGENTS.md ← You are here
- ├── plugin-Codex/ ← The installable plugin
- │ ├── .Codex-plugin/
+ ├── plugin-claude-code/ ← The Claude Code installable plugin
+ │ ├── .claude-plugin/
│ │ └── plugin.json
│ ├── bin/ ← Hook scripts (bash)
│ ├── skills/ ← Skill definitions (SKILL.md files)
│ └── template/ ← Knowledge folder templates
├── plugin-openai-codex/ ← Codex port (independent installable unit)
│ ├── .codex-plugin/
│ │ └── plugin.json
│ ├── hooks.json ← Codex hook registration
│ ├── bin/ ← Codex-standard scripts + Codex adapter
│ ├── commands/ ← Codex command entrypoints
│ ├── skills/ ← Copied ARIA skills (schema-compatible)
│ └── template/ ← Copied Codex-standard knowledge templates
- ├── plugin-Codex-cowork/ ← Cowork port (skills-only; no hooks API in Cowork runtime)
- │ ├── .Codex-plugin/
+ ├── plugin-claude-cowork/ ← Cowork port (skills-only; no hooks API in Cowork runtime)
+ │ ├── .claude-plugin/
│ │ └── plugin.json
│ ├── skills/ ← 26 skills (24 distinct + 2 aliases)
- │ ├── template/ ← Knowledge folder templates (schema mirror of plugin-Codex/)
+ │ ├── template/ ← Knowledge folder templates (schema mirror of plugin-claude-code/)
│ ├── .mcp.json ← 12 MCP servers across 4 categories
│ └── release.sh ← Builds aria-cowork-<version>.plugin
├── plugin-cursor-template/ ← Cursor port (repo-skeleton, not a plugin install)
│ ├── .cursor/ ← Cursor-native config
│ │ ├── hooks.json
│ │ ├── aria-knowledge.local.md
│ │ └── rules/ ← 5 compiled .mdc files (25 skills compiled into 5)
│ ├── AGENTS.md ← Cursor's equivalent of AGENTS.md
│ ├── QUICKSTART.md ← Cursor-adapted quickstart
│ ├── knowledge/ ← Knowledge folder (lives at root in Cursor port, not under template/)
│ ├── scripts/aria/ ← Hook scripts (instead of bin/)
│ └── audit/ ← Frozen audit artifacts for the 2.16.1 port build
└── docs/ ← Extended documentation (future)
```
## Key Conventions
- - **`plugin-Codex/` is the installable unit** — everything inside it is what users copy to their plugins directory
- - **`plugin-openai-codex/` is the Codex installable unit** — independent adapter surface, same knowledge schema. Codex `plugin-Codex/` remains the standard for template/content shape.
- - **`plugin-cursor-template/` is the Cursor repo-skeleton** — not a plugin install. Users clone or unzip its contents into the root of their own project. Cursor compiles 25 skills into 5 `.cursor/rules/*.mdc` files because Cursor's Rules system doesn't have a one-skill-per-folder concept. Knowledge folder schema stays compatible with `plugin-Codex/template/`.
- - **Template files** in `plugin-Codex/template/` are either plugin-managed (diffable on `/setup`) or user-owned (created once, never overwritten). See `plugin-Codex/skills/setup/SKILL.md` for the authoritative list.
- - **Version** lives in `plugin-Codex/.Codex-plugin/plugin.json`
- - **Hook scripts** in `plugin-Codex/bin/` are bash — they read config from `~/.Codex/aria-knowledge.local.md`
+ - **`plugin-claude-code/` is the Claude Code installable unit** — everything inside it is what users copy to their Claude plugins directory
+ - **`plugin-openai-codex/` is the Codex installable unit** — independent adapter surface, same knowledge schema. Claude `plugin-claude-code/` remains the standard for template/content shape.
+ - **`plugin-cursor-template/` is the Cursor repo-skeleton** — not a plugin install. Users clone or unzip its contents into the root of their own project. Cursor compiles 25 skills into 5 `.cursor/rules/*.mdc` files because Cursor's Rules system doesn't have a one-skill-per-folder concept. Knowledge folder schema stays compatible with `plugin-claude-code/template/`.
+ - **Template files** in `plugin-claude-code/template/` are either plugin-managed (diffable on `/setup`) or user-owned (created once, never overwritten). See `plugin-claude-code/skills/setup/SKILL.md` for the authoritative list.
+ - **Version** lives in `plugin-claude-code/.claude-plugin/plugin.json`
+ - **Hook scripts** in `plugin-claude-code/bin/` are bash — they read config from `~/.claude/aria-knowledge.local.md`
- **Skills** are markdown files — each skill is a `SKILL.md` with YAML frontmatter
- **Codex hooks** require Codex `plugin_hooks` enabled; the adapter reads `~/.codex/aria-knowledge.local.md` first, then falls back to `~/.Codex/aria-knowledge.local.md`
- - **`plugin-Codex-cowork/` is the Codex Cowork installable unit** — sibling to plugin-Codex/, both share schema-identical knowledge-folder outputs (per ADR-013). Cowork runtime is skills-only (no hooks API); enforcement is skill-embedded. Per ADR-094, bare-slash skill names resolve to plugin-Codex as canonical owner when both ports are loaded in the same session; cowork-namespaced variants are `/aria-cowork:handoff` etc.
+ - **`plugin-claude-cowork/` is the Claude Cowork installable unit** — sibling to `plugin-claude-code/`, both share schema-identical knowledge-folder outputs (per ADR-013). Cowork runtime is skills-only (no hooks API); enforcement is skill-embedded. Per ADR-094, bare-slash skill names resolve to plugin-claude-code as canonical owner when both ports are loaded in the same session; cowork-namespaced variants are `/aria-cowork:handoff` etc.
- **Cursor hooks** use `.cursor/hooks.json` and resolve script paths via `git rev-parse --show-toplevel`. Some Codex enforcement is weaker on Cursor (no transcript access, no documented pre-edit deny) — port uses an edit-intent marker file as the closest available mechanism. See `plugin-cursor-template/audit/ARIA_CURSOR_AUDIT_REPORT.md` §5.
## Development Workflow
- 1. Edit files in `plugin-Codex/`
- 2. To test, copy `plugin-Codex/` to `~/.Codex/plugins/marketplaces/local-desktop-app-uploads/aria-knowledge/`
- 3. Restart Codex to pick up changes
+ 1. Edit files in `plugin-claude-code/`
+ 2. To test, copy `plugin-claude-code/` to `~/.claude/plugins/marketplaces/local-desktop-app-uploads/aria-knowledge/`
+ 3. Restart Claude Code to pick up changes
### Codex Port Workflow
1. Edit Codex adapter files in `plugin-openai-codex/`
- 2. Keep durable knowledge template/schema changes in sync with `plugin-Codex/` — Codex remains the schema standard
+ 2. Keep durable knowledge template/schema changes in sync with `plugin-claude-code/` — Claude remains the schema standard
3. Enable Codex plugin hooks with `codex features enable plugin_hooks` before testing automatic hooks
4. Install via `.agents/plugins/marketplace.json` or copy `plugin-openai-codex/` into a Codex local marketplace
### Cursor Port Workflow
1. Edit Cursor adapter files in `plugin-cursor-template/`
- 2. Keep durable knowledge surfaces in sync with `plugin-Codex/template/` — Codex remains the schema standard. Knowledge folder shape lives at `plugin-cursor-template/knowledge/` (root-level, not nested under `template/`).
- 3. The 5 `.mdc` rule files (`aria-commands`, `aria-audit`, `aria-context`, `aria-core`, `aria-rule-22`) are *compiled* views of the 25 canonical skills in `plugin-Codex/skills/`. When a skill changes, the corresponding section in the `.mdc` file needs a matching edit — no auto-build pipeline exists yet.
+ 2. Keep durable knowledge surfaces in sync with `plugin-claude-code/template/` — Claude remains the schema standard. Knowledge folder shape lives at `plugin-cursor-template/knowledge/` (root-level, not nested under `template/`).
+ 3. The 5 `.mdc` rule files (`aria-commands`, `aria-audit`, `aria-context`, `aria-core`, `aria-rule-22`) are *compiled* views of the canonical skills in `plugin-claude-code/skills/`. When a skill changes, the corresponding section in the `.mdc` file needs a matching edit — no auto-build pipeline exists yet.
4. Users install by unzipping the cursor port artifact (or cloning the folder) into the root of their own project, then restarting Cursor.
### Cowork Port Workflow
- 1. Edit Cowork-specific files in `plugin-Codex-cowork/`. Most skills mirror `plugin-Codex/` via ADR-013 schema-identical outputs; cowork-specific skills (`daily-audit`, cowork-modified `/extract-doc`, etc.) live only here.
- 2. Keep MCP-consuming skills (clip-thread, extract-doc, meeting-notes, digest, sync-decisions) byte-faithful between ports per ADR-014; plugin-Codex remains schema source-of-truth.
- 3. Per ADR-094, when both ports load in the same session, bare-slash command names (`/handoff`, `/extract`, etc.) resolve to plugin-Codex as canonical owner; cowork-namespaced variants are `/aria-cowork:handoff` etc.
- 4. Build with `./release.sh` in `plugin-Codex-cowork/` — produces `aria-cowork-<version>.plugin`. Install by dragging into a Cowork conversation or via Settings → Plugins → Install from file.
+ 1. Edit Cowork-specific files in `plugin-claude-cowork/`. Most skills mirror `plugin-claude-code/` via ADR-013 schema-identical outputs; cowork-specific skills (`daily-audit`, cowork-modified `/extract-doc`, etc.) live only here.
+ 2. Keep MCP-consuming skills (clip-thread, extract-doc, meeting-notes, digest, sync-decisions) byte-faithful between ports per ADR-014; plugin-claude-code remains schema source-of-truth.
+ 3. Per ADR-094, when both ports load in the same session, bare-slash command names (`/handoff`, `/extract`, etc.) resolve to plugin-claude-code as canonical owner; cowork-namespaced variants are `/aria-cowork:handoff` etc.
+ 4. Build with `./release.sh` in `plugin-claude-cowork/` — produces `aria-cowork-<version>.plugin`. Install by dragging into a Cowork conversation or via Settings → Plugins → Install from file.
5. Cowork runs as a skills-only plugin (no hooks API). The `/daily-audit` skill substitutes for SessionStart on first message.
## Rules
- Follow the universal rules in `Projects/AGENTS.md`
- **This is a public repository** — never commit personal information, API keys, secrets, credentials, internal URLs, or any sensitive data. Content here is visible to anyone on GitHub.
- The plugin's own template content (working-rules, change-decision-framework, enforcement-mechanisms) is both shipped content AND documentation of how the plugin works — edits to these have dual impact
- Bump version in `plugin.json` when making release-worthy changes
## Knowledge Repository
Project-specific architecture decisions live in `~/Projects/knowledge/projects/aria/`:
- `decisions/002-knowledge-extraction-architecture.md` — task-based /extract + audit promotion model
- `decisions/006-full-rule22-format-every-edit.md` — full format on every edit (no compression)
- `decisions/008-skill-knowledge-connections.md` — skill-knowledge connection discovery + drift detection
Cross-project knowledge that applies to ARIA:
- - `knowledge/rules/working-rules.md` — the 34 universal rules (ARIA's source of truth ships in plugin-Codex/template)
+ - `knowledge/rules/working-rules.md` — the 34 universal rules (ARIA's source of truth ships in plugin-claude-code/template)
- `knowledge/rules/change-decision-framework.md` — Rule 22 framework
- `knowledge/rules/enforcement-mechanisms.md` — enforcement tier model
- `knowledge/guides/Codex/plugin-development.md` — Codex plugin patterns
- `knowledge/guides/Codex/cowork-plugin-validation.md` — Codex Cowork plugin patterns (sibling guide; relevant if coordinating with aria-cowork or shipping a Cowork-side plugin)
Pre-staged ADR candidates live in `~/Projects/knowledge/intake/decisions-backlog.md` — check there for what's currently queued for next `/audit-knowledge`. Themes queued here historically drift as ADRs promote; the live backlog is the source of truth.
Use `/context aria` to load relevant knowledge by project tag.