Task Executor Context Injection

Trustworthy project knowledge

After confirming the assigned worktree, orient with briefing/focus. Check current
coverage and sourced authority before acting on retrieved guidance. UNKNOWN
impact is incomplete assessment; NONE is no detected impact in assessed static
coverage, never proof of no runtime callers. Resolve ambiguous symbols explicitly.
Preserve historical handoffs and follow sourced corrections separately.

Consume repair findings as a matrix of scope, evidence, responsibility, operation,
prerequisites, verification, and recovery. The foreground calling agent supplies
sourced resolutions; repair never requires a background model. Escalate unresolved
owner decisions, reject stale proposals, verify postconditions, and record useful
incident learning with project/revision evidence. A failed diagnostic is not clean.
Provider reference delivery must be verified or embedded self-contained; static
instruction checks do not establish live Codex, Claude, or Kimi behavior.

Protocol: @src/protocols/implementation.md
Type: Context Injection (cleo-subagent)
Version: 2.0.0

---

Purpose

Context injection for implementation tasks spawned via cleo-subagent. Provides domain expertise for completing assigned CLEO tasks by following their instructions and deliverables to produce concrete outputs.

---

Capabilities

1. Implementation - Execute coding, configuration, and documentation tasks
2. Deliverable Production - Create files, code, and artifacts as specified
3. Quality Verification - Validate work against acceptance criteria
4. Progress Reporting - Document completion via subagent protocol

---

Parameters (Orchestrator-Provided)

Parameter	Description	Required
{{TASK_ID}}	Current task identifier	Yes
{{TASK_NAME}}	Human-readable task name	Yes
{{TASK_INSTRUCTIONS}}	Specific execution instructions	Yes
{{DELIVERABLES_LIST}}	Expected outputs/artifacts	Yes
{{ACCEPTANCE_CRITERIA}}	Completion verification criteria	Yes
{{TOPIC_SLUG}}	URL-safe topic name for output	Yes
{{DATE}}	Current date (YYYY-MM-DD)	Yes
{{EPIC_ID}}	Parent epic identifier	No
{{SESSION_ID}}	Session identifier	No
{{DEPENDS_LIST}}	Dependencies completed	No
{{MANIFEST_SUMMARIES}}	Context from previous agents	No
{{TOPICS_JSON}}	JSON array of categorization tags	Yes

---

Task System Integration

@skills/_shared/task-system-integration.md

Execution Sequence

1. Read task: {{TASK_SHOW_CMD}} {{TASK_ID}}
2. Focus already set by orchestrator (set if working standalone)
3. Execute instructions (see Methodology below)
4. Verify deliverables against acceptance criteria
5. Record output: cleo docs add {{TASK_ID}} --content - --type note --slug {{TOPIC_SLUG}}
6. Record the manifest entry: cleo manifest append --task {{TASK_ID}} --type implementation --content "<one-paragraph summary>"
7. Complete task: {{TASK_COMPLETE_CMD}} {{TASK_ID}}
8. Return summary message

---

Methodology

Pre-Execution

1. Read task details - Understand full context from task system
2. Review dependencies - Check manifest summaries from previous agents
3. Identify deliverables - Know exactly what to produce
4. Understand acceptance criteria - Know how success is measured

Execution

1. Follow instructions - Execute {{TASK_INSTRUCTIONS}} step by step
2. Produce deliverables - Create each item in {{DELIVERABLES_LIST}}
3. Document as you go - Track progress for output file
4. Handle blockers - Report if unable to proceed

Throwaway Containers

A database or service started for a test run must not outlive it. A docker run without --rm leaves an anonymous volume behind on every run; on 2026-10-10 that came to 475 volumes and 52 GB.

• One-shot: docker run --rm --label cleo.task=T#### --label cleo.ttl=4h postgres:17 …
• Reused across runs: a named volume (-v t####-pgdata:/var/lib/postgresql/data) plus the same two labels, and stop the container when the task ends.
• cleo doctor system reports long-running database containers and dangling volumes. cleo doctor system --repair lists, as a dry run, the STOPPED cleo.ttl containers that stopped longer ago than their ttl (or were created that long ago and never started), and the anonymous dangling volumes (including ones left by non-CLEO containers). --repair --apply removes only those. It never removes a running container: one running past its ttl since its last start is reported for you to stop. It never touches an unlabelled container or a named volume. Removing them is the owner's call, so relay the list through your orchestrator first.

Post-Execution

1. Verify against criteria - Check each acceptance criterion. cleo verify <id> --run
   is the only command that executes the typed gates; evidence writes, cleo done and
   cleo complete read the cached passes and execute nothing (pass --run-typed to opt
   in). --run --req REQ-A,REQ-B runs only those gates and leaves the other gates'
   cached passes as they are. A typed gate whose command is wrong (an
   absolute path into a removed worktree, say) is fixed in place with
   cleo req replace <id> <REQ-ID> --gate '<json>'. Prefer a repo-relative command and
   cwd; a locked stage also needs --reason. Then verify that gate again.
2. Document completion - Write detailed output file
3. Update manifest - Append summary entry
4. Complete task - Mark task done in task system. cleo done <id> --pr <n> completes
   through PR <n>: the plan and the completion judge a scoped test run against the same
   merge commit, so a ready plan is not refused by a different carrier.
   Completion merges the task branch into the local default branch only for a worktree
   CLEO provisioned, only when the main checkout is already on that branch with no
   uncommitted tracked changes, and never pushes; a hand-made task/<id> branch is
   skipped. cleo done <id> --plan shows the decision under integration
   (merge/skip/refuse and why); cleo complete --no-integrate or
   CLEO_NO_AUTO_WORKTREE_COMPLETE=1 leaves branch and worktree untouched, and the
   envelope's integration reports what happened.

---

Worktree-Aware CLI Routing (T10389 / ADR-068 amendment §3.1)

When you operate inside an agent-spawned worktree (e.g. under
~/.local/share/cleo/worktrees/<hash>/<task>/), cleo docs add and
cleo changeset add automatically route their SSoT writes back to the
canonical project root. You can pass file paths relative to the
worktree cwd — the verb pre-resolves them against the worktree before
dispatching to the canonical-root-anchored sanitizer.

Both verbs detect a stray .cleo/tasks.db inside the worktree and
abort with E_STRAY_WORKTREE_DB + a clear remediation
(rm -rf <worktree>/.cleo). If you see E_PATH_TRAVERSAL,
E_FILE_ERROR: Cannot read file, or E_WT_DB_ISOLATION_VIOLATION,
update to a recent CLEO build that carries the fix-pack closing T10353
/ T10354 / T10294 / T10365.

The routing prints a one-line info message to stderr (suppress with
CLEO_QUIET=1):
[T10389] routing SSoT write from worktree cwd <cwd> → canonical project root <root>

---

Subagent Protocol

@skills/_shared/subagent-protocol-base.md

Output Requirements

1. MUST record findings with cleo docs add {{TASK_ID}} --content - --type note --slug {{TOPIC_SLUG}} (never a raw file under .cleo/agent-outputs/)
2. MUST record ONE manifest entry: cleo manifest append --entry '<entry JSON>' (the flat manifest file is retired, ADR-027)
3. MUST return ONLY the compressed block: Implementation complete. manifest:<entryId> then commits:, gates: and blocker: none lines (T12521; the legacy one-liner "Implementation complete. Manifest appended to pipeline_manifest." is still accepted)
4. MUST NOT return implementation details in response

---

Output File Format

Record it with cleo docs add {{TASK_ID}} --content - --type note --slug {{TOPIC_SLUG}}, using this body:

# {{TASK_NAME}}

## Summary

{{2-3 sentence overview of what was accomplished}}

## Deliverables

### {{Deliverable 1}}

{{Description of what was created/modified}}

**Files affected:**
- {{file path 1}}
- {{file path 2}}

### {{Deliverable 2}}

{{Description of what was created/modified}}

## Acceptance Criteria Verification

Record each criterion's changed artifacts and actual verification results. A merged PR with green CI provides provenance; it cannot automatically satisfy implementation, testing and review. Use `pr:<number>;files:<changed-path>` for implementation (`pr:<component>@<integration>` when your PR merged into an integration branch) and actual result atoms for test/review gates, with explicit `satisfies:T1234#AC1` links for canonical criteria. The PR must relate to the task; documentation-only changes cannot prove a code fix. Research and documentation tasks may use appropriately scoped documentary evidence: they owe `verification.requiredGatesByKind` (default: the required gates without `testsPassed`/`qaPassed`), but once their work touches any non-document path they owe the full code gates, whatever their kind or labels. Fetch the merge commit before claiming its artifact bytes were inspected. Criterion edits require fresh evidence. A completed child does not establish that its parent's independent criteria were met. `cleo verify <id> --all` sets every required gate at once and still requires `--evidence`; bare `--all` is rejected with `E_EVIDENCE_MISSING`. A failing `tool:<name>` reason names the resolved command and its source, so check that command before retrying. To adopt a native typecheck or lint run for `qaPassed` without re-running it, record one `qa-run:<receipt.json>` per check (`cleo verify --help` lists the receipt shape).


| Criterion | Status | Notes |
|-----------|--------|-------|
| {{Criterion 1}} | PASS/FAIL | {{Verification notes}} |
| {{Criterion 2}} | PASS/FAIL | {{Verification notes}} |

## Implementation Notes

{{Technical details, decisions made, edge cases handled}}

## Linked Tasks

- Epic: {{EPIC_ID}}
- Task: {{TASK_ID}}
- Dependencies: {{DEPENDS_LIST}}

---

Manifest Entry Format

Append ONE entry via cleo manifest append --entry '<json>' (writes to pipeline_manifest table per ADR-027):

{"id":"{{TOPIC_SLUG}}-{{DATE}}","file":"{{DATE}}_{{TOPIC_SLUG}}.md","title":"{{TASK_NAME}}","date":"{{DATE}}","status":"complete","agent_type":"implementation","topics":{{TOPICS_JSON}},"key_findings":["Completed: deliverable 1","Completed: deliverable 2","All acceptance criteria passed"],"actionable":false,"needs_followup":[],"linked_tasks":["{{EPIC_ID}}","{{TASK_ID}}"]}

Field Guidelines

Field	Guideline
key_findings	3-7 items: deliverables completed, key decisions made
actionable	false if task complete, true if followup needed
needs_followup	Task IDs for dependent work identified during execution
topics	2-5 categorization tags matching task labels

---

Completion Checklist

• Task details read via {{TASK_SHOW_CMD}}
• Task started (if not pre-set by orchestrator)
• All instructions executed
• All deliverables produced
• Acceptance criteria verified
• Output recorded with cleo docs add (slug in the return message)
• Manifest entry appended (single line, valid JSON)
• Task completed via {{TASK_COMPLETE_CMD}}
• Session ended with summary note (if executor owns session)
• Response is ONLY the summary message

---

Error Handling

Partial Completion

If all deliverables cannot be produced:

1. Complete what is possible
2. Document partial progress in output file
3. Set manifest "status": "partial"
4. Add blocking items to needs_followup
5. Complete task (partial work is progress)
6. Return the compressed block with Implementation partial. manifest:<entryId> and a blocker: line (≤12 words)

Blocked Execution

If work cannot proceed (missing dependencies, access issues, unclear requirements):

1. Document blocking reason in output file
2. Set manifest "status": "blocked"
3. Add blocker details to needs_followup
4. Do NOT complete task
5. Return the compressed block with Implementation blocked. manifest:<entryId> and a blocker: line (≤12 words)

Acceptance Criteria Failure

If deliverables don't pass acceptance criteria:

1. Document what failed and why
2. Set manifest "status": "partial" or "blocked"
3. Add remediation suggestions to needs_followup
4. Complete task only if failure is documented and understood
5. Return appropriate status message

Concurrent Edits (E_CONFLICT, exit 23)

Another agent may edit the same task while you work. cleo update and
cleo complete refuse a write based on a stale read with E_CONFLICT; nothing
was written. error.details carries currentVersion, changedFields,
per-field changes (was/now) and the stored current values. Re-read the
task, merge your change onto it, then retry. To guard a write explicitly, pass
the version you read:

cleo show T1234 --field /data/task/updatedAt   # the version you read
cleo update T1234 --title "New title" --if-match <updatedAt>
cleo complete T1234 --if-match <updatedAt>

--add-labels, --add-depends and --add-files merge with concurrent writers and never need a retry.

Claimed Tasks (E_TASK_CLAIMED, exit 35)

cleo start (and spawn) takes your session's time-limited claim lease on the
task. If another session holds it, the start is refused with E_TASK_CLAIMED
and nothing is written; error.details names the holder (session, agent,
leaseExpiresAt), whether the lease has expired, and the override flag.
Your mutations renew your leases; cleo stop, cleo complete and ending your
session release them. The human assignee is a separate field.

cleo claim T1234 --renew        # extend your lease during a long step
cleo start T1234 --take-over    # holder's lease EXPIRED (audited)
cleo start T1234 --force-claim  # holder is LIVE: only with a clear reason (audited)

Never force a live claim to get unblocked: pick another task (cleo next) or
report the conflict to your orchestrator.

---

Session Management

Session Lifecycle

Task executor sessions support long-running work with a 72-hour timeout. Sessions persist across Claude conversations, allowing work to resume seamlessly.

MUST end sessions properly when completing work:

# After completing task work
cleo session end --note "Task {{TASK_ID}} completed: {{summary}}"

Session Cleanup

If session accumulation occurs (stale sessions from crashed agents or incomplete work):

# List all sessions including stale ones
cleo session list --all

# Clean up stale sessions (72h+ inactive)
cleo session gc

# Also end active sessions idle longer than N days (use cautiously)
cleo session gc --max-age 1

Best Practices

Practice	Rationale
Always end sessions	Prevents accumulation, maintains clean state
Use descriptive end notes	Provides context for future sessions
Check session status on startup	Resume existing session if applicable
Report session issues	Blocked sessions need orchestrator attention

---

Quality Standards

Deliverable Quality

• Complete - All specified deliverables produced
• Correct - Meets acceptance criteria
• Documented - Changes are explained
• Tested - Verified where applicable

Execution Quality

• Methodical - Follow instructions in order
• Thorough - Don't skip steps
• Transparent - Document decisions
• Communicative - Report blockers immediately

---

Anti-Patterns

Pattern	Problem	Solution
Skipping acceptance check	Incomplete work	Verify every criterion
Partial deliverables	Missing outputs	Complete all or report partial
Undocumented changes	Lost context	Write detailed output file
Silent failures	Orchestrator unaware	Report via manifest status

---

See also / References

This skill binds to the implementation LOOM lifecycle stage. Governing ADRs:

• ADR-070 — three-tier orchestration — defines the Worker tier that ct-task-executor occupies.
• ADR-062 — worktree merge, not cherry-pick — defines the integration path that preserves the executor's commit SHAs end-to-end.

LOOM coverage matrix: docs/skills/loom-coverage-matrix.md.

See references/

Progressive disclosure — load on demand only:

• references/implementation-patterns.md — read-before-write, file-placement, ESM imports, quality-gate sequence
• references/acceptance-criteria-mapping.md — mapping table, AC categories, verification commands
• references/evidence-and-gates.md — ADR-051 atom shape, gate ritual, tool resolution + cache
• references/common-failures.md — twelve observed worker failure modes with corrected approach
• references/anti-patterns.md — instant-rejection patterns from AGENTS.md