Skip to content

AGENTS.md

Latest commit

 

History

History
84 lines (65 loc) · 10.8 KB

AGENTS.md

File metadata and controls

84 lines (65 loc) · 10.8 KB

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

  1. memory/constitution.md — governing principles. Override only with explicit human approval.
  2. .claude/memory/MEMORY.md — operational memory: workflow rules + project state, indexed. (agent-local, not committed to repo — load if present; skip if absent)
  3. docs/specorator.md — full workflow definition. (scaffold stub in fresh specorator init installs — defer to plugin CLAUDE.md §Specorator workflow if not yet populated)
  4. docs/specorator-product/ — Specorator's own product steering for template-improvement work. Use docs/steering/ as downstream project steering templates.
  5. 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.md are 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. See docs/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/. Use templates/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 into sites/dist/); prefer GitHub Pages. Update in the same PR as user-visible changes.
  • Consult inputs/ at intake. Every conductor's scope phase lists inputs/ and asks the user which items are relevant. Never auto-extract zips or archives — extraction is always a confirmed step. See docs/inputs-ingestion.md and ADR-0017.
  • Escalate ambiguity. No guessing. Ask the human or open a clarifications block.
  • Template-self changes use /specorator:update first. 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; verify green locally; never --no-verify. See docs/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.md per folder max. Folders below the repo root start with frontmatter (title, folder, description, entry_point: true); root README.md is exempt.
  • Glossary terms one-per-file under docs/glossary/<slug>.md via /glossary:new "<term>". Legacy single-file docs/UBIQUITOUS_LANGUAGE.md deprecated 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.md imports 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 with manifest.md and schema.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.