# Global install
npm install -g codeops-mcp

# Or with yarn
yarn global add codeops-mcp

{
    "mcpServers": {
        "codeops": {
            "command": "codeops-mcp"
        }
    }
}

{
    "mcpServers": {
        "codeops": {
            "command": "codeops-mcp",
            "args": ["/path/to/custom/docs"]
        }
    }
}

{
    "mcpServers": {
        "codeops": {
            "command": "codeops-mcp",
            "env": {
                "CODEOPS_DOCS_PATH": "/path/to/custom/docs"
            }
        }
    }
}

┌──────────────────────────────────────────────────────────────────┐
│  REVERSE PATH (existing codebase → requirements → rebuild)       │
│                                                                  │
│  retro_requirements → make_requirements → make_plan → exec_plan  │
└──────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────┐
│  FORWARD PATH (new project → requirements → implementation)      │
│                                                                  │
│  make_requirements → make_plan → exec_plan                       │
└──────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────┐
│  QUICK PATH (add a feature to existing codebase)                 │
│                                                                  │
│  make_plan → exec_plan                                           │
└──────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────┐
│  UPGRADE PATH (bring outdated artifacts to current standards)     │
│                                                                  │
│  upgrade_plan [feature] / upgrade_requirements                    │
└──────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────┐
│  DISAMBIGUATION PATH (eliminate ambiguity before any work)        │
│                                                                  │
│  grill_me → make_plan → exec_plan                                │
│  grill_me → make_requirements → make_plan → exec_plan            │
│  grill_me (standalone deep-dive)                                  │
└──────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────┐
│  QUALITY GATE (review artifacts before execution)                 │
│                                                                  │
│  make_plan → preflight [feature] → exec_plan                     │
│  make_requirements → preflight requirements → make_plan           │
│  preflight (standalone audit of any artifact)                     │
└──────────────────────────────────────────────────────────────────┘

User: make_plan

Agent: What feature would you like to plan?

User: Add JWT authentication to our API

Agent: [Asks clarifying questions, analyzes codebase, then creates:]
  plans/jwt-auth/
  ├── 00-index.md
  ├── 01-requirements.md
  ├── 02-current-state.md
  ├── 03-auth-middleware.md
  ├── 04-token-service.md
  ├── 07-testing-strategy.md
  └── 99-execution-plan.md

User: exec_plan jwt-auth

Agent: [Reads the execution plan, implements tasks one by one,
        runs verification after each task, updates progress,
        asks about commits after each verified task]

User: I want to build a university lab management SaaS. Researchers book lab rooms,
ethics committee approves studies, participants sign up on a public page.
Built with Node, TypeScript, PostgreSQL.

make_requirements

Agent: [Conducts multi-turn discovery interview]
  - Maps stakeholders and user types
  - Analyzes comparable systems (suggests features you haven't thought of)
  - Walks through user journeys to find hidden requirements
  - Explores "what happens when..." edge cases
  - Produces formal requirement documents:

  requirements/
  ├── README.md              # Index, glossary, dependency graph
  ├── RD-01-scaffolding.md   # Project setup
  ├── RD-02-data-model.md    # Database schema
  ├── RD-03-auth.md          # Authentication & RBAC
  ├── RD-04-lab-booking.md   # Core booking functionality
  ├── ...
  └── RD-12-deployment.md    # Production deployment

User: make_plan
Agent: I found requirement documents. Which RD would you like to implement?
User: RD-04-lab-booking.md
Agent: [Creates implementation plan based on the requirement document]

User: retro_requirements

Agent: [Systematically analyzes the codebase in 10 phases:]
  Phase 0: Reconnaissance — manifests, directory structure, tech stack
  Phase 1: Structural Analysis — layers, modules, entry points, patterns
  Phase 2: Data Model — entities, relationships, constraints
  Phase 3: API Surface — endpoints, CLI commands, public interfaces
  Phase 4: Behavior Catalog — features translated to requirement statements
  Phase 5: Business Rules — validation, authorization, domain logic
  Phase 6: Cross-Cutting — auth, errors, logging, caching
  Phase 7: Integrations — external APIs, databases, services
  Phase 8: Gaps & Debt — TODOs, missing tests, security gaps
  Phase 9: Synthesis — produces the reconstruction brief

Output:
  requirements/_retro/
  ├── 00-project-profile.md
  ├── 01-architecture-analysis.md
  ├── ...
  ├── 08-gaps-and-debt.md
  └── 09-reconstruction-brief.md   ← Feed this to make_requirements

retro_requirements --scope src/auth          # Analyze only the auth module
retro_requirements --continue                # Resume an interrupted session

User: upgrade_plan jwt-auth

Agent: [Reads all plan documents, compares against current templates]

  Upgrade Report: jwt-auth
  Current Version: 1.5.0 (or "none — pre-versioning")
  Target Version: 1.7.0

  Will Be Added: commit mode flags, security checklist, techdocs step
  Will Be Updated: session protocol, success criteria
  Will Be Preserved: all technical specs, task states, scope decisions

  Proceed with upgrade?

User: upgrade_requirements

Agent: [Reads all RD documents, compares against current templates,
        adds missing sections like security considerations]

User: make_techdocs

Agent: [Analyzes codebase architecture and produces:]
  docs/
  ├── index.md                  # Home page with techdocs: true frontmatter
  ├── architecture/
  │   ├── overview.md           # System overview and diagrams
  │   ├── data-model.md         # Entity relationships
  │   └── api-design.md         # API surface documentation
  └── decisions/
      └── ADR-001-*.md          # Architecture Decision Records

User: gitcm

Agent: [Stages all changes, writes a detailed commit message to a temp file,
        commits using git commit -F, cleans up]

Result:
  feat(auth): add JWT token refresh endpoint

  - Add POST /api/auth/refresh endpoint
  - Implement token rotation with refresh token family tracking
  - Add rate limiting (5 refreshes per minute per user)
  - Tests added for all edge cases

User: gitcmp

Agent: [Same as gitcm, plus rebase and push. Reports conflicts if any.]

User: grill_me

I want to add a caching layer to my API

Agent: [Identifies the design tree — major decision branches:]
  1. What are you caching? (responses, queries, computed values)
  2. Cache backend? (Redis, in-memory, CDN)
  3. Invalidation strategy? (TTL, event-driven, manual)
  4. Cache key design? (naming convention, namespacing)

Agent: [Walks each branch one decision at a time:]
  "For Branch 1, we need to decide: what exactly are you caching?"
  → User answers
  "You said database queries. That implies [consequence]. Is that OK?"
  → Drills deeper into sub-decisions
  → Surfaces assumptions: "I'm now assuming X, Y, Z. Correct?"
  → Moves to next branch only when current one is fully resolved

Output: A shared understanding summary with all decisions, assumptions,
        constraints, and deferrals — ready for make_plan or make_requirements

User: grill_me

I want to add webhook support to our notification system.
Once we're aligned, let's make_plan.

Agent: [Runs full grill-me protocol on webhooks — retry strategy,
        payload format, authentication, rate limiting, failure handling,
        deduplication — resolving every ambiguity]

Agent: [Transitions to make_plan with Phase 1.1 already complete]

User: preflight jwt-auth

Agent: [Reads all plan documents in plans/jwt-auth/, then systematically audits:]

  Dimension 1: Codebase Grounding
    — Verifies every file reference, import, and component actually exists
    — Checks that assumed patterns match what the code actually uses

  Dimension 2: Completeness & Coverage
    — Finds missing error handling, edge cases, rollback steps

  Dimension 3: Internal Consistency
    — Cross-checks claims between documents for contradictions

  Dimension 4: Feasibility & Risk
    — Identifies technical risks, dependency conflicts, performance concerns

  Dimension 5: Clarity & Actionability
    — Flags vague language, ambiguous terms, missing acceptance criteria

Output: Findings report with severity ratings, options analysis for each
        finding, and recommendations. Iterates until clean pass.

preflight requirements              # Audit all requirement documents
preflight requirements RD-03        # Audit a specific requirement document
preflight jwt-auth 03-api-design    # Audit a specific plan document
preflight src/auth/                 # Audit any file or directory
preflight --continue                # Resume an interrupted session

User: analyze_project /path/to/my/project

Agent: [Reads package.json/Cargo.toml/go.mod/pyproject.toml, scans directory
        structure, detects language, framework, test runner, build tools]

Output: A complete .clinerules/project.md with:
  - Build, test, and verify commands
  - Directory layout
  - Coding conventions
  - Git conventions
  - Cross-references to all rule documents

# Install dependencies
yarn install

# Build
yarn build

# Run tests (107 tests across 4 test files)
yarn test

# Watch mode
yarn test:watch

src/
├── index.ts              # MCP server entry point
├── config.ts             # Configuration resolution
├── types/
│   └── index.ts          # Type definitions & constants
├── store/
│   ├── rule-store.ts     # In-memory document store
│   └── search-engine.ts  # TF-IDF search engine
├── tools/
│   ├── get-rule.ts       # Get rule by name
│   ├── list-rules.ts     # List all rules
│   ├── search-rules.ts   # Full-text search
│   ├── analyze-project.ts # Project analysis & project.md generation
│   └── get-setup-guide.ts # Setup instructions
└── __tests__/
    ├── store/            # Store & search engine tests
    └── tools/            # Tool integration tests
docs/                     # 13 bundled rule markdown files