context-os: Skill for Claude Code

Coordinated Agent Teams

Methodology for decomposing implementation specs into agent DAGs with verified coordination patterns. Prevents integration surprises through contract-first boundaries, evidence-based parallelism decisions, and independent verification.

Meta-Principle: "The coordination overhead must cost less than the parallelism saves. If the DAG plan takes longer to write than sequential execution would take, just build it sequentially."

---

When to Use This Skill

Apply this skill when:

• Implementation spec exists and needs decomposition into agent tasks
• 3+ agents will work on interdependent modules
• Parallel execution would save meaningful wall-clock time
• Work spans multiple context windows or worktrees
• Integration risk is high (multiple agents writing to connected systems)

Do NOT use for:

• Solo agent implementations (< 3 agents)
• Embarrassingly parallel work (no dependencies, e.g., batch processing)
• Exploratory work without a spec (use feature-planning first)
• Work that fits in a single context window

The tell: If you're drawing arrows between agents on a napkin, use this skill. If you can describe the build as "just do steps 1-5 in order," don't.

---

The Coordination Overhead Test (Run First)

Before planning ANY multi-agent build, answer honestly:

Total estimated agent-hours:        ___ hours
Estimated spec-writing time:        ___ hours
Estimated merge/integration time:   ___ hours
Coordination overhead:              ___ hours (spec + merge)

Sequential build time:              ___ hours (agent-hours, no parallelism)
Parallel build time:                ___ hours (critical path + coordination)

Is parallel faster?                 ___ yes/no
By how much?                        ___ hours saved

If coordination overhead > 30% of sequential build time → just build sequentially.

The LinkedIn Pipeline succeeded with sequential agents (~15 hours, zero context loss). A transcript processing build succeeded with ~15 parallel agents (minutes end-to-end). The difference: transcript processing was embarrassingly parallel (disjoint batches). Pipeline phases were interdependent (sequential was correct).