Randall Stillwell 9c1aaaa61f Bootstrap agent-context pipeline (L1 + L2 + L3)

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>

2026-05-23 14:55:18 -05:00

4.3 KiB

Raw Permalink Blame History

name

description

multitask

tools

role-doc-writer

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.

single

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 " 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

Read the convoy file and the merged diff.
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
Draft the CHANGELOG entry. Format: - **<Feature name>** — <one sentence on the user benefit, not the implementation>
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")
Decide if a new .cursor/rules/ file is warranted. Threshold: the convention applies to >3 future PRs and is glob-scopeable.
Decide if README needs an update (rare).
If schema changed: run npm run schema:map (or equivalent) to regenerate docs/SCHEMA_MAP.md. Commit the regenerated file in the same PR.
Write all updates as a single docs-only PR. Use the existing PR template; add  since it's docs-only.
Print: "Docs PR drafted. Files changed: . 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 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.

4.3 KiB Raw Permalink Blame History