docs: Formalize Founding Principles in README

[krishagel]

Summary

Extract and formalize Geoffrey's architectural principles in README.md, mapping them to PAI v2.0's 14 founding principles. This creates a clear philosophical foundation for development decisions.

Inspiration: PAI v2.0 README - 14 Founding Principles

User Story

As a contributor to Geoffrey, I want clearly documented architectural principles so that I understand the design philosophy and make consistent decisions.

Requirements

Extract Principles from Current Documentation

Current locations:

• CLAUDE.md - Code-first philosophy, progressive disclosure
• docs/architecture-decisions.md - OmniFocus patterns, caching decisions
• docs/skill-development.md - SKILL.md validation patterns
• Geoffrey-PRD.md - Product vision

Map to PAI v2.0's 14 Principles:

PAI v2.0 Principle	Geoffrey Implementation	Status
Clear Thinking + Prompting	Problem clarification before implementation	✅ Implicit
Scaffolding Over Model	Three-tier progressive disclosure	✅ Strong
Deterministic Systems	Runtime data fetching, no hardcoded state	✅ Strong
Code Before AI	Scripts in skills/, deterministic tools	✅ Strong
Specification-First	Test before implementation	❌ Missing
UNIX Philosophy	Modular skills, single responsibility	✅ Strong
Engineering Principles	Production-grade patterns	🟡 Partial
CLI Interfaces	All scripts CLI-based	✅ Strong
Decision Hierarchy	Goal → Code → CLI → Prompts → Agents	✅ Implicit
Self-Modifying Systems	Infrastructure encodes learnings	🟡 In Progress
Skill Management	SKILL.md frontmatter + triggers	✅ Strong
History Systems	Session capture and categorization	🟡 In Progress
Agent Personalities	Consistent identity (Tier 1)	✅ Strong
Science as Cognitive Loop	Hypothesis → Experiment → Measure	❌ Missing

Acceptance Criteria

• README.md has "Founding Principles" section
• At least 10 principles documented with rationale
• Each principle includes Geoffrey-specific example
• Principles referenced in architecture decisions
• Link to PAI v2.0 for full context

Technical Implementation

Files to Modify

• README.md - Add Founding Principles section (after Overview, before Installation)
• docs/architecture-decisions.md - Reference principles in decisions

Proposed README Structure

# Geoffrey

Personal AI infrastructure built on Claude Code...

## Founding Principles

Geoffrey follows these architectural principles, inspired by [Personal AI Infrastructure v2.0](https://github.com/danielmiessler/Personal_AI_Infrastructure):

### 1. Scaffolding Over Model
**Architecture matters more than AI capability.**

- Three-tier progressive disclosure (Tier 1: always, Tier 2: on activation, Tier 3: just-in-time)
- Example: OmniFocus tags fetched at runtime, not hardcoded

### 2. Code Before AI
**Build deterministic CLI tools, then wrap with AI orchestration.**

- Skills orchestrate scripts (JXA, bash, Python)
- Example: `omnifocus-manager/scripts/get_tags.js` fetches data deterministically
- Code is cheaper, faster, more reliable than prompts

### 3. Deterministic Systems
**Favor predictable, repeatable outcomes over probabilistic behavior.**

- Runtime data fetching, no stale caches
- Example: `knowledge/preferences.json` stores rules, not data dumps

### 4. Progressive Disclosure
**Load only what's needed, when it's needed.**

- Tier 1: System/preferences (50-100 lines, always loaded)
- Tier 2: SKILL.md (loaded when skill activates)
- Tier 3: Scripts/data (fetched just-in-time)

### 5. UNIX Philosophy
**Modular, composable, single responsibility.**

- Each skill does one thing well
- Example: `knowledge-manager` learns preferences, `omnifocus-manager` manages tasks

### 6. Self-Modifying Systems
**Infrastructure learns and improves from experience.**

- Hooks extract preferences automatically
- History enables pattern detection
- Example: SessionEnd → update preferences.json

### 7. Skill Management
**Dynamic routing with modular loading.**

- SKILL.md frontmatter defines triggers
- Example: "add task" → omnifocus-manager activates

### 8. CLI Interfaces
**Command-line tools over GUIs.**

- All scripts CLI-based for automation
- Example: `bun scripts/add_task.js` vs GUI clicks

### 9. Identity-First Design
**Consistent personality and decision framework.**

- Tier 1 identity always loaded (strengths, values, decision style)
- Example: Green-Orange Analytical Action-Taker profile

### 10. Evidence-Driven Development
**Validate against code, never assume behavior.**

- Inspect before claiming
- Conservative language (functionally validated vs production-ready)

[Additional principles as discovered...]

## Installation

...

Architecture Decisions Format

# Architecture Decisions

All decisions reference [Founding Principles](../README.md#founding-principles).

## Decision: Runtime Data Fetching (Not Hardcoded)

**Principle:** #3 Deterministic Systems, #2 Code Before AI

**Context:** OmniFocus has 129 tags that could change...

**Decision:** Fetch tags at runtime via `get_tags.js`

**Rationale:** 
- Data always current (Principle #3)
- Context stays lean (Principle #4)
- Script is deterministic (Principle #2)

Testing Plan

• Manual review: Ensure principles align with actual implementation
• Cross-reference: Check architecture-decisions.md references
• Consistency check: Verify examples match codebase

Research Findings

PAI v2.0's 14 Founding Principles

Philosophical Categories:

1. Thinking/Planning (2 principles)

   • Clear Thinking + Prompting
   • Specification-First

2. Architecture (3 principles)

   • Scaffolding Over Model
   • Deterministic Systems
   • UNIX Philosophy

3. Implementation (5 principles)

   • Code Before AI
   • Engineering Principles
   • CLI Interfaces
   • Decision Hierarchy
   • Self-Modifying Systems

4. Runtime (4 principles)

   • Skill Management
   • History Systems
   • Agent Personalities
   • Science as Cognitive Loop

Geoffrey Already Implements:

• 10/14 principles (strong or partial)
• Missing: Specification-First, Science as Cognitive Loop
• In Progress: Self-Modifying Systems (feat: Implement hook system (SessionEnd, PreToolUse) based on PAI v2.0 #3), History Systems (feat: Implement history capture system (JSONL + Obsidian routing) #4)

Best Practices from PAI v2.0

Principle Documentation Pattern:

1. Bold statement (what)
2. Rationale (why)
3. Implementation (how)
4. Example (concrete)

Cross-Referencing:

• Link principles in technical docs
• Reference by number (feat: Implement hook system (SessionEnd, PreToolUse) based on PAI v2.0 #3) or name (Deterministic Systems)

Dependencies

None (documentation only)

References

• PAI v2.0: README.md
• PAI v2.0: 14 Founding Principles
• Geoffrey: CLAUDE.md, docs/architecture-decisions.md

[krishagel]

Completed in PR #9.

Documented 10 founding principles in README.md with Geoffrey-specific examples and rationale, and updated architecture-decisions.md to cross-reference principles.

Changes merged to main.