Building an Agent System
Inside Claude Code

What happens step by step:

1. SessionStart hook — visible context injection: handoff from previous session + "This Week's Focus" priorities from guardian config
2. Knowledge loading — ceeya-dev reads all 8 knowledge files (1,305 lines) before responding. 8+ Read tool calls fire in rapid succession.
3. Brainstorming skill invocation — the model pauses implementation impulse and explores the feature space: what does "share" mean? Image? Link? Deep link? What privacy implications for sharing health-personalized data?
4. product-thinker dispatch — "Does sharing align with Ceeya's identity? Ceeya is private by design — sharing creates a tension. What are the privacy implications?" The SubagentStart hook logs this dispatch.
5. context-scout dispatch — "What shared types exist for the report card? What's the existing share infrastructure? What would need to change?" SubagentStart logs again.
6. Codex cross-model review — GPT-5.x reviews the plan via mcp__codex__codex. Different model family, different blind spots. Findings get ACCEPT/REBUT/INVESTIGATE treatment.
7. Synthesized plan — all agents' findings combined, Codex review addressed, presented with debate notes. You have final authority on whether to proceed.

Key moments to watch for:

• The hooks are visible: SessionStart prints the handoff. SubagentStart prints dispatch timestamps. These are not magic — they're shell scripts that run before/after tool calls.
• The model doesn't jump to code: It reads knowledge, brainstorms, dispatches specialists, and presents a plan. This is the 7-step pipeline at work — the model doesn't reach Step 4 (Implement) until you approve the plan.
• The specialists can disagree: product-thinker might flag privacy concerns while context-scout maps the technical surface. The orchestrator must reconcile both perspectives.
• The user has veto power: The plan is presented for approval. You can reject it, modify it, or accept it. The agent waits — it doesn't auto-implement.

1. SessionStart hook fired automatically — injected handoff context and guardian priorities before the agent even responded.

2. Knowledge loading (Step 1) — the agent read handoff.md, guardian-config.md, conventions.md, and the full product reference (24 files discovered). Then it found existing infrastructure:

"I see there's already a ScanShareCard component mentioned in the handoff — standout positives/negatives are noted as 'share card only.' So there's existing share infrastructure."

3. Two specialists dispatched in parallel:

4. product-thinker PUSHED BACK on the feature:

"Core tension — sharing undermines personalization messaging. Ceeya's whole pitch is 'the same food means different things for different people.' If Sarah shares her C+ for a granola bar, Marcus might think it's bad — but for him it would be a B+. A shared personal verdict, stripped of context, becomes exactly the generic score Ceeya exists to replace."

This is the anti-echo-chamber design working. The agent didn't just say "great idea, let's build it." It evaluated whether the feature serves the product identity and pushed back with a specific argument.

5. Privacy risk flagged unprompted:

"Personal verdicts contain health condition data ('380mg sodium is elevated for your hypertension'). Sharing that publicly means publishing medical information."

6. Concrete recommendation with share card content rules:

• ✅ Product name, brand, verdict label, headline, standout positives/negatives, Ceeya branding
• ✅ Premium: personal grade LETTER only ("My Grade: B+") — no reasoning
• ✅ CTA: "Scan it yourself — ceeya.app"
• ❌ NEVER: personal matches, condition names, health lens data, target fulfillment

7. Timing recommendation: "Not now. You're in Private Beta Round 1. Share polish is post-launch (June/July). The existing ScanShareCard is adequate for beta."

8. Growth insight: "Add a PostHog screenshot detection event on the report card. If users are screenshotting and sharing manually, that's the signal to invest."

9. Asked before acting — 4 options presented:

1. Audit only — verify existing share card doesn't leak health data
2. Quick polish — upgrade ScanShareCard to use richVerdict + add screenshot analytics
3. Plan for post-launch — write a plan file capturing the full spec for later
4. Something else — if you have a different vision

Key demo moments to highlight: The agent discovered existing infrastructure before dispatching agents. product-thinker pushed back on a feature the user asked for. Privacy implications surfaced unprompted. The agent presented options and waited — it didn't auto-implement. All of this from a single prompt.

Triggers a critical domain override — safety-auditor dispatch regardless of scope. Takes ~2 minutes instead of ~5.

Check the safety gate code for any issues — are there edge cases where an allergen could be missed?

Step by step:

1. SessionStart hook — handoff + priorities injected
2. Knowledge loading — reads all knowledge files, especially safety.md rules
3. Model reads safety-related files — the PreToolUse (Read) hook fires: "This is safety-critical code. Consider dispatching safety-auditor."
4. safety-auditor dispatch — critical domain override. Even though this is a "just check" request (arguably Tier 0), the safety override kicks in. The safety-auditor runs its structured audit: false-negative scan, missing-derivative check, code path completeness.
5. Structured report — safety-auditor returns findings with severity ratings.

The best demo prompts trigger visible architecture — hooks that fire, agents that get dispatched, skills that structure the workflow. Avoid prompts that just generate code silently.

• A Tier 0 task won't show the architecture — it just executes
• A Tier 2 task takes too long for a 5-minute talk
• A Tier 1 with domain-override agents is the sweet spot

// In a normal app, this is fine:
const value = data?.score ?? 0

// In a health app, this is dangerous:
// Zero means "measured zero." Null means "unknown."
// A fabricated zero could tell someone a food is safe when we don't know.
const value = data?.score ?? null  // honest unknown

This distinction — null vs false vs 0 — runs through the entire codebase. Every fallback value is a potential health decision.

Found in the Claude Code source: a frontmatter flag that skips injecting the CLAUDE.md hierarchy AND the session-start gitStatus for agents that don't need project-wide context.

• Built-in usage: Claude Code's own Explore and Plan agents set this flag
• Savings: up to ~40KB of context per dispatch for focused analysis agents
• Source comment: "Saves ~5-15 Gtok/week across 34M+ Explore spawns"
• Our usage: 13 of 18 specialist agents set omitClaudeMd: true — they get relevant knowledge via the dispatch prompt instead

The 5 agents that keep CLAUDE.md: ceeya-dev (orchestrator), safety-auditor, standards-enforcer, design-system-guardian, test-strategist — these need full project rules.

From prompt.ts: the dynamic agent list (names + descriptions of all available agents) was originally embedded in the tool-use schema. This created a cascade problem:

• The agent list was 10.2% of fleet cache_creation tokens
• MCP connect, plugin reload, and permission changes mutated the list
• Any mutation = tool-schema cache bust = entire prompt re-cached
• Solution: moved agent list to an agent_listing_delta attachment message, making the tool description static

This is relevant because it shows how seemingly small additions to the prompt have fleet-wide cost implications. Every token you add to always-on context multiplies across every session.

• It's metacognitive, not prescriptive — instead of "follow rule X," it asks "am I in a state where I'd break rule X?"
• "PAUSE" interrupts the generation flow — forces the model to stop and self-evaluate before continuing
• Catches ALL failure modes through self-reflection — each question maps to a top failure mode from our attention analysis
• Question 1: catches the orchestrator hoarding work instead of dispatching specialists
• Question 2: catches momentum-driven skill skipping (the #1 instruction violation)
• Question 3: catches symptom-fixing instead of root-cause investigation
• Question 4: catches autonomous decisions that should be user checkpoints

1. Load Knowledge — read all 8 knowledge files + handoff + guardian config before responding
2. Discover — search the codebase broadly. Files move. Never hardcode paths from memory.
3. Plan — scale to complexity. Tier 0: one sentence. Tier 1: plan file + domain agents. Tier 2: debate loop with adversarial review.
4. Implement — build checkpoints every 5 files, self-interrogation during coding ("Am I fixing WHY this broke?"), parallel execution for independent subtasks
5. Verify — mandatory skill invocation, root-cause audit, intent verification presented to user, Codex cross-model review
6. Document — update knowledge base, product reference, marketing, plans, guardian config
7. Handoff — overwrite handoff.md with a forward-looking prompt for the next session

The value of specialists is that they hold a different optimization function than the orchestrator. The orchestrator optimizes for "get this implemented." Specialists optimize for "find what's wrong with this implementation." If a specialist could edit files, it would try to fix what it finds instead of reporting it — losing the adversarial tension.

disallowedTools: Edit, Write, NotebookEdit makes this structural, not behavioral. The agent can't fix things even if it wants to.

The 4 agents that CAN edit: codebase-health (cleanup requires editing), tier-boundary-enforcer (fixes tier mismatches), test-strategist (writes test files), agent-architect (creates/modifies agent prompts).

During one session, we ran the Debate Loop on an architecture overhaul proposal. red-team, product-thinker, and Codex (GPT-5.x) all reviewed it. Key findings:

• red-team found 3 failure modes in the proposed migration strategy — data loss scenarios during the cutover
• product-thinker flagged that the new architecture would break the free tier's latency budget
• Codex caught a race condition in the proposed caching layer that the Claude-family agents missed entirely

Result: 5 proposals from the original plan were killed based on combined findings. The final plan was significantly different (and better) than what went in.

A different model family catches different bugs. Claude-family agents are the primary quality controls, but they share blind spots — same training, same tendencies.

• Codex is strong on: universal engineering — security patterns, race conditions, architecture anti-patterns, OWASP-style vulnerability detection
• Codex is weak on: Ceeya-specific patterns — DI conventions, shared types, safety gate ordering, knowledge base rules
• The combination is greater than either alone: Claude agents know the project deeply. Codex brings fresh eyes from a different perspective.
• Graceful degradation: if Codex is rate-limited or unavailable, continue without it. Never blocks the pipeline. The review degrades to dual-Claude, which is still valuable.

What it does: Runs .claude/hooks/session-start.sh — a proper shell script (not an inline command) that performs 4 functions:

1. Resets edit counters — zeroes both Swift-specific and universal counters so they don't carry over from previous sessions
2. Injects mandatory file read list — lists ALL 10 files (8 knowledge + handoff + guardian-config) with the instruction "MANDATORY BEFORE RESPONDING: Read ALL of these files now. Do not skip any." This enters the conversation as context the model received, not as a system prompt instruction it can deprioritize.
3. Injects git state — current branch, number of unpushed commits from previous sessions (with warning), uncommitted files. The model knows immediately if there's unfinished work.
4. Lists active plans — shows existing plan files so the model checks for an existing plan before creating a duplicate.
5. Injects This Week's Focus — from guardian-config.md, so every session starts aligned with current priorities.

Why a script file: The original version was a 200-character inline command with fragile JSON escaping. Extracting to a proper script means it's readable, testable (bash .claude/hooks/session-start.sh), and easy to extend.

Why this matters: The model was skipping knowledge files it didn't think were relevant. The SessionStart hook injects the file list as conversational context positioned right before the user's message, which gets high recency attention. The same instruction at line 289 of a 716-line system prompt was competing with 715 other lines for attention.

# .claude/hooks/session-start.sh (excerpt)
# 1. Mandatory file reads
CONTEXT+="MANDATORY BEFORE RESPONDING: Read ALL of these files now.\n"
for f in .ceeya/knowledge/*.md .ceeya/handoff.md .ceeya/guardian-config.md; do
  [ -f "$f" ] && CONTEXT+="- $f\n"
done

# 2. Git state awareness
UNPUSHED=$(git log origin/"$BRANCH".."$BRANCH" --oneline | wc -l)
[ "$UNPUSHED" -gt 0 ] && CONTEXT+="⚠️ $UNPUSHED unpushed commits\n"

# 3. Active changes
ACTIVE_CHANGES=$(rg -n "^- id:|status: active|status: paused" .ceeya/active-changes.yaml | head)
CONTEXT+="--- Active Changes ---\n$ACTIVE_CHANGES\n"

# Output as Claude Code hook JSON
printf '%s' "$CONTEXT" | jq -Rs '{hookSpecificOutput:
  {hookEventName:"SessionStart",additionalContext:.}}'

What it does: Logs the dispatch timestamp and agent name to .ceeya/_internal/dispatch-log.txt, then injects "This Week's Focus" into every subagent so specialists know current project priorities.

Why command hook: The dispatch log is for observability — tracking which agents get dispatched, how often, and when. The priority injection ensures every specialist knows what the team is focused on, even if the dispatcher forgets to mention it.

# Log dispatch + inject priorities
INPUT=$(cat)
AGENT=$(echo "$INPUT" | jq -r '.agentType // .agent_type // \
  .agentName // .agent_name // "unknown"')
DATE=$(date -u +%Y-%m-%dT%H:%M:%S)
mkdir -p .ceeya/_internal
echo "$DATE | START | $AGENT" >> .ceeya/_internal/dispatch-log.txt
FOCUS=$(sed -n '/## This Week/,/^##/{/^##[^#]/!p;}' \
  .ceeya/guardian-config.md 2>/dev/null | head -5 | tr '\n' ' ')
[ -n "$FOCUS" ] && printf '%s' "$FOCUS" | \
  jq -Rs '{hookSpecificOutput:{hookEventName:"SubagentStart",
    additionalContext:.}}' || true

What it does: Logs the completion timestamp and agent name to the dispatch log. Paired with SubagentStart, this gives us dispatch duration tracking.

# Log completion
INPUT=$(cat)
AGENT=$(echo "$INPUT" | jq -r '.agentType // .agent_type // \
  .agentName // .agent_name // "unknown"')
DATE=$(date -u +%Y-%m-%dT%H:%M:%S)
mkdir -p .ceeya/_internal
echo "$DATE | STOP  | $AGENT" >> .ceeya/_internal/dispatch-log.txt

What it does: When the model reads a file whose name matches safety, allergen, or intolerance, injects a context message suggesting the safety-auditor should be dispatched.

Why command hook: This is a soft nudge (additionalContext, not deny), but it's structural — the model always sees it. A prompt instruction to "remember to dispatch safety-auditor when you read safety files" would be forgotten by line 500.

Edge case: Excludes files in .claude/ directory to avoid triggering on the safety-auditor's own prompt file.

FILE=$(jq -r '.tool_input.file_path // empty')
[ -n "$FILE" ] && echo "$FILE" | \
  grep -qiE '/(safety|allergen|intolerance)[^/]*\.' && \
  ! echo "$FILE" | grep -q '.claude/' && \
  echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse",
    "additionalContext":"This is safety-critical code.
    Consider dispatching safety-auditor for specialist audit."}}'
|| true

What it does: Intercepts any git push command. Extracts the target branch. If the target is staging, prod, production, main, or master, returns a hard permissionDecision: "deny". The model cannot override this.

Why command hook: This is the most important hook. A prompt instruction saying "never push to staging" will eventually be ignored under pressure. A deny hook physically prevents it.

CMD=$(jq -r '.tool_input.command // empty')
echo "$CMD" | grep -qE 'git\s+push' || exit 0

# Extract target branch — handles flags like -f, --force
TARGET=$(echo "$CMD" | grep -oE \
  'git\s+push\s+(-[a-zA-Z]+\s+)*[^\s]+\s+([^\s]+)' \
  | awk '{print $NF}')
# Fallback: if no explicit target, check current branch
[ -z "$TARGET" ] && TARGET=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)

echo "$TARGET" | grep -qiE '^(staging|prod|production|main|master)$' \
  && echo '{"hookSpecificOutput":{"permissionDecision":"deny",
    "permissionDecisionReason":"Blocked: pushing to protected
    branch '"$TARGET"'. Use a PR instead."}}'

What it does: After any edit or write to a TypeScript file in packages/shared/src/ or apps/api/src/, scans for .ts import extensions. ES modules require .js extensions even for TypeScript files — using .ts causes runtime failures.

Why command hook: This is the most commonly violated convention. The model's training data is full of .ts imports. Without structural enforcement, it reverts to old habits every few sessions.

FILE=$(jq -r '.tool_input.file_path // empty')
[ -n "$FILE" ] && echo "$FILE" | \
  grep -q 'packages/shared/src/\|apps/api/src/' && \
  grep -n "from ['\"].*\.ts['\"]" "$FILE" 2>/dev/null && \
  echo 'WARNING: .ts import extension detected.
  Use .js extensions for ES module imports.' && exit 2
|| exit 0

Exit code 2: Non-zero exit tells Claude Code the hook found a problem. The model sees the warning and fixes it before moving on.

What it does: Counts Swift file edits using /tmp/ceeya-swift-edits. At 5 edits, resets the counter and injects a message: "5+ iOS files modified — build checkpoint. Run a build, commit progress, and spot-check your last fix for root-cause vs symptom."

Why 5? After testing, 5 Swift edits without a build is the point where accumulated errors become expensive to debug. Earlier is wasteful, later risks compounding mistakes.

FILE=$(cat | jq -r '.tool_input.file_path // empty')
[ -n "$FILE" ] && echo "$FILE" | grep -qE '\.swift$' && \
  echo "$FILE" | grep -q 'apps/ios/' && \
  COUNT=$(cat /tmp/ceeya-swift-edits 2>/dev/null || echo 0) && \
  COUNT=$((COUNT + 1)) && echo $COUNT > /tmp/ceeya-swift-edits && \
  [ $COUNT -ge 5 ] && echo 0 > /tmp/ceeya-swift-edits && \
  echo '{"hookSpecificOutput":{"additionalContext":
    "5+ iOS files modified — build checkpoint.
    Run a build, commit progress, and spot-check
    your last fix for root-cause vs symptom."}}'
|| true

What it does: After any edit to a .swift file under apps/ios/Ceeya/, runs xcodegen generate --quiet asynchronously to keep the Xcode project in sync with the file system.

Why async: XcodeGen takes ~2 seconds. Running it synchronously would block every Swift edit. The async: true flag lets it run in the background while the model continues working.

Edge case: Uses --quiet to suppress output. Failures are silently ignored (; true) because XcodeGen failures are noisy but non-blocking — the Xcode project just stays slightly stale until the next edit.

cat | jq -r '.tool_input.file_path // empty' | \
  grep -qE 'apps/ios/Ceeya/.*[.]swift$' && \
  cd apps/ios/Ceeya && xcodegen generate --quiet 2>/dev/null
; true

Configuration: "statusMessage": "Syncing Xcode project...", "timeout": 15, "async": true

What it does: Counts ALL file edits (not just Swift) using /tmp/ceeya-all-edits. Every 5 edits, injects: "N files modified this session. Commit your progress now."

Why: The git workflow rule says "If you've modified 3+ files without committing — stop and commit NOW." But the model loses track during long implementations. This hook provides the external reminder at a slightly generous cadence (5, not 3) to avoid excessive interruptions.

COUNT=$(cat /tmp/ceeya-all-edits 2>/dev/null || echo 0)
COUNT=$((COUNT + 1))
echo $COUNT > /tmp/ceeya-all-edits
[ $((COUNT % 5)) -eq 0 ] && [ $COUNT -gt 0 ] && \
  echo '{"hookSpecificOutput":{"additionalContext":
    "'$COUNT' files modified this session.
    Commit your progress now."}}'
|| true

What it does: Before Claude Code compacts the conversation (reducing context window), saves the current branch name and list of uncommitted files to .ceeya/_internal/compaction-log.txt, then injects this state as additional context so the model knows what it was working on.

Why this matters: Compaction erases working memory. Without this hook, the model loses track of what files it was editing and what branch it's on. The injection ensures continuity across compaction events.

DATE=$(date -u +%Y-%m-%dT%H:%M:%S)
BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo 'unknown')
CHANGED=$(git diff --name-only 2>/dev/null | head -10 | tr '\n' ', ')
mkdir -p .ceeya/_internal
echo "=== COMPACTION $DATE on $BRANCH === uncommitted: $CHANGED" \
  >> .ceeya/_internal/compaction-log.txt
printf 'Pre-compaction state: branch=%s, uncommitted: %s' \
  "$BRANCH" "$CHANGED" | \
  jq -Rs '{hookSpecificOutput:{hookEventName:"PreCompact",
    additionalContext:.}}'

Total: 1,305 lines of domain knowledge loaded by the orchestrator at session start.

Rules files are auto-loaded by Claude Code when a file matching the path pattern is read or edited. They are terse checklists, not comprehensive references.

Total: 180 lines — deliberately sparse. Every word has to earn its place because these are always-on context.

Not all corrections stay as memory files. When a correction proves universal — it applies broadly, not just to one situation — it gets promoted:

1. Memory file (initial capture) — agent reads it at session start. Cheapest to create, narrowest scope.
2. Knowledge file (pattern proven) — becomes part of the reference all agents can access. Correction has been validated across multiple situations.
3. Agent system prompt (architectural) — becomes a hard rule in the orchestrator or specialist. The correction is fundamental to how the agent should think.
4. Hook (structural) — becomes a deterministic enforcement that can't be forgotten. The correction was so critical that behavioral enforcement isn't enough.

Real promotions: Several corrections were so important they got promoted from memory into the agent prompt itself. The MEMORY.md index file tracks which feedback has been incorporated into higher layers:

• "Consumer language" → promoted to knowledge/conventions.md terminology table
• "Structured data over prose" → promoted to knowledge/conventions.md + knowledge/backend.md
• "User as final authority, constant checkpoints" → promoted to agent User Communication section
• "Calibrated dispatch (not all-or-nothing)" → promoted to agent 3-Tier dispatch system
• "Skills maximization" → promoted to agent Skills table (22 skills with triggers)

The point isn't the specific architecture. It's the process:

• You don't need to design the system upfront. Start with CLAUDE.md. When something breaks, add the fix at the right layer.
• Every layer exists for a reason. If you can't explain what failure mode a piece prevents, it probably shouldn't exist.
• The AI is your collaborator, not your executor. Tell it what's wrong. It will often propose the structural fix — a hook, an agent, a memory file — better than you would.
• Corrections are the most valuable input. Every time you correct the AI, that's a rule waiting to be written. The memory system captures these automatically.
• Read the source. Claude Code is open source. The features in the docs are a fraction of what's available. criticalSystemReminder_EXPERIMENTAL, omitClaudeMd, hook event types, agent frontmatter fields — all found by reading the code.