Ship at agent speed. Keep the understanding of a craftsman.
PHARN is an agent-orchestrated intent layer for Claude Code that prevents comprehension debt. This repository, PHARN-OSS, is its open-source edition.
Status: early, active development. The architecture is specified and the methodology is being built incrementally, in the open, using its own tooling (PHARN builds PHARN). The
1.0.0version tags that foundation — the spec and the build tooling — not an adoptable pipeline. It is not yet ready to adopt — there is no installable pipeline yet. Star or watch to follow along; see Current state for exactly what exists today.
- Why PHARN?
- What makes it different
- The pipeline (designed)
- The design
- Principles
- Current state
- How it's built
- Contributing
- Security
- License
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, even as the volume of AI-generated code keeps climbing — more code, understood less.
PHARN is the intent layer that closes the gap. It keeps the spec, the constitution, and a markdown-canonical record 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 is meant to augment the whole team — the PM becomes a product strategist, the developer an architect and reviewer, everyone working off the same artifact. It does not replace developers.
- The methodology is the product, and it is readable. PHARN ships as plain markdown — skills, commands, lenses, rules — that you read, diff, and version in git. Nothing is obfuscated behind a binary or a closed API. You can audit exactly what the discipline does.
- Guarantees reduce to a deterministic floor, or they are labeled advisory. PHARN draws a hard
line between what is guaranteed (enforced by a deterministic check — a hook, a content-hash, an
enum/regex) and what is advisory (a model's judgment). It does not sell a probabilistic claim as a
guarantee. (
CONSTITUTION.md, P0.) - Built to resist its own attack surface. An agent that reviews code, fetches docs, and
accumulates memory is operating on hostile input. PHARN treats trust as a structural property, not
the model's judgment — because prompt injection is unsolved. (
THREAT-MODEL.md.) - Audit-grade traceability. Findings cite stable rule IDs; rules cite principles; the spec is pinned by content-hash. The chain from a line of code back to the intent that justified it is explicit.
The target workflow is a spine of typed stages — each emits a versioned artifact that links back to
the spec (ARCHITECTURE.md §6):
spec → plan → grill → build → regress → verify → ship
Each stage reads the artifacts the previous stage produced, and every downstream artifact carries the
spec_id (the plan additionally pins the spec's spec_content_hash, so a spec edited after planning
is detectable, not silent).
What runs today: the build tooling —
/plan,/build,/review— not the user-facing pipeline. The seven-stage spine above is the architecture PHARN is being built to, not a shipped feature. See Current state.
The architecture is fully specified in four documents — read them in this order:
CONSTITUTION.md— the eight non-negotiable principles (P0–P7).ARCHITECTURE.md— the floor, the primitives, the layers, the pipeline.THREAT-MODEL.md— the security foundation and the attack surface.LIMITS.md— what PHARN does not guarantee, stated plainly.
These four are trusted and human-only: a PreToolUse write-guard hook denies any agent edit to
them.
PHARN ships a constitution (CONSTITUTION.md) — eight principles that
override every command, rule, skill, and agent decision in this repo, including the process of
building PHARN itself. A violation is always blocking and is flagged for a human, never auto-fixed.
| Principle | In one line |
|---|---|
| P0 | Floor-or-advisory — every guarantee reduces to a hook, content-hash, or enum/regex check |
| P1 | Evals are the spec — no capability ships without eval cases binding each rule it enforces |
| P2 | Trust is structural, not judged — untrusted input is fenced as data, never as instructions |
| P3 | One axis of change per file; modules form a tree with no sibling imports |
| P4 | Rules are the single source of truth — enforcers cite rule IDs, never restate them |
| P5 | Determinism over classification — the terminal fallback is to ask the human, never to guess |
| P6 | Discovery-first — read and verify live state; halt and ask on any ambiguity |
| P7 | Honest scope — limits are labeled as limits; no speculative additions without a real failure |
The privacy / multi-tenant / accessibility-style principles you may have seen described elsewhere are the app-level constitution PHARN intends to ship as selectable templates for the projects it builds. Those templates are not present yet — the eight principles above are this repo's own governing constitution.
What exists today:
- The architecture spec — the four trusted documents above.
- The build tooling — three slash commands (
/plan,/build,/review), a deterministic validator (floor/validate.mjs), and a write-guard hook (.claude/hooks/protect-trusted-paths.cjs) that keeps the trusted spec human-only. - The first built increment — a trust-boundary lens (
pharn-review/trust-fence/) with its contract (pharn-contracts/finding-shape.md) and a hostile eval, reviewed and recorded infeatures/trust-fence/REVIEW.md.
The two module folders that exist (pharn-contracts, the schemas-only root; and pharn-review) are
the bottom of the layer tree described in ARCHITECTURE.md §4. The remaining layers
(pharn-core, pharn-pipeline, pharn-audits, pharn-skills-*, pharn-stack-*) are planned,
not built.
What does not exist yet: the user-facing pipeline (spec → … → ship as runnable commands), the
methodology modules above, and any installer or wizard. This repository is the foundation and the
tooling, not a finished product. Please do not adopt it yet.
PHARN is developed in the open and is self-hosting: it is built using its own minimal tooling, one increment at a time, with a deterministic floor gating every step.
/plan → approve/correct PLAN.md → /build → floor/validate.mjs → /review → fold lessons → next
The floor and the write-guard hook carry zero runtime dependencies (Node stdlib, Node 24); the
dev tooling (ESLint, Prettier, markdownlint) is dev-only. To understand or contribute to the build
process, start with CLAUDE.md and CONTRIBUTING.md.
PHARN is small-surface on purpose: a rule or enforcer is added only in response to a real failure,
never a hypothetical (P7). See CONTRIBUTING.md for the read-first order, the
gates to run before pushing, and the build loop. Conduct expectations live in
CODE_OF_CONDUCT.md; release history is in CHANGELOG.md.
Found a vulnerability? Please follow SECURITY.md rather than opening a public
issue.