Agentic Engineering

Agentic Engineering

Design tasks so AI agents can execute them reliably. This is not about using Copilot features — it is about architecting work so agents succeed on the first attempt, fail loudly when they can't, and hand off cleanly to the next agent.

Why This is Copilot-Exclusive

The patterns here are specific to Copilot CLI's agent execution model: task() dispatch, read_agent / write_agent lifecycle, SQL session state, and background agents with mode: "background". They don't map directly to interactive coding sessions in other tools.

When to Use

• Decomposing a large task before dispatching it to an agent or fleet
• Designing a multi-agent workflow where context must transfer between agents
• Debugging why an agent produced incorrect or incomplete output
• Establishing quality standards for a new agentic workflow

When NOT to Use

Core Principles

1. The 15-Minute Task Unit

Rule: Each agent dispatch should complete in roughly 15 minutes of human-equivalent focused work. In practice: 1–3 files changed, 1 clear outcome, no more than one decision required.

Why: Agents fail when context exceeds what fits in a single focused pass. Long tasks require the agent to hold too much state, make too many decisions, and produce outputs that are hard to verify.

Signs a task is too large:

• Description contains "and" more than twice
• Requires reading more than 5 files to complete
• Has more than one possible success state
• Cannot be verified by a single test or check

Signs a task is too small:

• It is just a file read or a lookup
• A single edit call handles it entirely
• No judgment is required

Decomposition pattern:

Large task: "Implement user authentication with JWT and refresh tokens"
↓ decompose
T-01: Add User schema + bcrypt password field (DB layer only)
T-02: Implement POST /auth/login endpoint (validate + sign JWT)
T-03: Implement POST /auth/refresh endpoint (validate refresh token)
T-04: Add auth middleware (extract + verify JWT on protected routes)
T-05: Integration tests for T-02, T-03, T-04

Each task has one clear output that can be verified independently.

2. Eval-First Loop

Rule: Define the verification criterion before dispatching the agent, not after.

Why: Agents optimized toward a concrete pass/fail signal produce more correct output than agents working toward a vague goal. The verification criterion is the specification.

❌ Vague:
"Implement the export function and make sure it works."

✅ Eval-first:
"Implement the export function.
 Verification: `npm test -- export.test.ts` must pass with 0 failures.
 If tests don't exist, write them first (AC: returns valid CSV for valid input,
 returns 422 for invalid date range, returns empty CSV for empty result set)."

Pattern in SQL:

INSERT INTO todos (id, title, description) VALUES
  ('impl-export', 'Implement CSV export', 
   'Write src/services/export.ts. Verified by: npm test -- export.test.ts (all pass). If tests absent, write tests first.');

3. Explicit Input/Output Contracts

Rule: Every agent task must have a declared input and a declared output. Never rely on implicit context from the conversation history.

Why: Background agents start with no conversation history. Fleet agents run in isolated contexts. Agents that assume they "remember" previous turns produce inconsistent results.

Input contract — what the agent needs to start:

• Exact file paths to read
• Specific values to use (not "use the same approach as before")
• SQL queries to run for current state

Output contract — what the agent produces:

• Files created or modified (exact paths)
• SQL rows inserted or updated
• Return value if used as a sub-agent

# Weak (implicit):
"Continue implementing the auth system."

# Strong (explicit contract):
Input: src/auth/schema.ts (exists), src/auth/middleware.ts (does not exist yet)
Task: Create src/auth/middleware.ts that reads JWT from Authorization header,
      verifies with the secret in process.env.JWT_SECRET, attaches user to req.user.
Output: src/auth/middleware.ts created; exports verifyToken middleware function.
Verification: npm test -- auth.middleware.test.ts

4. Prefer Built-In Composition Over Wrapper Skills

Rule: When the platform can programmatically call an existing built-in workflow, reuse that primitive instead of inventing a thin wrapper file around it.

Why: Built-ins already carry user expectations, maintenance, and platform-native behavior. Duplicating them as near-identical local artifacts adds drift without adding capability.

Design handoffs around the real primitive:

Goal: review the finished change before merge

Weak:
"After implementation, use our custom review wrapper and then summarize it."

Stronger:
"After implementation, trigger the platform's built-in review step, then return BLOCKER /
CONCERN / PASS findings plus the next action."

When translating upstream patterns, this is often an adapt rather than an adopt signal. For example, Claude Code v2.1.108+ can chain built-in commands such as /review, /security-review, or /init through its Skill tool. In Copilot CLI, preserve that composition intent by calling the existing built-in command explicitly or routing to the closest existing skill or agent flow rather than creating a redundant new skill.

5. Fail Fast, Surface Errors Early

Rule: Agents should stop and surface uncertainty rather than guess and continue.

Why: An agent that guesses wrong halfway through a task produces partial, hard-to-revert changes. An agent that stops early saves time.

Configure via prompt:

If you are uncertain about the expected behavior, stop and surface the question
as a BLOCKER rather than making an assumption and continuing.
Format: BLOCKER: [question] [what you would assume if forced to continue]

6. State via SQL, Not Session Memory

Rule: Workflow state must live in SQL, not the agent's conversation memory.

Why: Agents compact, context windows expire, background agents start fresh. SQL state is persistent, queryable, and explicit.

-- Track multi-agent workflow state
CREATE TABLE IF NOT EXISTS workflow_state (
    step TEXT PRIMARY KEY,
    status TEXT DEFAULT 'pending',
    output TEXT,
    agent_id TEXT,
    completed_at TEXT
);

-- Agent reads its input from SQL, not conversation history
SELECT output FROM workflow_state WHERE step = 'schema-design' AND status = 'done';

Workflow: Decompose a Task for Agent Dispatch

1. State the outcome — one sentence: what exists when done?
2. Identify the smallest completable unit — can it be done in 15 min?
3. Define the verification criterion — what test/check proves it?
4. Write the input contract — what files/values does the agent need?
5. Write the output contract — what does the agent produce?
6. Insert into SQL — description must include verification criterion

INSERT INTO todos (id, title, description) VALUES
  ('auth-middleware', 
   'Create auth middleware',
   'Input: src/auth/schema.ts (read). 
    Task: Create src/auth/middleware.ts, export verifyToken function.
    Output: src/auth/middleware.ts created.
    Verification: npm test -- auth.middleware.test.ts (all pass).');

Task Decomposition Checklist

Before dispatching an agent task, confirm:

• Task completes in ~15 min (1–3 files, 1 outcome)
• Verification criterion is explicit and runnable
• Input files/values are named explicitly (no "use the context from before")
• Output artifacts are specified (exact paths or SQL rows)
• Failure mode is defined (what to do if verification fails)
• State needed across agents is in SQL, not assumed from conversation

Anti-Patterns

See Also

• plan-mode-mastery — structuring plans for Copilot execution
• team-planner — dispatching multi-agent specialist teams
• autopilot-patterns — safe autonomous execution patterns
• eval-harness — evaluation framework for LLM pipelines
• product-capability — engineering-ready capability specs with ACs