---
name: scorpio-execute
description: Execute development tasks from task files. Implements code in focused subagent sessions. Use when the user has task files to execute, wants to run through a task list, or asks to "build the tasks" or "start development".
---

# Task Execute Runner (alias: DEV Task Runner)

A methodology for executing development tasks with context-aware session management. Each task is implemented by a focused subagent.

> **Model role — implement.** This skill runs the pipeline's **implement** phase, so it targets the configured `{models.implement}` (model + optional `effort`) when `scorpio.config.json` sets it — falling back to `{models.default}` → the harness's main-session model. Per-role model selection is a **declaration honored to the granularity the harness supports** (the `modelSelection` capability): on Claude Code it's advisory (the Agent tool can't pick a model per dispatch from config) — state the intended model and apply it via agent frontmatter `model:` or `CLAUDE_CODE_SUBAGENT_MODEL`; the Claude Agent SDK honors it per agent-definition. See [docs/CONFIG.md](../../docs/CONFIG.md#per-role-models).

## Session Management Rules

- **Max 3 tasks per session.** After completing 3 tasks, update TASK-INDEX.md and instruct the user to continue in a new session.
- **One pipeline phase per session.** Do not auto-chain into scorpio-qa or scorpio-qa-final. Complete your batch, checkpoint, and stop.
- **Subagents write to files, return summaries.** Detailed output goes to disk, not into the parent's context.

## Prerequisites

This skill expects task files from **scorpio-task-plan** (`scorpio-task-plan`), **scorpio-feature-plan** (`scorpio-feature-plan`), or **scorpio-bug-investigate** (`scorpio-bug-investigate`).

### Basic Task Format

The minimum required fields:

```markdown
## [TASK-ID] [Task Title]

**Type**: Feature | Bug | Chore | Spike
**Priority**: P0 | P1 | P2 | P3
**Estimate**: XS | S | M | L
**Dependencies**: [TASK-ID] or None

### Description
[What needs to be done and why]

### Acceptance Criteria
- [ ] [Criterion 1]
- [ ] [Criterion 2]

### Technical Notes
[Implementation hints, gotchas, or constraints]
```

### Enhanced Task Format

Additional fields for feature and bug fix tasks (all optional but recommended):

```markdown
## [TASK-ID] [Task Title]

**Type**: Feature | Bug | Chore | Spike
**Priority**: P0 | P1 | P2 | P3
**Estimate**: XS | S | M | L
**Dependencies**: [TASK-ID] or None

### Description
[What needs to be done and why]

### Implementation Approach
[Specific technical approach - how to solve the problem]

### Files to Create/Modify
- `path/to/file.ts` - [what to add/change]
- `path/to/file.ts` - [what to add/change]

### Integration Points
- Uses: `existing/code/path.ts` - [how it's used]
- Extends: `existing/component.tsx` - [how it's extended]
- Follows pattern: `similar/feature/path.ts` - [pattern to follow]

### Root Cause (Bug tasks only)
[Location, code snippet, and explanation of the bug]

### Acceptance Criteria
- [ ] [Specific, testable criterion]
- [ ] [Specific, testable criterion]
- [ ] Existing tests pass
- [ ] New tests added for [specific coverage]

### Test Strategy
- **Unit**: [What to unit test]
- **Integration**: [What to integration test]
- **Manual**: [Manual verification steps]

### Technical Notes
- Pattern reference: [path to similar code]
- Watch out for: [gotchas, edge cases]
```

## Execution Process

For each task, a subagent implements the code.

### Step 1: Subagent Implements

Spawn a focused subagent to implement the task.

**Execution Prompt Template:**

```
You are DEV, a focused development agent. Your job is to implement the following task.

## Task Specification
[Paste task file contents here]

## Instructions
1. Read the task requirements and acceptance criteria
2. If the task lists "Files to Create/Modify", focus on those files
3. If you need to understand a pattern, read at most ONE reference file
4. Implement the solution with clean, well-tested code
5. Run quality gates: lint, typecheck, test
6. Write your completion report to {docs.tasks}/done/[TASK-ID]-report.md

## Scope Rules — CRITICAL
- Read ONLY files relevant to this specific task
- Do NOT explore the codebase broadly
- DO read PROJECT-CONTEXT.md first (if present) for conventions, architecture boundaries, and security/safety rules — it's a concise summary, so this stays cheap; then read only the task-specific files
- If a file is long (500+ lines), read only the relevant section using line offsets
- For quality gate output, capture pass/fail and the first 20 lines of any failures only
- Don't implement beyond what's asked
- **Use the stack's real, idiomatic conventions — never invent one.** Match what the framework/ecosystem actually uses (verify against PROJECT-CONTEXT.md, the stack docs, or existing files); don't fabricate a plausible-looking convention the tooling won't recognize (e.g. a `.gdkeep` Godot ignores when the idiom is a real `.tscn`/`.gd` or a `.gitkeep`). If unsure of the idiom, check before committing to it.

## Completion Report Format
Write to {docs.tasks}/done/[TASK-ID]-report.md:
- What was implemented
- Files changed (full list of paths)
- Quality gates: pass/fail for each
- Any issues encountered

## Return to Parent
Return ONLY this summary (not the full report):
  TASK-ID: [ID]
  Status: DONE | BLOCKED
  Files changed: [list of file paths]
  Quality gates: [pass/fail summary]
  Report: {docs.tasks}/done/[TASK-ID]-report.md
```

### Step 2: Controlled Local Git Operations

Local git commands are allowed for task-level hygiene when policy permits:
- Follow branch guardrails from `git-policy.json` (or the project's configured git policy source)
- If `required_work_branch` is set (for this repo: `development`), do all implementation on that branch
- Do NOT create task branches unless the user explicitly asks for branch work
- Create at least one local commit for each implemented task/write session
- Do NOT push directly to `main` and do NOT merge `main` locally from this skill
- Promote `development` to `main` via PR + merge only

After the subagent returns, update TASK-INDEX.md and move the task file.

### After Each Task

1. Update TASK-INDEX.md with the task's status
2. Move the task file to `done/`
3. If this is the 3rd task in the session, checkpoint and tell the user to continue in a new session

### TASK-INDEX.md Checkpoint Format

```markdown
| Task | Dev Status | Task QA | Final QA | Notes |
|------|-----------|---------|----------|-------|
| CORE-001 | Done | Pending | - | Report: done/CORE-001-report.md |
| CORE-002 | Done | Pending | - | Report: done/CORE-002-report.md |
| UI-001 | Pending | - | - | Next up |
```

## Task File Organization

Recommended directory structure:

```
docs/
├── tasks/
│   ├── TASK-INDEX.md       # Master list with dependencies
│   ├── CORE-001.md
│   ├── CORE-002.md
│   ├── UI-001.md
│   ├── UI-002.md
│   └── done/               # Move completed tasks here
│       ├── CORE-001.md
│       └── UI-001.md
```

## Execution Order

Process tasks in dependency order:

1. Check `TASK-INDEX.md` for the build order
2. Start with tasks that have no dependencies
3. Only start a task when all its dependencies are in `done/`

## Manual Execution Workflow

For each task in order:

```bash
# 1. Read the task file
cat {docs.tasks}/CORE-001.md

# 2. Execute Step 1 (implementation)
# Use the execution prompt template above

# 3. Execute Step 2 (self-QA)
# Use the self-QA prompt exactly as written

# 4. Verify completion
# Check that acceptance criteria are met

# 5. Move to done
mv {docs.tasks}/CORE-001.md {docs.tasks}/done/
```

## Automated Execution

For automated sequential execution, use the included script:

```bash
# Run all pending tasks in order
~/.cursor/skills/scorpio-execute/scripts/run-tasks.sh {docs.tasks}

# Run a specific task
~/.cursor/skills/scorpio-execute/scripts/run-tasks.sh {docs.tasks}/CORE-001.md
```

See [scripts/run-tasks.sh](scripts/run-tasks.sh) for the automation script.

## Task Completion Checklist

Before marking a task done:

- [ ] All acceptance criteria are addressed in the implementation
- [ ] Quality gates pass (lint, typecheck, test, build)
- [ ] Completion report written to `{docs.tasks}/done/[TASK-ID]-report.md`
- [ ] Task changes committed locally (or explicitly reported as already_complete with no new work)
- [ ] TASK-INDEX.md updated
- [ ] Task file moved to `done/` folder

## Handling Blocked Tasks

If a task cannot be completed:

1. Document the blocker in the task file
2. Add a `**Status**: BLOCKED` line with reason
3. Skip to the next task
4. Return to blocked tasks after blockers are resolved

```markdown
**Status**: BLOCKED
**Blocker**: Waiting for API credentials from external service
**Blocked Since**: 2024-01-15
```

## Error Recovery

If execution fails mid-task:

1. Note what was completed in the task file
2. Add partial progress markers to acceptance criteria
3. Resume from where you left off

```markdown
### Acceptance Criteria
- [x] Database schema created (DONE 2024-01-15)
- [~] API endpoints implemented (IN PROGRESS - /users done, /orders pending)
- [ ] UI components built
```

## Integration with Planning Skills

This skill is the execution layer for three planning workflows:

### Project Planning Workflow
```
scorpio-project-intake → scorpio-project-artifacts → scorpio-task-plan → scorpio-execute → task-review-final → task-triage-findings
```
For: New products, major modules, greenfield or brownfield projects

### Feature Development Workflow
```
scorpio-feature-intake → scorpio-feature-plan → scorpio-task-plan → scorpio-execute → task-review-final → task-triage-findings
```
For: Adding specific features to existing codebases

### Bug Fixing Workflow
```
scorpio-bug-intake → scorpio-bug-investigate → scorpio-task-plan → scorpio-execute → task-review-final → task-triage-findings
```
For: Investigating and fixing bugs with proper diagnosis

All three workflows produce task files compatible with scorpio-execute (`scorpio-execute`). After execution, tasks proceed to QA review.

## Quality Standards

Each task execution should:

- **Be atomic** - Complete one task fully before moving to the next
- **Be verifiable** - Each acceptance criterion can be checked
- **Leave no debris** - Clean up any temporary files or debug code
- **Be documented** - Changes are clear from the completion report

## Next Steps

After completing a batch of tasks:

1. Use **scorpio-qa** to validate each task's implementation (per-task code review + AC validation)
2. Use **scorpio-qa-final** for final-pass review (cross-task integration + UI testing)
3. Use **scorpio-qa-rework** to triage findings and generate rework tasks if needed

**Each of these should be a separate session** to manage context effectively.