Agent Kit

Shared Cursor rules, workflow personas, slash commands, and skills for rcrdk TypeScript / React projects — coding rules in .mdc, Strict/Lean personas, /rcrdk-* macros and ops commands, and bundled skills.

This is a source repository, not a dependency. Its content is copied into each consumer as committed files under agents/; consumers have no submodule and fetch nothing at install time. Used by rcrdk/utils and app templates.

Deeper diagrams and adoption flows: docs/foundations.md · docs/flows-and-adoption.md.

---

What you get

Layer	Format	Loaded by
Rules	.mdc with YAML front matter	Cursor, Claude Code (via agents/rules)
Personas	.md agents (name + description)	Cursor + Claude (.cursor/agents, .claude/agents)
Commands	.md slash commands	Cursor / Claude (/rcrdk-*)
Skills	SKILL.md per skill directory	Cursor, Claude Code (via agents/skills)

Rules cover TypeScript style, React patterns, testing, commits, GitHub CLI account safety (gh-personal only), security, docs upkeep, Codebase Memory MCP–first discovery, plus always-on workflow orchestration and honest delivery.

Personas separate roles (/plan vs /do vs /review) with Strict/Lean pipelines and a /secure gate — see workflow-orchestrator.

Commands automate commits, test fixes, rule reviews, codebase indexing, DX/setup, and multi-phase macros (full delivery, hotfix, dual review, incidents, …).

Skills bundle behavioral refinements (Karpathy Guidelines, TDD, clean code, reviewers, …).

---

Quick start

1. Clone agent-kit somewhere

git clone git@github.com:rcrdk/agent-kit.git ~/dev/agent-kit

It is a working copy you install from — it does not need to live inside the consumer.

2. Install into the consumer repo

From the consumer's root:

node ~/dev/agent-kit/scripts/setup-consumer.mjs

This copies rules/, personas/, commands/, and skills/ into the consumer's agents/, writes its own scripts/setup-agent-links.mjs, merges gitignore / prettierignore entries and the setup:agent-links package script, then runs the linker.

After linking:

.cursor/rules    → agents/rules/     ← committed copies
.cursor/agents   → agents/personas/  ← workflow personas
.cursor/commands → agents/commands/
.cursor/skills   → agents/skills/
.claude/rules    → agents/rules/
.claude/commands → agents/commands/
.claude/skills   → agents/skills/
.claude/agents   → agents/personas/  ← same personas for Claude Code

Commit agents/ — it is now the consumer's own content. Reload Cursor if rules, agents, or commands do not appear.

3. Calibrate the project (recommended)

In Cursor, run:

/intake

Reads the app root README.md and writes project.mdc (Strict/Lean, security gate, active agents/skills) using templates/project.mdc.template.

4. Index the codebase (optional)

/rcrdk-index-codebase

Requires Codebase Memory MCP. The command checks MCP config and adds .codebase-memory/ to .gitignore.

---

Repository layout

agent-kit/
├── rules/
│   └── *.mdc            # flat — coding + workflow rules for every project
├── personas/
│   └── *.md             # slash-routed workflow agents (/plan, /do, …)
├── agents-md/
│   └── base.md          # shared AGENTS.md body, inserted at install time
├── scripts/
│   ├── setup-consumer.mjs   # copies the kit into a consumer repo
│   └── check-rules.mjs  # validates rules, commands, personas, and base.md
├── skills/
│   └── <name>/SKILL.md  # bundled skills (incl. karpathy-guidelines)
├── docs/
│   ├── foundations.md
│   └── flows-and-adoption.md
├── templates/
│   ├── AGENTS.md
│   ├── project.mdc.template
│   ├── agents-*.md
│   ├── mcp.json
│   ├── claude-settings.json
│   └── dx/
└── commands/
    └── *.md             # /rcrdk-* ops + macros

Rules are flat and universal. Every .mdc in rules/ is copied into every consumer repo — no per-project folders, no overrides. Where projects genuinely differ, the rule covers both cases and states how to detect which applies: project-structure (feature-driven vs flat src/), package-installation (pnpm / yarn / npm / bun), test-runner (Vitest / Jest).

Personas live in kit personas/ as .md files with name + description (Cursor + Claude agent format). They are copied to agents/personas/, which .cursor/agents and .claude/agents point at.

Commands live at commands/ root — same set for every consumer repo.

agents-md/base.md is inserted into the consumer's root AGENTS.md once, at install time, and is that project's prose from then on. See agents-md/README.md.

One block stays generated: between <!-- BEGIN:agent-kit-rules --> and <!-- END:agent-kit-rules -->, rebuilt from the consumer's own agents/rules/*.mdc on every setup:agent-links run, because Claude Code has no rules directory.

Each consumer owns its linker. templates/setup-agent-links.mjs is copied into the project as a real script — it reads only that project's agents/ folder and knows nothing about agent-kit.

---

Quality modes (Strict / Lean)

Set in project.mdc (via /intake). Default without a file: Lean for small tasks.

Mode	Pipeline
Strict	/plan → /do → /debug → /test → /review → /secure if gate → /refactor? → /doc / /git
Lean	/do → /debug if needed → /review → /git; /test and /secure if gate or requested

/secure gate after /review when the change touches secrets, auth/RBAC, multi-tenant, PII/GDPR, or public APIs/webhooks/uploads. When unsure, run /secure. Details: workflow-orchestrator.

---

Personas

Command	Persona	Role
/intake	intake	README → project.mdc
/architect	architect	Architecture — no feature code
/plan	planner	Plan + Strict/Lean handoff
/do	executor	Implementation
/review	code-reviewer	Code review
/debug	debugger	Diagnosis / root cause
/test	qa-tester	Tests
/secure	security-reviewer	Security
/refactor	refactorer	Structure without behavior change
/doc	document-specialist	Docs / JSDoc
/git	git-master	Branches, commits, PRs
/restart	restart	Local restart from project.mdc
/devops	devops	CI/CD, environments, deploy
/sre	sre	Incidents, observability
/data	data-engineer	Data pipelines / modeling
/product	product	Prioritization / roadmap

/agents lists active agents and skills from project.mdc.

---

Slash commands

Ops

Command	Description
/rcrdk-commit-unstaged	Commit staged files first, then unstaged/untracked as small Conventional Commits; tests last
/rcrdk-index-codebase	Index or reindex with Codebase Memory MCP; verify install; gitignore .codebase-memory/
/rcrdk-review-rules	Review branch changes against project rules; summarize fixes; ask before implementing
/rcrdk-fix-tests	Fix broken tests only; log-scoped or branch-aware discovery
/rcrdk-setup-agent-kit	Install or refresh agent-kit — copy content in, wire scripts, gitignore, symlinks
/rcrdk-setup-dx	Install selected DX from rcrdk/utils — ESLint, Prettier, TS, EditorConfig, VS Code, Husky

Macros (multi-phase)

Command	Description
/rcrdk-full-delivery	Strict pipeline in one conversation
/rcrdk-hotfix	Lean implement + debug + light review
/rcrdk-dual-review	Code review + security in one pass
/rcrdk-debug-and-fix	Debugger then executor
/rcrdk-document-commit	Docs + conventional commit message (no auto-commit)
/rcrdk-honest-close	Symptom/cause/evidence close summary
/rcrdk-platform-pipeline	CI/CD-only DevOps pass
/rcrdk-prod-incident	Production incident triage (SRE)

Each command is a markdown file with YAML front matter (name, description).

---

Bootstrap a new consumer repo

From the consumer repository root:

KIT=~/dev/agent-kit    # your agent-kit clone

# Fresh install, or refresh the copied content of an existing consumer
node "$KIT"/scripts/setup-consumer.mjs

# Wire scripts and config only, leave agents/ content alone
node "$KIT"/scripts/setup-consumer.mjs --no-vendor

# Preview
node "$KIT"/scripts/setup-consumer.mjs --dry-run

Or in Cursor: /rcrdk-setup-agent-kit

The script copies rules/, personas/, commands/, skills/ into agents/, writes scripts/setup-agent-links.mjs, README stubs, AGENTS.md, MCP and Claude settings, merges gitignore / prettierignore entries and the setup:agent-links package script, then runs the linker.

Re-running it overwrites the names agent-kit ships and leaves consumer-only files alone. Review the diff before committing — deliberate local edits to a shared rule get reverted otherwise.

Templates live in agent-kit/templates/ (templates/dx/ for DX configs used by /rcrdk-setup-dx). Use --dry-run to preview, --force-scripts to regenerate the consumer's linker.

---

Rules overview

All rules live in rules/ and apply to every project that copies agent-kit in.

Category	Rules
Workflow	workflow-orchestrator — Strict/Lean, /secure gate, persona routing; honest-delivery — symptom/cause/evidence DoD
Discovery	codebase-memory-first — MCP before filesystem search
Architecture	project-structure, imports, barrel-exports, file-size-limits, deduplication
TypeScript	typescript, type-imports, strict-equality, naming-conventions, function-parameters, …
Style	constants-and-variables, control-flow, functional-programming, optional-chaining, array-access, …
React	react-components, utility-functions
Testing	test-runner, test-approach, test-fixing, test-mocks, test-organization, test-date-mocks, …
Process	ask-before-commit, github-cli — gh-personal alias only, commit-messages, package-installation, documentation, security, cursor-rules, file-naming

Writing a rule that fits every project

A rule must hold in a flat src/utils/ repo and a feature-driven src/features/ repo, under any package manager, with Vitest or Jest. When something varies, name the signal to detect it (lockfile, devDependencies, presence of src/features/) and cover each case — never hardcode one project's paths or commands.

---

Skills overview

See skills/README.md. Bundled: karpathy-guidelines, clean, code-reviewer, debugger, evidence-verifier, interviewer, logic-reviewer, performance, security-reviewer, tdd.

---

Adding or changing content

New rule (applies to every project)

1. Create rules/<name>.mdc
2. Follow cursor-rules.mdc (front matter, alwaysApply or globs)
3. Make it hold for every consumer — cover both src/ layouts, any package manager, either test runner
4. Copy it into consumer repos and re-run their setup:agent-links

New persona

1. Create personas/<name>.md with YAML front matter (name, description)
2. Add a row to workflow-orchestrator routing
3. Document in this README’s Personas table
4. Copy it into consumer repos

Validate before committing

node scripts/check-rules.mjs

Checks front matter, dead .mdc links, hardcoded package managers or test runners, personas, and unknown tokens in base.md.

Shared AGENTS.md content

1. Edit agents-md/base.md
2. Apply the same edit by hand in each consumer's AGENTS.md — the base is inserted once at install and never regenerated
3. Commit the result

New skill (bundled in agent-kit)

1. Create skills/<name>/SKILL.md with YAML front matter (name, description)
2. Document in skills/README.md
3. Copy skills/<name>/ into consumer repos that want it

New slash command

1. Create commands/<name>.md with:

   ---
   name: rcrdk-my-command
   description: One-line summary for Cursor command picker
   ---

2. Document workflow in the markdown body

3. Update consumer agents/commands.md and agents/README.md in utils, saas-template, and indexes catalog when the command ships

4. Copy it into consumer repos

---

Consumer setup (for maintainers)

The consumer's scripts/setup-agent-links.mjs is a copy of templates/setup-agent-links.mjs. It reads only that project's agents/ folder and does four things:

// 1. agents/commit-messages.cursorrules  ⇐ agents/rules/commit-messages.mdc
// 2. .cursor/{rules,skills,commands,agents} and .claude/{…} → ../agents/*
// 3. CLAUDE.md → AGENTS.md, .cursorrules → agents/commit-messages.cursorrules
// 4. AGENTS.md rules block ⇐ agents/rules/*.mdc front matter

Gitignore in consumer repos — only the generated views; everything under agents/ is committed:

# Agent symlinks and generated files (created by setup:agent-links)
.cursor/rules
.cursor/skills
.cursor/commands
.cursor/agents
.claude/rules
.claude/commands
.claude/skills
.claude/agents
.claude/settings.local.json
CLAUDE.md
.cursorrules
agents/commit-messages.cursorrules

# Codebase Memory MCP (local index — see /rcrdk-index-codebase)
.codebase-memory/

Prettierignore the copied folders (/agents/rules, /agents/personas, /agents/commands, /agents/skills) so reformatting does not make every later copy-in diff every file.

---

Ecosystem

agent-kit is the rules + personas + commands + skills layer for rcrdk TypeScript/React repos. These tools complement it — not vendored inside agent-kit, but designed to work together:

Tool	Role	How it connects
Codebase Memory MCP	Local repo knowledge graph — calls, routes, architecture, semantic search	codebase-memory-first rule; /rcrdk-index-codebase command
Superpowers	Agentic skills — brainstorming, TDD, planning, subagent-driven development, code review	Copy the skills you want into a project's agents/skills/, keeping upstream's LICENSE
Karpathy Guidelines	Agent behavior — clarify assumptions, minimal diffs, verifiable success criteria	Bundled in skills/karpathy-guidelines/ (MIT)

Third-party skills (optional)

A project can add skills from other libraries by copying the skill folder into its own agents/skills/<name>/. Keep the upstream LICENSE alongside it, and record where it came from so it can be refreshed later. setup:agent-links needs no configuration — it links the whole agents/skills/ folder, whatever is in it.

Skill content stays owned by its upstream project; agent-kit only ships its own bundled skills.

---

Related

Resource	Link
docs/foundations.md	Kit ↔ Cursor diagrams, role separation
docs/flows-and-adoption.md	Flows A–H, adoption checklist, maintenance
indexes catalog	Personal map of tools and workflows
saas-template	App template built on agent-kit
Cursor rules docs	https://cursor.com/docs/context/rules

---

License

Same as consuming projects — internal rcrdk tooling. Open for reuse across rcrdk repos.