mathews-tom 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 -vand.git/configfor issue tracker hints- root
AGENTS.mdandCLAUDE.md - root
CONTEXT.mdandCONTEXT-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.mdorCONTEXT-MAP.mdwith per-context glossaries. - Record ADR lookup rules. Use
docs/adr/for global decisions and context-localdocs/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.mdexists and states the tracker, allowed operations, and required tools.docs/agents/triage-labels.mdmapsneeds-triage,needs-info,ready-for-agent,ready-for-human, andwontfix.docs/agents/domain.mdstates single-context or multi-context layout and ADR lookup rules.- The chosen instructions file contains exactly one
## Agent contextblock. - Existing user-authored content outside that block is preserved.