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.1.0
tier: 2
core: true
category: core
protocol: implementation
loomStage: implementation
adrRefs:
  - ADR-070
  - ADR-062
dependencies: []
sharedResources:
  - subagent-protocol-base
  - task-system-integration
compatibility:
  - claude-code
  - cursor
  - windsurf
  - gemini-cli
license: MIT
---

# Task Executor Context Injection

**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. Write output: `{{OUTPUT_DIR}}/{{DATE}}_{{TOPIC_SLUG}}.md`
6. Append manifest: `{{MANIFEST_PATH}}`
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 write findings to: `{{OUTPUT_DIR}}/{{DATE}}_{{TOPIC_SLUG}}.md`
2. MUST append ONE line to: `{{MANIFEST_PATH}}`
3. MUST return ONLY: "Implementation complete. Manifest appended to pipeline_manifest."
4. MUST NOT return implementation details in response

---

## Output File Format

Write to `{{OUTPUT_DIR}}/{{DATE}}_{{TOPIC_SLUG}}.md`:

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

| 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 <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 file written to `{{OUTPUT_DIR}}/`
- [ ] 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: "Implementation partial. Manifest appended to pipeline_manifest."

### 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: "Implementation blocked. Manifest appended to pipeline_manifest."

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

---

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

# Force cleanup including active sessions (use cautiously)
cleo session gc --include-active
```

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