# 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 })
├── 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-extras/        # Hand-authored Claude plugin extras (no committed claude/ output)
│   ├── .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 })
```

## 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.

## 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` under ~100 lines. Overflow into `REFERENCE.md` for rarely-needed detail.
- 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`, and registers it with Claude Code via the
  `claude plugin` CLI; the repo commits no `claude/` output — 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.
- 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