canopy: Instructions file for Codex

AGENTS.md

This file is the canonical entry point for AI coding agents working in the canopy repo, following the agents.md convention. It mirrors the essentials from CLAUDE.md; when the two disagree, CLAUDE.md is authoritative and this file should be updated to match.

What this project is

Canopy is git-native prompt management for AI agent workflows. Prompts are structured records with composable sections, inheritance, versioning, and schema validation. The JSONL file IS the database; cn emit renders prompts to plain .md (or .ts) files for any downstream tool to consume. Minimal runtime dependencies, advisory file locks for concurrent agents, Bun runtime.

Canopy is part of the os-eco ecosystem alongside warren (control plane), burrow (sandbox), plot (coordination), mulch (expertise), and seeds (issue tracking). See SPEC.md for the full design record.

Tech stack at a glance

• Runtime: Bun (runs TypeScript directly; no build step on the CLI).
• Language: TypeScript with strict mode (noUncheckedIndexedAccess, no any).
• Lint / format: Biome (biome.json). Errors fail CI; the useFilenamingConvention rule enforces kebab-case filenames.
• Tests: bun test discovers *.test.ts next to the file under test; configuration lives in bunfig.toml.
• Storage: JSONL files under .canopy/ (one per record type, diffable / mergeable, merge=union gitattribute).
• CLI: cn (defined in src/index.ts, dispatched via commander).

Project layout

canopy/
├── src/
│   ├── index.ts            # cn CLI entry point + Commander wiring
│   ├── commands/           # one file per subcommand
│   ├── render.ts           # inheritance resolution
│   ├── validate.ts         # schema validation
│   ├── store.ts            # JSONL read/write with advisory locks
│   ├── output.ts           # human + JSON output helpers
│   ├── frontmatter.ts      # YAML frontmatter renderer
│   ├── yaml.ts             # minimal built-in YAML parser
│   └── ...
├── scripts/                # quality-gate scripts (size, debt, coverage, …)
│   ├── check-all.ts            # canonical quiet runner (byte-identical fleet-wide)
│   ├── check-ci-parity.ts      # CI ⇄ check:all parity gate (byte-identical fleet-wide)
│   ├── ci-parity-config.json   # per-repo parity escape hatches (aliases / ciOnly)
│   ├── validate-agents-md.ts   # validates this file's references
│   ├── generate-cli-docs.ts    # emits docs/cli-reference.md
│   ├── check-file-sizes.ts
│   ├── check-debt-markers.ts
│   ├── check-coverage.ts
│   ├── report-test-timing.ts
│   └── report-quality-metrics.ts
├── budgets/                # ratchet budgets (coverage, file-size, debt)
├── docs/
│   ├── cli-reference.md    # auto-generated; do not edit
│   └── architecture.mmd    # mermaid service diagram
├── .canopy/                # canopy's own prompts (dogfood)
├── .factory/skills/        # repo-local agent skills
├── .github/workflows/      # ci.yml + publish.yml + auto-merge.yml
├── SPEC.md                 # V1 design record
├── README.md               # user-facing pitch
├── CHANGELOG.md            # release history
├── RUNBOOK.md              # release / triage / rollback procedures
├── biome.json
├── bunfig.toml
├── tsconfig.json
└── package.json