陌讯skills聚合平台

programming-pm

📁 dangeles/claude 📅 7 days ago
4
总安装量
4
周安装量
#51576
全站排名
安装命令
npx skills add https://github.com/dangeles/claude --skill programming-pm

Agent 安装分布

opencode 4
claude-code 4
github-copilot 4
codex 4
kimi-cli 4
gemini-cli 4

Skill 文档

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.

State Anchoring

Start every response with: “[Phase N/6 – {phase_name}] {brief status}”

Before starting any phase (Phase 1 onward): Read /tmp/programming-pm-state-{workflow-id}.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 software-developer or copilot
  • Research coordination: For literature reviews, use lit-pm
  • General coordination: For non-software multi-agent work, use technical-pm

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)

  • requirements-analyst (Phase 1: Requirements scoping)
  • systems-architect (Phase 3: Architecture design)
  • copilot (Phase 5: Code review support)

Optional Specialists (workflow can proceed with reduced capability)

  • edge-case-analyst (Phase 2: Pre-mortem support)
    • If missing: Inform user. Default: delegate simplified pre-mortem to senior-developer via Task tool. Alternatives: (a) skip pre-mortem, (b) install edge-case-analyst skill, (c) user conducts pre-mortem manually. You do NOT conduct the pre-mortem yourself.
  • mathematician
    • If missing: Inform user. Delegate algorithm design to senior-developer via Task tool. Flag output as “designed without specialist mathematician review.”
  • statistician
    • If missing: Inform user. Delegate statistical work to senior-developer via Task tool. Flag as “unvalidated — no specialist statistician review.”
  • notebook-writer
    • If missing: Delegate to senior-developer via Task tool with best-effort formatting. Flag as “created without notebook-writer specialized formatting.”
    • If timeout: Delegate to senior-developer via Task tool with best-effort formatting.

Pre-Flight Check Execution

# Check required skills
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

# Check optional skills (handles both SKILL.md and skill.md naming)
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: /tmp/programming-pm-state-{workflow-id}.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: "/tmp/programming-pm-session-{timestamp}-{pid}/"
  archival_guidelines_path: "{session_dir}/archival-guidelines-summary.md"
  guidelines_found: boolean
  guidelines_source: string  # Path to CLAUDE.md or "defaults"
  cleanup_on_complete: boolean  # Default true

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"  # Optional, generated in Phase 3
  implementation: []

exceptions:
  overrides: []
  accepted_risks: []

State Recovery

On session resume:

  1. Read state file from /tmp/programming-pm-state-*.yaml
  2. Verify last_updated within 72 hours
  3. Display current phase and completed gates
  4. Offer: Continue from current phase OR restart

Workflow Phases

Phase 0: Archival Guidelines Review

Owner: programming-pm (automatic) Checkpoint: Never (always runs automatically) Duration: 2-5 minutes Session Setup: Creates /tmp/programming-pm-session-{YYYYMMDD-HHMMSS}-{PID}/

Initialize workflow session and extract archival guidelines, preferring .archive-metadata.yaml over CLAUDE.md, with code-specific extraction focus.

Process:

  1. Create session directory: /tmp/programming-pm-session-$(date +%Y%m%d-%H%M%S)-$$/
  2. Store session path in workflow state for downstream agents

Primary Source: .archive-metadata.yaml

  1. Follow the archival compliance check pattern: a. Read the reference document: ~/.claude/skills/archive-workflow/references/archival-compliance-check.md b. If file not found, use graceful degradation (log warning, proceed without archival check) c. Apply the 5-step pattern to all file creation operations
  2. Read .archive-metadata.yaml from the repo root
  3. Extract code-specific guidelines:
    • naming_conventions.project_specific_rules for *.py, *.js, *.ts patterns
    • structure.summary.source_code and structure.summary.tests
    • naming_conventions.summary.tests (test file pattern)
    • naming_conventions.summary.files (general file naming)
  4. Include the archival_context block in all downstream phase handoffs

Fallback: CLAUDE.md (Deprecated)

If .archive-metadata.yaml is not found:

  1. WARN: “Archival guidelines read from CLAUDE.md (fallback). Run archive-workflow to generate .archive-metadata.yaml for structured guidelines.”
  2. Check if .archive-metadata.yaml previously existed:
    • Look for docs/organization/final-organization-report.md
    • If found: WARN “Archival metadata was previously present but is now missing. Re-run archive-workflow.”
  3. Read CLAUDE.md and extract guidelines using existing prose extraction logic:
    • Code directory structure (src/, modules/, experiments/)
    • Git workflow (commit conventions, no destructive operations, stage specific files)
    • Testing conventions (if present)
    • Documentation conventions (README, inline comments, docstrings)
    • Repository organization for code vs. documentation
  4. Produce archival-guidelines-summary.md as before

Output

Write archival-guidelines-summary.md to the session directory with:

  • Source: “.archive-metadata.yaml” or “CLAUDE.md (fallback)”
  • Project type, naming conventions, directory structure
  • Enforcement mode (from YAML, or “advisory” default)
session_setup:
  session_dir: "/tmp/programming-pm-session-{timestamp}-{pid}/"
  archival_summary_path: "{session_dir}/archival-guidelines-summary.md"
  guidelines_found: boolean
  guidelines_source: string  # ".archive-metadata.yaml" or "CLAUDE.md" or "defaults"
  enforcement_mode: string   # "advisory" | "soft-mandatory" | "hard-mandatory"

Downstream Handoff

Include archival_context block in all agent dispatches (per the standard archival context block defined in archival-compliance-check.md):

archival_context:
  guidelines_present: true/false
  source: ".archive-metadata.yaml"  # or "CLAUDE.md" or "defaults"
  naming_convention: "snake_case"
  output_directory: "src/"
  enforcement_mode: "advisory"
  user_override: null

Quality Gate: Session directory created, archival summary written.

Failure Handling:

  • .archive-metadata.yaml malformed: Treat as missing, fall back to CLAUDE.md
  • CLAUDE.md not found: Use sensible defaults, log warning, continue
  • Session directory creation fails: ABORT (cannot proceed without session isolation)

Session Cleanup:

  • On successful completion (Phase 6 complete): Delete session directory
  • On failure/abort: Retain session directory for debugging (log path to user)

Timeout: 5 min (ABORT on timeout – cannot proceed without session)

Handoff Validation (Phase 0 → Phase 1):

# Validate session handoff before proceeding to Phase 1
python3 "${SKILL_DIR}/scripts/validate-handoff.py" \
  "${SESSION_DIR}/handoffs/phase0-session-handoff.yaml" \
  "session_handoff"

if [ $? -ne 0 ]; then
  echo "❌ Phase 0 handoff validation FAILED"
  echo "Options:"
  echo "  (A) Fix issues in session handoff and retry"
  echo "  (B) Override with documented gaps (logged to session state)"
  read -p "Choice [A/b]: " OVERRIDE_CHOICE

  if [ "$OVERRIDE_CHOICE" != "b" ] && [ "$OVERRIDE_CHOICE" != "B" ]; then
    echo "Aborting. Fix session handoff and restart workflow."
    exit 1
  else
    echo "⚠️  Override: Proceeding with gaps (documented in session-state.json)"
    jq '.phase0_handoff_override = true | .phase0_handoff_gaps = "See validation errors above"' \
      "${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 0 handoff validated successfully"
fi

Phase Transition: Phase 0 complete -> Quality Gate 0 -> PROCEED to Phase 1: Requirements and Scoping

Phase 1: Requirements and Scoping

If resuming: Read /tmp/programming-pm-state-{workflow-id}.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:

  1. Invoke requirements-analyst with project goal and session context
  2. Review requirements document for completeness
  3. Present requirements to user for approval

Quality Gate 1: Requirements Approval:

  • Type: Human judgment (programming-pm review)
  • Criteria:
    • Problem statement is specific (no vague terms like “better”, “faster”)
    • Success criteria are measurable (numbers, thresholds, or boolean conditions)
    • Scope boundaries (IN/OUT) explicitly defined
    • Dependencies identified
  • 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):

# Validate requirements handoff before mode selection
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

Steps:

Step 1: Run Complexity Detection

# Source the detection function
source "${SKILL_DIR}/references/mode-selection-criteria.md"

# Run detection on requirements handoff
REQUIREMENTS_FILE="${SESSION_DIR}/handoffs/phase1-requirements-handoff.yaml"
DETECTION_RESULT=$(detect_tier "$REQUIREMENTS_FILE")

# Parse results
DETECTED_TIER=$(echo "$DETECTION_RESULT" | cut -d'|' -f1)
CONFIDENCE=$(echo "$DETECTION_RESULT" | cut -d'|' -f2)
REASON=$(echo "$DETECTION_RESULT" | cut -d'|' -f3)

Triggers for each tier:

EXTENDED:

  • Component count >5
  • Requires BOTH statistics AND mathematics
  • Task count >15
  • Architectural complexity keywords: “distributed system”, “microservices”, “event-driven”, “real-time processing”
  • User explicit request: “extended analysis” or “comprehensive review”

SIMPLE:

  • Single component AND no stats/math
  • Utility script with <5 tasks
  • Data pipeline (ETL) with single component

STANDARD (default):

  • Multiple components (2-5)
  • Single specialization (stats OR math, not both)
  • Moderate task count (5-15)
  • Standard patterns: “web API”, “CLI tool”, “data analysis”, “visualization”

Step 2: Display Mode Selection Prompt

echo ""
echo "================================================"
echo "  Mode Selection (After Quality Gate 1)"
echo "================================================"
echo ""
echo "Detected tier: $DETECTED_TIER (confidence: $CONFIDENCE)"
echo "Reason: $REASON"
echo ""
echo "Mode descriptions:"
echo "  SIMPLE (1-2 hrs): Single component, no stats/math, <5 tasks"
echo "  STANDARD (4-6 hrs): Multi-component, optional stats/math, 5-15 tasks (default)"
echo "  EXTENDED (8-12 hrs): >5 components OR both stats+math OR >15 tasks"
echo ""

Step 3: User Override Confirmation

# High-confidence: allow override with 60s timeout
if [ "$CONFIDENCE" = "high" ]; then
  read -t 60 -p "Proceed with $DETECTED_TIER mode? [Y/n]: " USER_CHOICE

  if [ $? -ne 0 ]; then
    # Timeout - proceed with detected tier
    echo "No response (timeout 60s). Proceeding with: $DETECTED_TIER"
    SELECTED_TIER="$DETECTED_TIER"
  elif [ "$USER_CHOICE" = "n" ] || [ "$USER_CHOICE" = "N" ]; then
    # User wants override
    read -p "Select mode (1=SIMPLE, 2=STANDARD, 3=EXTENDED): " MODE_OVERRIDE
    case "$MODE_OVERRIDE" in
      1) SELECTED_TIER="SIMPLE" ;;
      2) SELECTED_TIER="STANDARD" ;;
      3) SELECTED_TIER="EXTENDED" ;;
      *) SELECTED_TIER="$DETECTED_TIER" ;;
    esac

    # Risky override confirmation
    if [ "$DETECTED_TIER" != "SIMPLE" ] && [ "$SELECTED_TIER" = "SIMPLE" ]; then
      echo "⚠️  WARNING: Selecting SIMPLE when $DETECTED_TIER recommended."
      read -p "Confirm risky override? [y/N]: " RISKY_CONFIRM
      if [ "$RISKY_CONFIRM" != "y" ]; then
        SELECTED_TIER="$DETECTED_TIER"
      fi
    fi
  else
    SELECTED_TIER="$DETECTED_TIER"
  fi
else
  # Medium/low confidence: require user confirmation
  read -p "Select mode (1=SIMPLE, 2=STANDARD, 3=EXTENDED) [default: $DETECTED_TIER]: " USER_CHOICE
  case "$USER_CHOICE" in
    1) SELECTED_TIER="SIMPLE" ;;
    2) SELECTED_TIER="STANDARD" ;;
    3) SELECTED_TIER="EXTENDED" ;;
    "") SELECTED_TIER="$DETECTED_TIER" ;;
    *) SELECTED_TIER="STANDARD" ;;  # Safest default
  esac
fi

Step 4: Record Mode Selection

# Create mode-selection.json
cat > "$SESSION_DIR/mode-selection.json" <<EOF
{
  "detected_tier": "$DETECTED_TIER",
  "confidence": "$CONFIDENCE",
  "reason": "$REASON",
  "selected_tier": "$SELECTED_TIER",
  "override": $([ "$DETECTED_TIER" != "$SELECTED_TIER" ] && echo "true" || echo "false"),
  "timestamp": "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
}
EOF

# Update session-state.json
if command -v jq &> /dev/null; then
  jq --arg tier "$SELECTED_TIER" '.mode = $tier' \
    "$SESSION_DIR/session-state.json" > "$SESSION_DIR/session-state.json.tmp"
  mv "$SESSION_DIR/session-state.json.tmp" "$SESSION_DIR/session-state.json"
fi

# Export for workflow use
export PROGRAMMING_PM_MODE="$SELECTED_TIER"

echo "✅ Mode selected: $SELECTED_TIER"

Step 5: Mode-Based Branching

# Workflow branching based on selected mode
if [ "$PROGRAMMING_PM_MODE" = "SIMPLE" ]; then
  echo "→ SIMPLE mode: Sequential execution, automated checks only"
  SKIP_EXTENDED_ANALYSIS=true
  PARALLEL_EXECUTION=false
elif [ "$PROGRAMMING_PM_MODE" = "EXTENDED" ]; then
  echo "→ EXTENDED mode: Wave-based parallel execution, extended reviews"
  SKIP_EXTENDED_ANALYSIS=false
  PARALLEL_EXECUTION=true
  EXTENDED_TIMEOUTS=true
else
  echo "→ STANDARD mode: Wave-based parallel execution, standard checks"
  SKIP_EXTENDED_ANALYSIS=false
  PARALLEL_EXECUTION=true
  EXTENDED_TIMEOUTS=false
fi

Backwards Compatibility:

# For sessions without mode-selection.json, default to STANDARD
if [ ! -f "$SESSION_DIR/mode-selection.json" ]; then
  echo "⚠️  Legacy session (no mode selection). Defaulting to STANDARD."
  export PROGRAMMING_PM_MODE="STANDARD"
fi

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 /tmp/programming-pm-state-{workflow-id}.yaml. Confirm Phases 0-1 are complete.

Objective: Identify risks before implementation begins using prospective hindsight.

Steps:

  1. Invoke edge-case-analyst (if available) or delegate simplified pre-mortem to senior-developer via Task tool
  2. Use pre-mortem template from references/pre-mortem-template.md
  3. Document at least 3 risks with likelihood, impact, and mitigation

Quality Gate 2: Pre-Mortem Completion:

  • Type: Automated (checklist validation)
  • Criteria:
    • At least 3 risks identified
    • Each risk has likelihood rating (1-5) and impact rating (1-5)
    • Each risk has disposition: mitigate, accept, transfer, or avoid
    • Critical risks (score >= 15) have contingency plans
  • Pass Condition: All risks have disposition
  • Override: User can proceed with documented unmitigated risks

Handoff Validation (Phase 2 → Phase 3):

# Validate pre-mortem handoff
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 /tmp/programming-pm-state-{workflow-id}.yaml. Confirm Phases 0-2 are complete.

Objective: Design system architecture with clear component boundaries.

Steps:

  1. Invoke systems-architect with requirements and risk assessment
  2. Review architecture for completeness
  3. Present architecture to user for approval
  4. Generate Architecture Context Document

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:
    • All components identified with responsibilities
    • Data flow documented (inputs, outputs, transformations)
    • Technology choices justified (libraries, frameworks)
    • Component interfaces defined
    • Testing strategy outlined
    • Architecture Context Document generated (.architecture/context.md exists)
  • Override: User can approve partial architecture for proof-of-concept

Handoff Validation (Phase 3 → Phase 4):

# Validate architecture handoff before implementation
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 /tmp/programming-pm-state-{workflow-id}.yaml. Confirm Phases 0-3 are complete.

Objective: Implement architecture with specialist agents in parallel.

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)

Steps:

Step 1: Task Decomposition

Parse architecture handoff to identify components and assign specialists:

ARCHITECTURE_FILE="${SESSION_DIR}/handoffs/phase3-architecture-handoff.yaml"

# Extract components
if command -v yq &> /dev/null; then
  COMPONENT_COUNT=$(yq eval '.handoff.components | length' "$ARCHITECTURE_FILE")

  # Initialize task list
  > "$SESSION_DIR/task-assignments.txt"

  # Iterate through components
  for i in $(seq 0 $((COMPONENT_COUNT - 1))); do
    COMPONENT_NAME=$(yq eval ".handoff.components[$i].name" "$ARCHITECTURE_FILE")
    COMPONENT_DESC=$(yq eval ".handoff.components[$i].responsibility" "$ARCHITECTURE_FILE")
    DEPENDENCIES=$(yq eval ".handoff.components[$i].dependencies[]" "$ARCHITECTURE_FILE" 2>/dev/null || echo "")

    # Determine specialist based on component characteristics
    SPECIALIST="senior-developer"  # default

    if echo "$COMPONENT_DESC" | grep -qiE "algorithm|optimization|complexity"; then
      SPECIALIST="mathematician"
    elif echo "$COMPONENT_DESC" | grep -qiE "statistic|hypothesis|regression|bayesian"; then
      SPECIALIST="statistician"
    elif echo "$COMPONENT_DESC" | grep -qiE "notebook|jupyter|ipynb|jupytext|interactive.analysis|parameter.sweep|analysis.report|visualization.notebook|reproducible.analysis|data.exploration"; then
      SPECIALIST="notebook-writer"
    elif echo "$COMPONENT_DESC" | grep -qiE "simple|utility|helper|wrapper"; then
      SPECIALIST="junior-developer"
    fi

    # Record task assignment
    TASK_ID="TASK-$(printf "%03d" $((i + 1)))"
    echo "$TASK_ID|$COMPONENT_NAME|$SPECIALIST|$DEPENDENCIES" >> "$SESSION_DIR/task-assignments.txt"
  done
else
  echo "⚠️  yq not found. Manual task decomposition required."
fi

Specialist assignment logic:

  • Algorithm design → mathematician
  • Statistical methods → statistician
  • Notebook/Jupyter creation → notebook-writer
  • Complex implementation → senior-developer
  • Routine implementation → junior-developer (supervised by senior)

Task assignment format:

task:
  id: "TASK-001"
  description: string
  assigned_to: skill_name
  dependencies: []
  estimated_duration: "2h"
  acceptance_criteria: []
  handoff_format: "See handoff-schema.md"
  architecture_context:
    path: "/path/to/.architecture/context.md"  # Absolute path if document exists
    component: "module_name"  # Component/module being implemented
    tier: 0  # 0=foundation, 1=core, 2=application (extracted from context doc)

Step 2: Wave-Based Parallel Execution

SIMPLE mode: Skip waves, execute sequentially.

STANDARD/EXTENDED mode: Execute in waves with stagger.

# Check execution mode
if [ "$PROGRAMMING_PM_MODE" = "SIMPLE" ]; then
  echo "SIMPLE mode: Sequential execution"

  # Execute tasks one at a time
  while IFS='|' read -r TASK_ID COMPONENT SPECIALIST DEPS; do
    echo "Executing $TASK_ID ($COMPONENT) with $SPECIALIST..."

    # Invoke specialist (synchronous)
    # Record start time for timeout monitoring
    START_TIME=$(date +%s)

    # ... invoke specialist ...

    # Wait for completion
  done < "$SESSION_DIR/task-assignments.txt"

else
  echo "STANDARD/EXTENDED mode: Wave-based parallel execution"
fi

Wave-Based Specialist Launch

Launch specialists in three waves to respect dependency ordering. Track all running agents to prevent double-launches.

Wave 1 (immediate) — Launch specialists whose output feeds other tasks:

If mathematician tasks exist in task-assignments.txt: For each mathematician task: Launch mathematician via Task tool. Description: “Mathematician: Design algorithm for {component_name}” Prompt: Include algorithm requirements from architecture phase, performance targets, and constraints. Write output to: {session_dir}/deliverables/{task_id}-math-analysis.md Record each launched task in running-agents tracking.

If statistician tasks exist in task-assignments.txt: For each statistician task: Launch statistician via Task tool. Description: “Statistician: Design statistical approach for {component_name}” Prompt: Include statistical requirements, data characteristics, and validation criteria. Write output to: {session_dir}/deliverables/{task_id}-stats-analysis.md Record each launched task in running-agents tracking.

These launch first because implementation specialists may depend on their output.

Wave 2 (after Wave 1 launches) — Launch implementation specialists for independent tasks:

Identify tasks with no dependencies (or dependencies already satisfied from prior phases). For each independent task not already launched in Wave 1: Launch senior-developer or junior-developer via Task tool (per task assignment). Description: “{Specialist}: Implement {component_name}” Prompt: Include architecture spec, coding standards, test requirements, and output path. Write output to: {session_dir}/deliverables/{task_id}-implementation/ Skip any task already tracked in running-agents (prevents double-launch).

Wave 3 (after Wave 1 specialists complete) — Launch specialists for dependent tasks:

For each task with unsatisfied dependencies: Check whether dependency output files exist in {session_dir}/deliverables/. If dependencies satisfied: Launch specialist via Task tool with dependency outputs included in prompt. If dependencies NOT satisfied: Wait and retry. If still not satisfied after 3 retries, inform user.

Monitor all agents via output file existence. When all tasks show deliverables, proceed to quality gate.

Step 3: Progress Monitoring

Monitor specialist outputs using file-based tracking:

# Progress monitoring loop
echo "Monitoring specialist progress..."

TIMEOUT_THRESHOLD=7200  # 2 hours (STANDARD mode)
if [ "$PROGRAMMING_PM_MODE" = "EXTENDED" ]; then
  TIMEOUT_THRESHOLD=14400  # 4 hours (EXTENDED mode)
fi

while true; do
  # Check running agents
  RUNNING_COUNT=$(wc -l < "$SESSION_DIR/running-agents.txt" 2>/dev/null || echo 0)

  if [ "$RUNNING_COUNT" -eq 0 ]; then
    echo "✅ All specialists completed"
    break
  fi

  # Check each running agent
  while IFS='|' read -r TASK_ID AGENT_PID; do
    # Check if process still running
    if ! ps -p "$AGENT_PID" > /dev/null 2>&1; then
      echo "  $TASK_ID completed (PID $AGENT_PID exited)"

      # Mark as completed
      echo "$TASK_ID|COMPLETED|$(date -u +"%Y-%m-%dT%H:%M:%SZ")" >> "$SESSION_DIR/task-status.txt"

      # Remove from running list
      grep -v "^$TASK_ID|" "$SESSION_DIR/running-agents.txt" > "$SESSION_DIR/running-agents.txt.tmp"
      mv "$SESSION_DIR/running-agents.txt.tmp" "$SESSION_DIR/running-agents.txt"
    else
      # Check for timeout
      START_TIME=$(grep "^$TASK_ID|" "$SESSION_DIR/task-start-times.txt" | cut -d'|' -f2)
      CURRENT_TIME=$(date +%s)
      ELAPSED=$((CURRENT_TIME - START_TIME))

      if [ "$ELAPSED" -gt "$TIMEOUT_THRESHOLD" ]; then
        echo "  ⚠️  $TASK_ID TIMEOUT (elapsed: ${ELAPSED}s, threshold: ${TIMEOUT_THRESHOLD}s)"

        # Timeout intervention (see timeout-config.md)
        # Option: Extend deadline, narrow scope, substitute specialist, or escalate
      fi
    fi
  done < "$SESSION_DIR/running-agents.txt"

  # Check progress file outputs (must be >100 words)
  for TASK_ID in $(awk -F'|' '{print $1}' "$SESSION_DIR/task-assignments.txt"); do
    PROGRESS_FILE="${SESSION_DIR}/progress/${TASK_ID}-progress.txt"

    if [ -f "$PROGRESS_FILE" ]; then
      WORD_COUNT=$(wc -w < "$PROGRESS_FILE")

      if [ "$WORD_COUNT" -ge 100 ]; then
        echo "  $TASK_ID progress OK ($WORD_COUNT words)"
      else
        echo "  $TASK_ID progress insufficient ($WORD_COUNT words, min 100)"
      fi
    fi
  done

  # Sleep before next check
  sleep 60  # Check every minute
done

Step 4: Quality Gate 4a – Specialist Completion Check

Validate specialist outputs before proceeding:

echo "Quality Gate 4a: Specialist Completion Check"

# Count critical vs. implementation specialists
CRITICAL_COUNT=$(grep -cE "mathematician|statistician" "$SESSION_DIR/task-assignments.txt" || echo 0)
IMPL_COUNT=$(grep -cE "senior-developer|junior-developer" "$SESSION_DIR/task-assignments.txt" || echo 0)
TOTAL_COUNT=$((CRITICAL_COUNT + IMPL_COUNT))

# Count completed tasks
COMPLETED_COUNT=$(grep -c "COMPLETED" "$SESSION_DIR/task-status.txt" || echo 0)

echo "Completion status: $COMPLETED_COUNT / $TOTAL_COUNT tasks"

# Decision table
if [ "$COMPLETED_COUNT" -eq "$TOTAL_COUNT" ]; then
  echo "✅ Gate 4a: PASS (100% completion)"
elif [ "$COMPLETED_COUNT" -ge $((TOTAL_COUNT * 3 / 4)) ]; then
  echo "⚠️  Gate 4a: CONDITIONAL PASS (75%+ completion)"
  echo "Note: $((TOTAL_COUNT - COMPLETED_COUNT)) task(s) incomplete"

  # Check if critical specialists completed
  CRITICAL_COMPLETED=$(grep -E "TASK-.*mathematician|TASK-.*statistician" "$SESSION_DIR/task-status.txt" | grep -c "COMPLETED" || echo 0)

  if [ "$CRITICAL_COMPLETED" -eq "$CRITICAL_COUNT" ]; then
    echo "→ All critical specialists completed. Proceeding with note."
  else
    echo "→ Critical specialists incomplete. RETRY required."
    exit 1
  fi
else
  echo "❌ Gate 4a: FAIL (<75% completion)"
  echo "→ RETRY required"
  exit 1
fi

Quality Gate 4b: Implementation Validation:

  • Type: Automated (output validation)
  • Criteria:
    • All specialist outputs exist and are >100 words
    • No critical blocking issues flagged
    • Handoffs validate against schema (validate-handoff.py)
    • Acceptance criteria met per task
  • Pass Condition: All criteria checked OR 75%+ with critical specialists complete
  • Fail Action: Retry incomplete tasks or escalate to user

Handoff Validation (Phase 4 → Phase 5):

# Validate all code handoffs from Phase 4 (may be multiple task handoffs)
echo "Validating Phase 4 code handoffs..."

VALIDATION_ERRORS=0

for HANDOFF_FILE in "${SESSION_DIR}/handoffs/phase4-"*"-handoff-"*.yaml; do
  [ ! -f "$HANDOFF_FILE" ] && continue

  # Determine handoff type based on filename
  if echo "$HANDOFF_FILE" | grep -q "math-handoff"; then
    HANDOFF_TYPE="math_handoff"
  elif echo "$HANDOFF_FILE" | grep -q "stats-handoff"; then
    HANDOFF_TYPE="stats_handoff"
  elif echo "$HANDOFF_FILE" | grep -q "code-handoff"; then
    HANDOFF_TYPE="code_handoff"
  else
    echo "⚠️  Unknown handoff type: $HANDOFF_FILE"
    continue
  fi

  echo "  Validating $(basename "$HANDOFF_FILE") as $HANDOFF_TYPE..."

  python3 "${SKILL_DIR}/scripts/validate-handoff.py" \
    "$HANDOFF_FILE" \
    "$HANDOFF_TYPE"

  if [ $? -ne 0 ]; then
    echo "  ❌ Validation failed for $(basename "$HANDOFF_FILE")"
    VALIDATION_ERRORS=$((VALIDATION_ERRORS + 1))
  else
    echo "  ✅ Validated successfully"
  fi
done

if [ "$VALIDATION_ERRORS" -gt 0 ]; then
  echo ""
  echo "❌ Phase 4 handoff validation FAILED ($VALIDATION_ERRORS error(s))"
  read -p "Fix issues and retry? [Y/n]: " RETRY_CHOICE

  if [ "$RETRY_CHOICE" != "n" ] && [ "$RETRY_CHOICE" != "N" ]; then
    echo "Returning to Phase 4..."
    exit 1
  else
    echo "⚠️  Override: Proceeding with validation errors (documented)"
    jq --arg count "$VALIDATION_ERRORS" '.phase4_handoff_override = true | .phase4_validation_errors = ($count | tonumber)' \
      "${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 "✅ All Phase 4 handoffs validated successfully"
fi

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 /tmp/programming-pm-state-{workflow-id}.yaml. Confirm Phases 0-4 are complete.

Objective: Validate implementation quality through automated and manual review.

Steps:

  1. Run automated checks (linting, type checking, tests)
  2. Invoke copilot for code review support
  3. If deliverables include notebooks: invoke notebook-writer to verify reproducibility standards, Jupytext format compliance, environment documentation, and session info
  4. Have senior-developer review all code (especially junior-developer outputs)
  5. Address feedback and re-run checks
  6. 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:

  1. Invoke systems-architect for targeted update (<10 minutes)
  2. Update specific sections of .architecture/context.md (not full regeneration)
  3. 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 review)
  • Automated checks (must all pass):
    • ruff check . returns 0 errors
    • mypy --strict src/ returns 0 errors (warnings acceptable)
    • Test coverage >= 80% for new code
  • Human review:
    • Code matches requirements specification
    • Edge cases from pre-mortem are handled
    • Documentation present (docstrings, type hints)
    • No obvious security issues
  • Fail Action: Return to developer with specific feedback
  • Override: programming-pm can approve with “tech debt” tag if deadline critical

Quality Gate 5: Test Pass:

  • Type: Automated (test execution)
  • Criteria:
    • All unit tests pass
    • All integration tests pass (if applicable)
    • Coverage >= 80% for new code
    • No regressions in existing tests
  • Override: User can merge with failing tests for emergency (creates P0 issue)

Handoff Validation (Phase 5 → Phase 6):

# Validate review handoff before VCS integration
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 /tmp/programming-pm-state-{workflow-id}.yaml. Confirm Phases 0-5 are complete.

Objective: Integrate changes with sync-config.py and version control.

Optional: Git Strategy Advisory

Before proceeding with version control integration, you MAY invoke git-strategy-advisor via Task tool in post-work mode to get scope-adaptive git recommendations:

Invocation (via Task tool):

Use git-strategy-advisor to determine git strategy for completed work.

mode: post-work

The advisor analyzes actual changes (files, lines, directories) and recommends branch strategy, branch naming, push timing, and PR creation.

Conflict resolution: If the advisor’s recommendation differs from Phase 6 Step 3’s existing logic (which creates a feature branch when on main), Phase 6 Step 3 takes precedence unconditionally. Present the advisor’s recommendation as an informational note in the completion summary (e.g., “Note: git-strategy-advisor suggests direct-commit for this trivial change”). The orchestrator proceeds with its default behavior.

Response handling: Read the advisor’s summary field for the human-readable recommendation. Optionally read strategy.branch.action to note whether the advisor agrees with the default strategy. Include the summary in the Phase 6 completion report.

Confidence handling: If the advisor returns confidence “none” (e.g., no git repository found), silently skip the git strategy section. If confidence is “low”, present the recommendation with a caveat noting limited accuracy.

This is advisory only. If git-strategy-advisor is not available or returns an error, proceed with existing Phase 6 logic unchanged.

Steps:

Step 1: Pre-Merge Validation

# Check sync-config.py availability
SYNC_CONFIG_PATH="/Users/davidangelesalbores/repos/claude/sync-config.py"

if [ -f "$SYNC_CONFIG_PATH" ]; then
  echo "Using sync-config.py for VCS integration"
  USE_SYNC_CONFIG=true
else
  echo "⚠️  sync-config.py not found. Falling back to direct git commands."
  USE_SYNC_CONFIG=false
fi

# If using sync-config.py, check status
if [ "$USE_SYNC_CONFIG" = true ]; then
  echo "Checking sync-config.py status..."

  "$SYNC_CONFIG_PATH" status

  if [ $? -ne 0 ]; then
    echo "⚠️  Sync status check failed. Proceeding with caution."
  fi
fi

# Validate all handoffs one final time
echo "Final handoff validation before merge..."

FINAL_VALIDATION_ERRORS=0

for HANDOFF_FILE in "${SESSION_DIR}/handoffs/"*.yaml; do
  [ ! -f "$HANDOFF_FILE" ] && continue

  HANDOFF_NAME=$(basename "$HANDOFF_FILE" .yaml)

  # Determine handoff type from filename
  if echo "$HANDOFF_NAME" | grep -q "session-handoff"; then
    HANDOFF_TYPE="session_handoff"
  elif echo "$HANDOFF_NAME" | grep -q "requirements-handoff"; then
    HANDOFF_TYPE="requirements_handoff"
  elif echo "$HANDOFF_NAME" | grep -q "premortem-handoff"; then
    HANDOFF_TYPE="premortem_handoff"
  elif echo "$HANDOFF_NAME" | grep -q "architecture-handoff"; then
    HANDOFF_TYPE="architecture_handoff"
  elif echo "$HANDOFF_NAME" | grep -q "math-handoff"; then
    HANDOFF_TYPE="math_handoff"
  elif echo "$HANDOFF_NAME" | grep -q "stats-handoff"; then
    HANDOFF_TYPE="stats_handoff"
  elif echo "$HANDOFF_NAME" | grep -q "code-handoff"; then
    HANDOFF_TYPE="code_handoff"
  elif echo "$HANDOFF_NAME" | grep -q "review-handoff"; then
    HANDOFF_TYPE="review_handoff"
  else
    echo "⚠️  Unknown handoff type: $HANDOFF_NAME"
    continue
  fi

  python3 "${SKILL_DIR}/scripts/validate-handoff.py" \
    "$HANDOFF_FILE" \
    "$HANDOFF_TYPE" > /dev/null 2>&1

  if [ $? -ne 0 ]; then
    FINAL_VALIDATION_ERRORS=$((FINAL_VALIDATION_ERRORS + 1))
  fi
done

if [ "$FINAL_VALIDATION_ERRORS" -gt 0 ]; then
  echo "⚠️  $FINAL_VALIDATION_ERRORS handoff(s) still have validation issues"
  echo "Review overrides in session-state.json"
fi

# Dry-run to detect conflicts (if using sync-config.py)
if [ "$USE_SYNC_CONFIG" = true ]; then
  echo "Running sync dry-run to detect conflicts..."

  "$SYNC_CONFIG_PATH" push --dry-run

  if [ $? -ne 0 ]; then
    echo "❌ Dry-run detected conflicts or issues"
    echo "Review and resolve before proceeding."
    read -p "Continue anyway? [y/N]: " CONTINUE_CHOICE

    if [ "$CONTINUE_CHOICE" != "y" ] && [ "$CONTINUE_CHOICE" != "Y" ]; then
      echo "Aborting merge. Resolve conflicts first."
      exit 1
    fi
  else
    echo "✅ Dry-run successful (no conflicts detected)"
  fi
fi

Step 2: Quality Gate 6 Validation

# Run Quality Gate 6 validation script
echo "Running Quality Gate 6 validation..."

"${SKILL_DIR}/scripts/validate-gate.sh" 6 \
  "${SESSION_DIR}/handoffs/phase5-review-handoff.yaml" \
  "${SESSION_DIR}"

if [ $? -ne 0 ]; then
  echo "❌ Quality Gate 6 FAILED"
  read -p "Override and proceed? [y/N]: " OVERRIDE_CHOICE

  if [ "$OVERRIDE_CHOICE" != "y" ] && [ "$OVERRIDE_CHOICE" != "Y" ]; then
    echo "Aborting. Fix Quality Gate 6 issues first."
    exit 1
  else
    echo "⚠️  GATE 6 OVERRIDE (logged)"
    jq '.gate6_override = true | .gate6_override_timestamp = now | .gate6_override_user = env.USER' \
      "${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 "✅ Quality Gate 6 PASSED"
fi

Quality Gate 6 Criteria:

  • Type: Automated (VCS checks)
  • Criteria:
    • All previous gates passed (or overrides documented)
    • No merge conflicts (verified by dry-run)
    • Review approved (from phase5-review-handoff.yaml)
    • Deliverable location documented
    • Files staged (if in git repo)
  • Override: Repository admin can force merge (logged for audit)

Step 3: Commit and Sync

# Create feature branch if needed
if git rev-parse --git-dir > /dev/null 2>&1; then
  CURRENT_BRANCH=$(git branch --show-current)

  if [ "$CURRENT_BRANCH" = "main" ] || [ "$CURRENT_BRANCH" = "master" ]; then
    echo "⚠️  On main branch. Creating feature branch..."

    # Generate branch name from requirements
    BRANCH_NAME="feature/programming-pm-$(date +%Y%m%d-%H%M%S)"

    git checkout -b "$BRANCH_NAME"
    echo "Created branch: $BRANCH_NAME"
  fi
fi

# Stage specific files (NEVER git add . or git add -A)
echo "Staging specific files..."

# Get changed files from handoff
if command -v yq &> /dev/null; then
  CHANGED_FILES=$(yq eval '.handoff.changes.files_changed[].path' \
    "${SESSION_DIR}/handoffs/phase5-review-handoff.yaml" 2>/dev/null)

  if [ -n "$CHANGED_FILES" ]; then
    echo "$CHANGED_FILES" | while read -r FILE; do
      if [ -f "$FILE" ]; then
        git add "$FILE"
        echo "  Staged: $FILE"
      fi
    done
  else
    echo "⚠️  No files listed in review handoff. Manual staging required."
  fi
else
  echo "⚠️  yq not found. Manual staging required."
  git status
fi

# Create commit with conventional format
PROBLEM_STATEMENT=$(yq eval '.handoff.requirements.problem_statement' \
  "${SESSION_DIR}/handoffs/phase1-requirements-handoff.yaml" 2>/dev/null | head -n1)

COMMIT_MESSAGE="feat(programming-pm): ${PROBLEM_STATEMENT}

Implemented via programming-pm workflow ($(date -u +"%Y-%m-%d"))

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"

git commit -m "$COMMIT_MESSAGE"

if [ $? -ne 0 ]; then
  echo "❌ Commit failed"
  exit 1
else
  echo "✅ Commit created successfully"
fi

# Sync to ~/.claude/ (if using sync-config.py)
if [ "$USE_SYNC_CONFIG" = true ]; then
  echo "Syncing changes to ~/.claude/..."

  "$SYNC_CONFIG_PATH" push

  if [ $? -ne 0 ]; then
    echo "❌ sync-config.py push failed"
    echo "Changes committed to git but not synced to ~/.claude/"
    echo "Run manually: $SYNC_CONFIG_PATH push"
  else
    echo "✅ Changes synced to ~/.claude/ successfully"
  fi
else
  echo "⚠️  Skipping sync-config.py push (not available)"
fi

Step 4: Create Planning Journal Entry

# Create planning journal entry documenting the workflow execution
if [ "$USE_SYNC_CONFIG" = true ]; then
  echo "Creating planning journal entry..."

  # Extract brief description from problem statement (first 60 chars)
  BRIEF_DESC=$(echo "$PROBLEM_STATEMENT" | cut -c1-60)

  "$SYNC_CONFIG_PATH" plan --title "$BRIEF_DESC"

  if [ $? -ne 0 ]; then
    echo "⚠️  Failed to create planning journal entry"
    echo "Create manually with: $SYNC_CONFIG_PATH plan --title '...'"
  else
    echo "Document the following in the journal entry:"
    echo "  - Objective: $PROBLEM_STATEMENT"
    echo "  - Specialists used: $(awk -F'|' '{print $3}' "${SESSION_DIR}/task-assignments.txt" | sort -u | tr '\n' ', ')"
    echo "  - Files changed: $(git diff --name-only HEAD~1 HEAD | wc -l | tr -d ' ')"
    echo "  - Testing: All quality gates passed"
    echo "  - Outcome: Success"
    echo ""
    read -p "Press Enter after documenting in journal..."
  fi
fi

Step 5: Session Cleanup

# Mark session as completed
jq '.status = "completed" | .completion_timestamp = now' \
  "${SESSION_DIR}/session-state.json" > "${SESSION_DIR}/session-state.json.tmp"
mv "${SESSION_DIR}/session-state.json.tmp" "${SESSION_DIR}/session-state.json"

# Determine if session should be deleted or preserved
SESSION_SUCCESSFUL=true

# Check for any gate overrides
if jq -e '.phase0_handoff_override or .phase1_handoff_override or .phase2_handoff_override or .phase3_handoff_override or .phase4_handoff_override or .phase5_handoff_override or .gate6_override' \
  "${SESSION_DIR}/session-state.json" > /dev/null 2>&1; then
  SESSION_SUCCESSFUL=false
  echo "⚠️  Session had overrides. Preserving for review."
fi

# Check for validation errors
if [ "$FINAL_VALIDATION_ERRORS" -gt 0 ]; then
  SESSION_SUCCESSFUL=false
  echo "⚠️  Session had validation errors. Preserving for review."
fi

# Delete or preserve session directory
if [ "$SESSION_SUCCESSFUL" = true ]; then
  echo "Session completed successfully. Cleaning up..."
  echo "Session directory: ${SESSION_DIR}"
  read -p "Delete session directory? [Y/n]: " DELETE_CHOICE

  if [ "$DELETE_CHOICE" != "n" ] && [ "$DELETE_CHOICE" != "N" ]; then
    rm -rf "${SESSION_DIR}"
    echo "✅ Session directory deleted"
  else
    echo "Session directory preserved: ${SESSION_DIR}"
  fi
else
  echo "⚠️  Session preserved for debugging: ${SESSION_DIR}"
  echo "Review session-state.json for overrides and validation errors."
fi

echo ""
echo "================================================"
echo "  Programming-PM Workflow Complete"
echo "================================================"
echo ""

Post-Merge Verification: After sync, prompt user to verify deliverable meets expectations. If issues found, create follow-up task (not rollback unless critical).

Quality Gate Specifications

Gate Override Protocol

When a quality gate fails:

  1. 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

  2. Offer options:

    • [Fix] Address all issues and re-run gate
    • [Override] Proceed with documented risk acceptance
    • [Escalate] Consult specialist for second opinion

  3. 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

  1. Diagnose: Read specialist progress file, analyze status
  2. 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
  3. Execute: Apply chosen option, log decision
  4. Learn: Add to exceptions-log.md for retrospective

Circuit Breaker Pattern

After 3 consecutive failures of the same type:

  1. Open circuit: Stop retrying automatically
  2. Alert user: Present failure summary with options
  3. 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

  1. Detect Conflict: Monitor for contradictory recommendations between specialists

  2. Classify Conflict:

    • Minor (implementation detail): senior-developer decides
    • Major (architecture change required): Escalate to user

  3. 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]

  4. Post-Resolution: Document decision in architecture spec

Team Composition

See references/team-composition.md for detailed guidance.

Default Team (Always Required)

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

Specialist Inclusion Criteria

Include mathematician when:

  • Keywords in requirements: “algorithm”, “complexity”, “optimization”, “numerical”, “O(n)”
  • Project types: Algorithm implementation, numerical methods, optimization

Include statistician when:

  • Keywords in requirements: “statistics”, “Monte Carlo”, “MCMC”, “uncertainty”, “confidence interval”, “power analysis”, “bootstrap”
  • Project types: Data analysis, simulation validation, ML evaluation

Include notebook-writer when:

  • Keywords in requirements: “notebook”, “jupyter”, “ipynb”, “Jupytext”, “interactive analysis”, “parameter sweep”, “analysis report”, “reproducible analysis”, “data exploration”, “visualization notebook”
  • Project types: Data analysis with interactive output, scientific computation with parameter sweeps, analysis reporting, exploratory data analysis

CAUTION: Do NOT include based on standalone “interactive” or “visualization” — these are too broad. Require a notebook-specific compound keyword.

Include junior-developer when:

  • Tasks can be decomposed into well-scoped units
  • Project has >3 independent implementation tasks

User Override

# Explicitly include specialist
programming-pm --include mathematician "Implement sorting algorithm"

# Exclude auto-detected specialist
programming-pm --exclude statistician "Data pipeline without validation"

# Minimal team (PM + senior only)
programming-pm --minimal "Simple CRUD API"

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 template
  • references/code-review-checklist.md – Quality gate criteria for code review
  • references/git-workflow.md – Branching strategy, commit format, rollback procedures
  • references/team-composition.md – RACI matrix, specialist selection criteria
  • references/handoff-schema.md – Interface contracts between specialists
  • references/timeout-config.md – Per-phase and per-specialist timeout configuration
  • git-strategy-advisor – Phase 6 git strategy consultation (optional, advisory)

Example Workflow

# User invokes programming-pm with a goal
User: "Create a Monte Carlo simulation library for option pricing"

# programming-pm executes:
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 gathering
  • systems-architect – Phase 3 architecture design
  • copilot – Phase 5 code review support
  • edge-case-analyst – Phase 2 pre-mortem support (optional)

This skill coordinates new skills:

  • senior-developer – Phase 4-5 implementation and review
  • junior-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)
GitHub 仓库 ↗ ← 返回陌讯 Skills 聚合平台
本页面由 陌讯 Skills 聚合平台 收录整理，数据定期更新。