Project Execution

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:

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:

# Write test that fails
def test_user_authentication():
    user = authenticate("user@example.com", "password")
    assert user.is_authenticated
# Run test → FAILS (feature not implemented)

Verification: Run pytest -v to verify tests pass.

GREEN Phase:

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

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

- [ ] 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:

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

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

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

# 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

Blocker Detection

Common Blockers:

• Failing tests that can't be fixed quickly
• Missing dependencies or APIs
• Technical unknowns requiring research
• Resource unavailability
• Scope ambiguity

Systematic Debugging

When blocked, apply debugging framework:

1. Reproduce: Create minimal reproduction case 2. Hypothesize: Generate possible causes 3. Test: Validate hypotheses one by one 4. Resolve: Implement fix or workaround 5. Document: Record solution for future

Escalation

When to escalate:

• Blocker persists > 2 hours
• Requires architecture change
• Impacts critical path
• Needs stakeholder decision

Escalation format:

## Blocker: [TASK-XXX] - [Issue]

**Symptom**: [What's happening]

**Impact**: [Which tasks/timeline affected]

**Attempted Solutions**:
1. [Solution 1] - [Result]
2. [Solution 2] - [Result]

**Recommendation**: [Proposed path forward]

**Decision Needed**: [What needs to be decided]

Verification: Run the command with --help flag to verify availability.

Quality Assurance

Definition of Done

Task is complete when:

• ✅ All acceptance criteria met
• ✅ All tests written and passing
• ✅ Code reviewed (self or peer)
• ✅ Linting passes with no warnings
• ✅ Type checking passes (if applicable)
• ✅ Documentation updated
• ✅ No known regressions
• ✅ Deployed to staging (if applicable)

Testing Strategy

Test Pyramid:

**Verification:** Run `pytest -v` to verify tests pass.
     /\
    /E2E\      Few, slow, expensive
   /------\
  /  INT  \    Some, moderate speed
 /----------\
/   UNIT    \  Many, fast, cheap

Verification: Run the command with --help flag to verify availability.

Per Task:

• Unit tests: Test individual functions/classes
• Integration tests: Test component interactions
• E2E tests: Test complete user flows (for user-facing features)

Velocity Tracking

Burndown Metrics

Track daily:

• Tasks remaining
• Story points remaining
• Days left in sprint
• Velocity (tasks or points per day)

Formulas:

**Verification:** Run `pytest -v` to verify tests pass.
Velocity = Tasks completed / Days elapsed
Estimated completion = Tasks remaining / Velocity
On track? = Estimated completion <= Sprint end date

Verification: Run the command with --help flag to verify availability.

Velocity Adjustments

If ahead of schedule:

• Pull in stretch tasks
• Add technical debt reduction
• Improve test coverage
• Enhance documentation

If behind schedule:

• Identify causes (blockers, underestimation)
• Reduce scope (drop low-priority tasks)
• Increase focus (reduce distractions)
• Request help or extend timeline

Exit Criteria

• [ ] All planned tasks are marked complete and the full test suite passes.
• [ ] A completion report is generated.
• [ ] Any rework, failed approach, or exhausted-retry blocker is recorded to

docs/lessons-learned.md as an open entry (a clean run needs none).

• [ ] No subsequent phase is auto-invoked (this is the terminal phase).

Related Skills

• Skill(superpowers:executing-plans) - Execution framework (if available)
• Skill(superpowers:systematic-debugging) - Debugging (if available)
• Skill(superpowers:test-driven-development) - TDD (if available)
• Skill(superpowers:verification-before-completion) - Validation (if available)
• Skill(attune:mission-orchestrator) - Full lifecycle orchestration

Related Agents

• Agent(attune:project-implementer) - Task execution agent

Related Commands

• /attune:execute - Invoke this skill
• /attune:execute --task [ID] - Execute specific task
• /attune:execute --resume - Resume from checkpoint

Mission Report

At mission completion, produce a Mission Report using the template from references/mission-report.md. The report documents:

• Mission identification: Links to brief, spec, plan
• Duration: Start, end, total time
• Outcome: success | partial | failed
• Delivered artifacts: Files created/modified/deleted
• Decisions: Key choices with rationale
• Validation evidence: Tests, reviews, demos
• Follow-ups: Recommended next steps

See references/mission-report.md for the full template and example reports for successful, partial, and failed missions.

Examples

See /attune:execute command documentation for complete examples.

Mission Report Template

Final mission report with artifacts, decisions, and evidence.

Purpose

The Mission Report is the definitive record of a completed mission. It documents what was delivered, why decisions were made, how success was validated, and what follow-up is needed. Use it to close missions and hand off to future maintainers.

When to Use

Generate a Mission Report when:

• A mission completes successfully (outcome: success)
• A mission is terminated early (outcome: partial or failed)
• User requests a final summary
• Handing off work to another agent or session
• Archiving for future reference

Do NOT generate when:

• The mission is still in progress (use Progress Report instead)
• The work was a single trivial change

Getting Started

1. Copy the template below 2. Fill required fields: mission, duration, outcome, delivered_artifacts, decisions, validation_evidence, follow_ups 3. Add optional lessons_learned, blockers_resolved, metrics if relevant 4. Store in mission archive or attach to PR/commit 5. Link from any related issues or discussions

Why This Pattern

Mission Reports create institutional memory. Without them, the rationale behind decisions decays: six months later, nobody remembers why a particular approach was chosen or what alternatives were considered.

The decisions field with alternatives_considered is especially valuable: it prevents future contributors from re-litigating settled questions without new information.

This pattern emerged from observing that teams with good documentation of "why" move faster than teams who must re-derive rationale from code archaeology.

Template

mission_report:
  # REQUIRED: Mission identification
  mission:
    name: "Implement user authentication"
    brief_ref: "docs/project-brief.md"
    spec_ref: "docs/specification.md"
    plan_ref: "docs/implementation-plan.md"

  # REQUIRED: Mission duration
  duration:
    start: "2024-03-20T09:00:00Z"
    end: "2024-03-20T14:30:00Z"
    total: "5h 30m"

  # REQUIRED: Mission outcome
  outcome: success | partial | failed

  # REQUIRED: What was delivered
  delivered_artifacts:
    - path: "src/auth/jwt.py"
      type: created | modified | deleted
      description: "JWT token generation and validation"
    - path: "src/api/middleware/auth.py"
      type: modified
      description: "Authentication middleware for protected routes"
    - path: "tests/auth/test_jwt.py"
      type: created
      description: "Unit tests for JWT module"

  # REQUIRED: Key decisions with rationale
  decisions:
    - decision: "Use RS256 algorithm for JWT signing"
      rationale: |
        Asymmetric encryption allows public key distribution for
        verification without exposing private key.
      alternatives_considered:
        - "HS256 (simpler but symmetric)"
        - "Opaque tokens (requires database lookup)"
      impact: "Requires key management infrastructure"

  # REQUIRED: How success was validated
  validation_evidence:
    - description: "All unit tests pass"
      evidence_type: test
      status: pass
      reference: "pytest tests/auth/ -v"
    - description: "Integration test covers full auth flow"
      evidence_type: test
      status: pass
      reference: "pytest tests/integration/test_auth.py"
    - description: "Security review completed"
      evidence_type: review
      status: pass
      reference: "docs/security-review.md"

  # REQUIRED: Recommended next steps
  follow_ups:
    - action: "Add refresh token rotation"
      priority: medium
      rationale: "Improves security posture"
      estimated_effort: small
    - action: "Implement token revocation"
      priority: low
      rationale: "Required for logout across devices"
      estimated_effort: medium

  # OPTIONAL: Lessons learned
  lessons_learned:
    - lesson: "Start with integration tests earlier"
      context: "Found integration issues late that required rework"
      application: "Write integration test first in future auth work"
    - lesson: "Document key rotation strategy before implementation"
      context: "Had to retrofit key management"
      application: "Include key rotation in initial design"

  # OPTIONAL: Blockers encountered
  blockers_resolved:
    - blocker: "API documentation was outdated"
      resolution: "Tested actual API behavior, updated tests"
      time_impact: "30 minutes"

  # OPTIONAL: Metrics
  metrics:
    files_changed: 5
    lines_added: 342
    lines_removed: 23
    tests_added: 12
    tests_passed: 12
    readiness_level_peak: 2

Example Reports

Example 1: Successful Feature Implementation

mission_report:
  mission:
    name: "Add rate limiting to API"
    brief_ref: "docs/project-brief-ratelimit.md"
    spec_ref: "docs/specification-ratelimit.md"
    plan_ref: "docs/implementation-plan-ratelimit.md"

  duration:
    start: "2024-03-19T10:00:00Z"
    end: "2024-03-19T15:30:00Z"
    total: "5h 30m"

  outcome: success

  delivered_artifacts:
    - path: "src/middleware/rate_limit.py"
      type: created
      description: "Token bucket rate limiter"
    - path: "src/api/routes.py"
      type: modified
      description: "Added rate limit decorator to endpoints"
    - path: "tests/middleware/test_rate_limit.py"
      type: created
      description: "Unit and integration tests"
    - path: "docs/api/rate-limiting.md"
      type: created
      description: "API documentation for rate limits"

  decisions:
    - decision: "Use Redis for distributed rate limiting"
      rationale: |
        Multiple API instances need shared state for accurate
        rate limiting. Redis provides atomic operations needed
        for token bucket algorithm.
      alternatives_considered:
        - "In-memory (doesn't work with multiple instances)"
        - "Database (too slow for rate limit checks)"
      impact: "Requires Redis in infrastructure"

    - decision: "Return 429 with Retry-After header"
      rationale: |
        Standard HTTP response for rate limiting. Retry-After
        helps clients implement backoff correctly.
      alternatives_considered:
        - "200 with error body (non-standard)"
      impact: "None, follows best practices"

  validation_evidence:
    - description: "Unit tests pass"
      evidence_type: test
      status: pass
      reference: "pytest tests/middleware/ -v"
    - description: "Load test shows correct rate limiting"
      evidence_type: test
      status: pass
      reference: "locust -f tests/load/rate_limit.py"
    - description: "Code review approved"
      evidence_type: review
      status: pass
      reference: "PR #123 approval"

  follow_ups:
    - action: "Add per-endpoint rate limit configuration"
      priority: medium
      rationale: "Some endpoints need different limits"
      estimated_effort: small
    - action: "Add rate limit metrics to monitoring"
      priority: high
      rationale: "Visibility into rate limit behavior"
      estimated_effort: small

  lessons_learned:
    - lesson: "Test with realistic request patterns"
      context: "Initial tests used uniform distribution, production
        has bursts"
      application: "Include burst scenarios in load tests"

  metrics:
    files_changed: 4
    lines_added: 287
    lines_removed: 12
    tests_added: 15
    tests_passed: 15
    readiness_level_peak: 1

Example 2: Partial Completion

mission_report:
  mission:
    name: "Migrate to new payment provider"
    brief_ref: "docs/project-brief-payment.md"
    spec_ref: "docs/specification-payment.md"
    plan_ref: "docs/implementation-plan-payment.md"

  duration:
    start: "2024-03-18T09:00:00Z"
    end: "2024-03-18T17:00:00Z"
    total: "8h 0m"

  outcome: partial

  delivered_artifacts:
    - path: "src/payments/new_provider.py"
      type: created
      description: "New payment provider integration (untested)"
    - path: "src/api/webhooks/payments.py"
      type: modified
      description: "Webhook handlers for new provider"
    - path: "docs/payment-migration-status.md"
      type: created
      description: "Migration status and remaining work"

  decisions:
    - decision: "Feature flag for gradual migration"
      rationale: |
        Cannot migrate all users at once. Feature flag allows
        testing with subset before full migration.
      alternatives_considered:
        - "Big bang migration (too risky)"
      impact: "Need to maintain both providers during transition"

  validation_evidence:
    - description: "Unit tests pass for new provider"
      evidence_type: test
      status: pass
      reference: "pytest tests/payments/ -v"
    - description: "Integration tests with sandbox"
      evidence_type: test
      status: fail
      reference: "Sandbox API returns unexpected errors"
    - description: "Webhook signature verification"
      evidence_type: test
      status: blocked
      reference: "Waiting on provider documentation"

  follow_ups:
    - action: "Resolve sandbox API issues"
      priority: critical
      rationale: "Blocks integration testing"
      estimated_effort: medium
    - action: "Complete webhook signature verification"
      priority: high
      rationale: "Security requirement"
      estimated_effort: small
    - action: "Run production migration with 1% traffic"
      priority: high
      rationale: "Validate real-world behavior"
      estimated_effort: small

  lessons_learned:
    - lesson: "Verify sandbox behavior matches production"
      context: "Sandbox API had different behavior than documented"
      application: "Request production access earlier"

  blockers_resolved:
    - blocker: "Provider API documentation incomplete"
      resolution: "Contacted provider support, received clarification"
      time_impact: "2 hours"

  metrics:
    files_changed: 3
    lines_added: 456
    lines_removed: 34
    tests_added: 8
    tests_passed: 5
    tests_failed: 2
    tests_blocked: 1
    readiness_level_peak: 2

Example 3: Failed Mission

mission_report:
  mission:
    name: "Upgrade database to PostgreSQL 16"
    brief_ref: "docs/project-brief-pg16.md"
    spec_ref: "docs/specification-pg16.md"
    plan_ref: "docs/implementation-plan-pg16.md"

  duration:
    start: "2024-03-17T14:00:00Z"
    end: "2024-03-17T16:30:00Z"
    total: "2h 30m"

  outcome: failed

  delivered_artifacts:
    - path: "docs/pg16-incompatibility-report.md"
      type: created
      description: "Analysis of PostgreSQL 16 incompatibilities"

  decisions:
    - decision: "Abort upgrade mission"
      rationale: |
        Critical incompatibility discovered: our ORM generates
        queries that are invalid in PG16. Fixing would require
        ORM upgrade which is out of scope.
      alternatives_considered:
        - "Proceed with ORM upgrade (estimated 2 weeks)"
        - "Rewrite affected queries manually (high risk)"
      impact: "Remain on PostgreSQL 15"

  validation_evidence:
    - description: "Incompatibility identified"
      evidence_type: test
      status: fail
      reference: "docs/pg16-incompatibility-report.md#L45"

  follow_ups:
    - action: "Schedule ORM upgrade project"
      priority: medium
      rationale: "Prerequisite for PostgreSQL 16"
      estimated_effort: large
    - action: "Review PostgreSQL 16 changelog for other changes"
      priority: low
      rationale: "Prepare for future upgrade"
      estimated_effort: small

  lessons_learned:
    - lesson: "Test major version upgrades earlier"
      context: "Found incompatibility 2.5 hours into mission"
      application: "Run compatibility tests before mission start"
    - lesson: "Check ORM compatibility matrix"
      context: "ORM didn't support PG16 at our version"
      application: "Verify all dependencies support target version"

  blockers_resolved: []

  metrics:
    files_changed: 1
    lines_added: 87
    lines_removed: 0
    tests_added: 0
    readiness_level_peak: 3

Required vs Optional Fields

Integration with Mission Orchestrator

The mission-orchestrator skill produces a Mission Report when:

1. All phases complete successfully (outcome: success) 2. Mission is terminated early (outcome: partial or failed) 3. User requests final report

Related References

• ../../mission-orchestrator/references/mission-charter.md - Original mission definition
• ../../mission-orchestrator/references/progress-report.md - Checkpoint reports during execution
• ../modules/mission-state.md - State persistence schema