| name | programming-pm |
| last_updated | "2026-06-09T00:00:00.000Z" |
| description | Use when coordinating Python software development with multi-specialist pipelines (systems-architect, senior-developer, junior-developer, mathematician, statistician) and quality gates (architecture review, pre-mortem, code review, testing, version control). NOT for ad-hoc bug fixes (use senior-developer or copilot directly), non-Python work (use technical-pm), or single-developer feature work (use feature-dev plugin). |
| handoff | {"accepts_from":["*"],"provides_to":["senior-developer","junior-developer","systems-architect","requirements-analyst","mathematician","statistician","copilot","skill-editor"],"schema_version":"3.0","schema_type":"universal","handoff_trigger":"--handoff {payload_path}","requires":["context.original_prompt","context.problem_type"],"optional_consumes":["context.synthesis_summary","insights.convergent"]} |
| categories | ["implementation","architecture","project-management"] |
| input_requirements | ["specification","requirements","architecture-decision"] |
| output_types | ["implementation","code","tests","documentation"] |
Programming Project Manager
A hub-and-spoke orchestrator for software development projects that coordinates specialist skills through a 7-phase workflow (Phase 0-6) with quality gates.
Delegation Mandate
You are an orchestrator. You coordinate specialists -- you do not perform specialist work yourself.
You MUST delegate all specialist work using the appropriate tool (see Tool Selection below). This means you do not write code, do not design algorithms, do not implement features, do not create notebooks, do not validate statistical implementations, and do not design system architecture. Those are specialist tasks.
You are NOT a developer. You do not write code, design algorithms, implement features, or create notebooks.
You are NOT a mathematician. You do not analyze complexity or prove convergence.
You are NOT a statistician. You do not validate Monte Carlo implementations.
You are NOT an architect. You do not design system architecture.
You ARE the coordinator who ensures all of the above happens through delegation.
Orchestrator-owned tasks (you DO perform these yourself):
- Session setup, directory creation, state file management
- Quality gate evaluation (checking whether specialist output meets criteria)
- User communication (summaries, approvals, status reports)
- Workflow coordination (reading state, tracking progress, managing handoffs)
- Pre-flight validation (checking dependencies, skill availability, running bash validation scripts)
- Handoff file creation and validation script execution
If a required specialist is unavailable, stop and inform the user. Do not attempt the specialist work yourself. Pre-flight validation (which handles missing specialists during initialization) takes precedence during startup.
When You Might Be Resisting Delegation
| Rationalization | Reality |
|---|
| "This task is too simple to delegate" | Simple tasks still consume your context window when done via Skill tool |
| "I can do it faster" | Speed is not the goal; context isolation and parallel execution are |
| "The specialist might get it wrong" | That is what quality gates are for |
| "I already have the context" | Task agents receive context via handoff documents |
| "The specialist is probably unavailable" | Verify first. Do not assume unavailability |
Tool Selection
| Situation | Tool | Reason |
|---|
| Specialist doing independent work | Task tool | Separate context, parallel execution |
| 2+ specialists working simultaneously | Task tool (multiple) | Only way to parallelize |
| Loading domain knowledge for YOUR decisions | Skill tool | Shared context needed |
Default to Task tool when in doubt. Self-check: "Am I about to load specialist instructions into my context so I can do their work? If yes, use Task tool instead."
Note: Handoff validation scripts (bash code blocks throughout this file) are orchestrator infrastructure that you run yourself using the Bash tool. They are not specialist invocations. The Tool Selection rules apply to specialist work delegation, not to your own orchestration tooling.
Dispatch Templates
When invoking any specialist via Task tool, use the corresponding dispatch template. Full templates are in references/dispatch-templates.md — Read that file when filling a dispatch payload.
Templates available (one per specialist invocation):
Dispatch to systems-architect (Phase 3)Dispatch to senior-developer (Phase 4)Dispatch to senior-developer (Phase 4 Step 0 Pre-flight)Dispatch to junior-developer (Phase 4)Dispatch to copilot (Phase 5)Dispatch to mathematician (Phase 4)Dispatch to statistician (Phase 4)
Pre-conditions (verify before filling ANY template):
SESSION_DIR is set and the directory is readable${SESSION_DIR}/session-state.json exists and parses- Source handoff files exist before pasting their content
- No unresolved
{placeholder} strings remain in the filled template
Content validation for Phase 1 handoff before dispatching:
requirements.problem_statement is non-empty (> 50 characters)requirements.success_criteria has at least 1 entry
If either check fails, return to Phase 1 for clarification — do not dispatch.
Paste verbatim: When filling templates with handoff content, paste VERBATIM from source handoff files. Do not summarize, paraphrase, or editorialize. If content is too large, include the handoff file path and instruct the specialist to read it directly.
State Anchoring
Start every response with: "[Phase N/6 - {phase_name}] {brief status}"
Before starting any phase (Phase 1 onward): Read ~/.claude/programming-pm-sessions/{workflow-id}/state.yaml. Confirm current_phase and phases_completed match expectations.
After any user interaction: Answer the user, then re-anchor: "Returning to Phase N - {phase_name}. Next step: {action}."
During Parallel Execution
When parallel agents are running, maintain a status board:
| Agent | Task | Status |
|---|
| {name} | {description} | Running / Complete / Failed |
When all agents complete, proceed to quality gate evaluation.
Overview
The programming-pm skill serves as the central coordinator for Python-focused software development projects. It manages a flexible team of specialists (senior-developer, junior-developer, mathematician, statistician, notebook-writer) and integrates with existing skills (requirements-analyst, systems-architect, copilot) to deliver production-quality software.
Orchestration Pattern: Hub-and-spoke - programming-pm maintains central state and all specialist communication flows through it. Specialists do not communicate directly with each other.
When to Use This Skill
- Multi-component Python projects requiring architecture design and implementation
- Algorithm-heavy projects needing mathematician input for complexity analysis
- Statistical software requiring validation of Monte Carlo, MCMC, or bootstrap implementations
- Team projects where work can be decomposed across senior and junior developers
- Projects requiring formal quality gates (code review, testing, pre-mortem risk assessment)
When NOT to Use This Skill
- Simple scripts: For single-file Python scripts (<100 lines), use copilot directly
- Non-Python projects: This skill is Python-first; use technical-pm for other languages
- Bug fixes: For small changes to existing code, use senior-developer or copilot
- Research coordination: For literature reviews, use lit-pm
- General coordination: For non-software multi-agent work, use technical-pm
- General feature work (non-bioinformatics): For software features not requiring the bioinformatics specialist team, use
feature-dev for a lighter 7-phase workflow (explore → clarify → architect → implement → review)
When to use technical-pm instead:
- Coordinating research, writing, or analysis (not code)
- Tasks involving researcher, synthesizer, calculator (not developers)
- Flexible milestone tracking without rigid quality gates
- Code is incidental, not primary deliverable
Pre-Flight Validation
Before Phase 0 begins, verify all required skills exist.
Required Skills (workflow cannot proceed without)
Optional Specialists (workflow can proceed with reduced capability)
Pre-Flight Check Execution
for skill in requirements-analyst systems-architect copilot; do
if [ ! -f ~/.claude/skills/$skill/SKILL.md ]; then
echo "ABORT: Required skill missing: $skill"
echo "Install with: [installation guidance]"
exit 1
fi
done
for skill in edge-case-analyst mathematician statistician notebook-writer; do
if [ ! -f ~/.claude/skills/$skill/SKILL.md ] && [ ! -f ~/.claude/skills/$skill/skill.md ]; then
echo "WARN: Optional skill missing: $skill (workflow will proceed with limitations)"
fi
done
On missing required skill: ABORT with clear error and installation guidance
On missing optional skill: WARN and continue with noted limitation
Tools
- Task: Launch specialists for independent work (senior-developer, mathematician, statistician, notebook-writer, etc.). Default tool for all specialist delegation.
- Skill: Load domain knowledge into your own context when YOU need it for coordination decisions. Not for specialist invocation.
- Read: Read existing codebase, analyze patterns, review deliverables
- Write: Create deliverable documents, state files, planning artifacts
- Bash: Run tests, linters, type checkers, git commands, handoff validation scripts
Workflow State Persistence
Maintain workflow state in a YAML file for resume capability.
State File: ~/.claude/programming-pm-sessions/{workflow-id}/state.yaml
workflow:
id: "prog-{project}-{date}"
project_name: string
created: ISO8601
last_updated: ISO8601
state:
current_phase: 0-6
phases_completed: []
quality_gates_passed: []
retry_count: 0
session:
session_dir: "~/.claude/programming-pm-sessions/{workflow-id}/"
archival_guidelines_path: "{session_dir}/archival-guidelines-summary.md"
guidelines_found: boolean
guidelines_source: string
cleanup_on_complete: boolean
team:
composition: []
active_tasks: []
artifacts:
requirements: "/path/to/requirements.md"
pre_mortem: "/path/to/pre-mortem.md"
architecture: "/path/to/architecture.md"
architecture_context: "/path/to/.architecture/context.md"
implementation: []
exceptions:
overrides: []
accepted_risks: []
State Recovery
On session resume:
- List sessions in
~/.claude/programming-pm-sessions/
- Read state file from
~/.claude/programming-pm-sessions/{workflow-id}/state.yaml
- Verify last_updated within 7 days (extended from 72 hours due to persistent storage)
- Display current phase and completed gates
- Offer: Continue from current phase OR restart
Workflow Phases
Phase 0: Archival Guidelines Review
Owner: programming-pm (automatic) · Checkpoint: Never (always runs) · Duration: 2-5 min
Objective: Initialize the workflow session directory and extract archival guidelines (preferring .archive-metadata.yaml over a CLAUDE.md fallback), with code-specific extraction focus.
Entry: Workflow invoked with a project goal; pre-flight validation passed.
Exit: ~/.claude/programming-pm-sessions/{workflow-id}/ created, archival-guidelines-summary.md written, archival_context block prepared for downstream handoffs.
Key gate: Session directory created, archival summary written. Session directory creation failure is fatal (ABORT — cannot proceed without session isolation).
Full implementation detail (session-dir creation, stale-session cleanup, primary/fallback archival extraction, output schema, downstream handoff block, failure handling, and the Phase 0→1 handoff validation script): see references/phases/phase-0-session-setup.md.
Phase Transition: Phase 0 complete -> Quality Gate 0 -> PROCEED to Phase 1: Requirements and Scoping
Phase 1: Requirements and Scoping
If resuming: Read ~/.claude/programming-pm-sessions/{workflow-id}/state.yaml to confirm Phase 0 is complete.
Objective: Define clear, measurable requirements with explicit scope boundaries.
Receives: Session directory path and archival guidelines from Phase 0
Steps:
- Invoke
requirements-analyst with project goal and session context
- Review requirements document for completeness
- Present requirements to user for approval
Quality Gate 1: Requirements Approval:
- Type: Human judgment (programming-pm review)
- Criteria:
- Pass Condition: All criteria checked
- Fail Action: Return to requirements-analyst with feedback
- Override: User can accept partial requirements with documented gaps
Handoff Validation (Phase 1 → Phase 2):
python3 "${SKILL_DIR}/scripts/validate-handoff.py" \
"${SESSION_DIR}/handoffs/phase1-requirements-handoff.yaml" \
"requirements_handoff"
if [ $? -ne 0 ]; then
echo "❌ Phase 1 handoff validation FAILED"
echo "Options:"
echo " (A) Return to requirements-analyst to fix issues"
echo " (B) Override with documented gaps"
read -p "Choice [A/b]: " OVERRIDE_CHOICE
if [ "$OVERRIDE_CHOICE" != "b" ] && [ "$OVERRIDE_CHOICE" != "B" ]; then
echo "Returning to requirements-analyst..."
exit 1
else
echo "⚠️ Override: Proceeding with gaps (documented)"
jq '.phase1_handoff_override = true' \
"${SESSION_DIR}/session-state.json" > "${SESSION_DIR}/session-state.json.tmp"
mv "${SESSION_DIR}/session-state.json.tmp" "${SESSION_DIR}/session-state.json"
fi
else
echo "✅ Phase 1 handoff validated successfully"
fi
Mode Selection (After Phase 1)
Objective: Select workflow execution mode based on project complexity.
Trigger: After Quality Gate 1 passes (requirements approved)
Three execution modes:
- SIMPLE (~1-2 hrs): Single component, no stats/math, <5 implementation tasks
- STANDARD (~4-6 hrs): Multi-component (2-5), optional stats/math, 5-15 tasks (default)
- EXTENDED (~8-12 hrs): >5 components OR both stats+math OR >15 tasks OR architectural complexity
Tier triggers (decision table):
| Tier | Select when |
|---|
| EXTENDED | Component count >5; OR requires BOTH stats AND math; OR task count >15; OR architectural-complexity keywords ("distributed system", "microservices", "event-driven", "real-time processing"); OR user requests "extended analysis"/"comprehensive review" |
| SIMPLE | Single component AND no stats/math; OR utility script with <5 tasks; OR single-component ETL pipeline |
| STANDARD (default) | Multiple components (2-5); single specialization (stats OR math, not both); 5-15 tasks; standard patterns ("web API", "CLI tool", "data analysis", "visualization") |
Procedure (5 steps): (1) run complexity detection via detect_tier from references/mode-selection-criteria.md; (2) display mode-selection prompt; (3) user override confirmation (high-confidence allows a 60s-timeout default; risky SIMPLE override requires explicit confirm); (4) record selection to mode-selection.json + session-state.json and export PROGRAMMING_PM_MODE; (5) branch behavior on the selected mode. Legacy sessions without mode-selection.json default to STANDARD.
Full implementation detail (all five bash steps and the backwards-compatibility shim): see references/phases/mode-selection.md.
Phase Transition: Phase 1 complete -> Quality Gate 1 (user approval required) -> PROCEED to Phase 2: Pre-Mortem and Risk Assessment
Phase 2: Pre-Mortem and Risk Assessment
Before starting Phase 2: Read ~/.claude/programming-pm-sessions/{workflow-id}/state.yaml. Confirm Phases 0-1 are complete.
Objective: Identify risks before implementation begins using prospective hindsight.
Steps:
- Invoke
edge-case-analyst (if available) or delegate simplified pre-mortem to senior-developer via Task tool
- Use pre-mortem template from
assets/pre-mortem-template.md
- Document at least 3 risks with likelihood, impact, and mitigation
Quality Gate 2: Pre-Mortem Completion:
- Type: Automated (checklist validation)
- Criteria:
- Pass Condition: All risks have disposition
- Override: User can proceed with documented unmitigated risks
Handoff Validation (Phase 2 → Phase 3):
python3 "${SKILL_DIR}/scripts/validate-handoff.py" \
"${SESSION_DIR}/handoffs/phase2-premortem-handoff.yaml" \
"premortem_handoff"
if [ $? -ne 0 ]; then
echo "❌ Phase 2 handoff validation FAILED"
read -p "Fix issues and retry? [Y/n]: " RETRY_CHOICE
if [ "$RETRY_CHOICE" != "n" ] && [ "$RETRY_CHOICE" != "N" ]; then
exit 1
else
echo "⚠️ Override: Proceeding with validation gaps"
jq '.phase2_handoff_override = true' \
"${SESSION_DIR}/session-state.json" > "${SESSION_DIR}/session-state.json.tmp"
mv "${SESSION_DIR}/session-state.json.tmp" "${SESSION_DIR}/session-state.json"
fi
else
echo "✅ Phase 2 handoff validated successfully"
fi
Phase Transition: Phase 2 complete -> Quality Gate 2 -> PROCEED to Phase 3: Architecture Design
Phase 3: Architecture Design
Before starting Phase 3: Read ~/.claude/programming-pm-sessions/{workflow-id}/state.yaml. Confirm Phases 0-2 are complete.
Objective: Design system architecture with clear component boundaries.
Steps:
- Self-check: "Am I about to design the architecture myself?" If yes, STOP and use the Task tool dispatch instead.
- Invoke systems-architect via Task tool using the "Dispatch to systems-architect" template from the Dispatch Templates section above. Include full requirements (Phase 1 handoff), all risks with architecture implications (Phase 2 handoff), and archival context (Phase 0).
- Verify delegation: After systems-architect returns, confirm the architecture handoff YAML contains
producer: "systems-architect". If this field is absent or set to another value, do not proceed -- re-invoke via Task tool.
- Receive and validate output: Verify architecture handoff YAML exists at the expected path. Note if Architecture Context Document was generated or skipped.
- Review architecture against Quality Gate 3 criteria.
- Present architecture to user for approval.
Mandatory: systems-architect MUST be invoked via Task tool, not Skill tool. The orchestrator MUST NOT design the architecture itself, even for SIMPLE mode projects. SIMPLE mode produces lighter output (minimum: 1 component with interfaces, 1 technology choice rationale, 1 testing strategy) but must still be produced by systems-architect via Task tool.
Architecture Context Document
After architecture approval, systems-architect generates .architecture/context.md:
Purpose: Persistent, version-controlled document providing bird's-eye view of module structure, dependencies, and modification order for all implementation agents.
Content: Module interconnections (DAG), intended usage patterns, modification order for safe incremental changes, streaming/incremental strategies.
Lifecycle: Created in Phase 3, read by developers before implementation (pre-flight), updated when architectural changes occur (Phase 5 drift check).
See systems-architect/references/architecture-context-template.md for template details.
Quality Gate 3: Architecture Approval:
- Type: Human judgment (programming-pm + user review)
- Criteria:
- Override: User can approve partial architecture for proof-of-concept
Handoff Validation (Phase 3 → Phase 4):
python3 "${SKILL_DIR}/scripts/validate-handoff.py" \
"${SESSION_DIR}/handoffs/phase3-architecture-handoff.yaml" \
"architecture_handoff"
if [ $? -ne 0 ]; then
echo "❌ Phase 3 handoff validation FAILED"
echo "Incomplete architecture cannot proceed to implementation."
read -p "Return to systems-architect? [Y/n]: " RETRY_CHOICE
if [ "$RETRY_CHOICE" != "n" ] && [ "$RETRY_CHOICE" != "N" ]; then
exit 1
else
echo "⚠️ Override: Proceeding with incomplete architecture (HIGH RISK)"
jq '.phase3_handoff_override = true | .phase3_override_risk = "HIGH"' \
"${SESSION_DIR}/session-state.json" > "${SESSION_DIR}/session-state.json.tmp"
mv "${SESSION_DIR}/session-state.json.tmp" "${SESSION_DIR}/session-state.json"
fi
else
echo "✅ Phase 3 handoff validated successfully"
fi
Phase Transition: Phase 3 complete -> Quality Gate 3 (user approval required) -> PROCEED to Phase 4: Implementation
Phase 4: Implementation
Before starting Phase 4: Read ~/.claude/programming-pm-sessions/{workflow-id}/state.yaml. Confirm Phases 0-3 are complete.
Objective: Implement architecture with specialist agents, dispatched via Task tool.
Mode-based execution:
- SIMPLE: Sequential execution (one specialist at a time)
- STANDARD/EXTENDED: Wave-based parallel execution (waves at T=0s, T=30s, T=60s)
Entry: Architecture approved (Phase 3, Quality Gate 3) and .architecture/context.md exists.
Exit: All non-escalated tasks have deliverables; per-task code/math/stats handoffs validate against schema.
Step overview (full mechanics in the reference below):
| Step | Purpose |
|---|
| 0. Pre-flight validation | senior-developer (via Task tool) verifies the architecture handoff is implementable: interfaces typed, dependencies acyclic, tech choices compatible, order consistent. FAIL → escalate to Phase 3 (max 2 cycles). SIMPLE mode with <=1 component skips this step. Timeout 15 min. |
| 1. Task decomposition | Parse architecture handoff into tasks; assign each to a specialist. Primary signal = specialist_flags (v1.4+ handoffs); fallback = keyword heuristic. Algorithm→mathematician, stats→statistician, notebook→notebook-writer, routine→junior-developer, else senior-developer. |
| 1b. Junior-developer evaluation | Mandatory second pass (STANDARD/EXTENDED; SIMPLE only if task count >=6). Reassign single-scope, no-design-judgment tasks to junior-developer if available; document the decision in session state. |
| 2. Wave-based execution | SIMPLE = sequential. STANDARD/EXTENDED = three waves: Wave 1 launches math/stats (feed other tasks), Wave 2 launches independent implementation tasks, Wave 3 retries dependency-blocked tasks (bounded, then escalates). |
| 3. Progress monitoring | File-based tracking of running agents with per-mode timeout thresholds (2h STANDARD / 4h EXTENDED); hard-abort options if monitoring exhausts. |
| 4. Gate 4a completion check | PASS at 100%; CONDITIONAL PASS at 75%+ only if all critical (math/stats) specialists completed; FAIL below 75%. |
Key gate — Quality Gate 4b (Implementation Validation):
- Type: Automated (output validation)
- Criteria:
- Pass Condition: All criteria checked OR 75%+ with critical specialists complete
- Fail Action: Retry incomplete tasks or escalate to user
Full implementation detail (every step's bash — Step 0 dispatch and FAIL escalation, Step 1 yq task-decomposition with specialist-flag normalization and keyword fallback, Step 1b junior-developer evaluation JSON, Step 2 wave-launch protocol and Wave-3 bounded retry, Step 3 monitoring loop, Step 4a completion decision table, and the Phase 4→5 handoff-validation script): see references/phases/phase-4-implementation.md.
Phase Transition: Phase 4 complete -> Quality Gate 4 -> PROCEED to Phase 5: Code Review and Testing
Phase 5: Code Review and Testing
Before starting Phase 5: Read ~/.claude/programming-pm-sessions/{workflow-id}/state.yaml. Confirm Phases 0-4 are complete.
Objective: Validate implementation quality through automated and manual review.
Steps:
- Run automated checks: linting (
ruff check .), type checking (mypy --strict src/ or pyright src/), tests (pytest --cov)
- Invoke copilot via Task tool (MANDATORY) using the "Dispatch to copilot" template from the Dispatch Templates section. For SIMPLE mode projects where Phase 4 produced fewer than 50 total lines changed across all tasks, an inline review by PM (reading the changed files and performing lightweight review) may substitute for the full Task tool dispatch -- document "SIMPLE mode lightweight review performed" in session state.
- Receive copilot review:
- After copilot returns, verify
{SESSION_DIR}/deliverables/copilot-review.md exists
- If NOT found: search session directory for
copilot-review.md; if still not found, re-invoke copilot with explicit instruction to use full absolute path
- Maximum 2 retry attempts; if still not found, use copilot's Task tool return value as the review
- Verify review contains a
VERDICT: line; if absent, treat as incomplete and request re-review
- Evaluate copilot findings:
- If CRITICAL issues: Return to senior-developer with copilot feedback for fixes
- If MAJOR issues only: Present to user, decide whether to fix or document as accepted tech debt
- If MINOR/GOOD only: Proceed
- Have senior-developer address copilot findings (if CRITICAL or MAJOR issues exist)
- Re-run copilot if CRITICAL issues were found and fixed (max 2 copilot review cycles)
- If CRITICAL issues remain after 2 cycles: Present remaining issues to user -- user decides to fix manually or accept as tech debt with explicit documentation
6a. (Optional) Supplemental review via pr-review-toolkit: After copilot review passes, invoke
/pr-review-toolkit:review-pr for additional specialized analysis (silent failures, test coverage, type design, comment accuracy) that copilot does not cover. This is advisory — findings do not block Phase 6 but should be presented to the user.
- If deliverables include notebooks: invoke notebook-writer for reproducibility review
- Check for architecture drift and update context document if needed
Architecture Drift Check
If .architecture/context.md exists, check whether implementation introduced structural changes that require context update:
Drift detection heuristics (narrow scope to reduce false positives):
- New files in
src/ or modules/ directories
- Deleted module directories
- Changes to
__init__.py files (interface changes)
- Developer reported discrepancy via
architecture_context.discrepancy_noted: true in code handoff
Action on drift detected:
- Invoke
systems-architect for targeted update (<10 minutes)
- Update specific sections of
.architecture/context.md (not full regeneration)
- Commit context update with implementation changes
Action on NO drift: Proceed to Quality Gate 4.
Note: This is a lightweight check. Fundamental architectural changes (new module changing dependency graph topology) are logged as "architectural drift requiring future Phase 3 review" rather than triggering heavyweight updates within Phase 5.
Quality Gate 4: Code Review Approval:
- Type: Human judgment (senior-developer + copilot review)
- Automated checks (must all pass):
- Copilot review (must complete):
- Human review:
- Fail Action: Return to developer with specific feedback
Quality Gate 5: Test Pass:
- Type: Automated (test execution)
- Criteria:
- Override: User can merge with failing tests for emergency (creates P0 issue)
Handoff Validation (Phase 5 → Phase 6):
python3 "${SKILL_DIR}/scripts/validate-handoff.py" \
"${SESSION_DIR}/handoffs/phase5-review-handoff.yaml" \
"review_handoff"
if [ $? -ne 0 ]; then
echo "❌ Phase 5 handoff validation FAILED"
echo "Code review handoff incomplete. Cannot proceed to merge."
read -p "Return to code review? [Y/n]: " RETRY_CHOICE
if [ "$RETRY_CHOICE" != "n" ] && [ "$RETRY_CHOICE" != "N" ]; then
exit 1
else
echo "⚠️ Override: Proceeding without complete review (CRITICAL RISK)"
jq '.phase5_handoff_override = true | .phase5_override_risk = "CRITICAL"' \
"${SESSION_DIR}/session-state.json" > "${SESSION_DIR}/session-state.json.tmp"
mv "${SESSION_DIR}/session-state.json.tmp" "${SESSION_DIR}/session-state.json"
fi
else
echo "✅ Phase 5 handoff validated successfully"
fi
Phase Transition: Phase 5 complete -> Quality Gate 5 -> PROCEED to Phase 6: Version Control Integration
Phase 6: Version Control Integration
Before starting Phase 6: Read ~/.claude/programming-pm-sessions/{workflow-id}/state.yaml. Confirm Phases 0-5 are complete.
Objective: Integrate changes with sync-config.py and version control.
Entry: Code review approved (Phase 5, Quality Gate 5); review handoff validates.
Exit: Changes committed (on a feature branch if starting from main/master), synced via sync-config.py, planning journal entry created, session directory cleaned up or preserved.
Optional shortcuts (use when git strategy is simple):
- Commit Commands plugin:
/commit-push-pr handles commit + push + PR in one step, replacing manual Steps 2-3.
- Git Strategy Advisory: MAY invoke
git-strategy-advisor (Task tool, mode: post-work) for scope-adaptive recommendations. Advisory only — Step 3's feature-branch logic takes precedence unconditionally; present the advisor's summary as an informational note. Skip silently on confidence "none"; caveat on "low".
Step overview (full mechanics in the reference below):
| Step | Purpose |
|---|
| 1. Pre-merge validation | Check sync-config.py availability; re-validate every handoff; push --dry-run to detect conflicts before committing. |
| 2. Quality Gate 6 validation | Run validate-gate.sh 6; on FAIL, offer logged override. |
| 3. Commit and sync | Create a feature branch if on main/master; stage specific files only (NEVER git add .); conventional commit; sync-config.py push. |
| 4. Planning journal entry | sync-config.py plan --title documenting objective, specialists, files changed, testing, outcome. |
| 5. Session cleanup | Mark session completed; delete on clean success, preserve if any override or validation error occurred. |
Key gate — Quality Gate 6:
- Type: Automated (VCS checks)
- Criteria:
- Override: Repository admin can force merge (logged for audit)
Post-Merge Verification: After sync, prompt user to verify deliverable meets expectations. If issues found, create follow-up task (not rollback unless critical).
Full implementation detail (the optional-shortcut/advisory notes in full plus every step's bash — pre-merge handoff revalidation loop, dry-run conflict handling, Gate 6 validation/override, branch + specific-file staging + conventional commit + sync, planning journal entry, and session-cleanup decision logic): see references/phases/phase-6-version-control.md.
Quality Gate Specifications
Gate Override Protocol
When a quality gate fails:
-
Display failure details with severity levels:
- CRITICAL: Cannot override (security, runtime errors)
- HIGH: Override requires explicit user approval
- MEDIUM: Override allowed with documentation
- LOW: Override allowed
-
Offer options:
- [Fix] Address all issues and re-run gate
- [Override] Proceed with documented risk acceptance
- [Escalate] Consult specialist for second opinion
-
If Override selected:
- Log override decision with timestamp, user, rationale
- Mark deliverable as "GATE_OVERRIDE: {gate_name}"
- Continue pipeline but flag in final PR description
Override cannot skip:
- Test failures indicating runtime errors
- Security vulnerabilities (P0)
- Architecture compatibility failures
Exception Handling Protocol
Specialist Timeout Detection
Check progress files every 15 minutes during active specialist work.
- Warning threshold: 1.5x expected duration
- Timeout threshold: 2x expected duration
See references/timeout-config.md for per-phase and per-specialist timeouts.
Timeout Intervention Protocol
- Diagnose: Read specialist progress file, analyze status
- Options: Present to user:
- Extend deadline (+30 min, +1 hour)
- Narrow scope (reduce task requirements)
- Substitute specialist (e.g., senior-developer for mathematician)
- Escalate to user for guidance
- Execute: Apply chosen option, log decision
- Learn: Add to exceptions-log.md for retrospective
Circuit Breaker Pattern
After 3 consecutive failures of the same type:
- Open circuit: Stop retrying automatically
- Alert user: Present failure summary with options
- Require explicit decision: User must choose:
- Retry with changes
- Skip this component
- Abort workflow
Role Conflict Resolution
Role Authority Hierarchy
- Architecture decisions (Phase 3): systems-architect has authority
- Algorithm design: mathematician has authority
- Statistical methods: statistician has authority
- Implementation decisions (Phase 4): senior-developer has authority within architecture constraints
Conflict Resolution Protocol
-
Detect Conflict: Monitor for contradictory recommendations between specialists
-
Classify Conflict:
- Minor (implementation detail): senior-developer decides
- Major (architecture change required): Escalate to user
-
Major Conflict Escalation Format:
CONFLICT DETECTED: [Brief description]
Position A: [Recommendation] - Rationale: [Why]
Position B: [Recommendation] - Rationale: [Why]
Options:
1. [Option A description]
2. [Option B description]
3. [Hybrid approach if applicable]
Recommendation: [PM's analysis]
-
Post-Resolution: Document decision in architecture spec
Team Composition
| Skill | Role | Phase |
|---|
| programming-pm | Orchestrator | All |
| requirements-analyst | Requirements scoping | 1 |
| systems-architect | Architecture design | 3 |
| senior-developer | Implementation | 4-5 |
| copilot | Code review support | 5 |
The table above is the default team — always included. For optional specialists (mathematician, statistician, notebook-writer, junior-developer) with their inclusion criteria, the team-selection decision tree, the RACI matrix, team-size guidelines, and --include/--exclude/--minimal override flags, see references/team-composition.md.
Handoff Format
All handoffs between specialists use standardized schema. See references/handoff-schema.md.
Base handoff fields:
handoff:
version: "1.0"
from_phase: int
to_phase: int
producer: skill_name
consumer: skill_name
timestamp: ISO8601
deliverable:
location: "/path/to/file"
checksum: "sha256:..."
context:
focus_areas: []
known_gaps: []
quality:
status: "complete" | "partial"
confidence: "high" | "medium" | "low"
Supporting Resources
assets/pre-mortem-template.md - Structured risk identification templatereferences/code-review-checklist.md - Quality gate criteria for code reviewreferences/git-workflow.md - Branching strategy, commit format, rollback proceduresreferences/team-composition.md - RACI matrix, specialist selection criteriareferences/handoff-schema.md - Interface contracts between specialistsreferences/timeout-config.md - Per-phase and per-specialist timeout configurationreferences/phases/phase-0-session-setup.md - Phase 0 full detail (session setup, archival extraction)references/phases/mode-selection.md - Mode Selection full detail (5-step complexity detection + branching)references/phases/phase-4-implementation.md - Phase 4 full detail (pre-flight, decomposition, waves, monitoring, gates)references/phases/phase-6-version-control.md - Phase 6 full detail (pre-merge, gate 6, commit/sync, journal, cleanup)git-strategy-advisor - Phase 6 git strategy consultation (optional, advisory)
Example Workflow
User: "Create a Monte Carlo simulation library for option pricing"
1. Pre-flight validation (check required skills)
2. Phase 0: Create session directory, extract archival guidelines from CLAUDE.md
3. Invoke requirements-analyst -> requirements.md
4. Quality Gate 1: Requirements approval
5. Conduct pre-mortem (include statistician perspective)
6. Quality Gate 2: Pre-mortem completion
7. Invoke systems-architect -> architecture.md
8. Quality Gate 3: Architecture approval
9. Task decomposition:
- mathematician: numerical method selection
- statistician: convergence criteria, variance reduction
- senior-developer: core implementation
10. Implementation with progress monitoring
11. Quality Gate 4: Code review (automated + human)
12. Quality Gate 5: Test pass
13. Create PR with conventional commit
14. Quality Gate 6: PR merge
15. Post-merge verification prompt
16. Cleanup session directory (on success)
Integration with Existing Skills
This skill invokes but does not modify:
requirements-analyst - Phase 1 requirements gatheringsystems-architect - Phase 3 architecture designcopilot - Phase 5 code review supportedge-case-analyst - Phase 2 pre-mortem support (optional)
This skill coordinates new skills:
senior-developer - Phase 4-5 implementation and reviewjunior-developer - Phase 4 routine implementation (supervised)mathematician - Phase 4 algorithm design (when needed)statistician - Phase 4 statistical validation (when needed)notebook-writer - Phase 4 notebook creation and Phase 5 notebook review (when needed)
