@codifier/cli 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/README.md +511 -0
  2. package/commands/init.md +3 -0
  3. package/commands/onboard.md +3 -0
  4. package/commands/research.md +3 -0
  5. package/dist/cli/add.d.ts +5 -0
  6. package/dist/cli/add.d.ts.map +1 -0
  7. package/dist/cli/add.js +23 -0
  8. package/dist/cli/add.js.map +1 -0
  9. package/dist/cli/bin/codifier.d.ts +7 -0
  10. package/dist/cli/bin/codifier.d.ts.map +1 -0
  11. package/dist/cli/bin/codifier.js +43 -0
  12. package/dist/cli/bin/codifier.js.map +1 -0
  13. package/dist/cli/detect.d.ts +12 -0
  14. package/dist/cli/detect.d.ts.map +1 -0
  15. package/dist/cli/detect.js +35 -0
  16. package/dist/cli/detect.js.map +1 -0
  17. package/dist/cli/doctor.d.ts +5 -0
  18. package/dist/cli/doctor.d.ts.map +1 -0
  19. package/dist/cli/doctor.js +58 -0
  20. package/dist/cli/doctor.js.map +1 -0
  21. package/dist/cli/init.d.ts +6 -0
  22. package/dist/cli/init.d.ts.map +1 -0
  23. package/dist/cli/init.js +93 -0
  24. package/dist/cli/init.js.map +1 -0
  25. package/dist/cli/update.d.ts +5 -0
  26. package/dist/cli/update.d.ts.map +1 -0
  27. package/dist/cli/update.js +25 -0
  28. package/dist/cli/update.js.map +1 -0
  29. package/dist/index.js +87 -0
  30. package/package.json +40 -0
  31. package/skills/brownfield-onboard/SKILL.md +107 -0
  32. package/skills/initialize-project/SKILL.md +145 -0
  33. package/skills/initialize-project/templates/evals-prompt.md +39 -0
  34. package/skills/initialize-project/templates/requirements-prompt.md +44 -0
  35. package/skills/initialize-project/templates/roadmap-prompt.md +44 -0
  36. package/skills/initialize-project/templates/rules-prompt.md +34 -0
  37. package/skills/research-analyze/SKILL.md +131 -0
  38. package/skills/research-analyze/templates/query-generation-prompt.md +61 -0
  39. package/skills/research-analyze/templates/synthesis-prompt.md +67 -0
  40. package/skills/shared/codifier-tools.md +123 -0
package/README.md ADDED
@@ -0,0 +1,511 @@
1
+ # CodifierMcp
2
+
3
+ **Institutional Memory for AI-Driven Development — Across Every Org Role**
4
+
5
+ CodifierMcp is a remote MCP (Model Context Protocol) server that gives AI assistants shared, persistent organizational knowledge. It captures learnings, decisions, and research findings from any team member — and surfaces them to any other member — creating a feedback loop that makes the organization smarter over time.
6
+
7
+ [![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)
8
+ [![TypeScript](https://img.shields.io/badge/typescript-5.5.3-blue)](https://www.typescriptlang.org/)
9
+ [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-1.21.1-purple)](https://modelcontextprotocol.io/)
10
+
11
+ ---
12
+
13
+ ## Table of Contents
14
+
15
+ - [Overview](#overview)
16
+ - [Key Capabilities](#key-capabilities)
17
+ - [Architecture](#architecture)
18
+ - [Use Cases](#use-cases)
19
+ - [Prerequisites](#prerequisites)
20
+ - [Installation](#installation)
21
+ - [Configuration](#configuration)
22
+ - [Environment Variables](#environment-variables)
23
+ - [MCP Client Configuration](#mcp-client-configuration)
24
+ - [MCP Tools](#mcp-tools)
25
+ - [Skills](#skills)
26
+ - [Developer Skills](#developer-skills)
27
+ - [Researcher Skills](#researcher-skills)
28
+ - [Remote Server (HTTP Mode)](#remote-server-http-mode)
29
+ - [Development](#development)
30
+ - [Architecture Details](#architecture-details)
31
+ - [Roadmap](#roadmap)
32
+
33
+ ---
34
+
35
+ ## Overview
36
+
37
+ CodifierMcp bridges the gap between AI assistants and your organization's institutional knowledge. Instead of starting from scratch in every session, AI assistants can:
38
+
39
+ 1. **Fetch Context**: Retrieve relevant rules, guidelines, decisions, and research findings from the shared knowledge base
40
+ 2. **Update Memory**: Save new insights, patterns, and learnings discovered during development or research
41
+ 3. **Follow Skills**: Walk through guided, conversational workflows that produce structured artifacts (rules, roadmaps, research reports)
42
+ 4. **Integrate with Data Sources**: Pull in repo code via RepoMix and query data warehouses via Athena
43
+
44
+ This creates a virtuous cycle where knowledge from a developer's session informs a researcher's analysis, and vice versa.
45
+
46
+ ### Key Capabilities
47
+
48
+ 1. **Org-scoped knowledge persistence** — Learnings from any person, any role, any project persist in a shared, searchable KB. A developer's discovery about a legacy API informs a researcher's analysis six months later.
49
+
50
+ 2. **Authenticated connectors to proprietary data** — RepoMix for private code repositories; AWS Athena for data warehouses. Future: SharePoint, Confluence, Google Drive.
51
+
52
+ 3. **Guided friction reduction via Skills** — Role-specific conversational workflows. Developers get project initialization with rules and roadmaps. Researchers get data discovery and synthesis. The LLM reads the Skill and guides the conversation — no choppy step-by-step protocol.
53
+
54
+ 4. **Multi-surface access** — IDE via MCP (Cursor, Claude Code, Claude Desktop). CLI installer (`npx codifier init`). Future: Teams bot.
55
+
56
+ ### Architecture
57
+
58
+ ```
59
+ ┌──────────────────────────────────────────────────────┐
60
+ │ MCP Clients │
61
+ │ (Claude Desktop, Cursor, Claude Code) │
62
+ │ │
63
+ │ Skills (.codifier/skills/) ← npx codifier init │
64
+ │ Slash Commands (.claude/commands/ or .cursor/rules/)│
65
+ └──────┬──────────────────────────┬────────────────────┘
66
+ │ stdio (local) │ SSE/HTTP (remote)
67
+ ↓ ↓
68
+ ┌─────────────────────────────────────────┐
69
+ │ CodifierMcp Server │
70
+ │ ├── Transport: stdio | SSE │
71
+ │ ├── Auth: Bearer token middleware │
72
+ │ └── MCP Tools (5) │
73
+ │ fetch_context / update_memory │
74
+ │ manage_projects / pack_repo │
75
+ │ query_data │
76
+ └──────┬──────────────────────────────────┘
77
+
78
+ ┌────┴────────────────────────────────┐
79
+ │ Supabase (PostgreSQL + pgvector) │
80
+ │ projects / repositories / memories │
81
+ │ api_keys │
82
+ └─────────────────────────────────────┘
83
+
84
+ Direct Integrations:
85
+ ├── RepoMix (npm programmatic API)
86
+ └── AWS Athena MCP (sidecar subprocess)
87
+ ```
88
+
89
+ **Skills are client-side.** Each Skill is a markdown instruction file the LLM reads locally. The LLM drives the conversation and calls MCP tools only for data operations. There is no server-side session state.
90
+
91
+ ### Use Cases
92
+
93
+ - **Project Initialization**: Follow the Initialize Project Skill to generate Rules.md, Evals.md, Requirements.md, and Roadmap.md from a description, SOW, or existing codebase
94
+ - **Brownfield Onboarding**: Pack an existing repo with RepoMix and generate an architectural summary
95
+ - **Research & Analysis**: Define a research objective, discover Athena schema, execute queries, synthesize findings
96
+ - **Cross-Role Knowledge Flow**: A researcher's findings (stored as `research_finding`) are retrieved by a developer via `fetch_context` when initializing a related project
97
+ - **Onboarding AI Assistants**: New AI sessions automatically learn your team's conventions and decisions
98
+
99
+ ---
100
+
101
+ ## Prerequisites
102
+
103
+ ### Remote Install (Recommended)
104
+
105
+ No local setup required. You need:
106
+
107
+ 1. **API auth token** — obtain from your Codifier deployment admin
108
+ 2. **MCP-compatible AI client** — Claude Desktop, Cursor, or Claude Code CLI
109
+
110
+ **Install Skills and MCP config in one command:**
111
+ ```bash
112
+ npx codifier init
113
+ ```
114
+
115
+ This scaffolds Skills into `.codifier/skills/`, writes slash commands to the correct client location, prompts for your server URL and API key, writes `.codifier/config.json` and the client-specific MCP config, and verifies connectivity.
116
+
117
+ ### Local / Self-Hosted Prerequisites
118
+
119
+ 1. **Node.js 18+** — `node --version`
120
+ 2. **Supabase project** — free tier at [supabase.com](https://supabase.com/); requires Project URL and Service Role Key
121
+ 3. **(Optional) AWS credentials** — for Research & Analyze Skill using Athena
122
+ 4. **(Optional) GitHub/GitLab token** — for private repo access via RepoMix
123
+
124
+ ---
125
+
126
+ ## Installation
127
+
128
+ ### Remote Install (Recommended)
129
+
130
+ ```bash
131
+ # Scaffold Skills and MCP config into your project
132
+ npx codifier init
133
+ ```
134
+
135
+ The CLI prompts for your Codifier server URL (default: `https://codifier-mcp.fly.dev`) and API key, then:
136
+ - Copies all Skills to `.codifier/skills/`
137
+ - Writes slash commands to `.claude/commands/` (Claude Code), `.cursor/rules/` (Cursor), or `.codifier/commands/` (generic)
138
+ - Writes `.mcp.json` (Claude Code) or equivalent client config
139
+ - Verifies MCP connectivity via `GET /health`
140
+
141
+ Alternatively, configure the MCP connection manually:
142
+
143
+ ```bash
144
+ # Claude Code CLI
145
+ claude mcp add --transport http codifier https://codifier-mcp.fly.dev/mcp \
146
+ --header "Authorization: Bearer <your-token>"
147
+ ```
148
+
149
+ ### Local / Self-Hosted Install
150
+
151
+ ```bash
152
+ # 1. Clone
153
+ git clone https://github.com/yourusername/codifierMcp.git
154
+ cd codifierMcp
155
+
156
+ # 2. Install dependencies
157
+ npm install
158
+
159
+ # 3. Build
160
+ npm run build
161
+
162
+ # 4. Configure
163
+ cp .env.example .env
164
+ # Edit .env with your values
165
+ ```
166
+
167
+ ---
168
+
169
+ ## Configuration
170
+
171
+ ### Environment Variables
172
+
173
+ ```bash
174
+ # Data Store (supabase is default; confluence is legacy)
175
+ DATA_STORE=supabase
176
+
177
+ # Supabase (required when DATA_STORE=supabase)
178
+ SUPABASE_URL=https://your-project.supabase.co
179
+ SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
180
+
181
+ # Transport mode
182
+ TRANSPORT_MODE=http # or stdio for local MCP clients
183
+
184
+ # HTTP auth (required when TRANSPORT_MODE=http)
185
+ HTTP_PORT=3000
186
+ API_AUTH_TOKEN=your-secure-random-token # openssl rand -base64 32
187
+
188
+ # Logging
189
+ LOG_LEVEL=info # debug | info | warn | error
190
+
191
+ # RepoMix — private repo access (optional)
192
+ GITHUB_TOKEN=ghp_xxxx
193
+ GITLAB_TOKEN=glpat-xxxx
194
+ BITBUCKET_TOKEN=xxxx
195
+
196
+ # AWS Athena — Research & Analyze Skill (optional)
197
+ AWS_REGION=us-east-1
198
+ AWS_ACCESS_KEY_ID=xxxx
199
+ AWS_SECRET_ACCESS_KEY=xxxx
200
+ ATHENA_S3_OUTPUT_LOCATION=s3://your-bucket/athena-results/
201
+ ATHENA_DATABASE=default
202
+ ATHENA_WORKGROUP=primary
203
+ ```
204
+
205
+ | Variable | Required | Description |
206
+ |----------|----------|-------------|
207
+ | `DATA_STORE` | No | `supabase` (default) or `confluence` |
208
+ | `SUPABASE_URL` | When `supabase` | Supabase project URL |
209
+ | `SUPABASE_SERVICE_ROLE_KEY` | When `supabase` | Service role key (not anon key) |
210
+ | `TRANSPORT_MODE` | No | `stdio` (default) or `http` |
211
+ | `HTTP_PORT` | No | Port for HTTP server (default: 3000) |
212
+ | `API_AUTH_TOKEN` | When `http` | Bearer token for authentication |
213
+ | `GITHUB_TOKEN` | For private repos | GitHub PAT with repo read access |
214
+ | `AWS_*` / `ATHENA_*` | For Research & Analyze | AWS credentials and Athena config |
215
+ | `ATHENA_DATABASE` | No | Athena database/catalog name (default: `"default"`); overridable per `query_data` call |
216
+
217
+ ### MCP Client Configuration
218
+
219
+ #### Claude Code (CLI)
220
+
221
+ ```bash
222
+ # Remote (recommended — or use npx codifier init)
223
+ claude mcp add --transport http codifier https://codifier-mcp.fly.dev/mcp \
224
+ --header "Authorization: Bearer <your-token>"
225
+
226
+ # Local
227
+ claude mcp add --transport http codifier http://localhost:3000/mcp \
228
+ --header "Authorization: Bearer <your-token>"
229
+ ```
230
+
231
+ #### Claude Desktop
232
+
233
+ Claude Desktop requires the `mcp-remote` proxy to connect to SSE servers:
234
+
235
+ ```json
236
+ {
237
+ "mcpServers": {
238
+ "codifier": {
239
+ "command": "npx",
240
+ "args": [
241
+ "-y",
242
+ "mcp-remote",
243
+ "https://codifier-mcp.fly.dev/mcp",
244
+ "--header",
245
+ "Authorization:Bearer <your-token>"
246
+ ]
247
+ }
248
+ }
249
+ }
250
+ ```
251
+
252
+ #### Cursor / Other MCP Clients
253
+
254
+ Configure as a StreamableHTTP server at `https://codifier-mcp.fly.dev/mcp` with `Authorization: Bearer <token>` header.
255
+
256
+ ---
257
+
258
+ ## MCP Tools
259
+
260
+ Codifier exposes 5 tools via the MCP protocol:
261
+
262
+ | Tool | Description |
263
+ |------|-------------|
264
+ | `fetch_context` | Retrieve memories from the KB filtered by `project_id`, `memory_type` (rule, document, api_contract, learning, research_finding), and/or `tags` |
265
+ | `update_memory` | Create or update a memory within the active project scope |
266
+ | `manage_projects` | Create, list, or switch the active project; all subsequent calls are scoped to it |
267
+ | `pack_repo` | Condense a local or remote repository via RepoMix and store it as a versioned snapshot in the `repositories` table |
268
+ | `query_data` | Execute operations against Athena: `list-tables` (schema discovery), `describe-tables` (column metadata), `execute-query` (SELECT only). Accepts optional `database` parameter to override the `ATHENA_DATABASE` env var per call. |
269
+
270
+ ### Memory Types
271
+
272
+ | Type | Description |
273
+ |------|-------------|
274
+ | `rule` | Project conventions, security patterns, coding standards |
275
+ | `document` | Technical specs, ADRs, runbooks, best practices |
276
+ | `api_contract` | Endpoint specifications, schemas, auth requirements |
277
+ | `learning` | Insights captured during AI-assisted development |
278
+ | `research_finding` | Data analysis results from Research & Analyze sessions |
279
+
280
+ ---
281
+
282
+ ## Skills
283
+
284
+ Skills are client-side, model-agnostic Agent workflows — markdown instruction files that the LLM reads locally. The LLM drives the conversation and calls MCP tools only for data operations. There is no server-side session state or protocol round-trips between steps.
285
+
286
+ After running `npx codifier init`, Skills live in `.codifier/skills/` in your project. Slash commands in `.claude/commands/` (or the equivalent for your client) activate each Skill.
287
+
288
+ `skills/shared/codifier-tools.md` is a reference document covering all 5 MCP tools, their parameters, and usage patterns. Every Skill references it.
289
+
290
+ ### Developer Skills
291
+
292
+ #### Initialize Project (`/init`)
293
+
294
+ For greenfield and brownfield projects. Produces four artifacts persisted to the shared KB.
295
+
296
+ **Workflow:** collect project name and description → optionally accept SOW → optionally provide repo URLs → pack repos via `pack_repo` → generate Rules.md → generate Evals.md → generate Requirements.md → generate Roadmap.md → persist all artifacts via `update_memory`
297
+
298
+ **Context-aware generation:**
299
+
300
+ | Scenario | Context used | Generator behavior |
301
+ |----------|-------------|-------------------|
302
+ | Greenfield + SOW | description + SOW | Rules from SOW constraints and standards |
303
+ | Greenfield, no SOW | description only | Minimal scaffolding rules |
304
+ | Brownfield + SOW | description + SOW + repo snapshot | Target-state rules; SOW takes precedence over existing patterns |
305
+ | Brownfield, no SOW | description + repo snapshot | Rules extracted from existing codebase patterns |
306
+
307
+ #### Brownfield Onboard (`/onboard`)
308
+
309
+ Pack an existing repo and generate an architectural summary with minimal ceremony.
310
+
311
+ **Workflow:** collect repo URLs → call `pack_repo` for each → store versioned snapshots → generate architectural summary → persist learnings via `update_memory`
312
+
313
+ ### Researcher Skills
314
+
315
+ #### Research & Analyze (`/research`)
316
+
317
+ Connect to Athena, explore data, execute queries, synthesize findings.
318
+
319
+ **Workflow:** define research objective → provide context → discover Athena schema via `query_data list-tables` → select relevant tables → describe schemas via `query_data describe-tables` → generate SQL queries (user reviews before execution) → execute approved queries via `query_data execute-query` → synthesize findings → generate ResearchFindings.md → persist as `research_finding` memories via `update_memory`
320
+
321
+ ---
322
+
323
+ ## Remote Server (HTTP Mode)
324
+
325
+ ### Quick Start
326
+
327
+ ```bash
328
+ # Generate auth token
329
+ export API_AUTH_TOKEN=$(openssl rand -base64 32)
330
+
331
+ # Start in HTTP mode
332
+ TRANSPORT_MODE=http \
333
+ HTTP_PORT=3000 \
334
+ API_AUTH_TOKEN=$API_AUTH_TOKEN \
335
+ SUPABASE_URL=https://your-project.supabase.co \
336
+ SUPABASE_SERVICE_ROLE_KEY=your-key \
337
+ node dist/index.js
338
+ ```
339
+
340
+ ### Endpoints
341
+
342
+ | Endpoint | Methods | Auth | Description |
343
+ |----------|---------|------|-------------|
344
+ | `/health` | GET | No | Health check — returns `{"status":"ok"}` |
345
+ | `/.well-known/oauth-authorization-server` | GET | No | OAuth authorization server metadata (MCP SDK 1.7+ discovery) |
346
+ | `/.well-known/oauth-protected-resource` | GET | No | OAuth protected resource metadata |
347
+ | `/mcp` | POST | Yes | StreamableHTTP transport — stateless (MCP protocol 2025-03-26); GET/DELETE return 405 |
348
+ | `/sse` | GET | Yes | SSE transport for legacy clients |
349
+ | `/messages` | POST | Yes | SSE message endpoint |
350
+
351
+ ### Authentication
352
+
353
+ All endpoints except `/health`, `/.well-known/*`, and `OPTIONS` preflight requests require:
354
+ ```
355
+ Authorization: Bearer <API_AUTH_TOKEN>
356
+ ```
357
+
358
+ Requests without a valid token receive a `401` response with an OAuth-standard error body:
359
+ ```json
360
+ { "error": "unauthorized", "error_description": "..." }
361
+ ```
362
+
363
+ ---
364
+
365
+ ## Development
366
+
367
+ ### Project Structure
368
+
369
+ ```
370
+ codifierMcp/
371
+ ├── src/
372
+ │ ├── index.ts # Entry point (transport branching)
373
+ │ ├── config/
374
+ │ │ └── env.ts # Zod-validated configuration
375
+ │ ├── http/
376
+ │ │ ├── server.ts # Express server (StreamableHTTP + SSE)
377
+ │ │ └── auth-middleware.ts # Bearer token authentication
378
+ │ ├── datastore/
379
+ │ │ ├── interface.ts # IDataStore abstraction
380
+ │ │ ├── factory.ts # createDataStore() factory
381
+ │ │ ├── supabase-datastore.ts # Supabase implementation (default)
382
+ │ │ └── atlassian-datastore.ts # Confluence implementation (legacy)
383
+ │ ├── mcp/
384
+ │ │ ├── server.ts # Registers exactly 5 tools
385
+ │ │ ├── schemas.ts # Zod schemas for tool parameters
386
+ │ │ └── tools/ # 5 tool implementations
387
+ │ │ ├── fetch-context.ts
388
+ │ │ ├── update-memory.ts
389
+ │ │ ├── manage-projects.ts
390
+ │ │ ├── pack-repo.ts
391
+ │ │ └── query-data.ts
392
+ │ ├── integrations/
393
+ │ │ ├── repomix.ts # RepoMix programmatic API wrapper
394
+ │ │ └── athena.ts # Athena MCP sidecar client
395
+ │ ├── services/
396
+ │ │ ├── context-service.ts # Rule retrieval with relevance scoring
397
+ │ │ └── memory-service.ts # Memory enrichment and storage
398
+ │ └── utils/
399
+ │ ├── logger.ts # Logging (stderr only)
400
+ │ └── errors.ts # Custom error classes
401
+ ├── skills/
402
+ │ ├── shared/
403
+ │ │ └── codifier-tools.md # All 5 MCP tools reference
404
+ │ ├── initialize-project/
405
+ │ │ ├── SKILL.md
406
+ │ │ └── templates/
407
+ │ ├── brownfield-onboard/
408
+ │ │ └── SKILL.md
409
+ │ └── research-analyze/
410
+ │ ├── SKILL.md
411
+ │ └── templates/
412
+ ├── commands/
413
+ │ ├── init.md # /init slash command
414
+ │ ├── onboard.md # /onboard slash command
415
+ │ └── research.md # /research slash command
416
+ ├── cli/
417
+ │ ├── bin/codifier.ts # CLI entry point
418
+ │ ├── detect.ts # LLM client detection
419
+ │ ├── init.ts # npx codifier init
420
+ │ ├── update.ts # npx codifier update
421
+ │ ├── add.ts # npx codifier add <skill>
422
+ │ └── doctor.ts # npx codifier doctor
423
+ ├── supabase/
424
+ │ └── migrations/
425
+ │ ├── 001_initial_schema.sql
426
+ │ └── 002_v2_schema.sql # Drops sessions/insights; v2.0 schema
427
+ ├── docs/
428
+ │ ├── rules.yaml # Project development rules
429
+ │ └── evals.yaml # Rule evaluations
430
+ ├── Dockerfile
431
+ ├── fly.toml
432
+ └── package.json
433
+ ```
434
+
435
+ ### Commands
436
+
437
+ ```bash
438
+ npm install # Install dependencies
439
+ npm run build # Compile TypeScript → dist/
440
+ npm run dev # Build + run (stdio mode)
441
+ npm run watch # Watch mode (rebuild on changes)
442
+ ```
443
+
444
+ ### Adding New Features
445
+
446
+ 1. Review `docs/rules.yaml` before writing code
447
+ 2. Follow the `IDataStore` interface for any storage changes
448
+ 3. Use custom error classes from `utils/errors.ts`
449
+ 4. Log to stderr only (never stdout) — MCP uses stdout for protocol
450
+ 5. Validate all inputs with Zod schemas in `src/mcp/schemas.ts`
451
+ 6. Use strict TypeScript; explicit types required
452
+
453
+ ---
454
+
455
+ ## Architecture Details
456
+
457
+ ### Data Schema
458
+
459
+ Migration `002_v2_schema.sql` (applied 2026-02-24) dropped the `sessions` and `insights` tables. The active schema has 4 tables:
460
+
461
+ | Table | Key Fields | Purpose |
462
+ |-------|-----------|---------|
463
+ | `projects` | id, name, org, metadata | Top-level container; all entities scoped to a project |
464
+ | `repositories` | id, project_id, url, snapshot, file_tree, version_label | Versioned repo snapshots from RepoMix |
465
+ | `memories` | id, project_id, memory_type, title, content, tags, confidence, embedding, source_role | All knowledge entities (rules, docs, learnings, findings) |
466
+ | `api_keys` | id, project_id, key_hash | API key → project mapping for RLS |
467
+
468
+ ### Retrieval Strategy
469
+
470
+ **MVP**: Exact-match filtering on `project_id`, `memory_type`, and `tags`. Embeddings are stored on write but vector similarity search is deferred to v2.1.
471
+
472
+ **v2.1**: Hybrid retrieval — exact-match filters + vector ranking via pgvector.
473
+
474
+ ### Why Skills Instead of a Server-Side PlaybookRunner
475
+
476
+ The original v2.0 design used a server-side `PlaybookRunner` state machine with a `sessions` table, `run_playbook`, and `advance_step` tools. This was replaced in February 2026 for three reasons:
477
+
478
+ 1. **Eliminating round-trips**: Each playbook step required an MCP call. Skills let the LLM manage workflow state in its context window — zero extra tool calls for step transitions.
479
+ 2. **Model agnosticism**: Skill markdown files work with any LLM client. The YAML playbook format tied generation to Codifier's server-side prompt assembly.
480
+ 3. **Simplified server**: 5 stateless tools are easier to reason about, test, and scale. The Fly.io deployment runs always-on (`min_machines_running = 1`, `auto_stop_machines = false`) — no cold-start delay for clients.
481
+
482
+ ---
483
+
484
+ ## Roadmap
485
+
486
+ ### v2.1
487
+
488
+ | Feature | Description |
489
+ |---------|-------------|
490
+ | **Semantic search** | Activate vector similarity on `memories.embedding`; hybrid retrieval |
491
+ | **SkillManager / Umbrella MCP** | Proxy pattern for Confluence, SharePoint, GitHub, Jira connectors |
492
+ | **Researcher data sources** | SharePoint + Google Drive as selectable sources in Research & Analyze |
493
+ | **Architect Skills** | Technology evaluation, system modeling, ADRs |
494
+ | **Strategist Skills** | Roadmap planning, competitive analysis |
495
+ | **Teams bot** | Read-only KB queries + Skill steps as Adaptive Cards |
496
+ | **SSO / Entra ID** | Replace API key auth with org SSO |
497
+ | **Memory relationships** | Graph edges between memories for relationship queries |
498
+
499
+ ---
500
+
501
+ ## Additional Resources
502
+
503
+ - **MCP Documentation**: [modelcontextprotocol.io](https://modelcontextprotocol.io/)
504
+ - **Supabase**: [supabase.com/docs](https://supabase.com/docs)
505
+ - **RepoMix**: [github.com/yamadashy/repomix](https://github.com/yamadashy/repomix)
506
+ - **AWS Athena MCP**: [github.com/ColeMurray/aws-athena-mcp](https://github.com/ColeMurray/aws-athena-mcp)
507
+ - **TypeScript Handbook**: [typescriptlang.org/docs](https://www.typescriptlang.org/docs/)
508
+
509
+ ---
510
+
511
+ **Built with Claude Code**
@@ -0,0 +1,3 @@
1
+ Read and follow the instructions in .codifier/skills/initialize-project/SKILL.md. Use the Codifier MCP tools as directed by the skill.
2
+
3
+ If the skill file is not found at .codifier/skills/initialize-project/SKILL.md, inform the user: "Codifier skills are not installed yet. Run `npx codifier init` in your terminal to install them, then try this command again."
@@ -0,0 +1,3 @@
1
+ Read and follow the instructions in .codifier/skills/brownfield-onboard/SKILL.md. Use the Codifier MCP tools as directed by the skill.
2
+
3
+ If the skill file is not found at .codifier/skills/brownfield-onboard/SKILL.md, inform the user: "Codifier skills are not installed yet. Run `npx codifier init` in your terminal to install them, then try this command again."
@@ -0,0 +1,3 @@
1
+ Read and follow the instructions in .codifier/skills/research-analyze/SKILL.md. Use the Codifier MCP tools as directed by the skill.
2
+
3
+ If the skill file is not found at .codifier/skills/research-analyze/SKILL.md, inform the user: "Codifier skills are not installed yet. Run `npx codifier init` in your terminal to install them, then try this command again."
@@ -0,0 +1,5 @@
1
+ /**
2
+ * `codifier add <skill>` — install a single skill by name.
3
+ */
4
+ export declare function runAdd(skillName: string): Promise<void>;
5
+ //# sourceMappingURL=add.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"add.d.ts","sourceRoot":"","sources":["../../cli/add.ts"],"names":[],"mappings":"AAAA;;GAEG;AAUH,wBAAsB,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAe7D"}
@@ -0,0 +1,23 @@
1
+ /**
2
+ * `codifier add <skill>` — install a single skill by name.
3
+ */
4
+ import { cpSync, existsSync, mkdirSync } from 'fs';
5
+ import { join, dirname } from 'path';
6
+ import { fileURLToPath } from 'url';
7
+ const __dirname = dirname(fileURLToPath(import.meta.url));
8
+ const PACKAGE_ROOT = join(__dirname, '..', '..');
9
+ const SKILLS_SOURCE = join(PACKAGE_ROOT, 'skills');
10
+ export async function runAdd(skillName) {
11
+ const cwd = process.cwd();
12
+ const skillSource = join(SKILLS_SOURCE, skillName);
13
+ if (!existsSync(skillSource)) {
14
+ console.error(`Error: Skill "${skillName}" not found.`);
15
+ console.error('Available skills: initialize-project, brownfield-onboard, research-analyze');
16
+ process.exit(1);
17
+ }
18
+ const skillsDest = join(cwd, '.codifier', 'skills', skillName);
19
+ mkdirSync(skillsDest, { recursive: true });
20
+ cpSync(skillSource, skillsDest, { recursive: true });
21
+ console.log(`✓ Skill "${skillName}" installed to .codifier/skills/${skillName}/`);
22
+ }
23
+ //# sourceMappingURL=add.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"add.js","sourceRoot":"","sources":["../../cli/add.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AAEpC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,MAAM,YAAY,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;AACjD,MAAM,aAAa,GAAG,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;AAEnD,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,SAAiB;IAC5C,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAC1B,MAAM,WAAW,GAAG,IAAI,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC;IAEnD,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;QAC7B,OAAO,CAAC,KAAK,CAAC,iBAAiB,SAAS,cAAc,CAAC,CAAC;QACxD,OAAO,CAAC,KAAK,CAAC,4EAA4E,CAAC,CAAC;QAC5F,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;IAC/D,SAAS,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3C,MAAM,CAAC,WAAW,EAAE,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAErD,OAAO,CAAC,GAAG,CAAC,YAAY,SAAS,mCAAmC,SAAS,GAAG,CAAC,CAAC;AACpF,CAAC"}
@@ -0,0 +1,7 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Codifier CLI entry point
4
+ * Usage: npx codifier <command>
5
+ */
6
+ export {};
7
+ //# sourceMappingURL=codifier.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"codifier.d.ts","sourceRoot":"","sources":["../../../cli/bin/codifier.ts"],"names":[],"mappings":";AACA;;;GAGG"}
@@ -0,0 +1,43 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Codifier CLI entry point
4
+ * Usage: npx codifier <command>
5
+ */
6
+ import { program } from 'commander';
7
+ import { runInit } from '../init.js';
8
+ import { runUpdate } from '../update.js';
9
+ import { runAdd } from '../add.js';
10
+ import { runDoctor } from '../doctor.js';
11
+ program
12
+ .name('codifier')
13
+ .description('Codifier MCP — install and manage AI skills for your project')
14
+ .version('2.0.0');
15
+ program
16
+ .command('init')
17
+ .description('Scaffold Codifier skills, slash commands, and MCP config into this project')
18
+ .action(async () => {
19
+ await runInit();
20
+ });
21
+ program
22
+ .command('update')
23
+ .description('Pull the latest skills from the npm package into .codifier/skills/')
24
+ .action(async () => {
25
+ await runUpdate();
26
+ });
27
+ program
28
+ .command('add <skill>')
29
+ .description('Install a single skill by name (e.g., research-analyze)')
30
+ .action(async (skill) => {
31
+ await runAdd(skill);
32
+ });
33
+ program
34
+ .command('doctor')
35
+ .description('Verify MCP connectivity and check installed skill files')
36
+ .action(async () => {
37
+ await runDoctor();
38
+ });
39
+ program.parseAsync(process.argv).catch((err) => {
40
+ console.error('Error:', err.message);
41
+ process.exit(1);
42
+ });
43
+ //# sourceMappingURL=codifier.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"codifier.js","sourceRoot":"","sources":["../../../cli/bin/codifier.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,OAAO;KACJ,IAAI,CAAC,UAAU,CAAC;KAChB,WAAW,CAAC,8DAA8D,CAAC;KAC3E,OAAO,CAAC,OAAO,CAAC,CAAC;AAEpB,OAAO;KACJ,OAAO,CAAC,MAAM,CAAC;KACf,WAAW,CAAC,4EAA4E,CAAC;KACzF,MAAM,CAAC,KAAK,IAAI,EAAE;IACjB,MAAM,OAAO,EAAE,CAAC;AAClB,CAAC,CAAC,CAAC;AAEL,OAAO;KACJ,OAAO,CAAC,QAAQ,CAAC;KACjB,WAAW,CAAC,oEAAoE,CAAC;KACjF,MAAM,CAAC,KAAK,IAAI,EAAE;IACjB,MAAM,SAAS,EAAE,CAAC;AACpB,CAAC,CAAC,CAAC;AAEL,OAAO;KACJ,OAAO,CAAC,aAAa,CAAC;KACtB,WAAW,CAAC,yDAAyD,CAAC;KACtE,MAAM,CAAC,KAAK,EAAE,KAAa,EAAE,EAAE;IAC9B,MAAM,MAAM,CAAC,KAAK,CAAC,CAAC;AACtB,CAAC,CAAC,CAAC;AAEL,OAAO;KACJ,OAAO,CAAC,QAAQ,CAAC;KACjB,WAAW,CAAC,yDAAyD,CAAC;KACtE,MAAM,CAAC,KAAK,IAAI,EAAE;IACjB,MAAM,SAAS,EAAE,CAAC;AACpB,CAAC,CAAC,CAAC;AAEL,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,GAAU,EAAE,EAAE;IACpD,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;IACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
@@ -0,0 +1,12 @@
1
+ /**
2
+ * Environment detection — identifies which LLM client is in use
3
+ * by checking for client-specific directories.
4
+ */
5
+ export type ClientType = 'claude-code' | 'cursor' | 'windsurf' | 'generic';
6
+ export interface DetectedEnvironment {
7
+ clientType: ClientType;
8
+ commandsDir: string;
9
+ mcpConfigPath: string;
10
+ }
11
+ export declare function detectEnvironment(cwd?: string): DetectedEnvironment;
12
+ //# sourceMappingURL=detect.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../../cli/detect.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,MAAM,MAAM,UAAU,GAAG,aAAa,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;AAE3E,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,UAAU,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAsB,GAAG,mBAAmB,CA8BlF"}