Subagent-Driven Development (Shannon-Enhanced)

Overview

Execute plans with fresh subagent per task + quantitative quality gates.

Each task: Subagent implementation → Code review → Quality score → Advance if > 0.80.

Shannon enhancement: Numerical quality scoring, pattern learning from task history, MCP work tracking.

When to Use

Same-session task execution:

Staying in this session
Tasks mostly independent
Want continuous progress with quality gates
Plan already written and validated

Don't use when:

Need to review plan first
Tasks are tightly coupled
Plan needs revision

Quality Scoring (0.00-1.00)

Per-task scoring:

task_quality_score = (
  (implementation_completeness) * 0.4 +
  (test_coverage) * 0.35 +
  (code_review_score) * 0.25
)

Thresholds:

0.00-0.50: Needs major rework (Critical issues)
0.51-0.80: Has issues, fixable (Important issues)
0.81-0.95: Good, minor cleanup (Minor issues)
0.96-1.00: Excellent, ready to advance

Gate rule: Only advance to next task if task_quality_score > 0.80

The Process

1. Load Plan & Setup Tracking

# Serena metric initialization
plan_metadata = {
  plan_file: "path/to/plan.md",
  total_tasks: N,
  tasks_completed: 0,
  cumulative_quality_score: 0.0,
  estimated_completion_time: "X hours"
}

Create TodoWrite with all tasks, all in "pending" state.

2. Execute Task (Fresh Subagent)

Mark task as in_progress. Dispatch:

**Task N:** [task_name]
Implementation scope: [read task N from plan]

Requirements:
1. Implement exactly what task specifies
2. Write tests (TDD if task requires)
3. Verify all tests pass
4. Commit with conventional message
5. Report: what you implemented, test results, files changed

Work directory: [path]

Subagent reports implementation summary.

3. Code Review Gate

Dispatch code-reviewer with metrics:

# Review metrics (Serena)
review_context = {
  task_number: N,
  what_implemented: "[subagent report]",
  plan_requirement: "[task N from plan]",
  base_commit: "[SHA before task]",
  head_commit: "[SHA after task]",
  test_results: "[pass/fail counts]"
}

Reviewer returns: Strengths, Issues (Critical/Important/Minor), Assessment.

Calculate code_review_score:

code_review_score = (
  0.0 if critical_issues > 0 else (
    1.0 - (important_issues * 0.15) - (minor_issues * 0.05)
  )
)

4. Calculate Task Quality Score

task_quality_score = (
  implementation_completeness * 0.4 +  # Did they do what task asked?
  test_coverage * 0.35 +               # Tests > 80% code coverage?
  code_review_score * 0.25             # Review assessment score
)

Log to Serena with timestamp.

5. Gate Decision

IF task_quality_score > 0.80:
  ✓ ADVANCE: Mark complete, next task
ELSE:
  ⚠ NEEDS FIXES: Dispatch fix subagent
    "Fix issues from review: [list critical/important]"
    Re-review and recalculate score
    Loop until > 0.80

6. All Tasks Complete

After all tasks pass gates:

# Calculate cumulative metrics
cumulative_quality = average(all_task_quality_scores)
tasks_requiring_rework = count(tasks with score < 0.85 initially)

# Log to Serena for pattern learning
completion_metrics = {
  cumulative_quality_score: X.XX,
  tasks_completed: N,
  total_rework_cycles: R,
  average_quality_trend: "improving|stable|declining"
}

Dispatch final code-reviewer: "Review all completed tasks for integration readiness."

7. Finish Development

After final review passes:

I'm using the finishing-a-development-branch skill to complete this work.

Follow finishing-a-development-branch workflow.

Pattern Learning (Serena)

Track across plans:

Task types that consistently score > 0.90
Common issue patterns (missing tests, incomplete docs)
Rework cycles per task type
Average time per quality level

Use historical patterns to:

Predict which new tasks might need rework
Alert if task_quality_score declining (need different approach)
Estimate completion time more accurately
Identify high-risk task patterns

Metrics Checklist

Common Mistakes

❌ Skip code review between tasks ✅ Review every task before advancing

❌ Ignore task_quality_score, advance anyway ✅ Enforce quality gate > 0.80

❌ Don't track metrics ✅ Log all scores to Serena for learning

❌ Parallel implementation subagents (conflicts) ✅ One subagent at a time, sequential

Red Flags

Never:

Skip quality gate
Proceed with critical issues unfixed
Dispatch multiple implementation agents simultaneously
Advance without code review

Integration

Requires:

writing-plans - Creates plan file
requesting-code-review - Reviews each task
finishing-a-development-branch - Completes development

With:

testing-skills-with-subagents - Subagent tests its code
dispatching-parallel-agents - Could test code in parallel

Real-World Impact

Sample implementation (4 tasks):

Task 1: quality_score 0.92 ✓ advance
Task 2: quality_score 0.76 ⚠ rework → 0.88 ✓ advance
Task 3: quality_score 0.91 ✓ advance
Task 4: quality_score 0.85 ✓ advance
cumulative_quality: 0.89
1 task required rework
Pattern learning: Note task 2 type for future

subagent-driven-development