Agent Workspace

This is the canonical, harness-agnostic instruction file for this workspace. Every AI harness (Claude Code, Cursor, Aider, Copilot, etc.) reads its own convention file, but those files are just pointers back here. Edit this file — never the harness-specific ones.

Pointers: CLAUDE.md → @AGENTS.md, .claude/skills → .agents/skills, .cursor/rules → .agents/. See "Harness pointers" below.

What this workspace is

An agent workspace is a parent directory that groups several projects (referenced as symlinks to shared clones) so an agent — and a human in VS Code — can work across all of them at once. It bundles:

• Project references — a committed projects.yaml manifest lists clone URLs; each project is cloned once into $AGENTS_GIT_SRC_DIR and symlinked into projects/. The workspace pins no project commits (see docs/adr/0004-projects-as-symlinks-not-submodules.md and CONTEXT.md).
• Agent instructions — this file (AGENTS.md).
• Agent skills — reusable procedures in .agents/skills/.
• An issue tracker — beads (bd) in .beads/.

It is simultaneously a VS Code multi-root workspace (*.code-workspace), so every symlinked project shows up as a folder in the editor.

Homebrew, asdf v0.16+, and beads (bd) are hard requirements, on the same level. Homebrew is the package manager that installs the other two (including asdf itself), so set it up first. Homebrew also installs the small CLI utilities the workspace tooling relies on: jq (parses JSON) and yq (parses the project manifest). node/pnpm/python/uv/go/ruby/rust are all managed by asdf; each workspace pins versions in .tool-versions (python + uv + nodejs by default — nodejs provides npx for skill management). beads tracks work as issues in a local Dolt database under .beads/.

Agent-first. Multi-step, environment-adaptive tasks (installing asdf, provisioning toolchains, …) are run by you, the agent, via skills — not by a human running commands. The Makefile is the mechanical, deterministic layer and never invokes a harness. See docs/adr/0001-agent-first-task-execution.md.

Layout

.
├── AGENTS.md                 # ← you are here (canonical instructions)
├── CLAUDE.md                 # pointer → @AGENTS.md
├── CONTEXT-MAP.md            # multi-context index: one context per project (agent-maintained)
├── CONTEXT.md                # glossary: the workspace's own vocabulary (workspace / project / manifest)
├── *.code-workspace          # VS Code multi-root workspace (one folder per project)
├── Makefile                  # setup / update-projects / update-agent-skills / update-agent-deps
├── projects.yaml             # manifest: clone URLs of the projects this workspace references
├── projects/                 # one symlink per project → $AGENTS_GIT_SRC_DIR/<name> (git-ignored)
├── .tool-versions            # asdf toolchain pins (python + uv + nodejs by default)
├── .agents/
│   └── skills/               # agent skills — built-in (setup-homebrew, setup-asdf, setup-beads, setup-projects, add-project, …) + external copies via `npx skills`
├── skills-lock.json          # lockfile for external skills (created when you add the first one)
├── .claude/                  # Claude Code harness pointers (skills symlink, settings)
├── .vscode/                  # recommended extensions + shared editor settings
├── .beads/                   # beads issue tracker (local Dolt db, git-ignored; README committed)
├── docs/adr/                 # architecture decision records (0001 = agent-first, 0004 = projects-as-symlinks)
├── docs/agents/              # config for external engineering skills (issue tracker, triage labels, domain)
└── scripts/                  # helper scripts used by the Makefile

Project clones themselves live outside the workspace, in $AGENTS_GIT_SRC_DIR (default ~/agents/git_repos), shared across every workspace that references them.

Working rules

1. Harness-agnostic first. Put instructions in AGENTS.md and skills in .agents/skills/. Never write harness-specific files (CLAUDE.md, .cursor/rules, …) with real content — they only point here.
2. Projects own their code; the workspace only references them. A project's clone lives in $AGENTS_GIT_SRC_DIR and is symlinked into projects/. Commit code changes inside the project's own repo. The workspace pins no commits, so there is no parent pointer to update. Never commit the symlinks — they're git-ignored (only projects.yaml and projects/README.md are tracked).
3. Keep the workspace in sync. After adding/removing a project (editing projects.yaml or the symlinks), run make sync-workspace so the .code-workspace folder list matches projects/. add-project / sync-projects do this for you.
4. Track work in beads. Use bd (bd create, bd ready, bd list) for issues rather than scattering TODOs. See "Issue tracking (beads)" below; run bd prime for the full, current workflow.
5. Don't let projects go stale. Run make update-projects regularly.
6. Maintain the context map. This is a multi-context workspace: CONTEXT-MAP.md at the root indexes each project's context (and CONTEXT.md holds the workspace's own vocabulary). When you add or remove a project, register or remove its context entry and update the relationships so the map never lies.

Skills

Skills live in .agents/skills/<name>/SKILL.md. Available in this template:

• setup-homebrew — install/configure Homebrew. Run this first when onboarding a machine (asdf installs via brew).
• setup-asdf — install/configure asdf v0.16+, the blessed plugins, shims, and this workspace's toolchains. Run after setup-homebrew.
• setup-beads — install the bd issue tracker (via Homebrew) and initialize the workspace's local Dolt database with --skip-agents so the harness files stay untouched. Run after setup-homebrew.
• setup-projects — provision $AGENTS_GIT_SRC_DIR (env var + directory) and clone+symlink the projects in projects.yaml. Run after setup-homebrew.
• add-project — add a new project: record its URL in projects.yaml, clone it, symlink it into projects/, and register it in the VS Code workspace + issue tracker.
• update-workspace — refresh projects, skills, and dependencies so nothing goes stale.

Invoke a skill by reading its SKILL.md and following the procedure.

External skills from the skills.sh ecosystem are added with npx skills@latest add <owner/repo> -a universal (installs editable copies into .agents/skills/, tracked in skills-lock.json) and refreshed with make update-agent-skills. See docs/adr/0002-external-skills-via-skills-cli.md.

Issue tracking (beads)

This workspace tracks work with bd (beads). Issues live in a local Dolt database under .beads/ (git-ignored); .beads/issues.jsonl is a passive export, not the source of truth. Cross-machine sync is bd dolt push/pull, not committed files.

These instructions live here, in AGENTS.md, only — the canonical, harness-agnostic home. CLAUDE.md picks them up via @AGENTS.md. Do not let bd init write its own integration files (it clobbers CLAUDE.md and duplicates this); /setup-beads initializes the database with --skip-agents. See docs/adr/0003-beads-harness-agnostic-integration.md.

Quick reference:

bd ready                                    # find unblocked work
bd create "Title" --type task --priority 2  # file an issue
bd show <id>                                # detail
bd update <id> --claim                      # claim work atomically
bd close <id>                               # complete work
bd dolt push                                # sync issues to the remote

Run bd prime for the full, up-to-date workflow context.

Agent skills

Configuration read by external engineering skills (e.g. the mattpocock/skills set: to-issues, triage, qa, to-prd, improve-codebase-architecture, diagnose, tdd). The details live in docs/agents/ so they can evolve without touching this file.

Issue tracker

Work is tracked in beads (bd) — the workspace's own tracker. See docs/agents/issue-tracker.md.

Triage labels

The five canonical triage roles, applied as bd labels (default strings). See docs/agents/triage-labels.md.

Domain docs

Multi-context: CONTEXT-MAP.md at the root indexes one context per project. See docs/agents/domain.md.

Common commands

Harness pointers

These files exist only to redirect a specific harness back to the canonical sources. Do not put real content in them.

• CLAUDE.md — contains @AGENTS.md (Claude Code import).
• .claude/skills — symlink to ../.agents/skills.
• .claude/settings.json — Claude Code settings (minimal).