Cline rules

1# Generated Project Configuration
2 
3> **Auto-generated by `analyze_project`** (deep analysis)
4> **Project:** codeops-mcp
5> **Type:** library
6 
7---
8 
9## 🚨 MANDATORY: Load CodeOps Rules Before Any Work
10 
11**Before ANY planning or implementation, the AI agent MUST load these rules
12using the codeops-mcp tools:**
13 
141. `get_rule("agents")` — Load agent behavior rules **(REQUIRED FIRST)**
152. `get_rule("code")` — Load coding standards
163. `get_rule("testing")` — Load testing workflows
174. `get_rule("git-commands")` — Load git commit protocols
18 
19These rules are **mandatory** and must be consulted before every task.
20**Do NOT skip this step. Do NOT proceed without reading these documents.**
21 
22---
23 
24## Project Overview
25 
26- **Name:** codeops-mcp
27- **Description:** MCP (Model Context Protocol) server providing AI coding agents with universal, language-agnostic development rules. Includes coding standards, testing workflows, git conventions, plan creation/execution protocols, and intelligent project analysis for auto-generating project configurations.
28- **Type:** library (MCP server, published to npm)
29- **Author:** blendsdk
30- **License:** MIT
31- **Node Engine:** >=18.0.0
32- **Module System:** ESM (`"type": "module"`)
33 
34## Toolchain
35 
36- **Language(s):** TypeScript (ES2022 target, Node16 module resolution)
37- **Framework(s):** MCP SDK (`@modelcontextprotocol/sdk`)
38- **Package Manager:** yarn (v1, lockfile: `yarn.lock`)
39- **Test Framework:** Vitest (v2.x, `vitest run`)
40- **Build:** `tsc` (TypeScript compiler, outputs to `dist/`)
41- **Release:** semantic-release (with changelog, git, github, npm plugins)
42- **TypeScript Config:** Strict mode enabled (`strict: true`, `noUnusedLocals`, `noUnusedParameters`, `noImplicitReturns`, `noFallthroughCasesInSwitch`)
43 
44**Manifest files found:** package.json, tsconfig.json, vitest.config.ts, .releaserc.json, yarn.lock
45 
46## Commands
47 
48All commands assume execution from the project root. Prefix all shell commands with `clear &&`.
49 
50### Build
51 
52```bash
53clear && yarn build
54```
55 
56### Test
57 
58```bash
59# Run all tests (107 tests across 4 test files)
60clear && yarn test
61 
62# Run tests in watch mode
63clear && yarn test:watch
64 
65# Run tests with coverage
66clear && yarn test:coverage
67```
68 
69### Verify (before commit)
70 
71```bash
72# Full verification — run this before any git commit
73clear && yarn build && yarn test
74```
75 
76### Other Commands
77 
78```bash
79# Watch mode (recompile on change)
80clear && yarn watch
81 
82# Start the server
83clear && yarn start
84 
85# Clean dist/
86clear && yarn clean
87 
88# Update all dependencies
89clear && yarn ncu
90```
91 
92## Project Structure
93 
94### Type: Single repository
95 
96### Directory Layout
97 
98```
99docs/                    # Rule markdown documents (12 files, shipped with npm package)
100  agents.md              #   AI agent behavior rules
101  code.md                #   Coding standards (DRY, architecture, type safety)
102  git-commands.md        #   Git commit protocols (gitcm/gitcmp)
103  grill_me.md            #   Deep disambiguation protocol (grill_me)
104  make_plan.md           #   Plan creation, execution protocol & implementation plan formatting
105  preflight.md           #   Preflight review protocol — multi-dimensional quality audit (preflight)
106  project-template.md    #   Project configuration template
107  requirements.md        #   Requirements gathering & documentation (make_requirements)
108  retro_requirements.md  #   Reverse requirements engineering (retro_requirements)
109  techdocs.md            #   Technical architecture documentation (make_techdocs)
110  testing.md             #   Testing standards & workflows
111  upgrade_plan.md        #   Plan & requirements upgrade protocol (upgrade_plan, upgrade_requirements)
112src/                     # TypeScript source code
113  index.ts               #   Main entry point — MCP server bootstrap
114  config.ts              #   Configuration resolution (CLI/env/defaults)
115  types/                 #   Type definitions
116    index.ts             #     All interfaces, types, constants, and metadata
117  store/                 #   Data layer
118    rule-store.ts        #     In-memory document store with O(1) lookup + fuzzy matching
119    search-engine.ts     #     TF-IDF search engine with field weighting
120  tools/                 #   MCP tool implementations (5 tools)
121    get-rule.ts          #     get_rule — Retrieve a rule document by name/alias
122    list-rules.ts        #     list_rules — List all rules grouped by category
123    search-rules.ts      #     search_rules — Full-text search across rules
124    analyze-project.ts   #     analyze_project — Scan project + generate/merge project.md
125    get-setup-guide.ts   #     get_setup_guide — Setup instructions for new projects
126  __tests__/             #   Test files (Vitest)
127    store/               #     Store layer tests
128      rule-store.test.ts
129      search-engine.test.ts
130    tools/               #     Tool layer tests
131      tools-setup.ts     #       Shared test fixture (lazy-loaded store + engine)
132      core-tools.test.ts #       Tests for get_rule, list_rules, search_rules, get_setup_guide
133      analyze-project-merge.test.ts  # Tests for analyze_project + merge engine
134dist/                    # Compiled output (git-ignored)
135```
136 
137### Architecture Layers
138 
139```
140┌─────────────────────────────────────────┐
141│  MCP Protocol (stdio transport)          │
142│  index.ts — Server + tool dispatcher     │
143├─────────────────────────────────────────┤
144│  Tools Layer (5 pure functions)          │
145│  get-rule, list-rules, search-rules,     │
146│  analyze-project, get-setup-guide        │
147├─────────────────────────────────────────┤
148│  Store Layer                             │
149│  RuleStore (in-memory Map<id, doc>)      │
150│  SearchEngine (TF-IDF inverted index)    │
151├─────────────────────────────────────────┤
152│  Types Layer                             │
153│  Interfaces, constants, metadata         │
154├─────────────────────────────────────────┤
155│  Config Layer                            │
156│  CLI args → env vars → bundled defaults  │
157└─────────────────────────────────────────┘
158```
159 
160## Coding Conventions
161 
162### Naming
163 
164- **Files:** kebab-case (e.g., `rule-store.ts`, `get-rule.ts`, `analyze-project.ts`)
165- **Exception:** `make_plan` uses underscore in ID (matches the doc filename `make_plan.md`)
166- **Classes:** PascalCase (e.g., `RuleStore`, `SearchEngine`, `StdioServerTransport`)
167- **Functions/Methods:** camelCase (e.g., `getRule`, `findByName`, `resolveConfig`, `analyzeProject`)
168- **Interfaces/Types:** PascalCase (e.g., `RuleDocument`, `SearchResult`, `ProjectAnalysis`, `ServerConfig`)
169- **Constants:** UPPER_SNAKE_CASE (e.g., `STOP_WORDS`, `FIELD_WEIGHTS`, `AUTO_UPDATE_SECTIONS`, `RULE_METADATA`)
170- **Inline constants (objects):** UPPER_SNAKE_CASE (e.g., `TOOL_DEFINITIONS`, `CATEGORY_INFO`)
171- **Module-scoped privates:** camelCase (e.g., `cachedStore`, `cachedEngine`)
172- **Test fixtures:** UPPER_SNAKE_CASE prefixed with `FIXTURE_` or `SAMPLE_` (e.g., `FIXTURE_FULL_PROJECT_MD`, `SAMPLE_ANALYSIS`)
173 
174### Code Style
175 
176- **Module format:** ESM with `.js` import extensions (required by Node16 resolution)
177- **Imports:** Type-only imports use `import type { ... }` syntax
178- **JSDoc:** Every exported function, class, and interface has JSDoc comments with `@param`, `@returns`, `@module` tags
179- **Section separators:** `// ============` comment blocks separate logical sections within files
180- **Error handling:** Errors caught and returned as formatted markdown strings (`**Error:** message`), never thrown to caller
181- **Console output:** All log output goes to `stderr` (stdout reserved for MCP protocol)
182- **Access modifiers:** Class members use `protected` for internal/overridable, `public` for API surface
183- **Const assertions:** `as const` used for object literals that define fixed shapes (e.g., `FIELD_WEIGHTS`, `type: 'object' as const`)
184 
185### Patterns
186 
187- **Pure function tools:** Each tool is a standalone exported function taking (store/engine, args) → string
188- **Formatter pattern:** Private `format*()` functions handle all markdown output generation
189- **Lazy caching:** Test setup uses lazy singleton pattern (`cachedStore ?? build()`)
190- **Mutation-in-place:** Project analysis functions mutate the `analysis` object directly (passed by reference)
191- **Strategy pattern:** Merge engine uses `SectionMergeStrategy` classification (`auto-update`, `preserve`, `static`)
192- **Fuzzy matching chain:** RuleStore.findByName tries 5 strategies in priority order (exact → alias → case-insensitive → partial → title)
193 
194## Git & Commit Conventions
195 
196### Commit Scope
197 
198```
199# Use module/feature as scope:
200# feat(tools): add new MCP tool
201# fix(store): correct fuzzy matching
202# test(merge): add merge engine tests
203# refactor(types): reorganize interfaces
204# docs(rules): update coding standards
205 
206# Common scopes: tools, store, types, config, docs, merge, search, rules
207```
208 
209### Branch Strategy
210 
211- **Main branch:** `master` (used by semantic-release, see `.releaserc.json`)
212- **Feature branches:** `feature/[name]`
213- **Release:** Automated via semantic-release on `master` branch
214 
215### Release Process
216 
217- **Automated:** semantic-release handles versioning, changelog, npm publish, and GitHub releases
218- **Commit convention:** Conventional Commits (feat, fix, chore, etc.)
219- **Version:** Currently `1.2.0`
220- **Published files:** `dist/`, `docs/`, `README.md`, `LICENSE`
221- **Binary:** `codeops-mcp` CLI command (from `dist/index.js`)
222 
223## Special Rules (Project-Specific)
224 
225```
2261. The docs/ directory contains the core rule documents that are SHIPPED with the npm
227   package. Changes to docs/ files affect ALL users of codeops-mcp. Treat them as public API.
228 
2292. stdout is RESERVED for MCP protocol communication. All logging MUST go to stderr
230   (use console.error, not console.log, except for --version output).
231 
2323. Tool functions return formatted markdown strings — they never throw errors.
233   All error conditions are returned as "**Error:** message" formatted strings.
234 
2354. The analyze_project tool has TWO paths:
236   - Fresh generation: No existing .clinerules/project.md → generate from scratch
237   - Incremental merge: Existing file found → parse sections, merge with fresh scan,
238     preserve user customizations (Coding Conventions, Git Conventions, Special Rules),
239     update auto-detectable sections (Toolchain, Commands, Structure)
240 
2415. Tests use the REAL docs/ directory for integration testing (not mocks).
242   The test setup (tools-setup.ts) uses lazy caching to avoid repeated file I/O.
243 
2446. Import paths MUST include .js extension (e.g., './config.js', '../types/index.js')
245   because of Node16 module resolution with ESM.
246 
2477. The 12 rule document IDs are hardcoded in RULE_METADATA and RULE_ALIASES in types/index.ts.
248   Adding a new rule document requires updating both maps.
249 
2508. All test files live under src/__tests__/ mirroring the src/ structure.
251   Test files are excluded from TypeScript compilation (tsconfig.json exclude).
252```
253 
254## Test Structure
255 
256```
2574 test files, 107 total tests:
258 
259src/__tests__/store/rule-store.test.ts        — 22 tests (loading, lookup, fuzzy matching, categories, metadata)
260src/__tests__/store/search-engine.test.ts     — 12 tests (indexing, search, scoring, filtering, excerpts)
261src/__tests__/tools/core-tools.test.ts        — 28 tests (get_rule, list_rules, search_rules, get_setup_guide)
262src/__tests__/tools/analyze-project-merge.test.ts — 45 tests (parser, classifier, merge engine, integration)
263 
264Test style:
265- Integration tests using real docs/ directory
266- Temp directory tests for filesystem operations (mkdtemp + cleanup)
267- Fixture constants for merge tests (FIXTURE_FULL_PROJECT_MD, SAMPLE_ANALYSIS, etc.)
268- beforeAll for shared setup, beforeEach/afterEach for temp dirs
269```
270 
271## Cross-References
272 
273The generic rule files that read this `project.md`:
274 
275- **make_plan.md** — Uses verify command, file paths, commit scope, task file path patterns
276- **code.md** — Uses language conventions, architecture rules
277- **testing.md** — Uses test commands, test locations, test framework
278- **git-commands.md** — Uses commit scope, verify command
279- **agents.md** — Uses shell commands, verify command
280- **requirements.md** — Uses project type, tech stack, and conventions for requirements discovery
281- **retro_requirements.md** — Uses project type, tech stack for codebase analysis adaptation
282