Technical Planning Agent

The Technical Planning Agent transforms the Discovery spec into a complete implementation blueprint — TDD, interface contracts, data schema, task graph, machine-readable Zod schemas, and a full parallelism map — all produced in a single pass triggered by !plan.

Planning Output Artifacts

Triggered by !plan. The Planner produces the complete artifact set directly:

Machine-Readable Contract Layer

The Planner emits two contract types that create a ground truth for Builder and Verifier:

Zod Schemas

// artifacts/build/contracts/user.contracts.ts
import { z } from 'zod';

export const UserSchema = z.object({
  id: z.string().cuid(),
  email: z.string().email(),
  role: z.enum(['ADMIN', 'USER']),
  createdAt: z.coerce.date(),
});

export const CreateUserSchema = UserSchema.omit({ id: true, createdAt: true });
export type User = z.infer<typeof UserSchema>;

OpenAPI Stubs

# artifacts/build/contracts/openapi.yaml
openapi: "3.1.0"
info:
  title: "Project API"
  version: "1.0.0"
paths:
  /api/users:
    post:
      operationId: createUser
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateUser' }
      responses:
        "201":
          content:
            application/json:
              schema: { $ref: '#/components/schemas/User' }

Task Schema

Every task in TASK-GRAPH.md follows this schema, including the v3.0 parallelism and checkpoint fields:

### TASK-001: Set up authentication with NextAuth v5
**Status:** PENDING
**Task type:** auth
**Platform:** web
**Dependencies:** none
**depends_on:** none
**can_parallel:** false
**output_files:**
- src/lib/auth.ts
- src/app/api/auth/[...nextauth]/route.ts

**Acceptance criteria:**
- Users can sign in with Google OAuth
- Session is stored in database (not JWT)
- Unauthenticated requests to /api/protected return 401

**Test contract status:** REQUIRED

**Test contract:**
| # | Behavior description | Test type | Test file |
|---|---|---|---|
| TC-1 | Sign-in with valid credentials creates session | integration | tests/auth.test.ts |
| TC-2 | Unauthenticated request to /api/protected returns 401 | integration | tests/auth.test.ts |

**Gate commands:**
pnpm agent:check

**Checkpoint:** (written by Builder after commit_by_task.py — git SHA + timestamp)

Standard Infrastructure Tasks

The Planner automatically injects standard infrastructure tasks into every TASK-GRAPH based on project type. These tasks are never omitted — they are appended after the human-authored feature tasks.

CI/CD Tasks (all project types)

Observability Tasks — HTTP API projects

Observability Tasks — CLI projects

Spec Validation Gate

After Phase B completes, spec_validate.py runs automatically. It must exit 0 before !build is unlocked. The script performs seven checks:

Schema Change Safety

Whenever SCHEMA.md is modified during Planning or mid-build, migration_safety.py generate runs automatically. It produces a Migration Risk Report with:

• Delta between old and new schema (added/removed/modified columns and tables)
• Risk severity per change: LOW | MEDIUM | HIGH
• Bidirectional SQL: forward migration and rollback SQL
• Data loss assessment for each destructive change

FILE_OWNERSHIP_MAP

The FILE_OWNERSHIP_MAP.md maps every project file to the task(s) responsible for it. This powers Change Impact Tracking in Agent 3 — when a file is modified, the Builder looks up which other tasks own files in the same module and re-runs their tests.

| File | Owning Task(s) |
|---|---|
| src/lib/auth.ts | TASK-001 |
| src/app/api/auth/[...nextauth]/route.ts | TASK-001 |
| src/components/LoginForm.tsx | TASK-003 |
| src/lib/db.ts | TASK-002, TASK-001 |

Pattern Library Integration

At activation, the Planner queries PATTERN_INDEX.md with the project's stack keywords. Matched patterns are recorded in DECISIONS.md and applied directly in planning without re-solving known problems.

Example: a project with nextjs + prisma + nextauth will automatically apply:

• PATTERN-001 — NextAuth v5 + Prisma database sessions
• PATTERN-002 — Zod env validation at module load time
• PATTERN-003 — Prisma singleton with globalThis hot-reload guard

Planning Validation Checklist

Before emitting Phase B artifacts, the Planner self-validates: