Ct Task Executor

---
name: ct-task-executor
description: General implementation task execution for completing assigned CLEO tasks by following instructions and producing concrete deliverables. Handles coding, configuration, documentation work with quality verification against acceptance criteria and progress reporting. Use when executing implementation tasks, completing assigned work, or producing task deliverables. Triggers on implementation tasks, general execution needs, or task completion work.
version: 2.7.6
protocol: implementation
adrRefs:
  - ADR-070
  - ADR-062
dependencies: []
sharedResources:
  - subagent-protocol-base
  - task-system-integration
compatibility:
  - claude-code
  - cursor
  - windsurf
  - gemini-cli
license: MIT
metadata:
  version: 2.7.6
  tier: core
  install: harness
  covers:
    - packages/cleo/src/cli/commands/verify.ts
    - packages/cleo/src/cli/commands/complete.ts
    - packages/cleo/src/cli/commands/start.ts
    - packages/cleo/src/cli/commands/claim.ts
    - packages/core/src/validation/protocols/cant/implementation.cant
    - packages/core/src/validation/protocols/protocols-markdown/implementation.md
  loomStage: implementation
  lastReviewed: 2026-09-29
  stability: stable
---

# 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

### Post-Execution

1. **Verify against criteria** - Check each acceptance criterion
2. **Document completion** - Write detailed output file
3. **Update manifest** - Append summary entry
4. **Complete task** - Mark task done in task system

---

## 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:

```markdown
# {{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. 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.


| 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):

```json
{"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:

```bash
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.

```bash
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:

```bash
# 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):

```bash
# 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](../../../../.cleo/adrs/ADR-070-three-tier-orchestration.md) — defines the Worker tier that ct-task-executor occupies.
- [ADR-062 — worktree merge, not cherry-pick](../../../../.cleo/adrs/ADR-062-worktree-merge-not-cherry-pick.md) — defines the integration path that preserves the executor's commit SHAs end-to-end.

LOOM coverage matrix: [docs/skills/loom-coverage-matrix.md](../../../../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