4runr-cursor-setup

Documentation:

• Command Reference — Complete command and flag documentation
• Git Usage Guide — End-to-end Git repo usage guide

New Repo Quick Start

PowerShell:

# Step 1: Repair / normalize repo (safe)
npx -y 4runr-cursor-setup@latest doctor --fix --purge-orphans --strict

# Step 2: Install core commands
npx -y 4runr-cursor-setup@latest add core

# Step 3: Verify health
npx -y 4runr-cursor-setup@latest doctor --strict

Bash:

# Step 1: Repair / normalize repo (safe)
npx -y 4runr-cursor-setup@latest doctor --fix --purge-orphans --strict

# Step 2: Install core commands
npx -y 4runr-cursor-setup@latest add core

# Step 3: Verify health
npx -y 4runr-cursor-setup@latest doctor --strict

Golden Path

# Repair / normalize any repo (safe)
# Installs: manifest + docs + .cursor/rules/project.md
npx -y 4runr-cursor-setup@latest doctor --fix --purge-orphans --strict

# Install core commands (updates if already installed)
# Installs: .cursor/commands/* (4runr-start.md, 4runr-close.md)
npx -y 4runr-cursor-setup@latest add core --force

# CI / health check (fails if issues)
npx -y 4runr-cursor-setup@latest doctor --strict

# Read-only audit plan (for reviews)
npx -y 4runr-cursor-setup@latest doctor --plan

Note: If Cursor UI doesn't show Project Rules after running doctor --fix, reload the window (Ctrl+Shift+P → Developer: Reload Window).

Contract / Invariants

• Tool never overwrites un-managed files (even with --force)
• --force overwrites only tool-managed files (marker + manifest)
• remove GROUP deletes only manifest-owned files (marker + manifest entry)
• doctor --purge-orphans deletes only marker files not in manifest
• doctor --strict exits non-zero only when final issues exist

Usage

PowerShell / CMD / Bash:

# List available command groups
npx -y 4runr-cursor-setup@latest list

# Add a command group (replace GROUP with: core, planning, governance, or debugging)
npx -y 4runr-cursor-setup@latest add GROUP [--force] [--dry-run]

# Remove a command group
npx -y 4runr-cursor-setup@latest remove GROUP [--dry-run]

# Audit and repair
npx -y 4runr-cursor-setup@latest doctor [--fix] [--strict] [--json] [--dry-run] [--purge-orphans] [--plan]

PowerShell Examples:

# List groups
npx -y 4runr-cursor-setup@latest list

# Health check
npx -y 4runr-cursor-setup@latest doctor --strict

# Repair and normalize
npx -y 4runr-cursor-setup@latest doctor --fix --purge-orphans --strict

# Add groups (replace with actual group name)
npx -y 4runr-cursor-setup@latest add planning
npx -y 4runr-cursor-setup@latest add governance
npx -y 4runr-cursor-setup@latest remove debugging
npx -y 4runr-cursor-setup@latest add core --dry-run

✅ Replace GROUP with a real group name (planning, governance, debugging, core).

Available Groups

• core: Essential 4runr commands (start, close)
• planning: Planning commands (phase, task)
• governance: Governance commands (decision, scope-change)
• debugging: Debugging commands (repro, verify)

What /close Means

The /close command (from the core group) produces a session handoff summary. It is a reflection of verified repo state, not a progress generator.

Key Rules

• Evidence-gated: Every claimed change must be proven with repo evidence (git status, git diff, file paths, quoted snippets)
• Read-only sessions: If no files were changed, /close must explicitly state: "No files were created, modified, or deleted. This session was read-only inspection only."
• No hallucination: The command cannot invent work, summarize changes without evidence, or list files that don't exist
• Clean repo → clean close: A clean repository results in a read-only close output

Verification Gate

Every /close output starts with a mandatory REPO CONTEXT PROOF section:

• pwd (current directory)
• git rev-parse --show-toplevel (repo root verification)
• git status --porcelain (working tree status)

If git is unavailable (not a git repo or wrong directory):

• /close switches to NON-GIT MODE
• Output states: "NOT A GIT REPO / WRONG DIRECTORY"
• No claims about file modifications, diffs, or line numbers
• Provides a corrective hint (cd to repo root, or initialize git)

If git is available:

• Proceeds with VERIFICATION block:
  • git status output
  • git diff --name-only output
  • Explicit list of modified files (or "NONE")
• Only lists changes with evidence (git diff, file paths, quoted snippets)
• If evidence is unavailable, states "NOT AVAILABLE" rather than guessing

What It Does

• With changes: Lists verified changes with evidence (file paths, diffs, quotes)
• Without changes: States explicitly that the session was read-only
• Always: Provides next steps and project memory updates (docs/status.md, docs/todo.md, docs/decisions.md)

Important: /close reflects only what actually happened in the repo. It does not generate progress or invent improvements.

Upgrading Existing Repos

To update the /close template (and other core commands) in an existing repo:

npx -y 4runr-cursor-setup@latest add core --force

This updates the templates to the latest version while preserving your project structure.

Common Scenarios

"0 files written" When Adding a Group

Reasons and exact next steps:

1. Already installed and managed (normal)

   • Files exist, have marker, and are in manifest
   • Action: Nothing to do. This is expected.

2. Orphan marker files

   • Files have marker but aren't in manifest
   • Fix:

     npx -y 4runr-cursor-setup@latest doctor --purge-orphans
     npx -y 4runr-cursor-setup@latest add planning

     (Replace planning with the actual group name)

3. Unmanaged collision

   • Files exist without marker (user-created)
   • Tool will never overwrite these
   • Fix (manual):

     # Rename or move the colliding file
     mv .cursor/commands/4runr-start.md .cursor/commands/4runr-start.md.backup
     # Then re-run add
     npx -y 4runr-cursor-setup@latest add core

Orphan Marker Files

What they are:

• Files in .cursor/commands/ with the managed marker (<!-- managed-by: 4runr-cursor-setup -->) but not listed in the manifest

Why they exist:

• Manifest was deleted or reset
• Files were manually created with marker
• Manifest drift

Fix:

npx -y 4runr-cursor-setup@latest doctor --purge-orphans

What it does:

• Deletes only orphan marker files (safe)
• Never deletes managed files or unmarked files

Unmanaged Collision

What it is:

• A file exists at a path where the tool wants to install a template, but the file doesn't have the managed marker

Why it happens:

• User created a file manually
• File was created before tool installation

Resolution (manual):

1. Rename or move the colliding file:

   mv .cursor/commands/4runr-start.md .cursor/commands/4runr-start.md.backup

2. Re-run add:

   npx -y 4runr-cursor-setup@latest add core

Important: The tool will never overwrite unmanaged files, even with --force.

ETARGET / npx Cache Desync

Symptom:

• npx -y 4runr-cursor-setup@latest fails with ETARGET but the version exists on npm

Cause:

• npx cache is out of sync with npm registry

Fix (PowerShell):

npm cache clean --force
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx" -ErrorAction SilentlyContinue

Fix (Bash):

npm cache clean --force
rm -rf ~/.npm/_npx

Then retry your command.

Troubleshooting

PowerShell Error: The '<' operator is reserved for future use

Cause: Copied placeholder like GROUP from documentation without replacing it.

Fix: Use actual group names instead: planning, governance, debugging, or core.

Example:

# ❌ Wrong (causes error if you type GROUP literally)
npx -y 4runr-cursor-setup@latest add GROUP

# ✅ Correct (replace GROUP with actual name)
npx -y 4runr-cursor-setup@latest add planning

Development

# Build
npm run build

# Run tests
npm test

# Run smoke test
npm run test:smoke

# Development mode
npm run dev