AGENTS.md · git:20261001.5fd94dd · 2026-10-01 · sha256 d739176b32d88a0c

AGENTS.md git:20261001.5fd94ddA

Immutable. This exact content never changes and is served at /api/v1/blob/d739176b32d88a0c.

# Working on ai-prd-workflow

This repository is a set of prompts. The prompt files at the repo root are the product; everything else exists to ship them and to check them. Read CONTRIBUTING.md for the full rules; these are the ones an AI agent most often gets wrong.

- **Edit the root prompts, never `skills/`.** `skills/` is generated from the root prompts by `./install.sh --build`. After changing a prompt, rebuild and commit `skills/` in the same commit.
- **Shared sections live in `shared/`.** Some sections appear word for word in several prompts. Edit the file in `shared/` and run `python3 scripts/check-prompts.py --fix`; editing one copy fails CI.
- **Contracts move with the prompts.** If a prompt starts or stops reading or writing an artifact (PRD.md, FEATURES.md, RFCS.md, ...), update the contracts table in CONTRIBUTING.md in the same commit.
- **The example is real output.** `examples/url-shortener/after/` was produced by running the commands. Do not hand-edit it to match a prompt change; rerun the commands, or leave it and say it predates the change.
- **Versions move together.** `VERSION` in `install.sh`, `version` in `.claude-plugin/plugin.json`, and the CHANGELOG entry.

Before committing, run:

```bash
python3 scripts/check-prompts.py
python3 -m unittest discover scripts
./install.sh --build && bash scripts/test-install.sh
```

When writing prompt text: keep it tool-agnostic and concrete, and say why a rule exists when the reason is not obvious — the existing prompts do this, and the reasons are what stop a later edit from "simplifying" the rule away.