first-principles-cli

Install First Principles thinking rules, hooks, and skills for Claude Code.

Forces Claude to decompose problems, challenge assumptions, and derive solutions from verified facts instead of pattern matching.

Install

pnpm add -g first-principles-cli

Installation automatically:

• Copies rules to ~/.claude/rules/
• Copies /fp skill to ~/.claude/skills/
• Merges reminder hooks into ~/.claude/settings.json

What It Does

Three layers of enforcement

| Layer | Mechanism | When | |-------|-----------|------| | Rules (~/.claude/rules/) | Loaded into system context | Every conversation | | /fp skill | Wraps task with mandatory steps | When user invokes /fp <task> | | Hooks (UserPromptSubmit + PostCompact) | Injects short reminder | Every turn + after context compression |

The Three Steps

Every response follows:

1. Decompose -- Break the problem down to basic facts and constraints. Read the code before acting.
2. Challenge -- Separate verified facts from unverified assumptions. Verify or explicitly mark assumptions.
3. Rebuild -- Derive the solution from verified facts alone, not from convention or pattern matching.

/fp skill (strongest enforcement)

/fp build a system architecture diagram

When invoked, Claude is forced to:

• Read relevant project files before writing anything
• Explicitly list verified facts vs assumptions
• Only act on verified information

Rules installed

| File | Purpose | |------|---------| | first-principles.md | Core three-step thinking discipline | | code-standards.md | File headers, comments, package managers, git conventions | | prohibited.md | Hard prohibitions (no emoji, no npm, no fabrication, no workarounds) |

Uninstall

pnpm remove -g first-principles-cli

Automatically removes only the files this package installed. User-modified files are preserved.

Manual management

first-principles status     # Show what's installed
first-principles install    # Re-run installation
first-principles uninstall  # Remove components

Platform support

• macOS
• Linux
• Windows (Claude Code uses Git Bash for hooks)

How it works

The npm postinstall script copies template files to ~/.claude/ and merges hook configurations into settings.json. No runtime dependencies. No background processes.

The /fp skill works by placing the three-step instructions before the user's task in the same message, so Claude processes the constraints before seeing the task. This is structurally stronger than hooks (which inject reminders after the user message).

Limitations

Rules and hooks are soft enforcement -- they increase compliance probability but cannot guarantee 100% adherence. The /fp skill provides the strongest enforcement because it restructures the prompt itself.

For hard enforcement of specific behaviors (e.g., blocking npm), use permissions.deny in settings.json.

License

MIT