ascent-task-coordinator

name

ascent-task-coordinator

description

Multi-agent coordination pattern for Claude Code acting as Project Manager. Use when orchestrating background agents for feature implementation, when Claude Code should delegate rather than implement, or when running parallel investigation/implementation tasks. Provides task-list.json structure, progress tracking format, and agent role definitions. Keeps Claude Code in "coordinator mode" - dispatching work to specialized agents rather than writing code directly.

Project Coordinator Skill

Purpose

This skill enables Claude Code to operate as a project manager that coordinates multiple background agents to complete features. Claude Code should NEVER implement code directly—only dispatch, verify, and track progress.

Process Overview

┌─────────────────────────────────────────────────────────────────┐
│                    COORDINATOR (Claude Code / Opus)             │
│                                                                 │
│  1. Read task-list.json                                         │
│  2. Find next eligible task (pending + deps complete)           │
│  3. Spawn background agent with minimal context                 │
│  4. Wait for completion                                         │
│  5. Run verification                                            │
│  6. Update progress-report.md                                   │
│  7. Repeat                                                      │
└─────────────────────────────────────────────────────────────────┘
                              │
          ┌───────────────────┼───────────────────┐
          ▼                   ▼                   ▼
   ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
   │ TypeScript  │     │   Swift     │     │    SQL      │
   │   Agent     │     │   Agent     │     │   Agent     │
   │  (Sonnet)   │     │  (Sonnet)   │     │  (Sonnet)   │
   └─────────────┘     └─────────────┘     └─────────────┘

Task List JSON Structure

See resources/task-list.schema.json for full schema.

Minimal Task Structure

{
  "id": 9,
  "title": "Fix BUG-001: Blackout Dates",
  "status": "pending",
  "execution_mode": "delegate",
  "agent_type": "ascent-typescript-agent",
  "depends_on": [1],
  "files_to_modify": ["src/constraints/availability.ts"],
  "test_file": "tests/unit/blackoutDates.test.ts",
  "context_doc": "investigation-reports/bug-001-blackout-dates.md",
  "verification_cmd": "npm test -- --grep 'blackout'"
}

Key Fields

Field	Purpose
status	"pending", "in_progress", "complete", "failed"
execution_mode	"delegate" (spawn agent), "human" (skip), "coordinator" (do yourself)
agent_type	Which specialized agent to spawn
depends_on	Task IDs that must be complete first
context_doc	Path to investigation report or spec (agent reads this)
verification_cmd	Command to run after agent completes

Progress Report Format

Keep it lean. See resources/progress-report.example.md.

# Progress: [Feature Name]
Updated: 2025-12-28 14:30

## Status: Batch 2 - P0 Fixes

## Completed
- [x] Task 1-8: Investigation (Batch 1)

## In Progress
- [ ] Task 9: Blackout Dates - in_progress (agent spawned 14:25)

## Up Next
- Task 10: Commitments

## Blockers
None

Spawning Agents

When spawning a background agent, provide a minimal prompt:

Task 9: Fix BUG-001 - Blackout Dates

Context: Read investigation-reports/bug-001-blackout-dates.md

Files to modify:
- packages/engine/src/core/constraints/availability.ts
- packages/engine/src/core/types.ts

Test file to create:
- packages/engine/tests/unit/blackoutDates.test.ts

Approach: TDD - write failing tests first, then implement fix

When done, run: npm test -- --grep 'blackout'

DO NOT include:

• Full investigation report contents
• Implementation details
• Code snippets
• Anything the agent can read from files

Verification Flow

Agent completes
      │
      ▼
Run verification_cmd
      │
      ├─── PASS ──→ Update status="complete", update progress-report.md
      │
      └─── FAIL ──→ Check error, decide:
                    - Retry with same agent
                    - Spawn different agent
                    - Flag for human review

Batch Execution

Tasks can be organized into batches for parallel/sequential execution:

"execution_strategy": {
  "batches": [
    {"ids": [1,2,3], "parallel": true, "name": "Investigation"},
    {"ids": [4,5], "parallel": false, "name": "Critical Fixes"}
  ]
}

• parallel: true → Spawn all agents at once
• parallel: false → Wait for each to complete before next

File Organization

All artifacts belong in the feature folder. Structure:

features/1-in-progress/[feature-name]/
├── feature-brief.md              # Source of truth
├── task-list.json                # Agent-readable tasks
├── progress.md                   # Human-readable status
├── investigation-reports/        # Context gathering outputs
│   └── bug-001-[short-name].md
└── verification-reports/         # Test/review outputs
    └── integration-test-results.md

Naming Convention

Pattern: [task-id]-[type]-[short-name].md

Artifact Type	Pattern	Example
Investigation	task-[id]-investigation-[topic].md	task-03-investigation-rest-days.md
Implementation notes	task-[id]-notes-[topic].md	task-09-notes-blackout-fix.md
Verification	task-[id]-verification-[scope].md	task-17-verification-integration.md
Review	task-[id]-review-[type].md	task-15-review-code.md

Rules

• No loose files - Every artifact goes in a subfolder or is named with task ID
• Feature folder only - Never create files outside the feature folder
• Link in progress.md - If you create a file, add link to progress report
• Prefer updating over creating - Add to existing report rather than new file

Token Efficiency

Be extremely token efficient when creating artifacts:

• Not every task needs an artifact - Only create artifacts when explicitly requested or when they provide essential context for future tasks
• Minimize token output - Use very brief summaries (2-3 sentences max) and 3-5 bullet points
• Skip obvious details - Don't document what's already clear from code or task description
• Combine related artifacts - Group multiple related findings into a single report rather than creating separate files
• Focus on decisions and blockers - Document why choices were made, not what was done (code shows that)

Progress Report Links

When artifacts are created, add to progress:

## Artifacts
- Task 3: [investigation-reports/task-03-investigation-rest-days.md]
- Task 17: [verification-reports/task-17-verification-integration.md]

Resources

• resources/task-list.schema.json - JSON schema for validation
• resources/task-list.example.json - Minimal working example
• resources/progress-report.example.md - Lean format template