project-execution

What this skill does

## When To Use

- After planning phase completes
- Ready to implement tasks
- Need systematic execution with tracking
- Want checkpoint-based validation
- Executing task lists with dependencies
- Monitoring progress and velocity

## When NOT To Use

- No implementation plan exists (use `Skill(attune:project-planning)` first)
- Still planning or designing (complete planning phase before execution)
- Single isolated task (execute directly without framework overhead)
- Exploratory coding or prototyping (use focused development instead)

## Integration

**With superpowers**:
- Uses `Skill(superpowers:executing-plans)` for systematic execution
- Uses `Skill(superpowers:systematic-debugging)` for issue resolution
- Uses `Skill(superpowers:verification-before-completion)` for validation
- Uses `Skill(superpowers:test-driven-development)` for TDD workflow

**With imbue**:
- Uses `Skill(imbue:graduated-implementation)` at the ramp gate so
  each increment's ambition is earned by demonstrated understanding
  of the prior one, not ramped on completion alone

**Without superpowers**:
- Standalone execution framework
- Built-in checkpoint validation
- Progress tracking patterns

## Execution Framework

### Pre-Execution Phase

**Actions**:
1. Load implementation plan
2. Validate project initialized
3. Check dependencies installed
4. Review task dependency graph
5. Identify starting tasks (no dependencies)

**Validation**:
- ✅ Plan file exists and is valid
- ✅ Project structure initialized
- ✅ Git repository configured
- ✅ Development environment ready

### Task Execution Loop

**For each task in dependency order**:

```markdown
1. PRE-TASK
   - Verify dependencies complete
   - Review acceptance criteria
   - Create feature branch (optional)
   - Set up task context

2. IMPLEMENT (TDD Cycle)
   - Write failing test (RED)
   - Implement minimal code (GREEN)
   - Refactor for quality (REFACTOR)
   - Repeat until all criteria met

3. VALIDATE
   - All tests passing?
   - All acceptance criteria met?
   - Code quality checks pass?
   - Documentation updated?

4. RAMP GATE (before the next, more ambitious task)
   - Invoke Skill(imbue:graduated-implementation)
   - Demonstrate understanding of THIS increment, sized to stakes:
     low-stakes on the evidence gate (green tests plus a recorded
     tradeoff), high-stakes on the human explaining the diff unaided
   - On a clean demonstration, record it in the ramp ledger and
     mark the rung widened; below the band, hold and split the next
     task smaller instead of ramping

5. CHECKPOINT
   - Mark task complete IMMEDIATELY (do NOT batch)
   - Update execution state
   - Report progress
   - Identify blockers
```

**Task Completion Discipline**: Always call `TaskUpdate(taskId: "X", status: "completed")` right after finishing each task. Never defer completions to end of session.

**Verification:** Run `pytest -v` to verify tests pass.

### Post-Execution Phase

**Actions**:
1. Verify all tasks complete
2. Run full test suite
3. Check code quality metrics
4. Generate completion report
5. Prepare for deployment/release
6. Record lessons learned (see below)

### Record Lessons Learned (decision journal)

Implementation is where the honest lessons appear: the approach that had to be
reworked, the blocker that cost a day, the assumption from planning that did
not hold. Capture these in `docs/lessons-learned.md` now, blamelessly, instead
of letting them vanish into "done." Draft and confirm one entry per
substantive lesson:

- If leyline is installed, invoke `Skill(leyline:decision-journal)` and follow
  it to append a lesson entry: `what_happened`, `what_didnt_work`,
  `root_cause`, and a concrete `action`. Set `phase` to `execute`. Show the
  draft; append on confirmation (status starts `open`).
- Fallback (leyline absent): append to `docs/lessons-learned.md` by hand using
  the in-file ENTRY TEMPLATE; assign the next `LL-NNN` id.

Trigger this whenever execution involved rework, a failed approach, or a
blocker that exhausted the two-challenge / 3-attempt limit. A clean run with no
surprises needs no entry.

### Terminal Phase Notice

This is the **final phase** of the attune workflow. No auto-continuation occurs after execution completes. The workflow terminates here. Unlike brainstorming, specification, and planning phases, execution does NOT auto-invoke any subsequent phase.

## Task Execution Pattern

### TDD Workflow

**RED Phase**:
```python
# Write test that fails
def test_user_authentication():
    user = authenticate("[email protected]", "password")
    assert user.is_authenticated
# Run test → FAILS (feature not implemented)
```
**Verification:** Run `pytest -v` to verify tests pass.

**GREEN Phase**:
```python
# Implement minimal code to pass
def authenticate(email, password):
    # Simplest implementation
    user = User.find_by_email(email)
    if user and user.check_password(password):
        user.is_authenticated = True
        return user
    return None
# Run test → PASSES
```
**Verification:** Run `pytest -v` to verify tests pass.

**REFACTOR Phase**:
```python
# Improve code quality
def authenticate(email: str, password: str) -> Optional[User]:
    """Authenticate user with email and password."""
    user = User.find_by_email(email)
    if user is None:
        return None

    if not user.check_password(password):
        return None

    user.mark_authenticated()
    return user
# Run test → STILL PASSES
```
**Verification:** Run `pytest -v` to verify tests pass.

### Checkpoint Validation

**Quality Gates**:
```markdown
- [ ] All acceptance criteria met
- [ ] All tests passing (unit + integration)
- [ ] Code linted (no warnings)
- [ ] Type checking passes (if applicable)
- [ ] Documentation updated
- [ ] No regression in other components
```
**Verification:** Run `pytest -v` to verify tests pass.

**Automated Checks**:
```bash
# Run quality gates
make lint          # Linting passes
make typecheck     # Type checking passes
make test          # All tests pass
make coverage      # Coverage threshold met
```
**Verification:** Run `pytest -v` to verify tests pass.

## Progress Tracking

### Execution State

Save to `.attune/execution-state.json`:

```json
{
  "plan_file": "docs/implementation-plan.md",
  "started_at": "2026-01-02T10:00:00Z",
  "last_checkpoint": "2026-01-02T14:30:22Z",
  "current_sprint": "Sprint 1",
  "current_phase": "Phase 1",
  "tasks": {
    "TASK-001": {
      "status": "complete",
      "started_at": "2026-01-02T10:05:00Z",
      "completed_at": "2026-01-02T10:50:00Z",
      "duration_minutes": 45,
      "acceptance_criteria_met": true,
      "tests_passing": true
    },
    "TASK-002": {
      "status": "in_progress",
      "started_at": "2026-01-02T14:00:00Z",
      "progress_percent": 60,
      "blocker": null
    }
  },
  "metrics": {
    "tasks_complete": 15,
    "tasks_total": 40,
    "completion_percent": 37.5,
    "velocity_tasks_per_day": 3.2,
    "estimated_completion_date": "2026-02-15"
  },
  "blockers": []
}
```
**Verification:** Run `pytest -v` to verify tests pass.

### Progress Reports

**Daily Standup**:
```markdown
# Daily Standup - [Date]

## Yesterday
- ✅ [Task] ([duration])
- ✅ [Task] ([duration])

## Today
- 🔄 [Task] ([progress]%)
- 📋 [Task] (planned)

## Blockers
- [Blocker] or None

## Metrics
- Sprint progress: [X/Y] tasks ([%]%)
- [Status message]
```
**Verification:** Run the command with `--help` flag to verify availability.

**Sprint Report**:
```markdown
# Sprint [N] Progress Report

**Dates**: [Start] - [End]
**Goal**: [Sprint objective]

## Completed ([X] tasks)
- [Task list]

## In Progress ([Y] tasks)
- [Task] ([progress]%)

## Blocked ([Z] tasks)
- [Task]: [Blocker description]

## Burndown
- Day 1: [N] tasks remaining
- Day 5: [M] tasks remaining ([status])
- Estimated completion: [Date] ([delta])

## Risks
- [Risk] or None identified
```
**Verification:** Run the command with `--help` flag to verify availability.

## Blocker Management

###