# Principled Claude Code
> ⚠️ **ARCHIVED — This approach doesn't work well enough to recommend.**
>
> After extended real-world use, enforcing FPF through Claude Code hooks and skill chains turned out to be fundamentally flawed:
>
> - **Hooks are brittle.** They fire inconsistently, get bypassed silently, or block the wrong things. Mechanical gates don't map cleanly onto a reasoning agent's turn structure — and when they do fire, they can deadlock you out of your own project (as happened while trying to archive this very repo).
> - **Ceremony crowds out work.** Mandatory `/fpf-core → /fpf-worklog → /fpf-problem-framing → ...` chains before any real action bloat the context window and reduce the agent's effective reasoning capacity. The overhead became the weakest link (WLNK).
> - **The agent forgets.** Mid-session, principles, constraints, and skill chains dissolve. There is no durable enforcement — just prompts the model stops attending to as context grows.
> - **Skills-as-workflow-orchestrators is an anti-pattern.** Chaining `must invoke → must invoke → must invoke` turns a capable agent into a bureaucrat filling out forms. FPF is a thinking framework, not a workflow engine.
> - **Context overload kills agency.** Loading CLAUDE.md + multiple skills + hook feedback + artifact templates leaves little room for the actual problem. Agent effectiveness drops sharply.
>
> **What works instead:** FPF works well as **context-level guidance** — a spec loaded into project context in ChatGPT Projects, Claude Desktop, or similar tools where the model can consult it on demand without mandatory ceremony.
>
> **Successor project:** **[claude-code-fpf](https://github.com/m0n0x41d/claude-code-fpf)** — a single lightweight skill with an embedded semantic search index over FPF docs. Query FPF wisdom when you need it; no hooks, no mandatory chains, no context bloat.
---
An [FPF (First Principles Framework)](https://github.com/ailev/FPF) profile for Claude Code — making AI agents do **problem design and strategic creativity**, not just solution delivery.
**The shift:** In a world of cheap solution generation, the bottleneck is problem quality. This profile implements FPF's coupled double-loop factories:
- **Problem factory** (creative) — problematize → characterize → frame → portfolio → acceptance spec
- **Solution factory** (creative) — SoTA → strategize → generate variants → select from Pareto front → implement → verify
- **Factory of factories** (meta) — improve the first two when the workflow itself is the bottleneck
Both creativity and assurance are first-class — neither is subordinated. Templates are thinking tools; filling them IS the reasoning.
Implemented as a **tier-scaled, constraint-based** profile:
- **Task tiers** (T1-T4) scale ceremony proportionally — trivial fixes get zero overhead, architectural decisions get full pipeline
- **Constraint declarations** enforce creative quality (≥3 hypotheses, ≥3 variants, explicit strategy bets) not just process compliance
- **Layered context** — compact CLAUDE.md (~4KB) + skills loaded on demand + reference files searched but not loaded
## Install
Run this in your project directory:
```bash
curl -fsSL https://raw.githubusercontent.com/m0n0x41d/principled-claude-code/main/install.sh | bash
```
Or install into a specific directory:
```bash
curl -fsSL https://raw.githubusercontent.com/m0n0x41d/principled-claude-code/main/install.sh | bash -s -- /path/to/project
```
### Conflict handling
If the installer detects existing Claude artifacts (`CLAUDE.md`, `.claude/`, `.fpf/`), it will prompt you:
- **Backup** (default) — saves your existing files to `.backup/<timestamp>/` before installing
- **Override** — replaces existing files without backup
- **Cancel** — aborts installation
## Task tiers
The core design principle: **scale rigor to task size**.
| Tier | Examples | Protocol |
|------|----------|----------|
| **T1 Trivial** | Typo, syntax fix, quick answer | Direct action. No artifacts. |
| **T2 Localized** | Bug with clear cause, simple refactor | ANOM-* → fix → EVID-* |
| **T3 Substantive** | Feature, multi-file change, design decision | Full problem factory → solution factory |
| **T4 Architectural** | System design, tech choice, cross-cutting | T3 + SoTA survey + strategy card |
## What gets installed
```
your-project/
├── CLAUDE.md # FPF instructions (~4KB, tier-based)
├── .claude/
│ ├── settings.json # Hook configuration
│ ├── hooks/ # Mechanical gate enforcement
│ └── skills/ # FPF slash commands
│ ├── fpf-core/ # Session bootstrap + FPF rules
│ ├── fpf-worklog/ # Session logging
│ ├── fpf-review/ # End-of-session quality gate
│ ├── fpf-problem-framing/ # Anomaly records + problem cards
│ ├── fpf-characterize/ # Characterization passports
│ ├── fpf-problem-portfolio/ # Problem portfolio management
│ ├── fpf-sota/ # SoTA harvesting (survey existing approaches)
│ ├── fpf-strategize/ # Method family bet (first-class creative act)
│ ├── fpf-variants/ # Solution variant generation (NQD)
│ ├── fpf-selection/ # Qualitative Pareto selection
│ ├── fpf-parity/ # Fair comparison conditions (parity plan)
│ ├── fpf-evidence/ # Evidence records
│ ├── fpf-decision-record/ # Decision rationale records
│ └── fpf-glossary/ # Terminology + bridges
└── .fpf/ # FPF artifact workspace
├── anomalies/ # ANOM-*, PROB-*
├── characterizations/ # CHR-*, CHRC-*, SOTA-*
├── decisions/ # DRR-*, SEL-*, STRAT-*
├── evidence/ # EVID-*
├── glossary/ # Terms + bridges
├── portfolios/ # PPORT-*, SPORT-*
├── worklog/ # Session logs
└── templates/ # Compact templates for all artifact types
```
## Level 0 — System prompt patching (optional)
Level 0 patches Claude Code's **system prompts** via [tweakcc](https://github.com/Piebald-AI/tweakcc), making FPF concepts (WLNK, MONO, confidence labels, ADI cycle, Pareto analysis) active in the model's reasoning on **every turn** — not just when skills are invoked.
**This is optional and fragile.** It modifies Claude Code's compiled JavaScript. Every CC update can break patches. Disable auto-updates first.
```bash
# Prerequisites: tweakcc installed, CC auto-updates disabled
npx tweakcc@4.0.8
npx tweakcc@4.0.8 --apply
# Install FPF prompts + apply patches (interactive)
# Option A: curl one-liner
curl -fsSL https://raw.githubusercontent.com/m0n0x41d/principled-claude-code/main/install-level0.sh | bash
# Option B: from a local clone
./scaffold/install-level0.sh
```
See [docs/level-0-tweakcc-setup.md](docs/level-0-tweakcc-setup.md) for details, troubleshooting, and version compatibility.
| Component | Tested version |
|-----------|---------------|
| Claude Code | 2.1.52 |
| tweakcc | 4.0.8 |
## Constraints (enforced mechanically)
10 constraints matching CLAUDE.md §6 — creative, assurance, and session discipline:
| # | Constraint | Type | Tier | Enforcement |
|---|-----------|------|------|-------------|
| C1 | PROB-\* ≥3 hypotheses with trade-off axes | Creative | T3+ | Hook blocks source edits |
| C2 | SPORT-\* ≥3 genuinely distinct variants | Creative | T3+ | Hook blocks source edits |
| C3 | Selection policy stated before applying | Creative | T3+ | Skill-enforced |
| C4 | STRAT-\* invalidation conditions | Creative | T4 | Hook blocks source edits |
| C5 | No source edits without PROB/ANOM-\* | Assurance | T2+ | Hook blocks at ≥8 edits (Gate 1) |
| C6 | No L2 claims without EVID-\* | Assurance | T2+ | Stop hook (Gate 2) |
| C7 | EVID-\* commands + outputs + valid\_until | Assurance | T2+ | Stop hook (Gate 2) |
| C8 | Non-trivial/irreversible → DRR-\* | Assurance | T3+ | Stop hook (Gate 3) |
| C9 | /fpf-core + /fpf-worklog before side effects | Session | All | Hook blocks tools (Gate 0) |
| C10 | /fpf-review before ending | Session | T2+ | Stop hook (Gate 5) |
## Requirements
- `git` (for the installer)
- `jq` (used by hooks)
- Claude Code CLI
## Uninstall
```bash
rm -f CLAUDE.md
rm -rf .claude .fpf
```
## Context budget and modularity
CLAUDE.md (~5KB) is always loaded; skills (~2-3KB each) load on demand.
The FPF skills are **modular** — each `fpf-*` skill is an independent unit (problematization, characterization, strategizing, variant generation, selection, parity, evidence, etc.). You can add your own skill sets alongside FPF. The `.claude/skills/` directory is designed for coexistence: FPF skills use the `fpf-` prefix, leaving the namespace open for domain-specific or methodology-specific skill sets.
**If you have a global `~/.claude/CLAUDE.md`** with FPF-compatible rules (lifecycle states, WLNK/MONO, confidence levels), there will be overlap. Consider removing the duplicated sections from your global file when using this project profile.
Avoid installing competing *workflow orchestration* frameworks (multiple systems trying to control the same session lifecycle will conflict), but additional skill modules that extend rather than replace are welcome.
## License
MIT