PHARN

Ship at 8x speed. Keep the understanding of a 1x craftsman.

An agent-orchestrated intent layer for Claude Code that prevents comprehension debt.

---

Contents

• Why PHARN?
• Claude Code alone vs. PHARN
• The pipeline
• What's inside
• Quick start
• A session at a glance
• Principles
• Documentation
• Contributing
• License

---

Why PHARN?

Vibe-coding with an AI agent is fast — until the chat history scrolls away and takes the understanding with it. Six months later, nobody on the team can say why the code is shaped the way it is, what the constraints were, or which decisions were deliberate. That gap is comprehension debt — a term coined by Addy Osmani in early 2026 — and it compounds faster than any other kind.

This isn't hypothetical. A 2026 Anthropic RCT measured developers scoring ~17% lower on comprehension of code they shipped with AI assistance, while industry data shows PR volume nearly doubling — more code, understood less.

PHARN is the intent layer that closes the gap. It keeps the spec, the constitution, and a markdown-canonical memory bank in your repo — readable, diffable, and versioned in git. The agent does the typing; PHARN makes sure a human (and the next agent) can still reason about the result.

Your chat history is gone. Your spec isn't.

PHARN augments the whole team — the PM becomes a product strategist, the developer an architect and reviewer, and everyone works off the same artifact. It does not replace developers.

---

Claude Code alone vs. PHARN

Capability	Claude Code alone	+ PHARN
Planning rigor	Ad-hoc prompting	/pharn-plan → structured spec with sections and contracts
Adversarial review of plans	—	/pharn-grill — 7 grillers stress-test the plan before code
Code review	General suggestions	/pharn-review — 13 context lenses, each citing a rule ID
Compliance audits	—	7 standalone audits (privacy, security, a11y, supply-chain…)
Persistent project memory	Lost with the chat	Markdown memory bank, versioned in git
Model routing	Manual	Deterministic per-file tier + effort routing
Privacy / PII guardrails	—	privacy-shield + constitution-guard hooks
Audit trail	None	Findings fingerprinted in a ledger; constitution-enforced

---

The pipeline

The core workflow is six deterministic stages. Each is a slash command; each reads the spec and memory bank the previous stage produced.

  /pharn-plan      Draft a structured spec — sections, entity schema, contracts.
       │
       ▼
  /pharn-grill     7 grillers interrogate the plan; gaps surface before any code.
       │
       ▼
  /pharn-build     Wave-ordered phases generate code against your stack rules.
       │
       ▼
  /pharn-verify    Verifiers check the build against the plan's contracts.
       │
       ▼
  /pharn-review    13 lenses review the diff; every finding cites a rule ID.
       │
       ▼
  /pharn-ship      Gate on review thresholds, then open the PR.

Alongside the pipeline: /pharn-drift, /pharn-cost, /pharn-eval, /pharn-pr, /pharn-emit, /pharn-docs, and /pharn-memory.

---

What's inside

Modules are subfolders, each fetched independently by the installer — not npm packages. pharn-core is required; everything else depends on it.

Module	What it gives you
pharn-core	Constitution, markdown memory bank, privacy-shield + constitution-guard hooks, 4 base skills
pharn-pipeline	The 6-stage pipeline plus drift, cost, eval, pr
pharn-review	/pharn-review with 13 context lenses (architecture, security, privacy, a11y, …)
pharn-audits	7 standalone audits — privacy, security, a11y, PostHog + logging masking, license, supply-chain
pharn-skills-db	Database-host vendor bridges (Neon) — stack-agnostic, composed by the wizard
pharn-skills-orm	ORM vendor bridges (Drizzle, Prisma) — stack-agnostic
pharn-skills-auth	Auth vendor bridges (Better Auth, Clerk, Supabase Auth) — stack-agnostic
pharn-skills-payments	Payments vendor bridges (Stripe) — stack-agnostic
pharn-skills-email	Email vendor bridges (Resend) — stack-agnostic
pharn-stack-react	Framework-agnostic React 19 base (useEffect discipline, reused by every React stack pack)
pharn-stack-nextjs	Next.js App Router stack pack — 19 rule files, ai_docs, phase-variants, grill-banks; pair with pharn-skills-* for vendor bridges

---

Quick start

Via the wizard (recommended), inside any existing project:

npx pharn@latest init

The wizard detects your stack, walks you through which modules and which stack pack, then copies the chosen modules into your project's .claude/. Add modules later with:

npx pharn@latest add review
npx pharn@latest add audits

Starting from scratch? Scaffold the canonical stack first, then run the wizard:

npx create-next-app@latest my-app
cd my-app
npx shadcn@latest init
npx pharn@latest init

Manual install (no wizard): fetch pharn-core directly, then add modules via the CLI:

npx degit pharn-dev/pharn-oss/pharn-core .claude
npx pharn@latest add pipeline

Note: PHARN's /pharn-init (the wizard launcher) is separate from Claude Code's native /init. After installing PHARN, both are available — use /pharn-init for PHARN setup.

---

A session at a glance

Inside Claude Code, in your project:

1. /pharn-plan — describe the feature; PHARN writes a structured spec to your repo.
2. /pharn-grill — the plan gets stress-tested; you resolve the gaps it raises.
3. /pharn-build — phases generate the code, wave by wave, against your stack rules.
4. /pharn-verify — verifiers check the result against the plan's contracts.
5. /pharn-review — 13 lenses review the diff, each finding citing the rule it enforces.
6. /pharn-ship — once review thresholds pass, PHARN opens the PR.

When the session ends, the spec, the decisions, and the lessons stay in your repo.

---

Principles

PHARN ships a constitution — non-negotiable principles that override every rule, skill, and agent decision. Variants (gdpr-strict, standard, minimal) ship in pharn-core/templates/constitution/; the wizard picks one for your project.

1. Privacy by default — never store raw PII; PostHog events carry none; session recording off by default.
2. Multi-tenant isolation — every user-data table has orgId; every query filters by it.
3. Layer integrity — shared/ never imports features/; actions/ never touches the ORM directly.
4. No secrets in code — only env vars validated by env.ts.
5. Accessibility is not optional — keyboard access, labels, alt text; color is never the only signal.
6. Data lifecycle completeness — every PII entity is covered by export, deletion, and the masking plan.

The OSS methodology is fully open — every skill, lens, rule, and audit in this repo, Apache 2.0, no gated content.

---

Documentation

Doc	For
Getting started	Zero to your first feature in ~10 minutes
Architecture	How the modules fit together
Module anatomy	What lives in a module and why
Skill authoring	Writing a new skill
Rule authoring	Writing a new stack rule
Model & effort routing	Which model runs each agent, and how hard
Meta-rules	Precedence and conflict resolution
Contributing	How to propose a change

---

Contributing

See docs/contributing.md. Every authored skill, lens, phase, and audit carries valid frontmatter, evals, and — where PHARN-authored — the PHARN ✓ reviewed seal.

License

Apache 2.0. See LICENSE.