# AGENTS.md

Instructions for agents working on this repository.

## What This Repo Is

A personal Copilot CLI plugin containing custom agents and skills, shipped to Copilot, pi,
and Claude Code, plus PI extensions and Claude hooks for enhancing the coding agent
runtime. Changes here affect the behaviour of every agent, skill, and PI extension
available in the author's coding sessions.

## Structure

```
agent-cortex/
├── package.json           # PI package manifest (pi: { extensions, skills, packages })
├── plugin.json            # GitHub Copilot plugin manifest — agents, skills, MCP servers
├── agents/                # Custom agents — canonical composable <name>/ dirs
│   ├── *.agent.md         #   generated from <name>/ by scripts/build-copilot-agents.mjs
│   ├── ralph/             #   composable format — see agents/README.md
│   ├── plan/              #   "
│   ├── ralph-plan/        #   "
│   └── strategy/          #   "
├── skills/               # Grouped by domain, discovered recursively
│   ├── planning/         # Scope, spec, decompose
│   ├── engineering/      # The coding loop
│   ├── productivity/     # Workflow tooling
│   ├── style/            # Conventions and standards
│   ├── workflow/         # Orchestration and pipeline
│   └── review/           # Auditing and maintenance
├── extensions/           # PI extensions (one directory per extension, each with index.ts)
│   └── skill-stats/
│       ├── README.md      # Installation & usage
│       └── index.ts       # Extension entrypoint
├── hooks/                # Canonical Claude Code hooks (hooks.json + scripts — see docs/claude-hooks.md)
│   └── claude/           #   generated into the plugin's hooks.json + hooks/ by bin/installers/claude.mjs
├── claude/               # Committed Claude user-settings template — merged into ~/.claude/settings.json on install
├── claude-extras/        # Hand-authored Claude plugin extras
│   ├── .mcp.json         # MCP servers (context7, github) — copied into installs
│   └── scripts/          # statusline-command.sh — copied into installs (executable)
└── package.json          # PI package manifest (pi: { extensions, skills, packages })
```

## Versioning

Use `pnpm changeset` for all version bumps. Never edit versions manually.
`package.json`, `plugin.json`, and `CHANGELOG.md` stay in lockstep automatically.
See the `style-versioning` skill for the full workflow.

## Changelog

Generated automatically by changesets. Do not edit `CHANGELOG.md` manually.

## Coding Conventions

- **Never block the main thread**: no `*Sync` functions (`readFileSync`, `spawnSync`, …).
  Tooling code in `bin/`, `scripts/`, `lib/`, `hooks/`, and `test/` must be async —
  enforced by `scripts/check-no-sync.mjs` (runs via `pnpm lint`). Skill-owned
  scripts (`skills/*/scripts`) and `extensions/` are the remaining sync surfaces.
- **Share generic tooling helpers in `scripts/lib/`**: tooling code (installers under
  `bin/installers/`, hooks, other scripts) imports shared utilities from `scripts/lib/`
  (e.g. `compose-agent.mjs`, `fs.mjs`) rather than redefining them inline.

## Skill Conventions

- `SKILL.md` must include a YAML front-matter block with `name` and `description`.
- `description` must be ≤ 1024 characters. First sentence: what it does. Second: "Use when…".
- Keep `SKILL.md` near the ~150-line target in `docs/skills/skill-anatomy.md`, overflowing into
  purpose-named support files (`REFERENCE.md`, `EXAMPLES.md`, `FORMAT.md`). `style-tests`
  deliberately sits at the top of that range rather than splitting — its principles must load
  automatically with the skill.
- Add utility scripts to `scripts/` when an operation is deterministic and would otherwise be
  regenerated each time (e.g. install scripts, scanners).
- Skill names use kebab-case and are grouped by prefix where related (e.g. `review-security`,
  `review-code`; `style-code`, `style-comms`, `style-documentation`).

## Agent Conventions

- Agents live in composable `<name>/` directories under `agents/`: a shared `agent.md` body plus
  per-harness subdirectories `pi/`, `copilot/`, `claude/` (frontmatter.json and optional section
  files) per the spec in `agents/README.md`. `ralph`, `plan`, `ralph-plan`, and `strategy` all use
  the composable layout. The flat `agents/*.agent.md` files are **generated output** — composed
  from the canonical directories by the shared `bin/installers/copilot.mjs` code path behind both
  `agent-cortex install copilot` and `scripts/build-copilot-agents.mjs` (thin wrapper), and
  committed for Copilot CLI (plugin.json `agents: "agents/"` scans for `*.agent.md`); never edit
  them by hand. The Claude plugin is materialised by the install-time generator
  `bin/installers/claude.mjs`: a plain `agent-cortex install claude` copies it into
  `~/.agent-cortex/claude` (skills copied flat with `{{TOOL:...}}`/`{{PATH:...}}` substituted,
  never symlinked), writes the marketplace manifest at
  `~/.agent-cortex/.claude-plugin/marketplace.json`, merges the committed `claude/settings.json`
  template into `~/.claude/settings.json`, and registers it with Claude Code via the
  `claude plugin` CLI. The settings merge preserves personal config: the CLI owns exactly
  `enabledPlugins` + `extraKnownMarketplaces`, and every other key is left untouched. Only
  that settings template is committed under `claude/` — the generated plugin subtree is not;
  hand-authored plugin extras live in `claude-extras/` (`.mcp.json`, `scripts/`), and
  `--output <dir>` is the generate-only form (tests/CI materialiser checks); `ralph`
  is authored natively in `agents-native/` and copied verbatim; the other agents compose from their
  `claude/` harness dirs).
- Keep orchestration logic in the agent file; extract shared per-task workflow into a skill
  so it can be reused (e.g. ralph delegates per-task stage execution to `run-pipeline-stage`).

## PI Extension Conventions

- PI extensions live in `extensions/`, one subdirectory per extension.
- Each extension directory contains `index.ts` (entrypoint) and `README.md` (usage).
- Extensions are auto-discovered when the repo is installed as a PI package via `pi install`.
- Keep extensions lightweight: no internal LLM calls. Extensions observe events and provide
  commands — they should not add token overhead.
- Register CLI flags from the extension factory (load time), never from a `session_start`
  handler: PI matches parsed CLI flags against the extensions loaded at startup, so late
  registration makes the flag fail with `Unknown option`.
- Extensions that persist data should write to `~/.pi/agent-cortex/` (global, cross-project)
  and tag records with the project path for per-project slicing.
- PI extensions with Claude Code equivalents are ported to `hooks/claude/`; the port/reject
  audit with rationale lives in `docs/claude-hooks.md`.

## User preferences

Before making tooling or workflow decisions, read `docs/user-preferences.md` for the
user's personal development preferences (e.g. preferred package manager, tooling
choices). These preferences apply across all projects where this plugin is active.

## Task tracking

This project uses **bd (beads)** for task tracking.

Run `bd prime` at the start of each session for context.

Quick reference:
- `bd ready` — list unblocked work
- `bd create "Title" -p <0-3>` — create a task (P0 = critical)
- `bd update <id> --claim` — claim a task
- `bd close <id>` — complete a task
- `bd dep add <A> <B>` — **"A depends on B"** (B blocks A). First arg waits, second arg
  is waited-for. To express "X blocks Y", write `bd dep add Y X`.
- `bd dolt push` — sync to remote at session end