workflow-project-synthesis

Synthesize scattered project artifacts (plans, docs, tests, logs) into unified roadmap. Use when projects have accumulated sprawl across multiple planning documents, inconsistent naming, orphaned tests, or Beads issues out of sync with reality. Creates coherent execution plan while preserving research and maintaining referential integrity.

Project Synthesis

Transform projects with accumulated sprawl into clean, coherent execution plans without losing critical work.

When to Use

Use this skill when:

• Multiple competing or fragmented planning documents exist
• Tests and logs are scattered or orphaned
• Beads issues don't match current project reality
• Inconsistent naming schemes across artifacts
• Documentation has drifted from implementation

Don't use for:

• Greenfield projects (use standard Work Plan Protocol)
• Well-organized projects needing minor updates

Overview

Five-phase process:

1. Discovery - Scan and inventory all artifacts
2. Analysis - Extract concepts, map dependencies
3. Synthesis - Create unified plan with normalized naming
4. Cleanup - Archive superseded artifacts (non-destructively)
5. Validation - Verify integrity and test coverage

Phase 1: Discovery

Create Baseline

# Snapshot current state
git add . && git commit -m "Pre-synthesis snapshot" || true
export BASELINE_COMMIT=$(git rev-parse HEAD)

# Create synthesis workspace
mkdir -p .claude/synthesis/$(date +%Y%m%d_%H%M%S)
export SYNTHESIS_DIR=.claude/synthesis/$(date +%Y%m%d_%H%M%S)

# Run baseline tests
pkill -f "test" 2>/dev/null || true
./run_tests.sh > $SYNTHESIS_DIR/baseline-tests.log 2>&1 & wait $!
echo "Baseline: $BASELINE_COMMIT" > $SYNTHESIS_DIR/baseline.txt

Scan Project

# Find all planning artifacts
find . -type f \( -name '*plan*.md' -o -name '*roadmap*.md' -o -name '*spec*.md' \) \
  -not -path '*/node_modules/*' -not -path '*/.git/*'

# Find tests
find . -type f \( -name '*test*' -o -name '*spec*' \) \
  \( -name '*.py' -o -name '*.ts' -o -name '*.go' -o -name '*.rs' \) \
  -not -path '*/node_modules/*'

# Check Beads state
bd import -i .beads/issues.jsonl
bd list --json > $SYNTHESIS_DIR/beads-snapshot.json

Extract Concepts

Run python skills/workflow/project-synthesis/resources/scripts/extract_concepts.py to identify key concepts across all files:

• Class/function names from code
• Section headers from markdown
• Beads issue descriptions
• Critical architectural decisions

Output: $SYNTHESIS_DIR/concepts.json

Phase 2: Analysis

Build Dependency Graph

Map dependencies:

• Task dependencies (A must complete before B)
• Code dependencies (module A imports B)
• Beads blocked-by relationships
• Integration points (typed holes)

Output: $SYNTHESIS_DIR/dependencies.json

Identify Parallelization

Mark tasks that are:

• Truly independent (no shared state)
• Safe to execute concurrently
• Have clear integration points

Create Strategy Document

Document in $SYNTHESIS_DIR/strategy.md:

• Which artifacts to consolidate
• Key concepts to preserve
• Naming normalization plan
• Critical path
• Parallel streams

See skills/workflow/project-synthesis/resources/REFERENCE.md for strategy template.

Phase 3: Synthesis

Generate Unified Plan

Create plan.md with:

# Project Execution Plan

> Generated: [date]
> Baseline: [commit], tests passing
> Consolidated: [list source documents]

## Critical Path

### Phase 1: [Name] (Timeline)
- [ ] task-1-01-description
- [ ] task-1-02-description

### Phase 2: [Name] (Timeline)
- [ ] task-2-01-description

## Parallel Streams

### Stream A: [Name]
- [ ] task-a-01-description

## Dependencies
- task-2-01 depends on task-1-01, task-1-02

## Integration Points
- [Component A] ↔ [Component B]: Interface X

## Preserved Research
[Key findings from research documents]

Naming Standards

Apply consistently:

• Phases: phase-{n}-{name} (e.g., phase-1-foundation)
• Tasks: task-{phase}-{number}-{description} (e.g., task-1-01-setup-auth)
• Documents: plan.md, spec.md, test-plan.md, roadmap.md
• Beads: [PHASE-N] Task description

Update Beads

# Sync with unified plan
bd import -i .beads/issues.jsonl

# Archive obsolete issues
bd list --status done --json | jq -r '.[] | .id' | \
  xargs -I {} bd update {} --status archived --json

# Create issues from plan
grep '^\- \[ \] task-' plan.md | while read line; do
  task_id=$(echo "$line" | grep -oP 'task-\d+-\d+')
  desc=$(echo "$line" | sed 's/.*task-[0-9]+-[0-9]+-//')
  phase=$(echo "$task_id" | cut -d- -f2)
  bd create "[PHASE-$phase] $desc" --type feature --priority "$phase" --json
done

bd export -o .beads/issues.jsonl

Create Test Plan

Generate test-plan.md:

• Current coverage baseline
• Tests to preserve/update/archive
• New tests needed for unified plan
• Coverage targets by phase

Phase 4: Cleanup

Archive Non-Destructively

# Create archive structure
mkdir -p archive/{planning,research,tests,logs}

# Move superseded artifacts
for file in old-plan.md spec-v1.md; do
  mv "$file" "archive/planning/$(date +%Y%m%d)-$file"
done

# Move old logs
find . -name "*.log" -type f -mtime +7 -exec mv {} archive/logs/ \;

Critical: Create $SYNTHESIS_DIR/reference-map.json tracking all moves:

{
  "moved": [
    {"from": "old-plan.md", "to": "archive/planning/20251027-old-plan.md"}
  ]
}

Update References

Find and fix all references to moved files (scan markdown files for broken links).

Update Documentation

Update README.md with:

• Link to new plan.md
• Current phase and status
• Link to archive/ for history

Phase 5: Validation

Verify Integrity

# Test that nothing broke
pkill -f "test" 2>/dev/null || true
./run_tests.sh > $SYNTHESIS_DIR/post-synthesis-tests.log 2>&1 & wait $!
POST_TEST_STATUS=$?

# Compare with baseline
if [ $POST_TEST_STATUS -eq $BASELINE_TEST_STATUS ]; then
  echo "✅ Tests unchanged"
else
  echo "❌ Tests changed - investigate"
  exit 1
fi

Quality Gates

All must pass:

• [ ] Tests status unchanged from baseline
• [ ] All references valid (no broken links)
• [ ] Key concepts preserved in unified plan
• [ ] Naming normalized throughout
• [ ] Archive structure created with reference map
• [ ] Beads synchronized
• [ ] Documentation updated

Generate Report

Create $SYNTHESIS_DIR/SYNTHESIS-REPORT.md:

• What was consolidated
• What was archived
• Key concepts preserved
• Dependencies and sequencing
• Validation results
• Next steps

Commit

git checkout -b synthesis/cleanup-$(date +%Y%m%d)
git add plan.md test-plan.md README.md docs/ archive/ .beads/
git commit -m "Synthesis: unified plan and cleanup

Consolidated [N] docs, archived [N] superseded artifacts
Tests: passing, coverage unchanged
See: .claude/synthesis/[timestamp]/SYNTHESIS-REPORT.md"

git push -u origin synthesis/cleanup-$(date +%Y%m%d)

Bundled Scripts

The skill includes scripts in skills/workflow/project-synthesis/resources/scripts/:

• extract_concepts.py - Extract key concepts from all files

Run scripts with: python skills/workflow/project-synthesis/resources/scripts/<script-name>.py

Reference Documentation

For detailed guidance, see skills/workflow/project-synthesis/resources/REFERENCE.md which includes:

• Strategy Template - Structure for strategy document
• Troubleshooting Guide - Common issues and solutions
• Examples - Detailed examples of synthesis runs

Integration Notes

This synthesis operates at project level. After synthesis completes, resume normal Work Plan Protocol with the unified plan.md.

Synthesis preserves all multi-agent checkpoints and Beads state - no disruption to ongoing workflow.

---

Related Skills

• beads-workflow.md - Core Beads commands and session patterns
• beads-multi-session-patterns.md - Multi-session work coordination
• beads-dependency-management.md - Managing task dependencies
• beads-context-strategies.md - Context management across sessions

---

Last Updated: 2025-10-27 Format Version: 1.0 (Atomic)