mulch AGENTS.md

AGENTS.md

This file is the canonical entry point for AI coding agents working in the mulch 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

Mulch is a passive CLI (@os-eco/mulch-cli) that manages structured expertise files for coding agents. It has no LLM dependency — agents call ml record to store an insight and ml prime to load relevant expertise back into context, and mulch handles storage, validation, and retrieval. The JSONL files on disk are the database; ml prime renders them as agent-optimized markdown. Bun is the runtime: the source .ts files execute directly with no build step.

Mulch is part of the os-eco ecosystem alongside warren (control plane), burrow (sandbox), plot (coordination), seeds (issue tracking), and canopy (prompt management). See CLAUDE.md for the long-form design notes and ROADMAP.md for direction.

Tech stack at a glance

• Runtime: Bun (runs TypeScript directly; no build step on the CLI).
• Language: TypeScript with strict mode — no any, no @ts-ignore, no @ts-expect-error.
• Lint / format: Biome (biome.json). Errors fail CI; warnings are promoted to errors via --error-on-warnings.
• Tests: bun test discovers *.test.ts under test/ and next to scripts; configuration lives in bunfig.toml.
• Storage: JSONL files under .mulch/expertise/ (one file per domain, append-only, merge=union gitattribute for conflict-free concurrent writes).
• CLI: ml / mulch (entry point src/cli.ts, dispatched via commander).

Project layout

mulch/
├── src/
│   ├── cli.ts              # ml / mulch CLI entry point + Commander wiring + VERSION
│   ├── index.ts            # library entry point
│   ├── api.ts              # programmatic API surface
│   ├── commands/           # one file per subcommand (record, prime, sync, ...)
│   ├── schemas/            # record schemas + JSON schema definitions
│   ├── registry/           # type registry (built-in + custom types)
│   └── utils/              # lock, expertise IO, git/worktree, runtime flags
├── scripts/                # quality-gate + report scripts and their budgets
│   ├── check-all.ts            # canonical quiet gate runner (byte-identical fleet-wide)
│   ├── check-ci-parity.ts      # CI <-> check:all parity detector (byte-identical fleet-wide)
│   ├── ci-parity-config.json   # per-repo parity escape hatches (aliases / ciOnly)
│   ├── validate-agents-md.ts   # validates this file's references
│   ├── check-file-sizes.ts
│   ├── check-debt-markers.ts
│   ├── check-coverage.ts
│   ├── report-test-timing.ts
│   ├── report-quality-metrics.ts
│   └── version-bump.ts
├── test/                   # bun tests mirroring src/ layout
├── .mulch/                 # mulch's own expertise (dogfood)
├── .factory/skills/        # repo-local agent skills
├── .github/workflows/      # ci.yml + publish.yml + auto-merge.yml
├── README.md               # user-facing pitch
├── CHANGELOG.md            # release history
├── RUNBOOK.md              # release / triage / rollback procedures
├── CONFIG.md               # mulch.config.yaml reference
├── ROADMAP.md              # direction
├── biome.json
├── bunfig.toml
├── tsconfig.json
└── package.json