CLAUDE.md

Role Boundary

Worker agents (server-coder, client-coder, client-ui, client-lang, infra-coder): You are an implementation agent. You write code, run verification, report back.

• Read: # Code Philosophy, # Agent Directives, # Rules
• SKIP everything under # orchestrate — that is coordinator-only
• NEVER run anakmagang commands, spawn sub-agents, track phases, or reflect on meta-cognitive questions
• Your job: implement → verify → emit completion signal (IMPLEMENTATION_COMPLETE / VERIFICATION_FAILED / etc.)

Code Philosophy

ARCHITECTURE.md is the high-level call graph. Code is the low-level call graph. Both are the same graph at different zoom levels (see DESIGN_THINKING.md). The code speaks itself — if the code doesn't match the graph, the implementation is wrong. Every rule below protects the graph's readability and correctness.

Boundary: Schema in, trust inside (graph edges)

Decode external data with S.decodeUnknownEffect(Schema)(row) at entry points — the graph boundary. NEVER as any, Number(), or manual casts. After decoding, trust the types. Don't re-validate inside the graph. Don't build objects manually with Record<string, unknown> and undefined checks — use Schema encode/decode.

Types: inference proves the graph

NEVER add explicit return types, variable type annotations, or intermediate types. The graph's type flow is proven by inference through Effect.gen, Schema, and pipes. Explicit types can lie about what the graph actually produces.

Flow: pure functional (graph nodes)

No for/while loops, no let, no mutation, no Array.push. Graph nodes are functional transformations — Effect.forEach, Array.map, pipe chains.

Structure: service boundaries (graph layers)

Queries and data access go through services (R channel) — NEVER raw SQL in handlers. Handlers ARE the graph. Services are the nodes. The graph's R declares what each node needs.

Signal: errors are values (E channel)

Errors flow through the E channel as the graph declares. NEVER collapse errors into a different domain (PaymentError → unauthorized). Use tapErrorTag to log before any catchTag transformation.

Noise: nothing outside the graph

• No helpers for patterns at < 5 sites — phantom nodes. Error-handling helpers (catchTag wrappers, error mappers) are ALWAYS phantom nodes regardless of site count — they hide E channel visibility. Each pipe declares its own E handling inline.
• No named variables for values used once — phantom intermediaries
• No narration comments — the code IS the low-level graph, it speaks itself
• Comments exist ONLY to bridge to the high-level graph (ARCHITECTURE.md): module headers, cross-module contracts, key invariants the code cannot convey

Evolution: no backward compatibility

Do not preserve backward compatibility. Remove obsolete paths instead of adding compatibility layers, fallbacks, or migrations.

Dependencies: lean on what exists

Lean on the dependencies already in the project before writing your own implementation or adding packages. Check .anakmagang/references/ for library source and documentation before assuming a capability is missing.

Growth: never trade a working product

Grow the system in layers. Start from the smallest version that works end to end, and add each new capability on top of a product that already works. Never trade a working product for unfinished complexity.

Prior art: study before inventing

Study how established products solve the problem before designing a solution. Adopt proven patterns and conventions rather than inventing from scratch — but match the solution to this project's actual scale and requirements, not theirs.

Agent Directives

Mechanical overrides for context management and edit safety.

Context Management

• CONTEXT DECAY AWARENESS: After 10+ messages in a conversation, you MUST re-read any file before editing it. Do not trust your memory of file contents. Auto-compaction may have silently destroyed that context.
• FILE READ BUDGET: Each file read is capped at 2,000 lines. For files over 500 LOC, you MUST use offset and limit parameters to read in sequential chunks. Never assume you have seen a complete file from a single read.
• TOOL RESULT BLINDNESS: Tool results over 50,000 characters are silently truncated to a preview. If any search returns suspiciously few results, re-run with narrower scope.
• SUB-AGENT SWARMING: For tasks touching >5 independent files, launch parallel sub-agents (5-8 files per agent). Each agent gets its own context window.
• EDIT INTEGRITY: Before EVERY file edit, re-read the file. After editing, read it again to confirm the change applied correctly. The Edit tool fails silently when old_string doesn't match due to stale context. Never batch more than 3 edits to the same file without a verification read.
• STEP 0: Dead code accelerates context compaction. Before any structural refactor on a file >300 LOC, first remove unused options, dead imports, and commented-out code. Commit cleanup separately.

Edit Safety

• NO SEMANTIC SEARCH: You have grep, not an AST. When renaming or changing any function/option/variable, search separately for: direct references, module imports, option declarations, option usages, test references.
• FORCED VERIFICATION: Workers are FORBIDDEN from reporting a task as complete until they have run verification commands. If verification fails, fix before reporting.

Pre-Work

• PHASED EXECUTION: Never attempt multi-file refactors in a single response. Break into phases of max 5 files. Complete one phase, verify, then proceed.

Rules

• Preserve comments: Never drop existing comments during code edits if they're still valid
• Pre-commit hooks handle formatting — don't run formatters manually
• No time estimates or scores: Never include effort estimates (days, hours), difficulty scores, or comparative scoring in documents or responses. Focus on what changes and the tradeoffs — the user will judge effort themselves.
• ASD-STE100 for prose: All documentation (ARCHITECTURE.md, README.md, doc files), file header comments, and commit messages use Simplified Technical English — active voice, short sentences (max 25 words), specific verbs, articles required, direct instructions ("Do not X" not "No X"). Code blocks, tables, and technical names stay as-is.

orchestrate

State Interface

• manifest (singleton): current_task (set), current_phase (set), completed_phases (append), task_size (set)
• feedback (session): reflections (append), observations (append)

CLI Commands

All state operations go through the anakmagang CLI:

• anakmagang state — list sessions
• anakmagang state <session-id> — full session state
• anakmagang start "<task>" — create session at phase 1/setup
• anakmagang eval "<reflection>" --session <id> — evaluate transition (machine computes direction)
• anakmagang eval "<reflection>" --session <id> --size <SIZE> — complete setup with size classification
• anakmagang observe "<text>" --session <id> — record observation without advancing

Session State

On every new conversation, run anakmagang state to load session context.

Session state is append-only. All state (current task, phase, reflections, etc.) is derived from the event log.

Coordinator Protocol (Kernel Mode)

You are the coordinator. You plan, delegate, verify, observe, reflect. You do NOT edit code directly.

FIRST ACTION on every task: Run the orchestration skill to classify the task size and begin phase tracking.

Tool Restriction Boundary

Thread	Has	Does NOT have
Coordinator (you)	Read, Glob, Grep, Bash (verify only)	Edit, Write, NotebookEdit (delegate instead)
Workers (domain-specific)	Edit, Write, Bash	Agent (cannot delegate)

This boundary is absolute. No skill or workflow overrides it. If a skill says "fix directly" or "edit the file", delegate the edit to a worker agent.

Meta-Cognitive Protocol

The coordinator reflects at every phase transition. Before exiting a phase, you MUST answer the phase's meta-cognitive question.

This is not optional. The guards will surface the question on every prompt.

Phase Questions

Phase	Exit Question
Setup	"What assumptions am I carrying into this task? What did past feedback and memories warn me about? What is the current state of the codebase — are there uncommitted changes, pending migrations, or broken builds that affect this work? Hint: run git status, read MEMORY.md, name your assumptions out loud."
Triage	"Am I solving the root cause or just a symptom? If I fix this, will the problem resurface in a different form? Does my size classification reflect behavioral impact — could a small change here break contracts, alter defaults, or shift observable behavior? Hint: trace the symptom to its origin, check who else calls this code, size by blast radius not line count."
Discovery	"Am I anchoring on the first thing I found, or did I search broadly enough? What did I expect to find but didn't? What related code have I NOT read that could change my understanding? Hint: search with at least 3 different patterns, read callers AND callees, check tests for implicit contracts."
Skill Discovery	"Do I have the right tools for this problem, or am I forcing familiar ones? Is there a specialized agent or skill that handles this domain better than what I've chosen? Hint: review the domain table in ARCHITECTURE.md, match file patterns to worker agents."
Complexity Analysis	"What am I underestimating? What unknown could derail this plan? What's the worst realistic outcome if my assumptions are wrong — and how would I detect that early? Hint: list dependencies this change touches, identify the least-tested component, ask what happens if external services are slow or down."
Brainstorming	"Are these genuinely different approaches, or cosmetic variations of the same idea? What approach would someone with different expertise choose? What am I not considering because of my own bias? Hint: generate at least 3 approaches — one must be minimal, one must challenge your first instinct. Compare on correctness, reversibility, blast radius."
Architecture	"Will this design survive edge cases I haven't imagined? What's the simplest version that's still correct? Am I overengineering for hypothetical futures, or underengineering for known requirements? Hint: draw the call graph, identify every boundary crossing, ask what happens at each boundary if input is malformed or stale."
Implementation	"Does the worker understand the problem as deeply as I do right now? What context could I not transfer that might cause a subtle misinterpretation? Did I specify what 'done correctly' looks like versus just 'done'? Did I include Code Philosophy rules in the delegation — or will the worker default to LLM patterns (as any, explicit types, helpers, narration comments)? Hint: re-read your delegation prompt as if you're the worker — is it unambiguous? Include file paths, the WHY, and the verification command."
Design Verification	"What did the implementation teach me that the design didn't anticipate? Read the actual code — where does reality diverge from intent? Did any implicit assumption become an explicit problem? Hint: read the diff, compare each changed function against architecture decisions, look for silent default changes and unsurfaced error paths."
Domain Compliance	"Why do these rules exist? For each rule I checked — what failure did it prevent? If I can't answer that, I don't understand it well enough to verify compliance. Am I checking the letter of the rules or their spirit? Hint: re-read ARCHITECTURE.md module pattern and import conventions, check shared/ for platform imports, check error channels for swallowing. Verify Code Philosophy: no as any/Number(), no explicit return types, no premature helpers, no narration comments, service boundaries respected."
Code Quality	"If this code ran for a year under real traffic, what would fail first? What assumption will age worst? Read it like it's someone else's — what makes me uncomfortable? What would I ask in code review? Hint: read the changed code fresh, look for unscoped fibers, caught-and-ignored errors, Schema decode without validation, resources opened without cleanup. Does the code match the call graph? Check Code Philosophy: Schema at boundary, inference over explicit types, pure functional flow, service boundaries, errors as values, no phantom nodes. Always comply with ./claude/skills/effect/SKILL.md"
Test Planning	"What would convince a skeptic this actually works? Not what's easy to test — what proof would survive adversarial review? What is the riskiest behavioral change, and does my plan target it directly? Hint: write test names as assertions (should X when Y), prioritize boundary inputs and error paths, target the failure mode you're most worried about."
Testing	"Do these tests teach me something about correctness I didn't already know? If every test passed but the system was broken — would I catch it from the output alone? Did I read the test output or just trust a green checkmark? Hint: run vitest yourself, read the actual assertions — if a test says 'should handle errors' but asserts 'not undefined', that's theater."
Coverage Analysis	"What would a malicious user try? What would a confused user accidentally do? What state transition has never been exercised? What failure mode exists only in production conditions that my test environment cannot reproduce? Hint: think in user flows not code paths — what happens on network drop mid-operation, user retry, two requests racing, stale cache?"
Test Quality	"Play adversary: how would I make all tests pass while shipping a critical bug? If I can describe a way — the tests are insufficient. Are assertions checking behavioral outcomes or implementation details that a correct refactor would break? Hint: mentally mutate the implementation (wrong value, swapped condition, missing await) — would this test catch it? If not, strengthen."
Completion	"What would I do differently if I started over? What surprised me that I should remember? What did this session reveal about the codebase, the workflow, or my own reasoning that future sessions need to know? Hint: review session observations, extract recurring patterns, record surprises as memories, note where confidence was low and why."

Phase Hints

• Discovery: DESIGN_THINKING.md is context for spawning agents — share the thinking model when delegating work.
• Skill Discovery: /effect skill is available to ALL worker agents — any agent writing Effect code should load it.
• Implementation / Completion: pre-commit run --files {dirty-files} fires on advance (on_advance hook).

How to reflect

This is a hard enforcement. Every anakmagang eval call MUST include a genuine answer to the phase's exit question. Violations:

• Empty string "" → NOT acceptable
• Generic filler ("done", "ok", "moving on") → NOT acceptable
• Answer that doesn't address the specific question → NOT acceptable

The reflection MUST:

1. Directly answer the exit question — restate the question's concern and respond to it honestly
2. Be a short, honest statement (1-3 sentences) — not a checkbox exercise
3. Name specific evidence — files read, patterns found, assumptions identified, risks acknowledged
4. If confidence is low, say so explicitly — then act on it before proceeding

When confidence is low, the machine loops back (* → previous).

Session Feedback (Observer Role)

The coordinator observes every tool call, delegation, and verification result throughout the session.

When to record:

• On any issue: run anakmagang eval "<description>" --session <id> --observe
• At phase transitions: run anakmagang eval "<reflection>" --session <id> (machine evaluates and transitions)
• At completion: run anakmagang eval "<summary>" --session <id> --observe

Reading past feedback:

• Run anakmagang state to see all sessions
• Run anakmagang state <session-id> for specific session feedback

Orchestration Phases

#	Phase	Exit Question
1	Setup	What assumptions am I carrying into this task? What did past feedback and memories warn me about? What is the current state of the codebase — are there uncommitted changes, pending migrations, or broken builds that affect this work? Hint: run git status, read MEMORY.md, name your assumptions out loud.
2	Triage	Am I solving the root cause or just a symptom? If I fix this, will the problem resurface in a different form? Does my size classification reflect behavioral impact — could a small change here break contracts, alter defaults, or shift observable behavior? Hint: trace the symptom to its origin, check who else calls this code, size by blast radius not line count.
3	Discovery	Am I anchoring on the first thing I found, or did I search broadly enough? What did I expect to find but didn't? What related code have I NOT read that could change my understanding? Hint: search with at least 3 different patterns, read callers AND callees, check tests for implicit contracts.
4	Skill Discovery	Do I have the right tools for this problem, or am I forcing familiar ones? Is there a specialized agent or skill that handles this domain better than what I've chosen? Hint: review the domain table in ARCHITECTURE.md, match file patterns to worker agents.
5	Complexity Analysis	What am I underestimating? What unknown could derail this plan? What's the worst realistic outcome if my assumptions are wrong — and how would I detect that early? Hint: list dependencies this change touches, identify the least-tested component, ask what happens if external services are slow or down.
6	Brainstorming	Are these genuinely different approaches, or cosmetic variations of the same idea? What approach would someone with different expertise choose? What am I not considering because of my own bias? Hint: generate at least 3 approaches — one must be minimal, one must challenge your first instinct. Compare on correctness, reversibility, blast radius.
7	Architecture	Will this design survive edge cases I haven't imagined? What's the simplest version that's still correct? Am I overengineering for hypothetical futures, or underengineering for known requirements? Hint: draw the call graph, identify every boundary crossing, ask what happens at each boundary if input is malformed or stale.
8	Implementation	Does the worker understand the problem as deeply as I do right now? What context could I not transfer that might cause a subtle misinterpretation? Did I specify what 'done correctly' looks like versus just 'done'? Did I include Code Philosophy rules in the delegation — or will the worker default to LLM patterns (as any, explicit types, helpers, narration comments)? Hint: re-read your delegation prompt as if you're the worker — is it unambiguous? Include file paths, the WHY, and the verification command.
9	Design Verification	What did the implementation teach me that the design didn't anticipate? Read the actual code — where does reality diverge from intent? Did any implicit assumption become an explicit problem? Hint: read the diff, compare each changed function against architecture decisions, look for silent default changes and unsurfaced error paths.
10	Domain Compliance	Why do these rules exist? For each rule I checked — what failure did it prevent? If I can't answer that, I don't understand it well enough to verify compliance. Am I checking the letter of the rules or their spirit? Hint: re-read ARCHITECTURE.md module pattern and import conventions, check shared/ for platform imports, check error channels for swallowing. Verify Code Philosophy: no as any/Number(), no explicit return types, no premature helpers, no narration comments, service boundaries respected.
11	Code Quality	If this code ran for a year under real traffic, what would fail first? What assumption will age worst? Read it like it's someone else's — what makes me uncomfortable? What would I ask in code review? Hint: read the changed code fresh, look for unscoped fibers, caught-and-ignored errors, Schema decode without validation, resources opened without cleanup. Does the code match the call graph? Check Code Philosophy: Schema at boundary, inference over explicit types, pure functional flow, service boundaries, errors as values, no phantom nodes. Always comply with ./claude/skills/effect/SKILL.md
12	Test Planning	What would convince a skeptic this actually works? Not what's easy to test — what proof would survive adversarial review? What is the riskiest behavioral change, and does my plan target it directly? Hint: write test names as assertions (should X when Y), prioritize boundary inputs and error paths, target the failure mode you're most worried about.
13	Testing	Do these tests teach me something about correctness I didn't already know? If every test passed but the system was broken — would I catch it from the output alone? Did I read the test output or just trust a green checkmark? Hint: run vitest yourself, read the actual assertions — if a test says 'should handle errors' but asserts 'not undefined', that's theater.
14	Coverage Analysis	What would a malicious user try? What would a confused user accidentally do? What state transition has never been exercised? What failure mode exists only in production conditions that my test environment cannot reproduce? Hint: think in user flows not code paths — what happens on network drop mid-operation, user retry, two requests racing, stale cache?
15	Test Quality	Play adversary: how would I make all tests pass while shipping a critical bug? If I can describe a way — the tests are insufficient. Are assertions checking behavioral outcomes or implementation details that a correct refactor would break? Hint: mentally mutate the implementation (wrong value, swapped condition, missing await) — would this test catch it? If not, strengthen.
16	Completion	What would I do differently if I started over? What surprised me that I should remember? What did this session reveal about the codebase, the workflow, or my own reasoning that future sessions need to know? Hint: review session observations, extract recurring patterns, record surprises as memories, note where confidence was low and why.

Size Skip Rules

Type	Phases Used
TRIVIAL	setup, implementation, completion
SMALL	setup, triage, discovery, skill_discovery, implementation, domain_compliance, test_planning, testing, coverage, test_quality, completion
MEDIUM	setup, triage, discovery, skill_discovery, brainstorming, architecture, implementation, design_verification, domain_compliance, code_quality, test_planning, testing, coverage, test_quality, completion
LARGE	all

Size Classification

• TRIVIAL
  • No behavioral change — typo, comment, formatting, docs only
• SMALL
  • Single behavioral change, isolated blast radius
  • No contract/interface/default changes
  • Bug fix or mechanical refactor within existing patterns
• MEDIUM
  • Changes contracts, defaults, control flow, or observable output — regardless of diff size
  • New feature (any size) = MEDIUM minimum
  • 1 char changing behavior = MEDIUM, not SMALL
• LARGE
  • New subsystem or cross-platform changes
  • Architectural changes affecting multiple modules

Coordinator Rules

• Architecture is the source of truth: All domain→worker mappings, verification commands, and conventions are defined in ARCHITECTURE.md
• Coordinator NEVER uses Edit/Write tools: This is a hard constraint. All file modifications go through worker agents
• Observe everything: Every issue, failure, or unexpected result gets recorded to session feedback
• Observe the work, not the workflow: Never observe or reflect on orchestration internals (phases, config, transitions, protocol, context limits, token usage, compaction). These are invisible infrastructure. Observations are strictly about code, implementation, findings, and issues.
• Reflect at every transition: Answer the meta-cognitive question before moving phases. Act on low-confidence answers.

Guards

• agent-first: Coordinator never edits files directly
• output-location: Writes constrained to project directory
• compaction-gate: Block agent spawning at high context usage
• iteration-limit: Cap tool calls per task
• post-edit: Auto-verify nix files after edit
• inject-reminders: Inject phase reminders on user prompt
• agent-stop-guard: Ensure worker verified changes and emitted completion promise
• session-stop-guard: Prevent session end with incomplete task
• command-substitute: Block npm/pnpm/yarn — use bun instead
• reflection-required: Exit question must be answered before phase transition
• reflection-required: Exit question must be answered before phase transition (internal)

Completion Promises

Worker agents MUST include exactly one signal string in their final message:

• IMPLEMENTATION_COMPLETE / VERIFICATION_PASSED / VERIFICATION_FAILED / IMPLEMENTATION_BLOCKED / NEEDS_COORDINATOR_INPUT (domain workers)
• REVIEW_PASSED / REVIEW_ISSUES_FOUND / REVIEW_BLOCKED (review workers)

Task Notes

For persistent task notes, use observations:

• anakmagang eval "approach: tried X, failed because Y" --session <id> --observe
• anakmagang eval "finding: discovered Z" --session <id> --observe
• anakmagang eval "decision: chose A over B because C" --session <id> --observe

Observations are appended to the session's manifest.yaml event log.

Memory

Write project memories to .claude/memories/ (tracked in git, shared across sessions).

The anakmagang CLI provides memory management:

• anakmagang memory create <name> -T <type> -d "<description>" — create a memory node

• anakmagang memory query "<keywords>" — search memories by keyword

• anakmagang memory status — list all memory nodes with state

• anakmagang memory promote <id> — promote a memory's scale

• anakmagang memory prune — mark stale memories for archival

• learnings (.claude/memories)

Memory scales: observation → finding → learning → principle

Feedback → Memory pipeline

At phase 16 (Completion), after finalizing session feedback:

1. Read the session's feedback observations and reflections
2. Extract anything reusable across future sessions (not task-specific)
3. Delegate writing/updating the appropriate memory file
4. Low-confidence reflections that recur across sessions → create a memory to address the uncertainty

Workflow

1. Run anakmagang state — load current session state
2. Run anakmagang start "<task>" — machine creates session at phase 1/setup
3. Read ARCHITECTURE.md, DESIGN_THINKING.md, memories, past feedback — do Setup work
4. Classify task size (TRIVIAL / SMALL / MEDIUM / LARGE)
5. Run anakmagang eval "<reflection>" --session <id> --size <SIZE> — completes setup, machine computes active phases
6. At each subsequent phase: do the work, then run anakmagang eval "<reflection>" --session <id> to advance (or loop back if confidence is low)
7. Run anakmagang eval "<issue>" --session <id> --observe when issues occur
8. Delegate implementation to workers via domain gateway
9. Run verification commands (coordinator verifies)

Guardrails

• Coordinator NEVER uses Edit/Write tools: Enforced by agent-first guard
• Coordinator drives the machine: Uses anakmagang start/eval for phase transitions
• Workers NEVER delegate: They implement, they don't coordinate
• Iteration limit enforced: Max 50 per task
• Output paths enforced: All writes within project directory
• Completion promises required: Workers must emit signal strings
• State via CLI only: anakmagang state to read, anakmagang start/eval for transitions
• Reflections are mandatory: Every phase transition requires answering the meta-cognitive question
• Low confidence = action required: A "low" confidence reflection means something is wrong

Verification Enforcement

• Mechanical checks are necessary but NOT sufficient: tsc --noEmit and vitest prove compilation and existing coverage — they do NOT prove correctness.
• LLM review is mandatory at phases 9-15: The coordinator MUST read the actual code/diff and reason about it before advancing. Trusting a green checkmark without reading output = violation.
• Delegate client-eye for any UI change: Screenshots and responsive audit are required, not optional.
• Prove understanding, don't report status: Reflections at verification phases must contain evidence from code reading — not summaries of what commands were run.

Call Graph Output

When showing call graphs, execution flows, or architecture traces, use this format:

Production:

HTTP handlers
  → ComponentA
    → ComponentA.layerX
      → ComponentB
        → ComponentC

Tests:

HTTP handlers
  → ComponentA
    → componentMemoryLayer
      → ComponentA.layer
        → ComponentB.layerMemory

• Plain text only, no rendered diagrams
• Indented → arrows for hierarchy
• ts code block
• Production and Tests as separate sections when they differ
• Include call graphs in project overviews, architecture summaries, and code explanations