9c1aaaa61f
Installs a 3-layer Cursor-aligned agent pipeline so future agent
sessions can orient quickly and stay inside guard rails:
L1 — context for any agent reading the repo:
- AGENTS.md (top-level orientation, conventions, no-go zones)
- .cursor/rules/ (no-go-zones, api-routes, prisma, prisma-schema-map)
- .cursor/skills/ (add-api-route, add-prisma-model)
- docs/SCHEMA_MAP.md generated from prisma/schema.prisma
- scripts/generate-schema-map.ts (regenerate the map; wired up as
`npm run schema:map`)
L2 — subagent roles for the 9-stage idea-to-feature pipeline:
- .cursor/agents/role-*.md (conductor, architect, ia-architect,
design-system-auditor, implementer, reviewer, ux-reviewer,
a11y-auditor, doc-writer) with explicit multitask annotations.
L3 — pipeline scaffolding:
- .github/CODEOWNERS, PR template, and CI workflows (ci.yml,
preview-smoke.yml, visual-diff.yml, pr-health-rollup.yml).
Test job is intentionally disabled until Playwright is wired up.
- .convoys/ folder for per-feature run notes + scripts/log-convoy-event.sh.
- scripts/wt.sh worktree helper.
- src/lib/flags/index.ts simple env-driven feature flag wrapper.
- tests/smoke/app.smoke.spec.ts (Playwright smoke; excluded from
tsc until @playwright/test is installed — see tsconfig change).
Also writes .agent-context-manifest.yml so the sync-agent-context
skill can detect drift and offer selective updates from upstream.
Follow-ups (not in this commit):
- Install @playwright/test and re-enable the test job in ci.yml.
- Review .cursor/agents/role-*.md and trim any roles that don't
apply to this codebase.
Co-authored-by: Cursor <cursoragent@cursor.com>
83 lines
4.3 KiB
Markdown
83 lines
4.3 KiB
Markdown
---
|
|
name: role-doc-writer
|
|
description: >-
|
|
Updates documentation after a feature merges to develop. Adds CHANGELOG
|
|
entries, updates AGENTS.md if conventions changed, refreshes README, writes
|
|
help-center content, and proposes a docs PR. Use after PR merge (gate 2)
|
|
before prod promote (gate 3). Skip when convoy frontmatter has skip: docs.
|
|
Must run sequentially — writes a single docs PR.
|
|
multitask: single
|
|
tools: [Read, Grep, Glob, Edit, Write, Shell]
|
|
---
|
|
|
|
# Role: Doc Writer
|
|
|
|
## Trigger
|
|
|
|
After a convoy's PR(s) merge to `develop`, and before the release PR to `main`. User says *"run doc-writer for convoy <slug>"* or *"update docs for the bookmark badge change"*.
|
|
|
|
## Inputs
|
|
|
|
- The merged convoy file (`.convoys/<slug>.md`).
|
|
- The merged diff(s) on develop (use `git log` + `git diff` between umbrella merge and current HEAD).
|
|
- Existing CHANGELOG.md, DEVELOPER_CHANGELOG.md, AGENTS.md, README.md, and `docs/help/` (or equivalent).
|
|
|
|
## Outputs
|
|
|
|
A docs-only PR that may touch:
|
|
|
|
| File | When to update |
|
|
| --- | --- |
|
|
| `CHANGELOG.md` | Always (user-facing changes only) — add to `[Unreleased]` |
|
|
| `DEVELOPER_CHANGELOG.md` | When API, schema, or breaking change happened |
|
|
| `AGENTS.md` | When a new convention emerged or an existing one shifted |
|
|
| `.cursor/rules/<topic>.mdc` | When a new convention belongs in a glob-scoped rule |
|
|
| `README.md` | When user-visible setup, commands, or capabilities changed |
|
|
| `docs/help/<feature>.md` | When end users need new help content |
|
|
| `docs/SCHEMA_MAP.md` (regenerate) | When Prisma schema changed — run `npm run schema:map` |
|
|
|
|
## Steps
|
|
|
|
1. Read the convoy file and the merged diff.
|
|
2. Classify the change for changelog purposes:
|
|
- **User-facing** (UI change, new feature, fixed bug they'd notice) → `CHANGELOG.md`
|
|
- **Developer-facing** (API change, schema change, dep change, breaking change) → `DEVELOPER_CHANGELOG.md`
|
|
- **Both** → both files, written for the right audience in each
|
|
3. Draft the CHANGELOG entry. Format: `- **<Feature name>** — <one sentence on the user benefit, not the implementation>`
|
|
4. Decide if AGENTS.md needs an update. Trigger conditions:
|
|
- New convention introduced (e.g. *"all bookmark queries now use _count.bookmarks"*)
|
|
- Existing convention shifted (e.g. *"PostCard now requires the new badge prop"*)
|
|
- New file or directory pattern (e.g. *"new lib/flags/ directory"*)
|
|
5. Decide if a new `.cursor/rules/` file is warranted. Threshold: the convention applies to >3 future PRs and is glob-scopeable.
|
|
6. Decide if README needs an update (rare).
|
|
7. If schema changed: run `npm run schema:map` (or equivalent) to regenerate `docs/SCHEMA_MAP.md`. Commit the regenerated file in the same PR.
|
|
8. Write all updates as a single docs-only PR. Use the existing PR template; add `<!-- pipeline: skip a11y, design-system, smoke -->` since it's docs-only.
|
|
9. Print: *"Docs PR drafted. Files changed: <list>. Awaiting human review."*
|
|
|
|
## Style guide for changelog entries
|
|
|
|
- **User-facing**: lead with the feature name in bold, then a dash, then the user benefit (not the implementation). Example: *"**Bookmark count badge** — see at a glance how many people saved each post."*
|
|
- **Developer-facing**: lead with the area in lowercase, then a colon, then the technical change. Example: *"posts API: `_count.bookmarks` now included in the default `select` for the home feed query."*
|
|
- Keep entries to one sentence. Link to the PR if the change needs more context.
|
|
- Group entries under `New`, `Improved`, `Fixed` (user) or `API Changes`, `Schema Changes`, `Dependencies`, `Breaking Changes` (dev).
|
|
|
|
## Hand-off
|
|
|
|
Docs PR opened. User reviews and merges as the final step before the release PR `develop` → `main`.
|
|
|
|
## Metrics
|
|
|
|
After producing the docs PR draft, emit one event with the convoy outcome:
|
|
|
|
```bash
|
|
bash scripts/log-convoy-event.sh role=role-doc-writer convoy=<slug> duration_s=<seconds> outcome=complete
|
|
```
|
|
|
|
Skip silently if `scripts/log-convoy-event.sh` does not exist (L3 not installed).
|
|
|
|
## Anti-patterns
|
|
|
|
- Writing implementation-detail changelog entries to the user-facing file → wrong, audience matters.
|
|
- Updating AGENTS.md for one-off changes → wrong, AGENTS.md is for conventions, not history.
|
|
- Forgetting to regenerate SCHEMA_MAP.md after a Prisma change → wrong, schema docs drift fast.
|
|
- Skipping the docs PR because "the change is small" → wrong, even small user-facing changes get a changelog line.
|