The simple version
Before a helpful teammate can work well, they need to know where tasks live, what status words mean and which project terms are correct. This setup gives agents that context.
Agent setup
A beginner's guide to the repo's agent instruction system.
These files are not application features. They are a small operating manual that helps future agents and developers work in the same place, use the same labels and speak the same project language.
What was created
Four small files with one job each.
Think of the setup as signs inside the repository. Each file answers one practical question a future skill would otherwise have to guess.
AGENTS.md
The front door
A short note at the repo root that tells coding agents where to find the setup rules before they start work.
docs/agents/issue-tracker.md
Where work lives
Explains that issues and PRDs should be created in GitHub Issues for this repository.
docs/agents/triage-labels.md
What labels mean
Maps simple workflow states like needs-info and ready-for-agent to the labels used in the tracker.
docs/agents/domain.md
How to learn the project
Tells skills to read CONTEXT.md and use Soundfangled's own vocabulary before proposing or changing work.
Flow
What happens when you use a skill.
01
You ask for a skill
For example, you might ask to turn a plan into issues, triage a bug, diagnose a failure or zoom out on a code area.
02
The skill reads the repo guide
It checks AGENTS.md, then follows the more detailed files in docs/agents so it knows this repo's conventions.
03
It uses the right place and language
Issues go to GitHub, labels use the agreed names, and explanations use glossary terms from CONTEXT.md.
04
The result is easier to pick up later
Future humans and agents can understand what happened because the work follows one shared system.
Triage labels
Labels are just issue status words.
A label helps everyone see what an issue needs next. It is less about ceremony and more about avoiding the question, "what should happen with this?"
needs-triage
Someone needs to decide what this is.
A new issue was reported, but nobody has checked priority or next steps yet.
needs-info
We are waiting for an answer.
The bug report is missing steps to reproduce, a screenshot or the expected behaviour.
ready-for-agent
An AFK agent can pick this up.
The task has enough context, acceptance criteria and repo pointers to start without a meeting.
ready-for-human
A person should handle this.
The work needs product judgment, sensitive decisions or hands-on review.
wontfix
We decided not to do this.
The idea is out of scope, no longer relevant or conflicts with the project direction.
Domain language
CONTEXT.md keeps the words steady.
Junior devs often learn a codebase through names. This repo's glossary explains the words that matter, so a task says "Division" or "Hire Handoff" instead of inventing a new phrase every time.
How to use it
Content systemAsk for the outcome, not the file.
Turn this plan into issues.
to-issues
Creates GitHub issues with repo vocabulary, clear scope and useful acceptance criteria.
Triage this incoming bug.
triage
Reads the issue, asks for missing information if needed, then applies the right workflow label.
Diagnose this failing build.
diagnose
Reads domain context, reproduces the problem, narrows the cause and proposes a focused fix.
Zoom out on this code area.
zoom-out
Maps the relevant modules and callers using the project's glossary terms.
Beginner rule of thumb
When in doubt, read the smallest file first.
Start with AGENTS.md for the summary. Open the matching file in docs/agents only when you need more detail. That keeps the setup approachable instead of making every task feel like documentation homework.
Start at AGENTS.md
Use GitHub Issues for tasks
Use labels as next-step markers
Use CONTEXT.md for project words
The setup is deliberately small: one entry file, three detail files and a shared habit of reading context before making work.