PCL — Product Context Layer

Give AI coding agents persistent, structured knowledge of your product.

npx pcl-mcp init

Instead of re-explaining your personas, journeys, and architecture decisions every session, PCL serves them via MCP on demand. Any agent (Claude Code, Cursor, Windsurf) queries exactly what it needs, when it needs it.

Why PCL?

Without PCL, every coding session starts from scratch:

• Agents can't find your product docs unless you paste them into the prompt
• Context windows get bloated with irrelevant information
• You re-explain personas, business rules, and specs every single time
• No guardrails — agents make assumptions that violate your business rules

With PCL, agents load product knowledge on demand:

• Progressive disclosure — session start costs ~600 tokens (product summary + critical rules)
• Hybrid search (BM25 + semantic) finds the right context without you guiding it
• Live reindex on file save — edit a spec, agent sees it immediately
• Structured Zod schemas — agents get predictable, parseable frontmatter every time

Concrete use case

You ask your agent: "Build the checkout flow"

Without PCL: You paste your billing rules doc, the persona file, the journey map, and the spec into the chat. 4,000 tokens before the agent writes a line of code. Next session, you do it again.

With PCL: The agent auto-loads critical billing rules at session start (~200 tokens). When it starts the checkout feature, it pulls the relevant persona, fetches the journey steps, and checks the spec's acceptance criteria — all on-demand, only what's needed. Every session, automatically.

Quick Start

npm install pcl-mcp
npx pcl init            # prompts before adding example files, sets up CLAUDE.md
# add MCP config (see Agent Configuration below), then start a new agent session

Stack

| Layer | Technology | Why | |---|---|---| | Protocol | MCP (stdio) | Universal — works with every major agent | | Storage | SQLite + FTS5 | Zero infra, git-friendly, offline | | Keyword search | BM25 via FTS5 (title-weighted 10×) | Best-in-class for exact terms, IDs, proper nouns | | Semantic search | all-mpnet-base-v2 (local, 768d) | Higher quality than MiniLM, zero API cost, ~3ms/doc | | Embedding strategy | Split body + title embeddings | Separate semantic channels for body and title matching | | Hybrid fusion | Adaptive RRF (corpus-size-aware k) | Better recall on both small and large corpora | | Score filtering | 15% gap threshold | Prevents low-quality tail results from surfacing | | Cross-references | Auto frontmatter link resolution | Pulls related files into results automatically | | Validation | Zod schemas | Agents get predictable, parseable frontmatter | | File watching | Chokidar v4 | Live reindex on save |

Prerequisites

Node.js >= 22 (required — PCL uses modern Node APIs)

Install

npm install pcl-mcp
npx pcl init            # creates ./product with templates

Also available on GitHub Packages as @michaelgorski/pcl-mcp.

Import existing docs

If you already have markdown documentation in your repo, PCL can scan, classify, and import it automatically:

npx pcl init --scan         # scan + import existing docs, then scaffold remaining templates
npx pcl init --scan-only    # scan + import only, skip template scaffolding

The scanner:

• Walks your repo for .md files (skips node_modules, dist, .git, etc.)
• Classifies each file by directory name, filename, frontmatter keys, and content patterns
• Transforms matching files into PCL format with proper frontmatter
• Copies them into the product/ folder under the correct category
• Skips categories that already have imported files (no duplicate templates)

Supported classifications: persona, journey, spec, decision, domain, product

Agent configuration

Works with any MCP-compatible agent. Configuration examples below.

Claude Code — .claude/mcp.json

{
  "mcpServers": {
    "pcl": {
      "command": "node",
      "args": ["./node_modules/pcl-mcp/dist/src/server.js"]
    }
  }
}

Cursor — settings.json

"mcp.servers": {
  "pcl": {
    "command": "npx",
    "args": ["pcl-mcp", "serve"]
  }
}

Windsurf — MCP config

{
  "mcpServers": {
    "pcl": {
      "command": "npx",
      "args": ["pcl-mcp", "serve"]
    }
  }
}

File structure

/product
  product.md              ← north star doc (required)
  personas/
    001-max.md            ← one persona per file
  journeys/
    001-onboarding.md     ← one user journey per file
  specs/
    001-auth-flow.md      ← feature specs with acceptance criteria
  decisions/
    001-use-nextjs.md     ← architecture decision records (ADRs)
  domain/
    core-rules.md         ← business rules agents must never violate
  .pcl.db                 ← SQLite index (auto-generated, gitignore this)

Tools available to agents

| Tool | Params | Description | |---|---|---| | pcl_product_summary | — | Load the product north-star document. Call at session start. | | pcl_get_persona | id | Get a user persona by ID. Call before any user-facing feature. | | pcl_get_journey | id | Get a user journey by ID including step-by-step detail. | | pcl_get_spec | id | Get a feature spec by ID including acceptance criteria. | | pcl_get_decision | id | Get an architecture decision record (ADR) by ID. | | pcl_get_domain | id or "*critical" | Get domain rules by ID. Pass "*critical" to load all critical rules. | | pcl_list | type: "personas" | "journeys" | "specs" | "decisions" | "domain" | List all files of a given type with IDs, titles, and summaries. | | pcl_search | query, mode? ("hybrid" | "semantic" | "keyword"), types?, top_k? | Hybrid semantic + keyword search across all product files. | | pcl_related | id, top_k? | Find files semantically related to a given file ID. |

Prompts & Resources

In addition to tools, PCL exposes MCP prompts and resources:

Prompt: session-start — Returns a product summary + all critical domain rules. Agents can call this at the start of every coding session to orient themselves without loading every file.

Resources: pcl://files/{type}/{id} — Each indexed file is available as an MCP resource. Agents can browse and read individual files directly via the resource URI (e.g., pcl://files/persona/example-user).

How hybrid search works

PCL runs three parallel retrieval signals and fuses them with Reciprocal Rank Fusion:

query: "what does Max find frustrating about onboarding"

BM25 (FTS5, title-weighted 10×):
  → persona-max, journey-onboarding, spec-magic-link
  ↓ ranked by bm25(title=10×, body=1×) — exact terms, IDs, proper nouns

Semantic — body embedding (all-mpnet-base-v2, 768d):
  → journey-onboarding, persona-max, domain-core-rules
  ↓ cosine similarity on full-text embedding

Semantic — title embedding (all-mpnet-base-v2, 768d):
  → persona-max, journey-onboarding, spec-onboarding-ux
  ↓ cosine similarity on title + summary embedding

Adaptive RRF (k = corpus_size / 10):
  score(d) = Σ 1 / (k + rank(d))   fused across all three lists

Score gap filter (15% threshold):
  Drops results below 0.15 × top_score — removes noise

Cross-reference resolution:
  journey-onboarding.frontmatter.persona = "max"
  → auto-includes persona-max even if it ranked outside top-k

Result:  1. journey-onboarding  (0.94)
         2. persona-max         (0.87)
         3. spec-onboarding-ux  (0.71)

Why split embeddings? Body and title carry different semantic signals. A query like "checkout persona" should match a persona file by title even if its body content is mostly demographic data. Indexing them separately gives the fusion step two distinct semantic channels rather than one diluted one.

Why adaptive RRF k? Fixed k=60 over-smooths rankings on small corpora (10–20 files). Corpus-aware k scales down on small collections to let strong matches separate from weak ones.

Testing & Benchmarks

PCL ships with a full test suite and a multi-dimensional benchmark framework.

Tests

npm test            # run all tests (vitest)
npm run test:watch  # watch mode

Six test suites cover the full stack:

| Suite | Coverage | |---|---| | db.test.ts | SQLite operations, FTS5 queries, embedding storage | | embeddings.test.ts | Embedding generation, cache hits, dimension checks | | indexer.test.ts | File discovery, schema extraction, change detection | | schemas.test.ts | Zod frontmatter validation for all file types | | search.test.ts | Hybrid search, RRF, multi-hop decomposition, cross-refs | | tools.test.ts | MCP tool handlers, response formatting, error paths |

Benchmarks

npm run bench           # all benchmarks
npm run bench:perf      # latency benchmarks (search + embedding speed)
npm run bench:quality   # search quality: Precision@k, Recall@k, NDCG, MRR
npm run bench:tokens    # token efficiency across search modes
npm run bench:ablation  # hybrid vs keyword-only vs semantic-only comparison
npm run bench:ai        # Claude-judged result quality (requires ANTHROPIC_API_KEY)
npm run bench:report    # generate markdown report from results

| Suite | Measures | |---|---| | Performance | Search + embedding latency (p50/p95) | | Search quality | Precision@k, Recall@k, NDCG, MRR on labeled corpus | | Token efficiency | Tokens consumed per query across search modes | | Ablation | Quality delta: hybrid vs keyword-only vs semantic-only | | AI quality | Claude-judged relevance score for top-k results |

Human workflow

The system is only as good as what you put in. Discipline:

• Product decision made? → Write a decisions/ ADR (5 min)
• New feature being planned? → Write a specs/ file first, then code
• User research or feedback? → Update persona anti_patterns or jobs_to_be_done
• Business rule change? → Update domain/ first, then code
• New user journey discovered? → Add to journeys/

The agent does the rest.

Gitignore

product/.pcl.db      # SQLite index — auto-regenerated

License

MIT