8.0 KiB
name, description
| name | description |
|---|---|
| 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:
- Discovery - Scan and inventory all artifacts
- Analysis - Extract concepts, map dependencies
- Synthesis - Create unified plan with normalized naming
- Cleanup - Archive superseded artifacts (non-destructively)
- 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 patternsbeads-multi-session-patterns.md- Multi-session work coordinationbeads-dependency-management.md- Managing task dependenciesbeads-context-strategies.md- Context management across sessions
Last Updated: 2025-10-27 Format Version: 1.0 (Atomic)