seeds AGENTS.md

AGENTS.md

This file is the canonical entry point for AI coding agents working in the seeds repo, following the agents.md convention. It is intentionally short and command-focused: read it at session start to know how to build, test, and ship. CLAUDE.md is the long-form authoritative companion — when the two disagree, CLAUDE.md wins and this file should be updated to match.

What this project is

Seeds is a git-native issue tracker for AI agent workflows. The JSONL file IS the database: there is no binary store, no export pipeline, no separate sync daemon. All issues live in .seeds/issues.jsonl (one JSON object per line), templates in .seeds/templates.jsonl, plans in .seeds/plans.jsonl, and project config in .seeds/config.yaml. Files are diffable, mergeable (merge=union gitattribute + dedup-on-read), and edited only through the sd CLI, which holds advisory file locks so parallel agents never corrupt the store.

Seeds is part of the os-eco ecosystem alongside warren (control plane), burrow (sandbox), plot (coordination), mulch (expertise), and canopy (prompts). See SPEC.md for the V1 design record.

Tech stack at a glance

• Runtime: Bun (runs TypeScript directly; no build step).
• Language: TypeScript, strict mode (noUncheckedIndexedAccess, no any).
• Lint / format: Biome (biome.json) — tab indentation, 100-char line width, errors fail CI.
• Tests: bun test, Jest-compatible API, real I/O over temp dirs (no mocks). Tests are *.test.ts co-located with the file under test.
• Storage: JSONL under .seeds/; minimal built-in YAML parser (src/yaml.ts) for config.
• CLI: sd, defined in src/index.ts and dispatched via commander.

Project layout

seeds/
├── src/
│   ├── index.ts            # sd CLI entry point + command router
│   ├── version.ts          # VERSION constant (import without CLI side-effects)
│   ├── types.ts            # Issue, Template, Config, shared constants
│   ├── store.ts            # JSONL read/write/lock/atomic-rename
│   ├── id.ts               # ID generation ({project}-{4hex})
│   ├── config.ts           # YAML config load/save
│   ├── output.ts           # JSON + human output helpers
│   ├── yaml.ts             # minimal flat YAML parser
│   └── commands/           # one file per subcommand (create, ready, plan, …)
├── scripts/                # quality-gate scripts + budgets
│   ├── 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
├── .seeds/                 # seeds dogfoods seeds (its own issue store)
├── .factory/skills/        # repo-local agent skills
├── .github/workflows/      # ci.yml + publish.yml + auto-merge.yml
├── CLAUDE.md               # authoritative long-form agent doc
├── RUNBOOK.md              # release / triage / rollback procedures
├── SPEC.md                 # V1 design record
├── README.md               # user-facing pitch
├── CHANGELOG.md            # release history
├── biome.json
├── tsconfig.json
└── package.json