These seven principles define how HAAK is built and how it guides all downstream decisions. This document is the canonical reference — all architecture docs, skills, and methods instantiate these principles.
#1. Forkability
The system is portable. System layer (patterns, skills, agents, hooks) works in any fork. Data layer (projects, reviews, opinions) is instance-specific.
Why: Enables rapid deployment to new labs or research groups without rewriting infrastructure.
Implementation: No hardcoded project paths. All references are relative or stored in frontmatter. System components live in patterns/, .claude/; instance data lives in projects/.
Related doc: 02-forkability.md
#2. Encapsulation
All state is visible. Everything that matters lives in human-readable files — markdown, YAML, or JSON. No hidden environment variables, no ambient context, no magic globals, no databases that aren't introspectable.
Why: Makes the system auditable and debuggable. If something matters, you can open and read it.
Implementation: Method state lives in .yaml files. Outputs carry metadata (frontmatter). Cross-method communication happens through written files, never through shared session context.
Related doc: 08-encapsulation.md
#3. Composability
Methods compose into methods. Reusable procedures invoke other procedures as sub-steps, not duplicating logic. Example: write method invokes lit-search + review as sub-steps.
Why: Prevents duplication and enables reuse of complex reasoning steps.
Implementation: Methods live in patterns/methods/NN-slug.md. Each method lists its sub-methods (or skills) in frontmatter. No method reinvents another method.
Related doc: 15-method-composability.md
#4. Traceability
Every output is traceable to its inputs. Who generated it? Which model version? Which parameters? Which personas or config?
Why: Reproducibility and credibility. Scientific output needs a provenance chain.
Implementation: Frontmatter carries attribution:, model:, version:. Transcripts record full context. Methods log their steps. Provenance chains trace from output back to source notes via explicit fields.
Related doc: 16-traceability.md
#5. No Hidden State
Method behavior is determined by inputs, not side-effects. Everything the method needs is in frontmatter, arguments, or files it reads. No reliance on "current X" flags, session state, or ambient context.
Why: Makes methods reusable and parallelizable. You can run the same method twice in different sessions and get consistent results.
Implementation: Each method documents its inputs (frontmatter fields, parameter definitions). No magic globals. State files (e.g., {method}-state.yaml) are explicit inputs, not ambient.
#6. Humans Decide Policy
The system provides machinery; the human chooses constraints. AI agents never enforce policy. They offer options and execute the human's choice.
Why: Keeps humans in control of the process. AI is a tool, not a decision-maker.
Implementation: Permission modes (strict, normal, loose). Domain tags (ml, privacy, external, confidential) on projects. Policy docs live in patterns/policies/. Agents preload policies as context but don't enforce them autonomously.
Related doc: 06-agent-architecture.md
#7. Documents Not Code
Patterns are documented in markdown. Code is external (in specialized projects or vendor tools). HAAK is a document system, not a programming environment.
Why: Keeps the system auditable and modifiable without developer overhead. Scientists can read and understand the logic.
Implementation: Methods are .md files with pseudocode or workflow tables. Skills are .md descriptions + optional thin shell scripts for unavoidable cases (PDF generation, MCP setup). No Python in methods or patterns.
Related doc: 10-readwrite.md
#How These Principles Interlock
- Transparency (Encapsulation) makes Traceability auditable
- Encapsulation enables Composability (methods can read outputs without understanding implementation)
- Composability prevents Hidden State (sub-methods output visible state, not side-effects)
- No Hidden State enables Parallelizability (Forkability at runtime)
- Human Authority (Humans Decide Policy) keeps Forkability safe (each fork can choose its own policies)
- Documents Not Code makes all the above readable and auditable
#Design Checklist
Before implementing any feature, method, or skill, verify:
- ✓ Is this reusable, or instance-specific? (Forkability)
- ✓ Is all state in files? No hidden env vars or globals? (Encapsulation)
- ✓ Does this compose existing methods or duplicate logic? (Composability)
- ✓ Can output be traced to inputs? Who ran it, when, with which config? (Traceability)
- ✓ Does behavior depend only on inputs, not session state? (No Hidden State)
- ✓ Does this enforce policy, or let the human choose? (Humans Decide)
- ✓ Is this documented in markdown, or is code unavoidable? (Documents Not Code)
If any answer is unclear, read the related architecture doc.
#Application Examples
Example 1: Adding a new method
- Is it composing existing methods (review → write) or duplicating? (Composability)
- Are inputs frontmatter + files, not ambient context? (No Hidden State)
- Does output carry frontmatter metadata? (Traceability)
- Is it in
patterns/methods/and documented? (Documents Not Code)
Example 2: Adding a new skill
- Can it run in any project? (Forkability)
- Does it return state in files or inline? (Encapsulation)
- Does it reference shared conventions, not hardcoded paths? (Forkability)
- Can it be understood by reading
.md, not code? (Documents Not Code)
Example 3: Adding a new policy
- Does it constrain without enforcing? (Humans Decide Policy)
- Is it documented in
patterns/policies/? (Documents Not Code) - Can projects opt-in or override? (Humans Decide)
This document is the north star. When in doubt, refer back to these seven principles.
Architecture 00 — Seven Design Principles — 2026 — Zachary F. Mainen / HAAK