Contributing to Claude Prompts

Thank you for contributing to the Claude Prompts MCP server. This guide covers everything from your first PR to advanced contribution workflows.

Quick Start

# 1. Fork and clone
git clone https://github.com/<your-fork>/claude-prompts.git
cd claude-prompts-mcp/server

# 2. Install (hooks auto-configure via Husky)
npm install

# 3. Build and verify
npm run build && npm test

# 4. Create a branch
git checkout -b feat/my-change

# 5. Make changes, then commit with conventional format
git add <files>
git commit -m "feat(server): add new capability"

[!TIP] First time? Start with a docs fix or a small bug. The hooks will lint, format, and typecheck your staged files automatically.

Working in a second worktree

Step 2 above wires the git hooks, and it wires them per worktree. core.hooksPath is the relative path .husky/_, which husky generates and self-ignores, so git worktree add produces a worktree where that path does not resolve — and git skips every hook silently, with no warning and no failing exit code. Commits and pushes from there run no local validation at all.

Create additional worktrees with the bootstrap script, which adds the worktree, wires husky inside it, links every installed node_modules tree (the root, server/, and cli/ when it has one), and then verifies the hooks are executable before reporting success:

npm run worktree:create -- ../claude-prompts-mcp-featurex feat/my-change --from origin/main

To repair a worktree that already exists, run husky from inside it:

npx --prefix /path/to/main-worktree husky

npm run validate:git-hooks-active reports which case you are in. It is part of validate:all, and it passes without inspecting anything outside a linked worktree, so CI and plain clones are unaffected.

Do not create the second worktree with Claude Code's --worktree flag or EnterWorktree: anthropics/claude-code#72714 writes an absolutized core.hooksPath into the shared .git/config, which disables hooks in every worktree, including the main one. Plain git worktree add is unsafe for the reason above. Note also that the bootstrap script links node_modules by symlink, so npm ci or an install from a branch that changed package-lock.json writes through the link and mutates every worktree's dependency tree at once; a dependency change needs a worktree with a real install.

Development Environment

| Surface / requirement | Version | Notes | | ------------------------------------ | -------------------------- | ------------------------------------------------ | | MCP server and desktop extension | Node.js >=22.13.0 | CI tests the minimum and Node 24 | | Standalone CPM CLI runtime | Node.js >=18.18.0 | Separate self-contained compatibility surface | | Local development and publishing | Node.js 24 | .node-version is the repository pin | | npm | Bundled with Node | Run npm ci inside server/ | | Python tooling | See requirements-dev.txt | npm run setup:python installs the pins CI uses | | Git | Any recent | Required for Husky hooks |

The server uses node:sqlite without an experimental flag, which sets its runtime floor. Use Node 24 for repository development so local builds match the publish workflows — every CI job except the test matrix now reads the same .node-version, and the matrix is the only place 22.13.0 appears.

Install with npm ci, not npm install: ci reproduces package-lock.json exactly, and a tree that has drifted from the lockfile makes every local validate:* result describe a toolchain CI will not use. npm run validate:lockfile-sync reports that drift by name and runs inside validate:all. npm run setup:python does the same job for Ruff, Pyrefly, Pytest, and PyYAML, whose pins live in requirements-dev.txt — the same file CI installs from.

<details> <summary><strong>Repo Structure</strong></summary>

repo/
├── server/
│   ├── src/            # TypeScript sources
│   ├── dist/           # Compiled runtime (SSOT for behavior)
│   ├── prompts/        # Prompt registry and markdown templates
│   ├── resources/      # Gates, frameworks, styles
│   ├── config.json     # Runtime configuration
│   └── package.json    # Scripts + dependencies
├── docs/               # Canonical documentation (Diataxis)
├── plans/              # Living migration plans + guardrails
├── AGENTS.md           # Generated from CLAUDE.md + .claude/rules (do not edit)
└── CONTRIBUTING.md     # This file

</details> <details> <summary><strong>Available Scripts</strong> (run inside <code>server/</code>)</summary>

| Command | Description | | ------------------------------------------- | ------------------------------------------------------------------------------- | | npm run build | esbuild bundle to dist/index.js | | npm run typecheck | Strict TypeScript checks without emit | | npm run lint / lint:fix | ESLint validation + autofix | | npm run lint:ratchet | Fail if ESLint violations increased, or decreased without lowering the baseline | | npm run validate:format | Prettier check on every tracked JSON/MD/YAML (repo + server) | | npm run validate:all | Full validation suite (deps + architecture) | | npm run validate:arch | Dependency Cruiser architecture rules | | npm test | Unit suite only (see test:integration) | | npm run test:integration | Integration tests only | | npm run test:coverage | Coverage report (target: >80%) | | npm run generate:contracts | Regenerate MCP schemas from contracts | | npm run start:stdio / start:development | STDIO / Streamable HTTP for manual testing |

test:unit and test:coverage run every unit file through one Jest worker (-w 1), recycled when its heap passes 1,024 MB (the idle memory limit set in the script), because heap retained across files adds up: in one process it outgrew V8's default old-space ceiling on machines with less than about 14 GB of memory (2,240 MB measured on a 12 GB box), where the run aborted with JavaScript heap out of memory and exit 134. The scripts used to hide that behind a raised 4,096 MB heap ceiling (one process, 2.8 GB to 3.6 GB resident); the recycled worker keeps the heap bounded instead, so no script raises the ceiling any more.

Measured 2026-10-04 on the 12 GB box, full unit suite (336 files, 6,012 passed, 1 skipped in every run), peak resident set from /usr/bin/time -v:

| Script | Runner | Wall time | Peak resident set | | --------------- | -------------------------------------- | --------- | ----------------- | | test:unit | one process, 4,096 MB ceiling (before) | 2:02 | 2,836 MB | | test:unit | one recycled worker (now) | 1:41 | 1,295 MB | | test:coverage | one process, 4,096 MB ceiling (before) | 2:41 | 3,588 MB | | test:coverage | one recycled worker (now) | 2:06 | 1,419 MB |

The coverage run still meets the floors in jest.config.cjs (coverageThreshold): 62.56 percent of statements against 35. CI calls both scripts by name (test:ci and test:coverage in ci.yml) and passes no heap flag of its own. As of 2026-10-04 · measured peaks above · flips when a recycled run exits 134 or its wall time passes the single-process run.

What is retained was measured on 2026-09-29 (335 files): the heap left after each file, with a garbage collection forced between files, climbs from 41 MB to 2,096 MB, about 6 MB per file, and drops by more than 1 MB after only 8 files. The largest steps are the files that import the largest module graphs (the composition root in tests/unit/runtime/, 44 to 80 MB each; the ESLint rule tests, 61 MB), and a file that only imports Application keeps 89 of the 97 MB the full shutdown-order test keeps. So each file's loaded modules stay resident under Jest's ESM runtime; no single file leaks a server, database or timer that a teardown could free. The recycled worker bounds that growth rather than removing it. As of 2026-09-29 · measured 2,096 MB retained heap in one process · flips when a per-file retention fix lands.

</details>

Documentation Standards

Root-level README.md is governed by the README Charter — audience, voice rules, line budgets, Diátaxis section markers, and forbidden-word list. README PRs run npm run validate:readme; CI runs the same check on every route that can change README.md, so the PR template carries no README section.

Docs under docs/ follow the Diátaxis split documented in docs/README.md: tutorials (learning), how-to (problem-solving), reference (lookup), concepts (understanding).

Project guidance projection (AGENTS.md)

AGENTS.md at the repo root is generated, not authored. npm run guidance:sync (root package.json) renders it from CLAUDE.md plus .claude/rules/*.md; npm run guidance:check and CI's validate:agent-guidance fail when the committed file is stale. Edit the sources and regenerate; do not edit AGENTS.md by hand.

It is a compact semantic projection, not a concatenation: the handbook sections listed in PROJECTED_HANDBOOK_SECTIONS (scripts/sync-project-guidance.js) plus one dispatch entry per scoped rule, under a 32 KiB ceiling (MAX_PROJECT_GUIDANCE_BYTES). The ceiling and the dispatch entries exist because clients differ in what they load natively:

| Client | Loads natively | | ----------- | --------------------------------------------------------------- | | Claude Code | CLAUDE.md plus .claude/rules/*.md with paths: frontmatter | | Codex | Hierarchical AGENTS.md; no per-path rule activation | | OpenCode | AGENTS.md or CLAUDE.md, plus files named in instructions |

The pre-commit hook renders the file from the Git index rather than the working tree, so a partially staged source cannot leak unstaged text into the commit.

How to Contribute

Contribution Types

Choose the path that matches your change:

| I want to... | Path | Key docs | | ----------------------------- | ---------------------------------------------------- | --------------------------------------------------------------- | | Fix a bug or add a feature | Code changes | Architecture | | Create or edit a prompt/chain | Prompt contributions | Build Your First Prompt | | Add or modify a quality gate | Gate contributions | Gates Guide | | Add or modify a framework | Framework contributions | Frameworks Guide | | Improve documentation | Documentation | Docs Index |

Code Changes

1. Read Architecture Overview for the pipeline, transports, and runtime model.
2. Identify the correct domain from the ownership matrix in CLAUDE.md -- stages are thin orchestration, domain logic lives in services.
3. Make focused, reversible changes. Respect the guardrails in CLAUDE.md (AGENTS.md is generated from it; see Project guidance projection).
4. Keep STDIO and Streamable HTTP behavior in parity.
5. Register new modules through the Application orchestrator (server/src/runtime/).

[!IMPORTANT] TypeScript strict mode is enforced. Prefer dependency injection for custom services, but use library globals directly (e.g., trace.getTracer()) when the library provides its own accessor.

Prompt & Chain Contributions

All prompt/chain changes flow through MCP tools -- never edit files under server/resources/prompts/ directly.

• Create/update/delete: Use resource_manager with resource_type:"prompt"
• Schema: Follow Prompt YAML Schema
• Chains: See Chains Lifecycle and Chain Schema
• Test: Execute via prompt_engine and include output in your PR

Gate Contributions

• Add gate definitions under server/resources/gates/{id}/gate.yaml
• Follow Gate Configuration for schema
• See Quality Gates for precedence and verification types
• Update Gates Guide when behavior changes

Framework Contributions

• Add framework definitions under server/resources/frameworks/{id}/
• Follow the structure: framework.yaml (its system prompt goes inline as systemPromptGuidance) + phases.yaml + optional judge-prompt.md
• See Frameworks Guide for configuration

Documentation

All docs live under docs/ organized by Diataxis intent:

| Quadrant | Directory | For | | --------- | ----------------- | ----------------------------- | | Tutorials | docs/tutorials/ | Learning by doing | | How-to | docs/guides/ | Solving specific problems | | Reference | docs/reference/ | Looking up syntax/API details | | Concepts | docs/concepts/ | Understanding how things work |

• Update docs in the same changeset as code -- no deferred TODOs.
• Verify references against server/dist/** for behavioral accuracy.
• Consult Docs Index before creating new files.

Commit Conventions

This project uses Conventional Commits enforced by CI.

Format

<type>(<scope>): <description>

[optional body]

[optional footer]

Types

| Type | When | | ---------- | --------------------------------------- | | feat | New feature or capability | | fix | Bug fix | | refactor | Code restructuring (no behavior change) | | chore | Maintenance, deps, configs | | docs | Documentation only | | test | Adding or updating tests | | ci | CI/CD workflow changes | | perf | Performance improvement |

Scopes

Use these project-specific scopes:

server cli runtime pipeline gates frameworks prompts chains styles scripts hooks resources mcp-tools contracts parsers ci deps config logging metrics docs tests semantic execution

Examples

git commit -m "feat(gates): add shell verification timeout option"
git commit -m "fix(pipeline): correct framework authority resolution order"
git commit -m "docs(guides): update injection control frequency table"
git commit -m "refactor(runtime): extract module initialization to dedicated service"

Breaking Changes

Add ! after the type/scope (e.g. feat(mcp-tools)!: redesign resource_manager schema) and a BREAKING CHANGE: footer. Release Please reads either one to cut a major.

A change is breaking only if it alters the declared public API. That surface is defined in CLAUDE.md § Public API Contract — the MCP tool surface, the CLI commands, the resource formats, the Python hook contract, and the symbolic command language. Internal TypeScript exports, package manifest fields, src/ layout and build tooling are explicitly outside it.

This distinction is the difference between a version number that means something and one that climbs on every refactor. When unsure, ask: can a user observe this without reading our source? If not, it is not breaking.

| Change | Breaking? | | ----------------------------------------------- | ------------------------------------------ | | Rename a prompt_engine parameter | Yes — MCP tool surface | | Remove a cpm flag | Yes — CLI surface | | Change the gate YAML schema | Yes — resource format | | Restructure src/ layers, rewrite imports | No — internal | | Drop types / src from the published package | No — packaging, no library API is declared | | Add a validation script or CI job | No |

Testing

Decision Matrix

Run validations that match what you changed:

| I changed... | Run this | Required? | | -------------------------- | --------------------------------------------------------------------------------------------------- | --------- | | Server source code | Minimum Validation below (all four) | Yes | | Pipeline stages | npm test + smoke test both transports | Yes | | MCP tool schemas/contracts | npm run generate:contracts && npm run validate:contracts && npm run validate:tool-parameter-reads | Yes | | A prompt or chain template | Execute via prompt_engine, describe results in PR | Yes | | A gate definition | Execute via resource_manager, verify gate triggers | Yes | | Transport/runtime behavior | Smoke test BOTH: start:stdio and start:development | Yes | | Documentation only | Verify references against server/dist/** | Yes | | Dependencies | npm audit + full test suite | Yes |

Push validation is impact-aware and fail-closed:

| Push contents | Hosted/local route | | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | Canonical docs/plan Markdown only