Skip to content

Commit 31c3b5b

Browse files
d-padmanabhand-padmanabhan
committed
docs(checklist): rewrite NEW_REPO_CHECKLIST.md for the full multi-artifact setup
Old checklist was a December 2025 artifact: rules-only, Cursor-only, hard-coded to the submodule path, missing every artifact added in the last six months. New version is a top-to-bottom rewrite covering all five artifacts this repo now ships across three agents. Structure: 10 numbered sections that follow the natural setup order. 1. Pick your install method - trade-off table for setup script vs symlink vs copy vs submodule 2. Rules - symlink and submodule recipes plus the agent-neutral AGENTS.md / CLAUDE.md alternative 3. Skills (Agent Skills) - symlink recipes for all three agents (.cursor/skills, .claude/skills, .codex/skills) 4. Slash commands - copy and symlink options, points at the commands/README.md catalog 5. MCP server (optional, recommended) - npm install/build/link recipe, points at mcp/cursor-rules-mcp/INSTALLATION.md for per-agent config 6. Lifecycle hooks (optional) - cursor-hooks-install.sh recipe with the honest note that hooks are Cursor-specific today 7. Workspace context files - tasks.md.template plus the four complex-task templates, documents all eight template files that actually exist in rules/templates/, and names the four tmp/ subdirectories with the workflow each one serves 8. Pre-commit hooks (recommended) - mirror this repo's stack (gitleaks, ggshield, pre-commit-hooks, markdownlint) 9. Git hygiene - keeps the .git/info/exclude policy from the previous commit (ea453f3) with rationale intact 10. Verify - end-to-end smoke test with an actual git-status check that tmp/ exclusion is in effect Frontmatter description updated from "Cursor rules and context templates" to the full multi-artifact / multi-agent scope. Fixes (in the rewrite): - Drops the old smart-quote (U+2019 in "repo's") - Drops em-dashes I initially used in the template descriptions (caught by post-write Unicode scan); now ASCII-only to match the repo convention from style commit 3761314 - Documents the previously-undocumented mkdir entries (tmp/pr, tmp/pr_reviews, tmp/agent_reports, tmp/bug_reports) by naming the workflow each one serves - Replaces ls-only verification with an end-to-end smoke test that exercises rules, skills, commands, templates, and the tmp/ exclusion in a single block Size: 55 -> 199 lines. Every section earns its place; no padding.
1 parent ea453f3 commit 31c3b5b

1 file changed

Lines changed: 158 additions & 18 deletions

File tree

‎NEW_REPO_CHECKLIST.md‎

Lines changed: 158 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,50 +1,164 @@
11
---
22
title: New Repo Setup Checklist
3-
description: Quick checklist to wire Cursor rules and context templates into a repository.
3+
description: Wire rules, skills, slash commands, MCP server, hooks, and workspace context files into a repo for any AI coding agent (Cursor, Claude Code, Codex).
44
---
55

66
# New Repo Setup Checklist
77

8-
## Setup rules
8+
Wire this repo's rules, skills, slash commands, MCP server, hooks, and workspace context files into a new project. Agent-neutral: works with Cursor, Claude Code, and Codex.
99

10-
- [ ] Add the rules (recommended: submodule + symlink):
10+
> [!TIP]
11+
> **Fast path** (if you keep this repo as a shared checkout):
12+
>
13+
> ```bash
14+
> /path/to/cursor-engineering-rules/setup-workspace.sh -S -l .
15+
> ```
16+
>
17+
> `-S` symlinks `rules/`, `-l` writes only `tmp/tasks.md`. Use `-f` for the full context-file set. The rest of this checklist documents what the script does **and the extras (skills, commands, MCP, hooks) it does not yet automate**.
18+
19+
## 1. Pick your install method
20+
21+
| Method | When | Trade-off |
22+
|---|---|---|
23+
| **Setup script** (`setup-workspace.sh`) | Default | Fast; symlinks `rules/` and scaffolds `tmp/`. Does not wire skills, commands, MCP, or hooks yet. |
24+
| **Symlink** | Personal use across many projects | One `git pull` in the source repo updates every consumer. Symlinks don't survive zip download. |
25+
| **Copy** | Self-contained projects, version-pinned | No live updates; re-copy on each bump. |
26+
| **Submodule** | Team projects, version-controlled | Locks the version; survives zip; needs `git submodule update --remote` to bump. |
27+
28+
This checklist assumes symlink or submodule. Copy is one `cp -r` per directory.
29+
30+
## 2. Rules
31+
32+
Rules (`.mdc`) load globally (`alwaysApply: true`) or by file-glob match.
1133
1234
```bash
35+
# Symlink (personal, one repo)
36+
mkdir -p .cursor
37+
ln -s /path/to/cursor-engineering-rules/rules .cursor/rules
38+
39+
# Submodule (team, pinned)
1340
git submodule add https://github.com/d-padmanabhan/cursor-engineering-rules.git .cursor-rules
1441
mkdir -p .cursor
1542
ln -s ../.cursor-rules/rules .cursor/rules
43+
44+
# Verify
45+
ls -la .cursor/rules
46+
readlink .cursor/rules
1647
```
1748
18-
- [ ] Confirm `.cursor/rules` points where you expect:
49+
**Agent-neutral alternative:** ship a single `AGENTS.md` at the repo root (Cursor + Codex honor it; Claude Code reads `CLAUDE.md` natively and is rolling out `AGENTS.md` support). Useful when you don't want a `.cursor/` directory.
50+
51+
## 3. Skills (Agent Skills)
52+
53+
Skills are multi-step playbooks: test plans, deployment runbooks, security audits, refactor guides, etc. Auto-selected via the SKILL.md `description` triggers; invoke manually as `/skill-name`.
1954
2055
```bash
21-
ls -la .cursor/rules
22-
readlink .cursor/rules
56+
# Cursor
57+
ln -s /path/to/cursor-engineering-rules/skills .cursor/skills
58+
59+
# Claude Code
60+
mkdir -p .claude
61+
ln -s /path/to/cursor-engineering-rules/skills .claude/skills
62+
63+
# Codex
64+
mkdir -p .codex
65+
ln -s /path/to/cursor-engineering-rules/skills .codex/skills
2366
```
2467
25-
## Setup workspace context files
68+
Mix per project. See the **Skills shipped in this repo** section in the parent [README.md](README.md) for the catalog.
2669

27-
- [ ] Create `tmp/` (workspace-local, gitignored)
28-
- [ ] Create `tmp/tasks.md` (minimum)
70+
## 4. Slash commands
71+
72+
Slash commands provide explicit workflow phase transitions (`/plan`, `/build`, `/review`, `/self-review`, `/quick-review`, etc.).
2973

3074
```bash
31-
mkdir -p tmp/pr tmp/pr_reviews tmp/agent_reports tmp/bug_reports
32-
cp .cursor/rules/templates/tasks.md.template tmp/tasks.md
75+
# Copy (no upstream updates)
76+
mkdir -p .cursor/commands
77+
cp -r /path/to/cursor-engineering-rules/commands/* .cursor/commands/
78+
79+
# Symlink (live updates)
80+
ln -s /path/to/cursor-engineering-rules/commands .cursor/commands
81+
```
82+
83+
Type `/<command>` in your agent's chat to trigger. See [commands/README.md](commands/README.md) for the full catalog (~19 commands).
84+
85+
## 5. MCP server (optional, recommended)
86+
87+
Install if you want **on-demand rule loading** via tool calls instead of pre-loading every `.mdc`. Useful when context budget matters.
88+
89+
```bash
90+
cd /path/to/cursor-engineering-rules/mcp/cursor-rules-mcp
91+
npm install
92+
npm run build
93+
npm link # optional: makes `cursor-rules-mcp` globally invokable
94+
```
95+
96+
Then configure your agent. See [mcp/cursor-rules-mcp/INSTALLATION.md](mcp/cursor-rules-mcp/INSTALLATION.md) for per-agent setup (Claude Desktop, Cursor, Claude Code, Codex).
97+
98+
## 6. Lifecycle hooks (optional)
99+
100+
Deterministic guardrails (block reading `.env`, gate destructive shell commands) and audit logging via Cursor's hooks API.
101+
102+
```bash
103+
/path/to/cursor-engineering-rules/scripts/cursor-hooks-install.sh
33104
```
34105

35-
Optional (for complex work):
106+
See [docs/HOOKS.md](docs/HOOKS.md) for what each hook does, how to disable individual checks, and how to write your own. **Cursor-specific** today; the hooks API is not yet portable across agents.
36107

37-
- [ ] `tmp/project-brief.md`
38-
- [ ] `tmp/active-context.md`
39-
- [ ] `tmp/progress.md`
108+
## 7. Workspace context files
109+
110+
Per-task context that the workflow rules (`010-workflow.mdc`, `020-agent-audit.mdc`) consume.
111+
112+
```bash
113+
# Minimum: a tasks file
114+
mkdir -p tmp
115+
cp .cursor/rules/templates/tasks.md.template tmp/tasks.md
116+
```
117+
118+
For complex multi-phase work, add the full context set:
40119

41120
```bash
42-
cp .cursor/rules/templates/project-brief.md.template tmp/project-brief.md
121+
cp .cursor/rules/templates/project-brief.md.template tmp/project-brief.md
43122
cp .cursor/rules/templates/active-context.md.template tmp/active-context.md
44-
cp .cursor/rules/templates/progress.md.template tmp/progress.md
123+
cp .cursor/rules/templates/progress.md.template tmp/progress.md
124+
```
125+
126+
Other available templates (use as needed):
127+
128+
- `creative-template.md.template` - design exploration / brainstorming
129+
- `design.md.template` - formal design doc
130+
- `prd.md.template` - product requirements
131+
- `reflect-template.md.template` - post-task reflection
132+
133+
Optional working directories some workflows expect (create only what you use):
134+
135+
| Path | Used by |
136+
|---|---|
137+
| `tmp/pr/` | PR drafts |
138+
| `tmp/pr_reviews/` | `/self-review`, `/quick-review` output |
139+
| `tmp/agent_reports/` | `020-agent-audit.mdc` audit reports |
140+
| `tmp/bug_reports/` | bug investigation notes |
141+
142+
```bash
143+
mkdir -p tmp/pr tmp/pr_reviews tmp/agent_reports tmp/bug_reports
144+
```
145+
146+
## 8. Pre-commit hooks (recommended)
147+
148+
Mirror this repo's pre-commit stack so your consumer repo gets the same secret-scanning + lint baseline.
149+
150+
```bash
151+
brew install pre-commit # macOS
152+
# pip install pre-commit # any platform
153+
154+
cp /path/to/cursor-engineering-rules/.pre-commit-config.yaml .pre-commit-config.yaml
155+
pre-commit install
156+
pre-commit run --all-files # baseline run
45157
```
46158

47-
## Git hygiene (recommended)
159+
Key hooks: `gitleaks`, `ggshield` (secret scanning), `pre-commit-hooks` (trailing whitespace, large files, private keys, mixed line endings), `markdownlint`.
160+
161+
## 9. Git hygiene
48162

49163
- [ ] **Git Hygiene:** Add the following to `.git/info/exclude` (preferred) instead of the repo `.gitignore`: `**/tmp/`, `.terraform/`, `.terragrunt-cache/`. Do not modify the repo `.gitignore` for these entries.
50164

@@ -57,3 +171,29 @@ EOF
57171
```
58172

59173
Rationale: these are personal / per-clone workspaces and tool caches, not project-wide policy. `.git/info/exclude` keeps them out of *your* working tree without imposing the convention on every collaborator via the committed `.gitignore`.
174+
175+
## 10. Verify
176+
177+
End-to-end smoke test that the wiring actually works:
178+
179+
```bash
180+
# Rules: at least one known rule is on disk
181+
ls .cursor/rules/200-python.mdc # or 210-go.mdc, 410-aws.mdc, etc.
182+
183+
# Skills: at least one SKILL.md is discoverable
184+
ls .cursor/skills/*/SKILL.md | head -3 # expect 3+ matches
185+
186+
# Commands: at least one command markdown is present
187+
ls .cursor/commands/*.md | head -3 # expect 3+ matches
188+
189+
# Templates resolve through the rules symlink
190+
ls .cursor/rules/templates/ | head -5 # expect template files
191+
192+
# Workspace exclusion is in effect (tmp/ should not appear in `git status`)
193+
mkdir -p tmp && touch tmp/x && git status --short | grep '^?? tmp' && echo "FAIL: tmp/ leaking into git" || echo "ok: tmp/ excluded"
194+
rm tmp/x
195+
```
196+
197+
For agent-side verification: open a known file type (`.py`, `.tf`, `.go`) and confirm the matching rule is detected in the agent's settings panel (Cursor: Settings -> Rules & Memories; Claude Code: `/rules` command).
198+
199+
If any step fails, re-check the symlink / copy step for that artifact.

0 commit comments

Comments
 (0)