mathews-tom/project-context-setup

Project Context Setup

Scaffold the repo-local context files that make agent workflows consistent across sessions: issue tracker rules, triage labels, domain glossary layout, ADR layout, agent brief format, and out-of-scope memory.

When To Use

| Use this skill | Use another package | | -------------- | ------------------- | | A repo lacks docs/agents/ context files | adr-writer for one architecture decision | | Agents need consistent domain vocabulary | task-decomposer for an already-scoped feature | | Triage or issue publishing needs label conventions | github for direct GitHub CLI operations | | Multi-agent work needs durable issue briefs | handoff for session-local continuation notes |

Reference Files

| File | Contents | Load When | | ---- | -------- | --------- | | references/context-format.md | CONTEXT.md and CONTEXT-MAP.md glossary format | Creating or editing domain docs | | references/agent-brief.md | Durable ready-for-agent issue brief contract | Preparing issue handoff | | references/out-of-scope.md | Persistent memory for rejected enhancements | Triage includes wontfix decisions |

Core Workflow

1. Explore

Inspect the actual repo state before writing:

• git remote -v and .git/config for issue tracker hints
• root AGENTS.md and CLAUDE.md
• root CONTEXT.md and CONTEXT-MAP.md
• docs/adr/ and context-scoped ADR directories
• existing docs/agents/
• existing .out-of-scope/

Report what exists and what is missing. Do not overwrite existing files blindly.

2. Choose Setup Values

Resolve these values with the user or from clear repo evidence:

| Decision | Default | Output | | -------- | ------- | ------ | | Issue tracker | GitHub if a GitHub remote exists, otherwise local markdown | docs/agents/issue-tracker.md | | Triage labels | Canonical labels equal role names | docs/agents/triage-labels.md | | Domain docs | Single root context | docs/agents/domain.md | | Agent instructions file | Existing AGENTS.md, else existing CLAUDE.md | Updated ## Agent context block |

If both AGENTS.md and CLAUDE.md exist, update AGENTS.md for cross-agent portability. If neither exists, ask before creating one.

3. Write Context Files

Create or update these files:

docs/agents/
├── issue-tracker.md
├── triage-labels.md
└── domain.md

Use these conventions:

• Keep issue tracker instructions operational: exact CLI, label mutation policy, and whether agents may comment or close issues.
• Map canonical triage roles to real labels. Do not create duplicate labels when the repo already has equivalents.
• Document whether the repo uses a single root CONTEXT.md or CONTEXT-MAP.md with per-context glossaries.
• Record ADR lookup rules. Use docs/adr/ for global decisions and context-local docs/adr/ directories where present.

4. Add Agent Context Block

Add or update this block in the chosen instructions file:

## Agent context

### Issue tracker

See `docs/agents/issue-tracker.md` for where issues live and which operations agents may perform.

### Triage labels

See `docs/agents/triage-labels.md` for canonical triage roles and their concrete label strings.

### Domain docs

See `docs/agents/domain.md` for `CONTEXT.md`, `CONTEXT-MAP.md`, and ADR lookup rules.

Update the existing block in place if it already exists. Do not append duplicates.

5. Optional Domain Glossary

Create CONTEXT.md only when the user has resolved at least one domain term. Use references/context-format.md. Do not fill it with generic programming concepts.

Create CONTEXT-MAP.md only for multi-context repos where separate glossaries are needed.

Verification

• docs/agents/issue-tracker.md exists and states the tracker, allowed operations, and required tools.
• docs/agents/triage-labels.md maps needs-triage, needs-info, ready-for-agent, ready-for-human, and wontfix.
• docs/agents/domain.md states single-context or multi-context layout and ADR lookup rules.
• The chosen instructions file contains exactly one ## Agent context block.
• Existing user-authored content outside that block is preserved.