mcpctl/.taskmaster/docs/prd-agentic-teams.md

PRD: Agentic Teams — Foundation

Overview

mcpctl today orchestrates MCP servers, projects, prompts, skills, and chat agents. It does not orchestrate work. This PRD adds the foundation that lets human developers and autonomous agents be peers in the same project: a versioned vision layer (Epic → epictask → task), git repositories attached to projects, agents as many-to-many project members, ephemeral per-session pods where agents do real work, a swappable agent runtime, a task lifecycle with QA/Security/SRE gates, and a single human accept gate that fires a merge through the git provider's API.

The design record is docs/agentic-teams.md. This PRD converts §16 steps 1–3 of that document into an implementation spec. Steps 4–8 are named as deferred work at the end, deliberately without detail — they depend on open design questions (docs/agentic-teams.md §15) that are not closed.

Problem

Two failure classes motivate this work.

Nothing tracks work. There is no Epic, EpicTask, Task, Repository, or AgentProject model in src/db/prisma/schema.prisma, and no repository, service, route, or CLI code for any of them. Agents can chat and call tools, but there is no unit of work to assign, no lifecycle to advance, no branch or PR to attach, and no gate for a human to accept.

Completed tasks do not add up to the vision. From the design doc: you have a grand vision, you split it into tasks, you complete all the tasks, and you are left with a stick with wheels instead of a car. The root cause is not execution — it is that decomposition is lossy, tasks are graded mechanically ("compiles / lint / renders") rather than against intent, and integration is nobody's job. The fix is an authoritative, versioned Epic that every task can walk up to, so "what am I serving, and what does done-for-this look like" is always answerable.

A third, practical problem shapes the ordering: the design document's "don't rebuild, delegate" principle is correct in spirit, but several primitives it assumes do not exist in mcpctl yet. Those are enumerated under Execution Substrate Changes and must land before any agent can work a task.

Scope & Non-Goals

In scope (design doc §16 steps 1–3):

1. Epic / EpicTask / Task / CodeRepo entities + AgentProject membership, with project linkage, mcpd CRUD, CLI verbs, RBAC, backup, docs, and tests.
2. An AgentRuntime adapter interface and a first implementation running a headless coding agent inside an ephemeral per-session pod. Prove: pod spawn → clone repos → work a task branch → push → report.
3. Task lifecycle with QA / Security / SRE stages, PR linkage, the human accept gate, and merge through the git provider API, with post-merge failure reopening the task.

Explicitly out of scope — these are named in Deferred below and get placeholder tasks only: the Tier-2 design/product critic and Epic-comparison loop; collaboration modes (standup, joint exec sessions as a workflow); the confidence signal and escalation dashboard; per-persona memory and the coverage ledger; script artifacts and the baseline scorecard.

Not being built at all: a permission engine. mcpctl enforces coarse gates (who may transition a task, what RBAC a session needs); fine-grained per-tool approval stays inside the agent runtime.

Decisions Already Made

Decision	Choice	Rationale
Work-item RBAC name	Work items take tasks; the inference queue moves to inference-tasks	Matches the design doc's vocabulary. The inference-tasks alias already exists, so the URL prefix /api/v1/inference-tasks is unchanged
Roadmap-node spelling	Model EpicTask, resource epictasks, aliases epictask, et	Design doc §15 Q2; one word, matches the doc's own usage
Git-repo resource name	Model CodeRepo, resource repos, aliases repo, repository, repositories	Avoids repository.repository.ts and the collision with the data-access-layer term used throughout src/mcpd/src/repositories/
Epic revisions	Epic joins the existing ResourceRevision system as resourceType: 'epic'	The Epic is the auditable source of truth for "is this done"; scope changes must be visible. ResourceType is a string union by design, so this is a non-migration change
Agent membership	New AgentProject junction; Agent.projectId retained and kept in sync for one release	Design doc §4. ProjectMember was deliberately dropped in migration 20260223120000_remove_project_members; this is a narrower reversal — agent membership only, not human membership, which stays RBAC-driven
Invariants	Enforced in the service layer, not CHECK constraints	See Deployment constraint below
Agent brain	Home brain (Agent.llmId) for bare chat; the project's llmProvider/llmModel when the agent acts inside a project; optional per-membership override on AgentProject.llmId	Design doc §15 Q1 leans this way. This is the one open question that blocks the data model — the AgentProject.llmId column exists so the decision can be reversed without a migration

Deployment constraint (affects every schema task)

deploy/entrypoint.sh provisions the database with prisma db push --accept-data-loss, not prisma migrate deploy. Hand-written SQL in src/db/prisma/migrations/ therefore never runs in production. The single existing CHECK constraint, ChatThread_agent_xor_project (migration 20260717234728_add_project_chat_threads), is absent from any db push-provisioned database and is enforced only by ChatService.

Consequence: every invariant introduced here must be either expressible in the Prisma schema (unique constraints, non-null columns, enums, foreign keys) or enforced in the service layer with a test. Do not write CHECK constraints and assume they hold.

Core Concepts

The vision layer

Epic (the vision — project-scoped, versioned, revision-tracked)
  └── EpicTask  — a roadmap node; chains to other epictasks (dependency graph)
        └── Task — the unit of work, with its own lifecycle

An Epic holds the agreed done-criteria written at vision time, its scope-change history, and accepted-tradeoff decisions. An Epic is done only when 100% of the vision is delivered, or the user explicitly accepted the tradeoffs — recorded so "done" is honest and auditable.

An EpicTask is a roadmap node. EpicTasks chain to one another, so visualising them yields a dependency graph rather than a flat sequence. Each carries the decomposed subset of the Epic's acceptance criteria, so per-node completeness is computable.

A Task is the unit of work, owned by an EpicTask. Because Task → EpicTask → Epic, every task can resolve what it is serving by walking up the chain.

Two-level verification

Level	Checks	Who	When
Tier 1 — correctness / security / ops	Builds, runs, passes tests, stays secure, and the deployment-as-code is right for this project's real infrastructure	Developer + QA + Security + SRE personas	Inside the task's own lifecycle, before Done
Tier 2 — vision fidelity	Does the assembled result match the vision	Design/product critic	At the Epic level — deferred, not in this PRD

Tier 1 stages are gates inside the task loop. Their feedback bounces the task back to InProgress. They are not post-submit reviewers.

The SRE/Release stage reviews the deployment-as-code — is it targeting the right infrastructure, by the right method, with the right tooling. It reviews the deployment definition; it does not deploy. It exists because a large share of failures come from implicit operational rules a developer LLM does not know. Concrete example: this cluster runs default-deny network policies, so any new workload needs explicit egress and ingress rules. A developer LLM watching a connection fail will deep-dive the network-debugging path when the real cause is a missing egress policy silently dropping traffic. The SRE persona, holding per-project infra knowledge, flags that in review.

Agents as people

An agent exists independently of any project — a persistent identity with a name, description, system prompt, and a home brain. It joins zero, one, or many projects. Per-project role and scope hang off the membership junction, not off the agent.

Pod per session

Each agent session gets its own ephemeral pod. The pod is the workspace: an init container clones the project's repositories, the session is attached to project prompts, MCP tools, and scoped secrets, and the pod dies at session end. Agents do not share a live filesystem with each other — handoffs happen via git (branch + diff + verdict pinned to a commit). A single human may share one agent's environment via exec.

Schema Changes

All new models follow existing house conventions: id String @id @default(cuid()), version Int @default(1) as an optimistic-concurrency counter bumped unconditionally in the repository layer (see agent.repository.ts updateData.version = { increment: 1 }), plus createdAt / updatedAt.

Epic

model Epic {
  id                String   @id @default(cuid())
  name              String
  description       String   @default("")
  // The agreed statement of the vision. Body of the Epic.
  content           String   @db.Text
  // Checkable outcomes + intent/quality attributes that define 100% delivery.
  // Array of { id, text, kind: 'outcome' | 'quality', met: boolean }.
  doneCriteria      Json     @default("[]")
  // Accepted-tradeoff records: { what, why, who, deScopedBy, at }.
  acceptedTradeoffs Json     @default("[]")
  projectId         String
  status            EpicStatus @default(open)
  semver            String   @default("0.1.0")
  currentRevisionId String?
  ownerId           String
  version           Int      @default(1)
  createdAt         DateTime @default(now())
  updatedAt         DateTime @updatedAt

  project   Project   @relation(fields: [projectId], references: [id], onDelete: Cascade)
  owner     User      @relation(fields: [ownerId], references: [id], onDelete: Cascade)
  epicTasks EpicTask[]

  @@unique([name, projectId])
  @@index([projectId])
  @@index([name])
}

enum EpicStatus {
  open
  delivered              // 100% of doneCriteria met
  delivered_with_tradeoffs
  cancelled
}

EpicTask

model EpicTask {
  id           String   @id @default(cuid())
  name         String
  description  String   @default("")
  epicId       String
  // Decomposed subset of the Epic's doneCriteria this node is responsible for.
  doneCriteria Json     @default("[]")
  status       EpicTaskStatus @default(todo)
  ownerId      String
  version      Int      @default(1)
  createdAt    DateTime @default(now())
  updatedAt    DateTime @updatedAt

  epic      Epic     @relation(fields: [epicId], references: [id], onDelete: Cascade)
  owner     User     @relation(fields: [ownerId], references: [id], onDelete: Cascade)
  tasks     Task[]
  dependsOn EpicTaskEdge[] @relation("EpicTaskEdgeFrom")
  blocks    EpicTaskEdge[] @relation("EpicTaskEdgeTo")

  @@unique([name, epicId])
  @@index([epicId])
}

// Chaining between roadmap nodes. Modelled as an explicit edge table rather
// than a self-referencing array so the graph can be walked in both directions
// and edges can later carry a type.
model EpicTaskEdge {
  id        String   @id @default(cuid())
  fromId    String   // the dependent node
  toId      String   // the prerequisite node
  createdAt DateTime @default(now())

  from EpicTask @relation("EpicTaskEdgeFrom", fields: [fromId], references: [id], onDelete: Cascade)
  to   EpicTask @relation("EpicTaskEdgeTo",   fields: [toId],   references: [id], onDelete: Cascade)

  @@unique([fromId, toId])
  @@index([fromId])
  @@index([toId])
}

enum EpicTaskStatus {
  todo
  in_progress
  done
  cancelled
}

Cycle prevention in the edge graph is a service-layer check (see Deployment constraint): before creating an edge, walk to's transitive dependencies and reject if from is reachable.

Task

model Task {
  id           String   @id @default(cuid())
  name         String
  title        String
  description  String   @default("") @db.Text
  epicTaskId   String
  repoId       String?
  // The agent currently responsible. Null while unassigned.
  assigneeId   String?
  state        TaskState @default(todo)
  // Drives how much Tier-1 verification is engaged: trivial work may pass on a
  // light self-check; risky work engages QA / Security / SRE.
  risk         TaskRisk  @default(normal)
  // Git linkage, populated when the agent pushes.
  branch       String?
  headCommit   String?
  prUrl        String?
  prNumber     Int?
  // Free-form reviewer comment attached at the accept gate.
  reviewNote   String?  @db.Text
  ownerId      String
  version      Int      @default(1)
  createdAt    DateTime @default(now())
  updatedAt    DateTime @updatedAt

  epicTask  EpicTask     @relation(fields: [epicTaskId], references: [id], onDelete: Cascade)
  repo      CodeRepo?    @relation(fields: [repoId],     references: [id], onDelete: SetNull)
  assignee  Agent?       @relation(fields: [assigneeId], references: [id], onDelete: SetNull)
  owner     User         @relation(fields: [ownerId],    references: [id], onDelete: Cascade)
  verdicts  TaskVerdict[]
  sessions  AgentSession[]
  events    TaskEvent[]

  @@unique([name, epicTaskId])
  @@index([epicTaskId])
  @@index([state])
  @@index([assigneeId])
}

enum TaskState {
  todo
  in_progress
  building          // compile, run, smoke
  self_testing      // developer's own tests
  qa_review
  security_review
  sre_review
  done              // leaves the developer's loop
  awaiting_review   // human accept gate
  merged
  reopened          // post-merge failure
  cancelled
}

enum TaskRisk {
  trivial   // docs, formatting — light self-check may suffice
  normal
  high      // auth, secrets, migrations, cross-contract
}

// A Tier-1 persona's verdict, pinned to the commit it judged. Immutable —
// this is the provenance record the design doc calls "QA verified 3f2ab".
model TaskVerdict {
  id        String   @id @default(cuid())
  taskId    String
  stage     TaskState        // qa_review | security_review | sre_review
  agentId   String?
  commit    String
  passed    Boolean
  summary   String   @db.Text
  // Structured findings: [{ severity, message, path?, line? }]
  findings  Json     @default("[]")
  createdAt DateTime @default(now())

  task  Task   @relation(fields: [taskId],  references: [id], onDelete: Cascade)
  agent Agent? @relation(fields: [agentId], references: [id], onDelete: SetNull)

  @@index([taskId])
  @@index([taskId, stage])
}

// Append-only transition log. Every state change writes one row.
model TaskEvent {
  id        String   @id @default(cuid())
  taskId    String
  fromState TaskState?
  toState   TaskState
  actorType String   // 'user' | 'agent' | 'system'
  actorId   String?
  note      String?  @db.Text
  createdAt DateTime @default(now())

  task Task @relation(fields: [taskId], references: [id], onDelete: Cascade)

  @@index([taskId, createdAt])
}

CodeRepo

model CodeRepo {
  id            String   @id @default(cuid())
  name          String
  projectId     String
  // Clone URL. https for token auth, ssh for key auth.
  url           String
  defaultBranch String   @default("main")
  // Relative path under the session workspace root. Defaults to `name`.
  path          String   @default("")
  // Git provider, for PR/merge API calls. 'gitea' is the only driver in v1.
  provider      String   @default("gitea")
  // Secret holding the provider credential. Resolved through SecretService at
  // session-provision time — never stored in plaintext on the row.
  credSecretId  String?
  credSecretKey String?
  ownerId       String
  version       Int      @default(1)
  createdAt     DateTime @default(now())
  updatedAt     DateTime @updatedAt

  project Project @relation(fields: [projectId], references: [id], onDelete: Cascade)
  cred    Secret? @relation(fields: [credSecretId], references: [id])
  owner   User    @relation(fields: [ownerId], references: [id], onDelete: Cascade)
  tasks   Task[]

  @@unique([name, projectId])
  @@index([projectId])
}

AgentProject

Mirrors ProjectServer (schema.prisma): explicit join model with its own cuid id, createdAt, cascade on both sides, @@unique([a, b]). Indexes on both columns follow PersonalityPrompt, because both reverse lookups are needed ("agents of project", "projects of agent").

model AgentProject {
  id        String   @id @default(cuid())
  agentId   String
  projectId String
  // Per-project persona role. TEXT, not an enum, so adding a role later is a
  // non-migration change (same reasoning as ResourceProposal.resourceType).
  // v1 values: 'developer' | 'qa' | 'security' | 'sre'.
  role      String   @default("developer")
  // Optional per-membership brain override. Present so the open question in
  // docs/agentic-teams.md §15 Q1 can be answered either way without a migration.
  llmId     String?
  createdAt DateTime @default(now())

  agent   Agent   @relation(fields: [agentId],   references: [id], onDelete: Cascade)
  project Project @relation(fields: [projectId], references: [id], onDelete: Cascade)
  llm     Llm?    @relation(fields: [llmId],     references: [id], onDelete: SetNull)

  @@unique([agentId, projectId])
  @@index([agentId])
  @@index([projectId])
}

Agent.projectId is retained and written in sync with the junction for one release, so existing prepareContext / findByProjectId paths keep working. A follow-up removes it.

AgentSession

model AgentSession {
  id          String   @id @default(cuid())
  agentId     String
  projectId   String
  taskId      String?
  // Orchestrator handle — pod name on k8s, container id on docker.
  containerId String?
  state       SessionState @default(pending)
  image       String
  // Reaped when now() > expiresAt. Swept by the same style of GC loop as the
  // inference-task sweep in main.ts.
  expiresAt   DateTime
  lastError   String?  @db.Text
  ownerId     String
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
  endedAt     DateTime?

  agent   Agent   @relation(fields: [agentId],   references: [id], onDelete: Cascade)
  project Project @relation(fields: [projectId], references: [id], onDelete: Cascade)
  task    Task?   @relation(fields: [taskId],    references: [id], onDelete: SetNull)
  owner   User    @relation(fields: [ownerId],   references: [id], onDelete: Cascade)

  @@index([state])
  @@index([taskId])
  @@index([agentId])
}

enum SessionState {
  pending
  provisioning
  running
  ended
  failed
}

Back-relations on existing models

Prisma requires both sides of every relation. The blocks above show only the owning side; the following fields must be added to existing models or prisma generate fails:

Model	Fields to add
Project	epics Epic[], codeRepos CodeRepo[], agentMemberships AgentProject[], sessions AgentSession[]
User	ownedEpics Epic[], ownedEpicTasks EpicTask[], ownedTasks Task[], ownedRepos CodeRepo[], ownedSessions AgentSession[]
Agent	projectMemberships AgentProject[], assignedTasks Task[], verdicts TaskVerdict[], sessions AgentSession[]
Llm	agentProjects AgentProject[]
Secret	codeRepos CodeRepo[]

Agent.projectId and its project Project? relation stay as-is during the transition release, so Project carries both agents Agent[] (existing) and agentMemberships AgentProject[] (new).

Test helper

src/db/tests/helpers.ts clearAllTables must gain deleteMany calls for every new model — globals with nullable foreign keys do not cascade.

API Changes

All routes sit under /api/v1, follow the existing Fastify + zod-in-the-service pattern, and resolve project / agent name strings to ids at the route layer (as routes/skills.ts does).

New endpoints

# Vision layer
GET|POST       /api/v1/epics                       ?project=<name>
GET|PUT|DELETE /api/v1/epics/:id
GET            /api/v1/epics/:id/roadmap           → epictask graph + per-node completeness
POST           /api/v1/epics/:id/tradeoffs         → append an accepted-tradeoff record

GET|POST       /api/v1/epictasks                   ?epic=<name>&project=<name>
GET|PUT|DELETE /api/v1/epictasks/:id
POST|DELETE    /api/v1/epictasks/:id/edges         → { toId }  add/remove a dependency edge

# Work items
GET|POST       /api/v1/tasks                       ?project=&epictask=&state=&assignee=
GET|PUT|DELETE /api/v1/tasks/:id
POST           /api/v1/tasks/:id/transition        → { toState, note? }
POST           /api/v1/tasks/:id/verdict           → record a QA/Security/SRE verdict
POST           /api/v1/tasks/:id/accept            → { note? }  human accept gate → merge
POST           /api/v1/tasks/:id/reject            → { note }   → back to in_progress
GET            /api/v1/tasks/:id/events

# Repositories
GET|POST       /api/v1/repos                       ?project=<name>
GET|PUT|DELETE /api/v1/repos/:id

# Agent membership
GET            /api/v1/agents/:name/projects
POST|DELETE    /api/v1/agents/:name/projects/:project   → { role?, llm? }
GET            /api/v1/projects/:name/agents

# Sessions & exec
GET|POST       /api/v1/sessions                    ?project=&agent=&task=
GET|DELETE     /api/v1/sessions/:id
POST           /api/v1/sessions/:id/exec           → one-shot exec, returns { exitCode, stdout, stderr }
GET            /api/v1/sessions/:id/attach         → WebSocket, bidirectional stdio

# Git provider webhook
POST           /api/v1/webhooks/git/:provider      → post-merge failure reopens the task

Changed endpoints

/api/v1/inference-tasks/* is unchanged in shape. Only its RBAC resource name changes (see below).

RBAC Changes

The tasks namespace split

src/mcpd/src/validation/rbac-definition.schema.ts currently declares tasks in RBAC_RESOURCES and aliases task, inference-task, and inference-tasks all onto it — with the comment "the only 'task' we have is inference for now". That is no longer true.

Required changes:

1. RBAC_RESOURCES gains epics, epictasks, tasks (now meaning work items), repos, sessions, and inference-tasks.
2. RESOURCE_ALIASES maps task → tasks, epic → epics, epictask → epictasks, et → epictasks, repo → repos, repository → repos, repositories → repos, session → sessions, and inference-task → inference-tasks. The entry 'inference-tasks': 'tasks' is removed.
3. mapUrlToPermission in src/mcpd/src/main.ts gains epics, epictasks, tasks, repos, sessions, and maps /api/v1/inference-tasks to inference-tasks. Non-CRUD verbs need explicit cases above the map: POST /tasks/:id/accept|reject|transition → run:tasks:<name>, POST /sessions/:id/exec and GET /sessions/:id/attach → run:sessions:<name>.
4. nameResolvers (main.ts) gains epics, epictasks, tasks, repos, sessions so name-scoped grants match when the URL carries a cuid.

One-shot binding backfill

ResourceBindingSchema transforms resource through normalizeResource at parse time and stores the normalized string, so existing RbacDefinition.roleBindings rows already contain the literal "tasks" meaning inference. After the split, those grants would silently become work-item grants.

A one-shot startup migration must rewrite resource: "tasks" → "inference-tasks" across all RbacDefinition rows. Model the walk on migrateAdminRole in src/mcpd/src/main.ts (it iterates rbacRepo.findAll() and rewrites roleBindings in place).

It must be guarded so it runs exactly once — a blanket rewrite on every boot would clobber legitimate new work-item grants. Use the existing system-settings pattern: a boolean key in the mcpctl-system-settings Secret (SYSTEM_SETTINGS_SECRET in src/mcpd/src/bootstrap/system-settings.ts), read before the walk and written after. Wildcard bindings (resource: '*') are untouched — they already cover both.

Document the rename in docs/inference-tasks.md.

CLI Changes

Two project rules govern every resource added here:

• Everything settable via apply -f must also be a create flag.
• mcpctl get RESOURCE NAME -o yaml must round-trip through mcpctl apply -f.

New commands

mcpctl get epics|epictasks|tasks|repos|sessions [--project NAME]
mcpctl describe epic|epictask|task|repo|session NAME
mcpctl create epic|epictask|task|repo ...
mcpctl edit epic|epictask|task|repo NAME
mcpctl delete epic|epictask|task|repo NAME

mcpctl describe epic NAME            # roadmap: epictask graph + per-node completeness
mcpctl tasks accept NAME [--note ..] # human accept gate → merge via provider API
mcpctl tasks reject NAME --note ..   # → back to in_progress
mcpctl exec --project NAME AGENT -- bash

mcpctl exec semantics (design doc §10): exec drops the human into the working environment — the cloned repos, branches, tools, and deps. It does not attach to the agent's reasoning loop. The agent remains a separate process the human can still talk to.

Files to touch

Concern	File
Resource aliases	src/cli/src/commands/shared.ts RESOURCE_ALIASES
get columns + yaml kind	src/cli/src/commands/get.ts — row interfaces, getColumnsForResource, RESOURCE_KIND, toApplyDocs strip blocks
describe formatters	src/cli/src/commands/describe.ts — clean sections and tables, not key-value dumps
create subcommands	src/cli/src/commands/create.ts
apply -f	src/cli/src/commands/apply.ts — spec schemas, ApplyConfigSchema keys, KIND_TO_RESOURCE, dry-run counts, apply loops
edit	src/cli/src/commands/edit.ts validResources
Scoped fetch	src/cli/src/index.ts fetchResource / fetchSingleResource for --project scoping
Completions	scripts/generate-completions.ts CANONICAL_RESOURCES + ALIAS_ENTRIES, then pnpm completions:generate

Completions are generated, never hand-edited; src/cli/tests/completions.test.ts runs the generator with --check and fails on drift.

Execution Substrate Changes

These are the primitives the design document assumes but mcpctl does not have. They gate step 2.

1. Ephemeral pods

ContainerSpec in src/mcpd/src/services/orchestrator.ts has only image, name, command, env, ports, limits, labels, and network. generatePodSpec in src/mcpd/src/services/k8s/manifest-generator.ts hardcodes restartPolicy: 'Always', and no code anywhere uses the Kubernetes Job API.

ContainerSpec must gain:

• restartPolicy?: 'Always' | 'Never' | 'OnFailure'
• workdir?: string
• volumes?: Array<{ name: string; mountPath: string; kind: 'emptyDir' }> — the session workspace
• initContainers?: Array<{ name; image; command; env?; volumeMounts? }> — the repo-clone step

Both backends implement them: KubernetesOrchestrator and DockerContainerManager.

2. Session provisioning

A SessionService that: creates the AgentSession row; resolves the project's CodeRepo list and their credentials through SecretService (resolution failure is fatal for the attempt, matching InstanceService.attemptStart); builds a spec with an init container that clones each repo to its path under the workspace volume and checks out the task branch; starts the pod; and transitions the row to running.

Reaping runs as a GC sweep in the same style as the existing inference-task sweep in src/mcpd/src/main.ts: sessions past expiresAt are stopped, removed, and marked ended. Note these loops assume a single mcpd replica — there is no leader election, and this inherits that.

3. Exec surface

The hard part already exists. McpOrchestrator declares execInContainer, execInteractive, and attachInteractive; KubernetesOrchestrator implements the latter two over k8s.Exec and k8s.Attach, and src/mcpd/src/services/transport/persistent-stdio.ts uses them in production today. This work is an API and CLI surface over a proven primitive: a one-shot exec route, a WebSocket attach route with terminal resize and proper exit-code propagation, and the mcpctl exec client.

4. Git provider client

No Gitea or GitHub API client, PR creation, or webhook handling exists in product code. PRs are made today by the root-level pr.sh (curl against the Gitea API) or by an agent calling the gitea-mcp-server MCP tool.

A GitProvider interface in mcpd with a Gitea driver: createPullRequest, getPullRequest, getCombinedStatus, mergePullRequest. Credentials resolve from the CodeRepo's Secret. pr.sh is the reference for the endpoint shapes (POST /api/v1/repos/:owner/:repo/pulls). A webhook receiver validates the provider signature and reopens the task on post-merge failure.

AgentRuntime Interface

mcpctl builds an interface, not a runtime. ChatService is not a candidate — its tool loop is capped at MAX_ITERATIONS = 12 (clamped 1..50), which is a soft-DoS guard appropriate for chat and far too small for a coding task.

export interface AgentRuntime {
  startSession(opts: RuntimeSessionOpts): Promise<RuntimeSession>;
  send(sessionId: string, message: string): Promise<void>;
  status(sessionId: string): Promise<RuntimeStatus>;
  result(sessionId: string): Promise<RuntimeResult>;   // branch, head commit, summary
  endSession(sessionId: string): Promise<void>;
}

Implementation #1 runs a battle-tested headless coding agent inside the session pod. It already solves per-tool permission approval, git and branch mechanics, subagents, streaming, and MCP client behaviour — all things the design document explicitly declines to rebuild. The persona is delivered as prompt files in the container, which suits a file-aware coding runtime.

A second adapter is explicitly deferred; the interface exists so it stays possible.

Task Lifecycle

todo → in_progress → building → self_testing
         → qa_review        (feedback → in_progress)
         → security_review  (feedback → in_progress)
         → sre_review       (feedback → in_progress)
         → done → awaiting_review
                    accept → merged
                    reject → in_progress
       merged --post-merge failure (webhook)--> reopened

Verification effort scales with Task.risk: trivial work may pass on a light self-check; high engages all three review stages. The stages decide their own depth.

Transitions are guarded by a table of legal (from, to) pairs and applied as compare-and-swap — updateMany with the expected state in the where clause, then check the affected-row count. This is the same idiom InferenceTaskRepository uses so two racing claimants cannot both win. Every transition appends a TaskEvent.

The human approval gate is not a per-tool tri-state. It is a task-level yes/no plus a comment on the resolved outcome, and accepting it fires the merge. The human should not have to go to git.

Testing Strategy

Unit — src/db/tests/

• Schema tests per model (pattern: skill-schema.test.ts): create, unique constraints, cascade behaviour on project/epic/task delete, AgentProject uniqueness.
• clearAllTables in helpers.ts covers every new model.

Unit — src/mcpd/tests/

• Service tests: Epic done-criteria roll-up; EpicTask edge cycle rejection; task transition table including every illegal pair; compare-and-swap under concurrent transition.
• Route tests per resource (pattern: prompt-routes.test.ts, agent-routes.test.ts).
• RBAC: the tasks → inference-tasks backfill runs once and is idempotent on a second boot; a pre-existing view:tasks grant still authorizes /api/v1/inference-tasks afterwards and does not authorize /api/v1/tasks; name-scoped grants resolve for all new resources.
• Orchestrator: generatePodSpec emits restartPolicy, workdir, volumes, and init containers.
• Git provider: Gitea driver against a mocked HTTP server.

Unit — src/cli/tests/

• get -o yaml → apply -f round-trip for every new resource.
• create flag coverage: every field settable in apply has a matching flag.
• completions.test.ts assertions for the new resource words.

Smoke — src/mcplocal/tests/smoke/

Every feature ships smoke tests. Follow the CRUD pattern in personality.smoke.test.ts: a Date.now().toString(36) name suffix, a healthz() preflight that skips rather than fails when the daemon is unreachable, mcpctl --direct shelling, and explicit afterAll cleanup.

• epic.smoke.test.ts — Epic → EpicTask → Task create/list/describe/delete against live mcpd.
• repo.smoke.test.ts — CodeRepo CRUD, credential reference resolves.
• session.smoke.test.ts — provision a session pod against the real cluster, confirm the repo is cloned, exec a command, confirm the pod is reaped.
• task-lifecycle.smoke.test.ts — drive a task through the full transition chain including a rejected accept-gate bounce.

When a smoke test fails, fix the environment (deploy, backend, RBAC) — never weaken the assertion.

Deferred

Named here so the boundary is explicit. Each gets a single placeholder task with no detail, to be expanded once the corresponding open questions in docs/agentic-teams.md §15 are closed.

• Tier-2 vision critic and Epic-comparison. A review-only, non-executing design/product persona that judges the assembled result against the Epic in its native medium, producing reopen / new-task / exec outcomes. Blocked on §15 Q13 (does this need render/screenshot infrastructure, or can a design-aware persona judge from a structured artifact?).
• Collaboration modes. On-demand async standup (mcpctl standup --project NAME) and exec as a workflow rather than a command. Blocked on §15 Q4 and Q5.
• Confidence signal and escalation dashboard. Evidence-anchored confidence (retrieve K similar past tasks with their outcomes, ask how confident we are this resolves cleanly), thresholds driving autonomy, and a single cross-project human decision queue. Blocked on §15 Q12 (web / TUI / CLI?). Retrieval quality is the crux — weak retrieval quietly poisons the model.
• Memory and the coverage ledger. Global per-agent memory plus per-project knowledge, and a commit-pinned coverage ledger enabling delta-verification. Non-negotiable prerequisite: invalidation when a covered region changes, or the ledger becomes false confidence. Keep the trust boundary — the ledger is platform-verified machine fact; agent prose notes are opinion and never the gate.
• Script artifacts and the baseline scorecard. Reusable executable script artifacts at task, project, and agent scope, plus a provisioned baseline-rules scorecard. Blocked on §15 Q15 and Q16. Watch the incentive integrity risk: reward reused tools, not tool proliferation.

Implementation Phases

Phase A — foundation (blocks everything)

1. RBAC tasks namespace split, alias repoint, and the one-shot guarded binding backfill.
2. Prisma models Epic, EpicTask, EpicTaskEdge, Task, TaskVerdict, TaskEvent, CodeRepo, AgentSession + enums + migration + clearAllTables.
3. AgentProject junction, with Agent.projectId kept in sync for one release.

Phase B — mcpd CRUD 4. Epic resource: repository, service, zod validation, routes, main.ts wiring, revision opt-in. 5. EpicTask resource plus the edge graph and cycle rejection. 6. Task resource plus the transition table and compare-and-swap transitions. 7. CodeRepo resource with credential resolution. 8. RBAC wiring for all new resources: mapUrlToPermission, nameResolvers, non-CRUD verb cases. 9. Backup and YAML kinds for the new resources — BACKUP_KINDS, APPLY_ORDER, kindMap, the export loop, serializeResource, and main.ts kindFromSegment / importResource / deleteResource. Fix the pre-existing gap where skill is missing from the latter two.

Phase C — CLI 10. get columns and describe formatters for all new resources. 11. create, apply -f, edit, delete, with the yaml round-trip test. 12. Shell completions and their guard test. 13. Roadmap view: describe epic rendering the epictask graph with per-node completeness.

Phase D — execution substrate 14. Extend ContainerSpec and both orchestrator backends with restart policy, workdir, volumes, and init containers. 15. SessionService: provisioning, repo-clone init container, credential resolution, TTL and GC. 16. AgentRuntime interface plus adapter #1 running a headless coding agent in-pod. 17. Exec surface: one-shot exec route, WebSocket attach, and mcpctl exec.

Phase E — lifecycle and PR 18. Task lifecycle state machine, transition API, and TaskEvent log. 19. GitProvider interface plus the Gitea driver. 20. PR linkage and the human accept gate firing merge through the provider API. 21. QA / Security / SRE stage verdicts, risk-scaled, pinned to a commit. 22. Post-merge failure webhook reopening the task.

Phase F — cross-cutting 23. Documentation: docs/epics.md, docs/tasks.md, docs/repos.md, docs/sessions.md, the README resources table, and the CLAUDE.md resource cheatsheet. 24. Smoke tests for every new resource plus the session and lifecycle flows.

Phase G — deferred placeholders 25. Tier-2 vision critic and Epic-comparison loop. 26. Collaboration modes: async standup and exec joint sessions. 27. Confidence signal and escalation dashboard. 28. Per-agent memory and the coverage ledger. 29. Script artifacts and the baseline scorecard.