# AGENTS.md

This repository stores product PRDs and supporting specs for distributed-system features. Agents working in this repo must preserve document consistency, traceability, and stable IDs.

## Purpose

- Keep product specs readable by humans and deterministic for AI-assisted review.
- Treat templates in `templates/` as the default source for new documents.
- Treat existing feature docs as user-authored records: improve only when explicitly asked.
- Preserve authoring speed while enforcing consistency and review-readiness for later stages.

## Repository Structure

- `features/<feature-name>/PRD.md`: primary product document for one feature.
- `features/<feature-name>/Scenarios.md`: validation and operational scenarios for that feature.
- `templates/`: canonical starting point for new PRDs and scenarios.
- `shared/`: reusable personas, invariants, security, observability, and compatibility references.
- `automation/`: review guidance and future machine checks.

## Product-spec provenance and traceability

Every PRD should include traceability metadata in front matter.

### Required PRD metadata
- `title`
- `feature_id`
- `owner`
- `status` (`draft | review | approved`)
- `target_release`
- `created`
- `last_updated`

### Optional PRD metadata
- `priority`
- `reviewers`
- `milestone`
- `dependencies`
- `JIRA`

### JIRA behavior
- `JIRA` is optional.
- Supports one or more values.
- Values are free-form but should be clearly ticket-like identifiers (e.g., `FRM-1234`, `PORT-567`).
- If absent, PRD authoring remains valid, especially for historical/draft-only items.
- At `review`/`approved` stage, if `JIRA` is present it should validate as explicit tracker IDs.

## Required Rules

### 1. PRD Traceability Is Mandatory (with optional ticket field)

- PRDs should include clear upstream references via `JIRA` when available.
- If a feature is driven by multiple source tickets, include multiple `JIRA` values.

Rules:
- `JIRA` must be in optional front matter; one or more values are allowed.
- If present, values must be explicit and non-empty.
- Do not leave placeholder values (empty strings, `TBD`, or fabricated IDs).

### 2. Stable IDs Must Be Preserved

Use and preserve these namespaces:

- `FR-###`: functional requirements
- `NFR-###`: non-functional requirements
- `INV-###`: feature-local invariants
- `SCN-###`: scenarios
- `JTBD-###`: jobs to be done
- `G-###`: goals
- `NG-###`: non-goals
- `R-###`: risks

Rules:
- Keep IDs unique within a feature folder.
- Do not renumber existing IDs unless the user explicitly asks for normalization.
- When adding new IDs, continue the existing sequence instead of re-packing gaps.
- `Q-###` is not required; Open Questions are tracked as section entries, not namespaced IDs.
- For `status: review` or `status: approved`, FR/NFR/INV IDs should remain stable and monotonic within scope.

### 3. Section Structure Must Stay Predictable

PRDs should keep the standard section order from `templates/PRD.template.md`.

Required PRD sections:

1. Executive Summary
2. Press Release
3. FAQ
4. Jobs to Be Done
5. Problem and Context
6. Goals and Non-Goals
7. System Invariants
8. User / Operator Scenarios
9. Functional Requirements
10. Non-Functional Requirements
11. Success Metrics
12. Risks
13. Open Questions
14. References

Rules:
- Prefer existing headings over inventing alternate names.
- Use unnumbered `##` section headings matching `templates/PRD.template.md`.
- Keep heading levels consistent so automated checks can parse documents reliably.
- If a section is intentionally empty, state that explicitly rather than deleting the heading.
- New headings should be minimal and parser-safe.

### 4. Progressive quality gates by PRD status

For `status: draft`:
- Front matter present.
- Core sections exist (at minimum Executive Summary, Press Release, FAQ, Jobs to Be Done, Goals/Non-Goals, System Invariants, Functional Requirements, Non-Functional Requirements, Risks, Open Questions).
- FR/NFR/INV IDs may be sparse.
- Placeholders are allowed where ambiguity is being iterated.

For `status: review` or `status: approved`:
- No unresolved `TBD` in core scope sections.
- FR, NFR, INV IDs must be stable and monotonic.
- Each FR and NFR has at least one acceptance criteria block.
- Scenario coverage is present or explicitly deferred.
- Shared references should be valid Markdown links when used.
- Cross-linking quality checks become strict.

### 5. Cross-References Must Be Explicit

Agents should maintain clear links between problem, requirements, and validation.

Rules:
- Each functional requirement should point to supporting `JTBD-*` and/or `SCN-*` IDs where practical.
- Each scenario should include `Validates:` or `Related Requirements:` with explicit `FR-*` and/or `INV-*` IDs.
- Shared product-wide constraints should reference files under `shared/` instead of duplicating generic text.
- Acceptance criteria should remain attached to each `FR-*` block.
- In review/approved mode, validate reference format and linkability.

### 6. Existing Specs Are Historical Records

Unless the user explicitly requests edits to an existing feature:

- do not rewrite tone or structure of existing PRDs just for consistency
- do not mass-convert older docs to the latest template
- do not renumber IDs or reword requirements without a concrete reason

Template improvements and new-doc scaffolding are preferred over retroactive cleanup.

### 7. PRD Agent Workflow (required for agent execution)

When asked to create or update a spec:

1. Read `README.md`, relevant template, and target feature folder first (if it already exists).
2. Reuse terminology already present in that feature folder and `shared/`.
3. Apply metadata and IDs consistently with this policy.
4. Add or preserve `JIRA` before finalizing narrative body.
5. Keep requirements atomic, testable, and easy to cross-link.
6. Prefer concise prose and explicit bullets over broad narrative blocks.
7. Before finishing, check that IDs, cross-references, and front matter are internally consistent.

## Skills

See `.agents/skills/README.md` for the full skill index and runbooks. Skills use the SKILL.md format and are compatible with OpenAI Codex, GitHub Copilot, Cursor, and Claude Code.

### User-facing entry points

| Skill | Path | Purpose |
|---|---|---|
| `prd-draft` | `.agents/skills/prd-draft/SKILL.md` | Draft a new PRD from a feature description |
| `prd-update` | `.agents/skills/prd-update/SKILL.md` | Update an existing PRD without redrafting untouched sections |
| `prd-review` | `.agents/skills/prd-review/SKILL.md` | Harden a draft PRD for `status: review` |
| `prd-lint` | `.agents/skills/prd-lint/SKILL.md` | Run structural validation on a PRD |

### Implementation skills (invoked by entry points)

| Skill | Path |
|---|---|
| `prd-intake-collector` | `.agents/skills/internal/prd-intake-collector/SKILL.md` |
| `prd-scaffold-filler` | `.agents/skills/internal/prd-scaffold-filler/SKILL.md` |
| `prd-customer-centricity-review` | `.agents/skills/internal/prd-customer-centricity-review/SKILL.md` |
| `prd-shared-linker` | `.agents/skills/internal/prd-shared-linker/SKILL.md` |
| `prd-scenario-seeder` | `.agents/skills/internal/prd-scenario-seeder/SKILL.md` |
| `prd-question-resolver` | `.agents/skills/internal/prd-question-resolver/SKILL.md` |

Shared interaction contract: `.agents/skills/prd-agent-conversation-contract.md`

## AGENTIC execution flow

### Draft path — use `prd-draft` as the entry point

`prd-draft` orchestrates the full pipeline automatically:

1. `internal/prd-intake-collector` — converts idea into structured seed
2. `internal/prd-scaffold-filler` — populates all PRD sections
3. `internal/prd-customer-centricity-review` (`--mode=framing`) — checks narrative quality early
4. `internal/prd-shared-linker` — audits coverage and links shared references
5. `internal/prd-scenario-seeder` — generates `Scenarios.md`
6. `internal/prd-customer-centricity-review` (`--mode=coverage`) — checks FR/SCN traceability
7. `prd-lint` (draft mode) — validates structure

Invoke with: "Draft a PRD for [feature description]" or `/prd-draft`

### Update path — use `prd-update` as the entry point

`prd-update` orchestrates incremental edits automatically:

1. `internal/prd-scaffold-filler` (update mode) — changes only requested sections
2. `internal/prd-shared-linker` — refreshes shared references when touched
3. `internal/prd-scenario-seeder` — updates scenario coverage when behavior changes
4. `prd-lint` — validates the result in draft or strict mode

Invoke with: "Update [feature_id] to add [change]" or `/prd-update`

### Pre-review path — run before `status: review`

1. `internal/prd-question-resolver` — categorizes open questions, proposes resolutions
2. `prd-lint` (strict mode) — all warnings become errors
3. `internal/prd-customer-centricity-review` (`--mode=coverage`, strict) — full traceability audit

Invoke with: "Prepare [feature_id] for review" or `/prd-review`

When status moves to `review` or `approved`, always run the pre-review path first.

## Template Guidance

When editing templates:

- optimize for future authoring consistency, not for one feature only
- include examples that demonstrate the expected format
- prefer machine-parseable label/value blocks where requirements are likely to grow
- keep optional guidance clearly marked as optional
- preserve parser-friendly heading shapes and section order.

## Validation Checklist

Before proposing a spec change, verify:

- PRD frontmatter includes required keys.
- Optional `JIRA` entries are present and non-empty when used; if provided, identifiers are explicit.
- No required section is missing.
- ID format validity (`FR-###`, `INV-###`, `NFR-###`, `SCN-###`, `JTBD-###`, `G-###`, `NG-###`, `R-###`) and monotonic sequencing where stable IDs exist.
- every `FR-*` and `NFR-*` has acceptance criteria.
- every scenario points to requirements/invariants.
- shared references point to correct files when product-wide guidance is reused.
- unresolved placeholders are removed or clearly assigned before `review`/`approved`.

## Review Checklist

Before proposing for review:

- `status`-specific gates match Draft vs Review/Approved expectations above.
- section order is complete and parser-friendly.
- ID consistency and cross-linking health are clean.
- customer-outcome review is clear (`internal/prd-customer-centricity-review` returns PASS or explicit, scoped deferrals).
- no speculative behavior has been added without source/problem grounding.

## Default Writing Style

- Default to English unless the user requests another language.
- Keep wording concrete and product-facing.
- Prefer customer impact, operator behavior, and validation intent over implementation detail.
- Use relative Markdown links inside the repo so documents remain portable.