agentic-workflow
AGENTS.md0 starsChanged 6 months agoMITView on GitHub
Cross-tool root context for AI coding agents (Claude Code, Codex, Cursor, Aider, Copilot, Gemini, etc.). Tool-specific files (CLAUDE.md, .codex/, .cursor/rules/, .aider.conf.yml) @import this file rather than duplicate. One source of truth, many tools. Change project conventions here. Repo = template for spec-driven, agentic software development. Defines workflow, artifacts, roles for building products. Workflow itself = the deliverable. Replace this section with a product overview when a project uses the template.
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,700 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository45 other files it gives its agents.
- plugin-v2/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- plugin-v2/CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- .cursor/rules/agents.mdcCursor rule
- agentic-security-reviewSkill
- arc42-baselineSkill
- caveman-commitSkill
- caveman-helpSkill
- caveman-reviewSkill
- cavemanSkill
- create-goalSkill
- design-twiceSkill
- discovery-sprintSkill
- domain-contextSkill
- github-project-setupSkill
- grillSkill
- improve-codebase-architectureSkill
- issue-breakdownSkill
- issue-draftSkill
- issue-pr-syncSkill
- new-adrSkill
- new-glossary-entrySkill
- orchestrateSkill
- portfolio-trackSkill
- product-pageSkill
- project-reviewSkill
- project-runSkill
- project-scaffoldingSkill
- quality-assuranceSkill
- quality-metricsSkill
- record-decisionSkill
- review-fixSkill
- roadmap-managementSkill
- sales-cycleSkill
- specorator-designSkill
- specorator-improvementSkill
- specorator-onboardSkill
- stock-takingSkill
- tackle-issueSkill
- tdd-cycleSkill
- token-budget-reviewSkill
- tracer-bulletSkill
- ubiquitous-languageSkill
- verifySkill
The file
We split this AGENTS.md into the rules it gives an agent
4 rules. About 0 are common, 0 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 30
Consult
inputs/at intake: Every conductor's scope phase lists inputs/ and asks the user which items are relevant. - Very specific: line 31
Escalate ambiguity: No guessing. Ask the human or open a clarifications block.
- Very specific: line 33
No direct commits on
main/develop: Every change lands via topic branch + merged PR. - Very specific: line 44
Commit messages: imperative, reference IDs (feat(auth): add T-AUTH-014 password reset).
≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md
Cross-tool root context for AI coding agents (Claude Code, Codex, Cursor, Aider, Copilot, Gemini, etc.). Tool-specific files (CLAUDE.md, .codex/, .cursor/rules/, .aider.conf.yml) @import this file rather than duplicate.
One source of truth, many tools. Change project conventions here.
Project
Repo = template for spec-driven, agentic software development. Defines workflow, artifacts, roles for building products. Workflow itself = the deliverable. Replace this section with a product overview when a project uses the template.
Read these first
memory/constitution.md— governing principles. Override only with explicit human approval..claude/memory/MEMORY.md— operational memory: workflow rules + project state, indexed. (agent-local, not committed to repo — load if present; skip if absent)docs/specorator.md— full workflow definition. (scaffold stub in freshspecorator initinstalls — defer to plugin CLAUDE.md §Specorator workflow if not yet populated)docs/specorator-product/— Specorator's own product steering for template-improvement work. Usedocs/steering/as downstream project steering templates.- Current feature's
specs/<feature>/workflow-state.md— active stage + what's already produced.
Operating rules
- Stay in scope. Each agent role has a defined responsibility (see
.claude/agents/). No code in research; no requirement changes during implementation. - Specs = source of truth. Implementation reveals a missing requirement → escalate, no silent invent. Update spec first, then code.
- Respect quality gates. Acceptance criteria in
docs/quality-framework.mdare non-negotiable. - Agentic security review — opt-in for any feature with autonomous tool-using agents. Invoke from Stage 9 (Review) or QA track. See
docs/agentic-security-review.md. - Trace everything.
REQ-<AREA>-NNN,T-<AREA>-NNN,TEST-<AREA>-NNN,ADR-NNNN. Reference IDs in commits, PRs, artifacts. Seedocs/traceability.md. - EARS for requirements. Functional requirements use EARS notation — map 1:1 to tests. See
docs/ears-notation.md. - ADRs for irreversible decisions. Architecturally load-bearing → ADR in
docs/adr/. Usetemplates/adr-template.md. ADR bodies are immutable; supersede to change. - Update workflow state. Hand off a stage → update
specs/<feature>/workflow-state.md. - Keep a product page alive. Public page at
sites/src/pages/index.astro(Astro static site, built intosites/dist/); prefer GitHub Pages. Update in the same PR as user-visible changes. - Consult
inputs/at intake. Every conductor's scope phase listsinputs/and asks the user which items are relevant. Never auto-extract zips or archives — extraction is always a confirmed step. Seedocs/inputs-ingestion.mdand ADR-0017. - Escalate ambiguity. No guessing. Ask the human or open a
clarificationsblock. - Template-self changes use
/specorator:updatefirst. Keywords: new track, skill, workflow, update template. - No direct commits on
main/develop. Every change lands via topic branch + merged PR. Push deny is the backstop, not the gate. See.claude/memory/feedback_no_main_commits.md. - Branch per concern; verify before push. One concern per PR;
verifygreen locally; never--no-verify. Seedocs/branching.md,docs/worktrees.md,docs/verify-gate.md. - Codex opens its PR. Non-trivial changes via Codex own worktree → commit → push → open PR → report URL. See
.codex/README.md. - Memory edits are docs-only. Updates to
.claude/memory/ride own PR with no changeset. See.claude/memory/feedback_memory_edits.md.
Repo conventions
- Markdown for all artifacts. Concise; precision over completeness in early iterations.
- File names = kebab-case. Per-feature work under
specs/<feature-slug>/. - One
README.mdper folder max. Folders below the repo root start with frontmatter (title,folder,description,entry_point: true); rootREADME.mdis exempt. - Glossary terms one-per-file under
docs/glossary/<slug>.mdvia/glossary:new "<term>". Legacy single-filedocs/UBIQUITOUS_LANGUAGE.mddeprecated by ADR-0010. - Commit messages: imperative, reference IDs (
feat(auth): add T-AUTH-014 password reset).
Agent classes
Track taxonomy frozen in ADR-0026. Below: agent classes per track.
| Class | Location | Purpose | Methodology |
| Lifecycle (Stage 1–11 specialists) | .claude/agents/ | Build one feature: analyst, pm, ux/ui-designer, architect, planner, dev, qa, reviewer, release-manager, sre, retrospective. | docs/specorator.md |
| Discovery specialists (opt-in) | .claude/agents/ | Pre-Stage 1 ideation: facilitator + product-strategist, user-researcher, game-designer, divergent-thinker, critic, prototyper. Produces chosen-brief.md. | docs/discovery-track.md (ADR-0005) |
| Stock-taking (opt-in, brownfield) | .claude/agents/legacy-auditor.md | Inventory existing systems before new work. Produces stock-taking-inventory.md. | docs/stock-taking-track.md (ADR-0007) |
| Sales (opt-in, service provider) | .claude/agents/ | Pre-contract: sales-qualifier, scoping-facilitator, estimator, proposal-writer. Produces order.md. | docs/sales-cycle.md (ADR-0006) |
| Project manager (opt-in) | .claude/agents/project-manager.md | Client-engagement governance based on P3.Express. State lives projects/<slug>/. Never edits specs/. | docs/project-track.md (ADR-0008) |
| Roadmap manager (opt-in) | .claude/agents/roadmap-manager.md | Outcome roadmaps, stakeholder maps, comms log under roadmaps/<slug>/. Read-only on specs/. | docs/roadmap-management-track.md (ADR-0012) |
| Portfolio (opt-in) | .claude/agents/portfolio-manager.md | P5 Express X/Y/Z cycles. Reads specs/*/workflow-state.md; never modifies spec artifacts. | docs/portfolio-track.md (ADR-0009) |
| Project scaffolder (opt-in) | .claude/agents/project-scaffolder.md | Source-led onboarding from collected docs/folders. State lives scaffolding/<slug>/. | docs/project-scaffolding-track.md (ADR-0011) |
| Quality assurance (opt-in) | .claude/skills/quality-assurance/SKILL.md | ISO 9001-aligned readiness review. State lives quality/<slug>/. | docs/quality-assurance-track.md |
| Agentic security (opt-in) | .claude/skills/agentic-security-review/SKILL.md | OWASP-aligned review path for autonomous agent risks. Produces quality/<slug>/agentic-security-findings.md. Invocable from Stage 9 or QA track. | docs/agentic-security-review.md |
| Project review (opt-in) | .claude/skills/project-review/SKILL.md | Evidence-backed project history review. Captures learnings, proposes improvements, opens an issue, and creates the first draft PR from its own worktree. State lives quality/<slug>/. | docs/project-review-workflow.md |
| Issue-breakdown (opt-in) | .claude/agents/issue-breakdown.md | Post-tasks. Issue → draft PRs. Appends log + hand-off. | docs/issue-breakdown-track.md |
| Issue-draft (opt-in) | .claude/agents/issue-draft.md | Post-Stage-1. Early draft PR from idea.md; living-PRD issue body. | docs/issue-draft-track.md |
| Issue-tackle (opt-in) | .claude/skills/tackle-issue/SKILL.md | Triage-first conductor. Scans issue/PR for open tasks, proposes path, creates worktree, guides execution, opens PR. Triggers on "tackle issue #N" or /issue:tackle. | docs/issue-tackle-track.md |
| Design (opt-in) | .claude/agents/design-lead.md | Brand-aware surface creation. State lives designs/<slug>/. | docs/design-track.md (ADR-0019) |
| Specorator improvement (companion) | .claude/skills/specorator-improvement/SKILL.md | Improve this template's scripts, tooling, workflows, docs, agents, skills, templates, state, or operations. | docs/specorator.md |
| Operational bots | agents/operational/ | Scheduled routines (review-bot, docs-review-bot, plan-recon-bot, dep-triage-bot, actions-bump-bot). PROMPT.md + README.md per bot. | — |
Skills (.claude/skills/) = reusable how-tos any agent invokes. Conductor skills are the conversational entry points — see .claude/skills/README.md.
Architecture refactor trigger: when the user asks to improve architecture, reduce coupling, refactor shallow modules, or make code more testable / AI-navigable, read .claude/skills/improve-codebase-architecture/SKILL.md before proposing edits.
Tool-specific notes
- Claude Code. Subagents, commands, skills, memory under
.claude/; permissions in.claude/settings.json.CLAUDE.mdimports this file plus constitution + memory index. - Codex. Primary context = this file. Codex specifics in
.codex/. - Cursor / Aider. Primary context = this file.
.cursor/rules/optional. - Plugins.
plugins/is the external capability contract layer adopted by ADR-0036: 12 versioned plugin groups, each withmanifest.mdandschema.json, used by downstream MCP tooling and external agents. Keep manifests and schemas in sync when a capability surface changes. - All tools. Templates in
templates/are framework-agnostic Markdown.
When the harness gets in your way
Process-light, with local + CI quality signals (npm run verify, PR-title checks, spell check, Pages, security scans, deps). Branch protection is light for early adoption. Fighting tooling? Fix the process, don't work around it.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.