Spec Driven Release

Spec-Driven Release

Orchestrate safe, automated deployments through strict 8-phase release workflow with staging validation, smoke testing, rollback capabilities, and release documentation.

Context files are THE LAW: tech-stack.md, source-tree.md, dependencies.md, coding-standards.md, architecture-constraints.md, anti-patterns.md

If ambiguous or conflicts detected: HALT and use AskUserQuestion

Execution Model

This skill expands inline. After invocation, execute Phase State Initialization immediately. Do not wait passively, ask permission, or offer execution options.

Self-Check (if ANY box is true = VIOLATION):

• Stopping to ask about token budget
• Stopping to offer execution options
• Waiting passively for results
• Asking "should I execute this?"
• Skipping a phase because it "seems simple"
• Combining multiple phases into one
• Summarizing instead of loading a reference file
• Skipping verification because "I already wrote the file"

IF any box checked: EXECUTION MODEL VIOLATION. Go directly to Phase State Initialization now.

Anti-Skip Enforcement Contract

This skill enforces 4 independent anti-skip layers. ALL FOUR must fail for a step to be skipped:

1. Fresh-context subagent execution - Subagents run in isolated context without accumulated bias
2. Binary CLI gates - devforgeai-validate phase-check/phase-complete/phase-record (compiled, cannot be forged by LLM)
3. Hook enforcement - Shell scripts in .claude/hooks/ run outside LLM control
4. Step registry + artifact verification - .claude/hooks/phase-steps-registry.json tracks every mandatory step

Execute-Verify-Gate Pattern: Every mandatory step in every phase file has three parts:

• EXECUTE: The exact action to perform
• VERIFY: How to confirm the action happened (Glob, Grep, exit code, Task result)
• RECORD: CLI command to record completion (devforgeai-validate phase-record)

Token Optimization Bias is PROHIBITED. Do not skip, compress, or shortcut any step. Every phase step exists because a previous failure proved it necessary. (Reference: RCA-001, RCA-002, RCA-041)

Core Capabilities

1. Automated Deployment - Platform-agnostic (K8s, Docker, AWS, Azure, GCP, Vercel, Netlify, VPS)
2. Progressive Rollout - Blue-green, canary, rolling, recreate strategies
3. Smoke Testing - Health checks, critical path validation, performance verification
4. Rollback Capability - Automatic rollback on failure detection
5. Release Documentation - Release notes, changelog, audit trail
6. Multi-Environment - Staging-first with production promotion
7. Build & Publish - Tech stack detection, build execution, registry publishing

Philosophy

"Deploy with Confidence, Fail Gracefully, Safety Over Speed"

Parameter Extraction

Extract story ID, environment (staging/production), and deployment strategy from conversation context.

Skills cannot accept runtime parameters. All information extracted from conversation (YAML frontmatter, explicit statements, or file references).

See .claude/skills/spec-driven-release/references/parameter-extraction.md for the extraction algorithm.

Extraction methods: YAML frontmatter, file reference, explicit statement, status inference. Default environment: staging (if unable to determine).

Command Integration

Phase State Initialization [MANDATORY FIRST]

devforgeai-validate phase-init ${STORY_ID} --workflow=release --project-root=.

Phase Orchestration Loop

SKIP_PHASES = []  # Set by Phase 01 Step 1.9 based on project type

FOR phase_num in [01, 02, 03, 04, 05, 06, 07, 08]:
    phase_id = phase_num

    IF phase_id in SKIP_PHASES:
        Write skip marker with documented reason
        devforgeai-validate phase-record ${STORY_ID} --workflow=release --phase={phase_id} --status=skipped --project-root=.
        CONTINUE to next phase

    1. ENTRY GATE: devforgeai-validate phase-check ${STORY_ID} --workflow=release --from={prev} --to={phase_id} --project-root=.
       IF exit != 0: HALT

    2. LOAD: Read(file_path=".claude/skills/spec-driven-release/phases/{phase_files[phase_id]}")
       Load FRESH - do NOT rely on memory of previous reads

    3. EXECUTE: Follow every step in the phase file (EXECUTE-VERIFY-RECORD triplets)
       - Each step's EXECUTE instruction tells you exactly what to do
       - Each step's VERIFY instruction tells you how to confirm it happened
       - Each step's RECORD instruction tells you what CLI command to call

    4. RECORD: devforgeai-validate phase-record ${STORY_ID} --workflow=release --phase={phase_id} --project-root=.

    5. EXIT GATE: devforgeai-validate phase-complete ${STORY_ID} --workflow=release --phase={phase_id} --checkpoint-passed --project-root=.
       IF exit != 0: HALT

Required Subagents Per Phase

Deviation Protocol: Any skip requires explicit user consent via AskUserQuestion.

Adaptive Phase Skipping

Phase 01 classifies the project and sets SKIP_PHASES:

Detection: Cargo.toml, package.json, pyproject.toml indicators (see Phase 01 steps).

Skipped Phase Protocol:

1. Load reference file for the phase (MANDATORY - even skipped phases load references)
2. Write skip marker with documented reason
3. Record skip via CLI gate
4. Advance to next phase

State Persistence

Location: devforgeai/workflows/${STORY_ID}-release-phase-state.json

Workflow Completion Validation

expected_phases = 8 - len(SKIP_PHASES)
IF completed_count < expected_phases: HALT "WORKFLOW INCOMPLETE - {completed_count}/{expected_phases} phases"
IF completed_count == expected_phases: "All {expected_phases} phases completed - Release workflow passed"

Success Criteria

Release complete when:

• Setup and classification completed
• Build artifacts created (if applicable)
• Pre-release validation passed (QA approved, tests passing, config exists)
• Staging deployment + smoke tests passed (if applicable)
• Production deployment + smoke tests passed (if applicable)
• Post-deployment validation passed (if applicable)
• Release notes generated, story archived
• Monitoring configured (if applicable), checkpoint cleaned up
• Story status = "Released"

Reference Files Index

Local references (loaded per-phase on demand, NOT consolidated):

Assets:

• .claude/skills/spec-driven-release/assets/templates/release-notes-template.md
• .claude/skills/spec-driven-release/assets/templates/deployment-config-template.yaml
• .claude/skills/spec-driven-release/assets/templates/rollback-plan-template.md

Automation Scripts:

• .claude/skills/spec-driven-release/scripts/health_check.py
• .claude/skills/spec-driven-release/scripts/smoke_test_runner.py
• .claude/skills/spec-driven-release/scripts/metrics_collector.py
• .claude/skills/spec-driven-release/scripts/rollback_automation.sh
• .claude/skills/spec-driven-release/scripts/release_notes_generator.py
• .claude/skills/spec-driven-release/scripts/emergency_rollback.sh
• .claude/skills/spec-driven-release/scripts/backup_database.sh