Reusable PM-orchestrated multi-agent workflow for Cursor: skills, custom subagents, rules, and handoff docs. Copy into a project and fill project-context.
Stack-agnostic core. NestJS + Next.js + Playwright skills ship as an optional pack.
| Path | Purpose |
|---|---|
.agents/AGENTS.md |
Skill routing and subagent map |
.agents/skills/ |
Practice skills + project-context |
.agents/skills/optional/ |
NestJS / Next.js / Playwright (opt-in) |
.cursor/agents/ |
Specialist subagent definitions |
.cursor/rules/ |
Always-on workflow + commit/PR rules |
docs/AGENT_WORKFLOW.md |
Type A/B/C pipeline, gates, fallback routing |
docs/handoffs/ |
Artifact README + templates |
docs/ stubs |
Vision, requirements, architecture, decisions, design |
From this repo root:
PROJECT=~/path/to/your-app
cp -R .agents .cursor "$PROJECT/"
mkdir -p "$PROJECT/docs"
cp -R docs/AGENT_WORKFLOW.md docs/handoffs docs/adrs docs/design \
docs/PRODUCT_VISION.md docs/REQUIREMENTS.md docs/ARCHITECTURE.md \
docs/DATA_MODEL.md docs/DECISIONS.md \
"$PROJECT/docs/"Then in the project:
- Edit
.agents/skills/project-context/SKILL.md(product name, UI language, layout, package filters). - Fill stub docs under
docs/as you learn the domain. - Optionally keep or delete
.agents/skills/optional/(see below). - Prefer Multitask Mode in Cursor for Type B feature work so specialists can run as subagents.
- Open a new chat and use the example prompts below (start with “Make this repo ready”).
If your app uses Nest + Next (+ Playwright):
- Keep
.agents/skills/optional/(already copied with the template). - Set paths in
project-context(common convention:apps/api,apps/web,e2e/). - Include those skills in PM handoffs for FE/BE/QA roles.
If not: delete .agents/skills/optional/ and ignore nest/next references in agent prompts.
PM (main agent)
→ BA / Marketing / Visual / PO
→ Architect → Security (design)
→ FE + BE (parallel) → QA
→ UX + Security (implementation)
→ DevOps (if infra)
Artifacts live in docs/handoffs/{feature-slug}/. See docs/AGENT_WORKFLOW.md and docs/handoffs/README.md.
Copy-paste these into Cursor after the template files are in your project. Prefer Multitask Mode for Type B features.
Use these first (once per project) so agents have product context and correct paths:
Read .agents/AGENTS.md and docs/AGENT_WORKFLOW.md. Fill .agents/skills/project-context/SKILL.md for this repo: product name, one-line purpose, UI language, layout paths (frontend/backend/e2e if any), package manager, and workspace package filters. Do not invent product claims — ask me if something is unclear.
Based on the codebase and project-context, draft stub docs/PRODUCT_VISION.md, docs/REQUIREMENTS.md, docs/ARCHITECTURE.md, and docs/DATA_MODEL.md. Keep them short, mark unknowns as TODOs, and align paths with the real repo layout. Do not invent business metrics or private URLs.
We use NestJS + Next.js + Playwright with apps/api, apps/web, and e2e/. Keep .agents/skills/optional/ and update project-context plus .agents/AGENTS.md so FE/BE/QA handoffs reference those optional skills. If we do not use that stack, tell me what to delete instead.
Add a domain skill at .agents/skills/<domain>/SKILL.md for our core domain rules (keep it short). Register it in .agents/AGENTS.md under skill load order. No secrets or proprietary customer data.
Act as PM per docs/AGENT_WORKFLOW.md (Type B). Feature: <describe the feature>. Create docs/handoffs/<feature-slug>/00-intake.md, then run the specialist pipeline with Multitask Mode. Do not skip PO, architect, security, QA, or UX without justifying in intake. Write all handoff artifacts to disk.
Type B, copy-heavy: update <page/CTA>. Follow docs/AGENT_WORKFLOW.md. Skip architect/devops if intake justifies it. Run marketing → PO → FE → QA → UX. Artifacts under docs/handoffs/<slug>/.
Type A decision: <decision question>. Follow docs/AGENT_WORKFLOW.md. Create docs/handoffs/<slug>/00-intake.md, delegate to /architect, record the outcome in docs/DECISIONS.md and an ADR if significant. No implementation unless I ask.
Type C bug: <repro and expected behavior>. Triage per docs/AGENT_WORKFLOW.md, create a lightweight handoff folder, fix with the right developer agent(s), then /qa-tester. Escalate to /architect only if the design is wrong.
Resume feature slug <feature-slug>. Read docs/handoffs/<feature-slug>/, verify PM gates from docs/handoffs/README.md, and continue from the first incomplete phase. Do not re-run completed phases unless artifacts are wrong.
Run /architect for docs/handoffs/<slug>/ — read 03-acceptance-criteria.md and 01-requirements-brief.md, write 04-architecture-design.md only.
Replace <…> placeholders with your feature details. Full phase tables and fallback routing: docs/AGENT_WORKFLOW.md.
Add project-specific domain knowledge as .agents/skills/<your-domain>/SKILL.md and list it in .agents/AGENTS.md. Do not put secrets or proprietary questionnaires in a public fork of this template.
- UI language: set in
project-context(template suggests English). - Code, commits, and docs: English.
- PR assignee: configure per project in
.cursor/rules/pull-requests.mdc/project-context— this template does not hardcode a GitHub user.
Maintainers and contributors use pre-commit for Conventional Commits, markdown lint, and formatting.
# Requires: brew install pre-commit (or pipx/pip install pre-commit)
pre-commit install
pre-commit run --all-filesHooks (see .pre-commit-config.yaml):
| Hook | When | What |
|---|---|---|
conventional-pre-commit |
commit-msg |
Enforces type(scope): subject |
markdownlint-cli2 |
pre-commit | Markdown lint (auto-fix where possible) |
prettier |
pre-commit | Formats .md, .yaml, .json |
pre-commit-hooks |
pre-commit | Trailing whitespace, EOF, YAML/JSON, secrets |
Config: .markdownlint-cli2.yaml, .prettierrc.json.
Improvements welcome. Please open a pull request — see CONTRIBUTING.md for guidelines and the PR checklist. The GitHub PR template lives under .github/PULL_REQUEST_TEMPLATE.md.
Use and adapt freely in your projects. No warranty.