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.

Related MCP server: Tages

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

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

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:

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

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