docs: #5 - Formalize Founding Principles in README

[krishagel]

Summary

Extracts and formalizes Geoffrey's architectural principles in README.md, mapped to PAI v2.0's founding principles framework.

Changes

• README.md - Added "Founding Principles" section with 10 documented principles
• docs/architecture-decisions.md - Updated all decisions to reference relevant principles

Principles Documented

#	Principle	Example
1	Scaffolding Over Model	Three-tier progressive disclosure
2	Code Before AI	OmniFocus JXA scripts
3	Deterministic Systems	Runtime tag fetching
4	Progressive Disclosure	Tier 1/2/3 loading
5	UNIX Philosophy	Focused, independent skills
6	Self-Modifying Systems	SessionEnd hooks
7	Skill Management	SKILL.md trigger routing
8	CLI Interfaces	bun scripts/add_task.js
9	Identity-First Design	Green-Orange profile
10	Evidence-Driven Development	Validate before claiming

Plus 3 principles in progress: Specification-First, History Systems, Science as Cognitive Loop.

Testing

• Manual review of markdown rendering
• Cross-reference links verified
• Principles align with codebase implementation

Checklist

• Documentation follows project conventions
• Links to PAI v2.0 included
• Each principle has Geoffrey-specific example
• Architecture decisions reference principles

Closes #5

[claude]

PR Review: Formalize Founding Principles in README

Summary

Strong documentation work that extracts and formalizes Geoffrey's architectural principles. The changes align well with the project's philosophy of progressive disclosure and evidence-driven development. A few suggestions for improvements below.

---

✅ Strengths

1. Excellent Progressive Disclosure

The PR itself follows Principle #4 beautifully:

• Tier 1 (README): High-level principles with concise examples
• Tier 2 (architecture-decisions.md): Detailed rationale with principle cross-references
• This is exactly the right layering strategy

2. Strong Cross-Referencing

The addition of principle links in architecture-decisions.md creates valuable traceability. This makes it easy to understand why decisions were made.

3. Geoffrey-Specific Examples

Each principle includes a concrete example from the codebase (e.g., OmniFocus JXA scripts, three-tier loading). This grounds abstract concepts in reality.

4. Honest Principles In Progress

Love the transparency about what's improving vs. what's future work. This aligns with Principle #10 (Evidence-Driven Development).

---

🔍 Suggestions for Improvement

1. Link Validation Needed (Minor)

The PR description says 'Cross-reference links verified' but I'd recommend actually clicking through each link to ensure they work.

2. Principle Numbering Consistency (Minor)

In CLAUDE.md, principles are named (e.g., 'Scaffolding > Model') while in README.md they're numbered (1-10). Consider adding a cross-reference table to CLAUDE.md.

3. Missing Architecture Decision Coverage (Minor)

Some sections in CLAUDE.md don't reference principles yet. Consider adding principle references to core architectural principles sections.

4. Evidence-Driven Development Example (Moderate)

Current example is good, but could use a Geoffrey-specific example like verifying tag counts by running scripts rather than assuming from documentation.

5. When to Apply Guidance (Enhancement)

Some principles (especially #6 Self-Modifying Systems) are complex. Consider adding brief 'When to Apply' subsections.

---

🔒 Security: ✅ No concerns (documentation-only)

⚡ Performance: ✅ No impact (~100 lines added, tier 3 loading)

🧪 Test Coverage: ⚠️ Manual testing only

Recommendation: Consider CI check for markdown link validation

---

📋 Code Quality: ✅ Excellent

• Consistent markdown formatting
• Clear, scannable structure
• Concrete examples
• Aligns with project's own principles

---

🎯 Final Recommendation: APPROVE with minor suggestions

This PR strengthens Geoffrey's documentation foundation significantly. The suggestions above are refinements, not blockers.

Before Merging:

1. Validate all markdown links work (priority: high)
2. Consider adding principle numbers to CLAUDE.md (priority: low)
3. Add missing principle references to CLAUDE.md sections (priority: medium)

Great work! The cross-referencing between principles and architecture decisions is particularly valuable for future contributors.