4runr-cursor-setup

CLI tool that drops Cursor slash commands (under .cursor/commands/), a manifest, and project memory files into your repo—safely, with upgrade-friendly setup.

Documentation:

• Command Reference — What each command does (start with Start here)
• Git Usage Guide — Using this in Git workflows

New Repo Quick Start

Run once from your repository root. This fixes baseline files and installs every command group.

npx -y 4runr-cursor-setup@latest setup --strict

• setup = normalize the repo and install all groups (see docs/COMMANDS.md).
• --strict = fail if something still needs attention (good for scripts).
• Run setup again anytime you upgrade this package to refresh managed templates.

Cursor: If Project Rules don’t appear after setup, reload the window (Ctrl+Shift+P → Developer: Reload Window).

Golden Path

# Full install or refresh (doctor --fix --purge-orphans + add every group --force)
npx -y 4runr-cursor-setup@latest setup

# 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

Getting updates: After npm resolves a newer 4runr-cursor-setup, run setup again. That reapplies the latest tool-managed templates (same as add GROUP --force for each group).

Per-group install (optional)

Use add GROUP when you only want some groups, or run setup --dry-run to preview the full pass.

Contract / Invariants

• setup runs doctor --fix --purge-orphans then add every group with --force (unless --no-force) so repeat runs pick up new templates from the installed package
• 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

# One-step: full install/refresh (see `setup --help` for flags)
npx -y 4runr-cursor-setup@latest setup

# Add a command group (replace GROUP with: core, planning, governance, debugging, or design)
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

# Full install or refresh all command groups
npx -y 4runr-cursor-setup@latest setup

# 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 (core, planning, governance, debugging, design).

Available Groups

• core: Essential 4runr commands (start, close, cognitive-debt re-orient)
• planning: Planning commands (plan interrogation, phase, task)
• governance: Governance commands (decision, scope-change)
• debugging: Debugging commands (repro, verify)
• design: UI/UX specialist command (product-quality frontend thinking)

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 refresh all tool-managed command templates after upgrading the package:

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

To update only one group (e.g. core):

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

Un-managed files are never overwritten; your project structure stays intact.

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