AI Coworker Development Principles

Status: Foundational specification Created: 2026-03-31 Authors: Mark Bodman, Claude (Software Engineer) References: Diversity of Thought Framework, IT4IT v3.0.1, EP-BUILD-HANDOFF spec

Purpose

This document defines the architectural principles for developing AI Coworker agents within the Digital Product Factory. It is the governing specification for all future agent design, tool assignment, memory strategy, and multi-agent orchestration.

These principles are derived from production testing, industry framework research (Anthropic Agent SDK, OpenAI Agents SDK, LangGraph, CrewAI, AutoGen), and the platform’s Diversity of Thought framework.

Principle 1: Specialization Over Generalization

A specialist with 5 focused tools outperforms a generalist with 40.

Rule

Each AI Coworker agent should have access to no more than 10 tools relevant to its current task. When tool count exceeds 15, tool selection accuracy degrades significantly, regardless of model capability.

Implementation

Tools are tagged with the phases and contexts in which they are relevant. The platform filters the tool list before each agent invocation, presenting only the tools the agent needs for its current role.

type ToolDefinition = {
  name: string;
  buildPhases?: BuildPhaseTag[];  // Only available during these phases
  // ... other fields
};

Evidence

• Haiku with 40+ tools entered repetition loops calling wrong tools
• Haiku with 5-9 phase-filtered tools correctly generated code and called sandbox tools
• Industry consensus (Azure, Redis, all major frameworks): 3-5 tools per specialist is optimal

Principle 2: Orchestrator-Worker Pattern

A coordinator routes work to specialists. Specialists do not route to each other.

Rule

Multi-step workflows use a hierarchical orchestrator-worker pattern. The build pipeline acts as the orchestrator, dispatching each phase to the appropriate specialist agent. Agents do not hand off directly to each other — the orchestrator mediates all transitions.

Implementation

Each build phase maps to a specialist agent:

Rationale

• Simple phases (ideate, plan, review, ship) are deterministic workflows that smaller models handle well
• The build phase requires complex multi-step tool reasoning and code generation — it needs a stronger model
• This matches the industry pattern: cheap models for routing, expensive models for complex reasoning
• Token budget is 3-4x lower per call, enabling more iterations within rate limits

Principle 3: Structured Handoffs, Not Conversation History

Pass decisions and context, not transcripts.

Rule

When work transitions between agents (or between phases), the outgoing agent produces a structured handoff document. The incoming agent reads only this document — never the raw conversation history from the previous phase.

Implementation

interface PhaseHandoff {
  fromPhase: BuildPhase;
  toPhase: BuildPhase;
  summary: string;              // 2-3 sentences, plain language
  evidence: Record<string, unknown>;  // Phase-specific artifacts
  openIssues: string[];         // What the next agent should know
  userPreferences: string[];    // Decisions the user made
}

Rationale

• Raw conversation history wastes tokens on irrelevant context (ideate discussion during build phase)
• Structured handoffs capture what matters: decisions, evidence, and user intent
• Each agent starts with a clean context window focused on its task
• Token reduction: ~16K per call → ~4K per call (3-4x improvement)

Principle 4: Diversity of Thought in Agent Design

Different agents should think differently, not just have different tools.

Rule

Each agent’s system prompt defines three cognitive components from the Diversity of Thought framework:

Implementation

Agent system prompts explicitly declare their perspective, heuristics, and success criteria. This is not decorative — it determines which solutions the agent considers and which it misses.

When a complex problem requires multiple perspectives (a rugged landscape in Diversity of Thought terms), the orchestrator consults multiple specialists before deciding. The combined output exceeds what any single agent would produce.

Rationale

• A team of diverse “good enough” agents outperforms a single “best” agent on complex problems
• Different perspectives reveal different solution peaks
• The IT4IT value streams already define distinct roles with different optimization targets
• This prevents the failure mode where every agent gives the same generic answer

Principle 5: Selective Memory, Not Total Recall

Remember decisions and rationale. Re-derive details from source.

Rule

The vector database (Qdrant) stores salient context — decisions, user preferences, design rationale, and cross-conversation insights. It does not store raw conversation transcripts, code content, or data that can be derived from the codebase or git history.

What to Store

What NOT to Store

Implementation

Each agent stores memories at natural decision points — not after every exchange. The memory is tagged with the agent role, build phase, and topic so retrieval is contextual.

Semantic recall uses the query context (current conversation + build phase) to retrieve the 5-8 most relevant memories. This is sufficient because memories are distilled to decisions and rationale, not raw detail.

Rationale

• Token efficiency: memories should be dense (high information per token)
• Retrieval quality: fewer, more relevant memories beat many marginally relevant ones
• The details are always available from primary sources (codebase, git, database)
• Memory serves as an index into knowledge, not a copy of it

Principle 6: Tools Must Be Self-Documenting

If the model can’t understand a tool from its schema, the schema is wrong.

Rule

Every tool definition includes:

• A description that explains what it does and when to use it
• Parameter descriptions with types, examples, and constraints
• Required parameters clearly marked

The build phase system prompt includes a tool usage guide that maps common tasks to specific tools with parameter examples.

Implementation

TOOL GUIDE:
- To create a new file: write_sandbox_file(path, content) — content is the FULL file
- To modify existing file: read first, then edit_sandbox_file(path, old_text, new_text)
- To run commands: run_sandbox_command(command)

Rationale

• Smaller models (Haiku) rely heavily on description quality for tool selection
• A model that sees write_sandbox_file with content: "The full file content to write" knows to pass the entire file
• A model that sees only content: string may omit it or pass a description instead
• This is the difference between a tool call succeeding and entering a retry loop

Principle 7: Human-in-the-Loop at Phase Boundaries

The human approves transitions, not individual tool calls.

Rule

Human approval gates exist at phase boundaries (ideate → plan, plan → build, review → ship), not at individual tool calls within a phase. Within a phase, the agent operates autonomously using its scoped tools.

Exception: executionMode: "proposal" tools present a card for approval before executing side effects that affect production (deploying to production, registering products, modifying user data).

Implementation

• Phase transitions require the agent to save evidence and pass a quality gate
• Quality gates are deterministic checks (design review required, tests must pass)
• The human sees a summary and approves/rejects/requests changes
• Within a phase, the agent calls tools freely without per-call approval

Rationale

• Per-call approval breaks the agent’s reasoning flow and wastes the user’s time
• Phase-boundary approval gives the human meaningful decision points
• Proposal tools handle the exceptions where individual actions need approval
• This matches the IT4IT value stream gate model

Principle 8: Fail Fast, Explain Clearly

Stop on the first error. Don’t retry blindly. Tell the user what happened.

Rule

When a tool call fails, the agent should:

1. Report the error in plain language
2. Explain what it was trying to do
3. Suggest what the user can do (if applicable)
4. Stop — do not retry the same call with the same arguments

The agentic loop enforces a tool repetition limit (3-5 calls of the same tool). This is a safety net, not a feature — agents should not need it if they handle errors correctly.

Rationale

• Blind retries waste tokens and rate limit budget
• Users need to understand what happened to provide guidance
• The repetition limit exists because smaller models sometimes loop — but well-prompted agents with focused tool sets rarely trigger it

Principle 9: Responsible Capacity Utilization

Use paid AI capacity for governed value, not empty activity.

Rule

AI coworkers should treat available paid capacity as an operating asset. When authorized work is available, idle capacity is waste. When no useful, safe, evidence-producing work is available, the coworker should record or surface the blocker rather than spend tokens to appear busy.

Useful capacity work includes:

• reducing human cognitive load
• advancing approved backlog work
• producing durable work products
• running verification and capturing evidence
• reviewing stale specs, plans, PRs, or runtime state
• identifying capability gaps
• converting repeated work into proceduralization candidates

Implementation

Capacity use should be driven by Standing Orders, calendar/availability state, safe work queues, and existing authority controls. Coworkers may continue low-risk governed work when humans are unavailable, but must stop at approval boundaries for consequential actions.

Rationale

A salaried employee who does nothing while valuable work exists wastes organizational capacity. Fixed-price or subscription AI capacity has the same economic shape. The goal is not to burn tokens. The goal is to convert available capacity into reviewed work, evidence, learning, and platform improvement.

Application

These principles apply to:

• All new agent development in the Build Studio pipeline
• AI Coworker conversations across all platform pages
• Agent tool registration and schema design
• Memory and context management
• Multi-agent orchestration and handoff
• External coding agents working on DPF, including Codex and Claude, through the canonical project rulebook

When these principles conflict with expediency, the principles win. A well-structured agent that works reliably is worth more than a quick hack that fails unpredictably.