0. Why This Happened

The goal was simple: build a family app for the kids - to help with school, plan things, have fun - and to explore the new world of AI-assisted coding. The background is backend & data engineer/enterprise architect, so frontend was learned along the way.

Below are the learnings and workflow that emerged. This is an ever-evolving subject, still being optimised. Shared memory systems across agents are the current investigation - watch this space.

1. The Setup: Multiple Agents, One Human

The most distinctive part of the workflow is running multiple AI agents in parallel, with separated roles.

Claude Code (“Ralph”) - The Reviewer Ralph is the Claude Code instance running locally in the IDE. The role is reviewer and senior architect, not code generator. Ralph reads the entire project context at session start, plans before executing, and maintains documentation with the same discipline as code. For reviews, Ralph delegates to three specialist sub-agents - more on this in Section 7.

Builder Agents - The Developers The architecture is designed for multiple builder agents working in parallel on different streams of work. Each runs on a VPS, accessible via Telegram and SSH, with full repo access to implement features and push branches.

Currently there’s one builder agent installed - Chiron, named after the centaur mentor from Greek mythology, running 24/7 on a VPS. The plan is to scale to multiple builders, each handling a separate work stream concurrently, all feeding into the same review process.

The Workflow Builders build. Ralph reviews.

  1. A plan/brief goes into a docs/plans/ directory with requirements, constraints, and which shared patterns to use.
  2. A builder agent reads the brief, implements the feature, and pushes a branch. With multiple builders, different briefs go to different agents working in parallel.
  3. Ralph reviews the branch against the project’s architecture principles, SSOT rules, and code quality standards.
  4. Ralph identifies issues, fixes them directly, and writes findings.
  5. Ralph writes learnings back to the builders via plan files and memory documents, so they can improve.
  6. Builders incorporate feedback in future work.

The Key Learning Implicit knowledge doesn’t transfer between agents. When the builder agent consistently produced Tailwind v3 patterns (the project uses v4), Ralph was tasked with creating a persistent lessons-learned document as a reference. This problem compounds with multiple builders - the documented standards become even more critical because no agent knows what any other agent knows.

Boundaries

  • Ralph is the reviewer, not the VPS operator. Read-only SSH to inspect builder work, no file modifications on builder VPS instances unless explicitly asked.
  • Builder agents have full access to the GitHub repos.
  • The human orchestrates task assignment - no agent self-assigns work. This becomes critical with multiple builders to avoid merge conflicts and overlapping work streams.

2. The Session Protocol

Every session follows a structured protocol. Not optional - mandatory.

Session Startup (Every Time, Including After Context Reset)

  • Read context files IN ORDER - not skimmed, fully read
  • Check for active work - Scan docs/plans/ for files with status: in-progress or status: paused. If paused work exists, surface it.
  • Confirm context - Brief summary of current phase, any active work found, and what’s ready to work on.

Task Triage

ComplexityExamplesProtocol
TrivialTypo fix, comment updateJust do it, no ceremony
SmallSingle-file bug fixBrief note in WORK_TRACKER.md
MediumMulti-file change, new componentDiscuss plan in chat, then execute
LargeArchitectural change, new systemFull plan file in docs/plans/, wait for approval

Default to lower ceremony. Escalate if complexity is discovered mid-task.

Planning Phase For non-trivial work:

  1. Enter Plan Mode explicitly
  2. Explore the codebase - Glob, Grep, Read
  3. Design the implementation approach
  4. Write the plan to docs/plans/YYYY-MM-DD_[brief-description].md
  5. Exit Plan Mode and wait for approval
  6. Only then write code

When to Ask vs. When to Execute

  • ASK before: New work, architectural decisions, shortcuts, anything not in the approved plan
  • EXECUTE without asking: Steps within an approved plan, routine implementation following established patterns
  • ALWAYS STOP: If about to take a shortcut, if duplication spotted, if something is more complex than planned

Pausing Work If work must be paused mid-session:

  1. Update the plan file with a ## Paused section (where stopped, what remains, context to resume)
  2. Set status: paused in frontmatter
  3. Next session detects this automatically

End of Session

  1. Run pnpm lint && pnpm build - verify clean
  2. Update plan file with current status
  3. Add session notes to WORK_TRACKER.md
  4. Create daily summary in docs/progress_updates/ if significant work done
  5. Update CURRENT_FOCUS.md if priorities changed

3. The One Rule: Single Source of Truth

SSOT is the non-negotiable principle. It overrides everything else.

What It Means in Practice Before writing ANY code:

  1. STOP if about to copy-paste - extract to shared instead
  2. Search before creating - check if a component/pattern exists
  3. Extend, don’t duplicate - add props to existing components
  4. Scope ALL CSS - every selector prefixed with component’s root class

The Golden Rule Test “If I need to fix a bug in this code, how many files do I need to change?” Answer should be 1. If more, you’re duplicating. “If I need to change button styling, how many files do I need to edit?” Answer should be 1. If more, you’re duplicating design.

Why This Matters So Much with AI The #1 source of bugs in the codebase has been duplicated code - both logic and design. AI agents are naturally inclined to generate self-contained solutions. They’ll happily create a new feedback overlay instead of using the shared one. They’ll write a new utility function instead of finding the existing one. SSOT has to be enforced through documentation, checklists, and review - it doesn’t happen naturally.

4. The Documentation System

The project maintains an unusually thorough documentation system. Every type of knowledge has a canonical home.

Why So Much Documentation? AI sessions are stateless. Every new conversation starts from zero. The documentation system preserves institutional knowledge across sessions. Without it, every session wastes time rediscovering decisions, understanding architecture, and relearning patterns.

The key insight: documentation is infrastructure, not ceremony. It directly reduces bugs, prevents wasted effort, and maintains velocity across hundreds of sessions.

What Gets Documented

  • Core principles - Non-negotiable rules. Read every session.
  • Working style - Communication preferences and expectations. Read every session.
  • Session protocol - Workflow rules. Read every session.
  • Project context - Architecture, tech stack. Read every session.
  • Current focus - Dynamic status. Read every session.
  • Design guidelines - Visual design system. Read before UI work.
  • Activity design system - UI patterns, CSS. Read before UI work.
  • Data architecture - Types, stores, hooks. Read before logic work.
  • Work tracker - Full task history (1000+ lines). On-demand.
  • Plan files - Execution plans with status tracking. Referenced during planned work.
  • Progress updates - Daily/phase summaries. Referenced for continuity.
  • Bug reports - Issues with root cause analysis. Referenced when relevant.

The Feedback Loop When a bug traces back to a pattern violation, the bug isn’t just fixed. The documentation is updated to prevent the class of bug. The check gets added to the pre-implementation checklist. The next session reads that checklist before writing code. The documentation system is self-improving.

5. How Decisions Get Made

The Decision Framework

  • Comfortable with incomplete information - don’t over-research reversible decisions
  • Think in risk-reward terms, not certainty percentages
  • Higher risk tolerance for reversible decisions; more caution for irreversible ones
  • No sunk cost fallacy - if something isn’t working, change course

What the AI Should Do

  • Present trade-offs, not binary choices
  • Challenge assumptions constructively - “this approach has X downside” not just “here are your options”
  • Once a plan is approved, execute with confidence - don’t relitigate
  • If genuinely uncertain, say so plainly
  • If a problem is spotted with the approved plan, raise it immediately

The “Never Defer” Rule Once work is planned and approved, the AI does NOT have authority to mark items as “deferred”, skip steps, decide something “can be done later”, or reduce scope without explicit approval.

If there’s a reason not to complete planned work: STOP, explain the issue clearly, ASK about adjusting scope, and WAIT for the decision.

This rule exists because AI agents will silently optimise for what seems most important. They’ll quietly drop item 7 of a 10-item plan because it seemed less critical. They have to be explicitly told they can’t do this.

6. Quality Bar

“Done” in this project means all of these:

  1. Code follows established patterns (checked against design system docs)
  2. No duplication introduced
  3. Existing violations fixed if the code was touched
  4. Tests pass, lint passes, build passes (pnpm lint && pnpm build)
  5. Documentation updated if patterns changed

“It works” is NOT sufficient. “It works AND it’s maintainable AND it follows established patterns” is the bar.

Pre-Implementation Checklist Before writing any UI code, the AI must:

  1. Read the design system documents
  2. Identify a reference implementation similar to what’s being built
  3. List all shared patterns that will be used
  4. Report: “I’ll use [patterns X, Y, Z]. Reference: [name]. New patterns needed: [list or none].”

This checklist has prevented more architectural violations than any automated check.

7. The Review Sub-Agents

Ralph doesn’t review alone. The review process is broken into three specialist perspectives, each implemented as a Claude Code sub-agent with its own persona, methodology, and output format.

The Security Specialist Persona: a security engineer with 15+ years in application security. Thinks like an attacker, advises like a defender. Runs structured reconnaissance and vulnerability analysis: mapping entry points, identifying trust boundaries, tracing sensitive data flows, checking authentication and authorisation, reviewing secrets management. Follows OWASP Top 10 checks adapted for the tech stack. Output classified by severity (Critical → High → Medium → Low → Informational).

The System Architect Persona: a senior system architect with 20+ years designing large-scale applications. Examines directory organisation, module boundaries, dependency flow, and layering. Checks whether dependencies flow inward, looks for circular dependencies, verifies barrel files, assesses structural scalability. For a TypeScript monorepo: package boundaries, shared package isolation, type organisation, configuration centralisation.

The Senior Engineer Persona: a senior software engineer with 15+ years of hands-on development. Focuses on implementation quality: readability, maintainability, pattern consistency, error handling, edge cases, performance, testability. Checks for unsafe any usage, unnecessary type assertions, anti-patterns that cause real pain - floating promises, missing error boundaries, N+1 patterns, memory leaks, inconsistent error handling.

How They Work Together Each sub-agent writes a structured review report to docs/reviews/. Ralph orchestrates which agents run based on the nature of the change. This mirrors how review works in mature engineering organisations: code review, architecture review, and security review are separate disciplines. The sub-agent model replicates this with AI.

8. Communication Style That Works

What Works

  • Direct and technical. Assume high competence.
  • Rationale for decisions - not just “use X” but “use X because Y”.
  • Being challenged constructively. No yes-man behaviour.
  • Backend analogies when explaining frontend concepts: “Zustand selectors are like SQL projections - you only subscribe to the fields you need.”
  • Risks vs benefits framing, not arbitrary confidence percentages.

What Doesn’t Work

  • Over-simplification or patronising tone
  • Excessive verbosity or hedging
  • Making assumptions instead of asking clearly
  • Silent shortcuts. If something is hard, say so - don’t silently simplify.

9. What Got Built (The Numbers)

In roughly one month, with this workflow:

  • ~81,000 lines of code across 279 source files
  • Monorepo with 4 shared packages and 2 apps
  • 70+ interactive activities across 11 topics
  • 625 unit tests + ~46 end-to-end tests
  • 3 accessibility themes (default, colorblind, high-contrast)
  • Age bands with CSS-only UI adaptation
  • Full TypeScript (migrated from JavaScript mid-project)
  • CI/CD pipeline with lint, type-check, test, build, and e2e stages

Tech stack: React 18, Vite, Tailwind CSS v4, Zustand, TypeScript (strict), Vitest, Playwright, pnpm workspaces + Turborepo, GitHub Actions.

10. The Project’s Evolution

Week 1: Monorepo setup, TypeScript migration of 194 files, package extraction, state management migration (Context → Zustand), design system rationalisation Week 2: Testing infrastructure (625 tests), content, activity design system docs, bug tracking system Week 3: Major code quality remediation (8 work streams, 29 findings), new activities Week 4: Second app integrated into monorepo, multi-agent workflow validated, AI tutor feasibility research, design uplift

The key pattern: the first two weeks were architecture and infrastructure, not features. Every feature built after that point was easier, faster, and less bug-prone because the foundations were solid.

11. Key Architectural Decisions

LocalStorage over Cloud Sync — Client-side only. No cross-device sync. Deferred until content justifies infrastructure investment. Store architecture designed to swap storage backends.

Data-Driven Activity Registry — Single registry file defining all 70+ activities. Eliminated ~70 thin page wrapper files. Adding a new activity is a 10-line registry entry.

CSS Variables over Pure Tailwind for Theming — Runtime theme switching requires CSS variables. Tailwind utilities are compile-time. Hybrid approach: Tailwind for layout, CSS variables for colour/spacing tokens.

Zustand over React Context — Three Zustand stores replacing three React Contexts. Selector-based subscriptions give granular reactivity. Persist middleware handles localStorage with schema versioning.

TypeScript Migration Before More Content — Full migration of 194 files before building more content. Branded ID types catch entire categories of bugs at compile time.

Monorepo from Day One — pnpm workspaces + Turborepo before the second app existed. When the second app was built, it immediately benefited from all shared infrastructure.

12. Lessons Learned

  1. SSOT prevents more bugs than testing. The pre-implementation checklist has been more effective than automated tests at preventing architectural violations.
  2. Documentation is infrastructure. Without context files, each AI session wastes significant time rediscovering architecture and conventions.
  3. Implicit knowledge doesn’t transfer between agents. Everything must be written down explicitly. This compounds with every additional agent added.
  4. Invest in foundations before content. Architecture, typing, design system, and testing happened before scaling up features.
  5. Schema migrations are essential for client-side apps. Client-side apps must handle data from any previous version appearing at any time.
  6. Features should be thin. The ideal feature component defines its unique logic and calls shared infrastructure for everything else.
  7. Pre-commit checks aren’t enough. The real prevention happens at the start - reading docs, identifying patterns, reporting the plan before writing code.
  8. The multi-agent model needs explicit standards. AI agents don’t share context. Document the standards where all of them can read them.
  9. AI agents will silently simplify. If something is hard, they’ll quietly reduce scope rather than flag it. The “Never Defer” rule exists because this was caught happening multiple times.
  10. The human is the architect, the agents are implementers. Direction, standards, and priorities come from the human. Neither agent self-assigns work.

13. What Makes This Workflow Different

Documentation-Driven AI Development — Treat Claude Code as a junior architect who must be properly briefed, given clear standards, and held to a quality bar. The documentation is the mechanism that makes stateless AI sessions productive.

Multi-Agent Architecture — Building separated from reviewing. Builder agents implement in parallel; a reviewer agent checks everything against the project’s standards. Currently running one builder, designed for many.

Architecture-First Thinking — Architectural correctness prioritised over velocity. Foundations before features.

Real Users from Day One — The app gets used daily by real users. Accessibility requirements are non-negotiable because the primary users need them.

Evolving Quality Bar — Each bug or quality issue leads to a systemic improvement, not just a point fix.

What’s Next

The current investigation is shared memory systems across AI agents - the ability for multiple AI assistants to maintain persistent, shared context about a project. Solving this unlocks scaling from one builder agent to several, each handling a different work stream in parallel, all feeding into one review process with shared institutional knowledge.

Georgios Antikatzidis is a Principal Enterprise Architect with 25+ years of building Data & AI platforms in financial services. He builds things with AI in his spare time.