Agent Setup

This is the project setup pattern I use when I want AI coding agents to work in a repo without rediscovering the rules every session.

The core idea is simple: put durable context in the repo, put live work state in the tracker, and make the handoff between humans, issues, and agents explicit.

What This Sets Up

• AGENTS.md for shared agent rules.
• CLAUDE.md for Claude Code-specific notes when a repo uses Claude.
• GOAL.md for long-running goal-loop conventions and evidence pointers.
• GUIDEPOST.md for guarded project scope and anti-drift decisions.
• docs/agents/issue-tracker.md for tracker routing.
• docs/agents/triage-labels.md for issue state vocabulary.
• docs/agents/domain.md for domain docs and ADR routing.
• scripts/check_scope_guards.py and .github/workflows/scope-guards.yml for optional mechanical anti-drift checks.

I use Linear as the canonical issue tracker, GitHub as code hosting and PR review, and Codex or Claude as execution agents. You can adapt the same shape to another tracker.

Why This Exists

Agents fail when project state is spread across chat history, stale markdown, half-remembered issue comments, and implicit human decisions.

This setup gives every agent the same answers:

• Where is the canonical work state?
• What is in scope?
• What is out of scope?
• Which issue is ready for an agent?
• Where are domain terms and architecture decisions recorded?
• What proof is required before calling work done?

State Ownership

• Linear owns live work state: issues, PRDs, blockers, acceptance, ownership, discussion, and completion.
• GitHub owns code, branches, commits, and PR review.
• AGENTS.md owns repo-local agent behavior.
• GUIDEPOST.md owns durable scope and requires explicit human approval to change.
• GOAL.md owns local goal-loop helper state and evidence pointers. It is not a duplicate work queue.
• docs/agents/* owns skill configuration: tracker routing, label vocabulary, and domain-doc layout.

If Linear and local markdown disagree about current work state, trust Linear. If local work implies a scope change, stop and update GUIDEPOST.md only with explicit approval.

New Repo Flow

1. Create the repo and push it to GitHub.
2. Create or confirm the Linear project.
3. Copy the files under templates/ into the repo.
4. Fill placeholders such as <github-owner>/<repo>, <linear-project>, and <codex-environment>.
5. Record explicit routing lines in Linear:

Repository: <github-owner>/<repo>
Codex environment: <codex-environment>
Default branch: main

6. Add project-specific scope decisions to GUIDEPOST.md.
7. Add any domain language to CONTEXT.md and architecture decisions to docs/adr/.
8. Verify the repo docs, tracker links, and routing before delegating work.

See docs/new-project-flow.md.

Existing Repo Flow

1. Audit the repo before writing.
2. Preserve existing project-specific rules.
3. Decide what tracker is canonical.
4. Add the docs/agents/* files.
5. Merge agent rules into AGENTS.md and CLAUDE.md instead of replacing them.
6. Add or carefully update GOAL.md and GUIDEPOST.md.
7. Confirm Linear and GitHub routing.
8. Verify the diff.

See docs/upgrade-project-flow.md.

Matt Pocock-Style Skill Compatibility

The docs/agents/* files are designed to give Matt Pocock-style engineering agent skills the context they usually need before they can operate safely:

• to-prd needs to know where to publish product requirements.
• to-issues needs tracker routing and label vocabulary.
• triage needs issue states and ready-for-agent rules.
• diagnose and tdd need domain docs and ADR routing.
• architecture review skills need domain vocabulary and prior decisions.

This is not an official integration with any one tool. It is a repo shape that makes those tools less dependent on chat memory.

See docs/skill-compatibility.md.

Included Skills

This repo includes public, scrubbed versions of the setup skills:

• skills/new-project/SKILL.md
• skills/upgrade-project/SKILL.md
• skills/setup-matt-pocock-skills/SKILL.md

Templates

Copy these into a repo and fill the placeholders:

• templates/AGENTS.md
• templates/CLAUDE.md
• templates/GOAL.md
• templates/GUIDEPOST.md
• templates/docs/agents/issue-tracker.md
• templates/docs/agents/triage-labels.md
• templates/docs/agents/domain.md
• templates/scripts/check_scope_guards.py
• templates/.github/workflows/scope-guards.yml

Examples

• examples/linear-codex-ready-issue.md