| name | spec-driven-release |
| description | Orchestrates production releases through spec-driven deployment workflow with structural anti-skip enforcement. Implements 8 phases covering setup, build, validation, staging, production deployment, post-deployment validation, documentation, and monitoring using the Execute-Verify-Gate pattern at every step. Designed to prevent token optimization bias through lean orchestration, fresh-context subagent delegation, and binary CLI gate enforcement. Supports multiple deployment strategies (blue-green, canary, rolling, recreate) and environments (staging, production). Use when deploying QA-approved stories. Always use this skill when the user runs /release.
|
| allowed-tools | ["Read","Write","Edit","Glob","Grep","AskUserQuestion","Task","Bash(devforgeai-validate:*)","Bash(git:*)","Bash(kubectl:*)","Bash(docker:*)","Bash(terraform:*)","Bash(ansible:*)","Bash(az:*)","Bash(aws:*)","Bash(gcloud:*)","Bash(helm:*)","Bash(dotnet:*)","Bash(npm:*)","Bash(pytest:*)","Bash(python:*)","Bash(cargo:*)","Skill"] |
| model | opus |
| effort | High |
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):
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:
- Fresh-context subagent execution - Subagents run in isolated context without accumulated bias
- Binary CLI gates -
devforgeai-validate phase-check/phase-complete/phase-record (compiled, cannot be forged by LLM)
- Hook enforcement - Shell scripts in
.claude/hooks/ run outside LLM control
- 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
- Automated Deployment - Platform-agnostic (K8s, Docker, AWS, Azure, GCP, Vercel, Netlify, VPS)
- Progressive Rollout - Blue-green, canary, rolling, recreate strategies
- Smoke Testing - Health checks, critical path validation, performance verification
- Rollback Capability - Automatic rollback on failure detection
- Release Documentation - Release notes, changelog, audit trail
- Multi-Environment - Staging-first with production promotion
- 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
| Context Marker | Set By | Description |
|---|
$STORY_ID | /release | Story identifier (STORY-NNN) |
$ENVIRONMENT | /release | Target environment (staging/production) |
Phase State Initialization [MANDATORY FIRST]
devforgeai-validate phase-init ${STORY_ID} --workflow=release --project-root=.
| Exit Code | Meaning | Action |
|---|
| 0 | New workflow | State file created. Set CURRENT_PHASE = "01". |
| 1 | Existing workflow | Resume. Run devforgeai-validate phase-status ${STORY_ID} --workflow=release to get CURRENT_PHASE. |
| 2 | Invalid story ID | HALT. Must match STORY-XXX pattern. |
| 127 | CLI not installed | Continue without enforcement (backward compatibility). |
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
| Phase | Name | File |
|---|
| 01 | Setup & Classification | phases/phase-01-setup-classification.md |
| 02 | Build & Package | phases/phase-02-build-package.md |
| 03 | Pre-Release Validation | phases/phase-03-pre-release-validation.md |
| 04 | Staging Deployment | phases/phase-04-staging-deployment.md |
| 05 | Production Deployment | phases/phase-05-production-deployment.md |
| 06 | Post-Deployment Validation | phases/phase-06-post-deployment-validation.md |
| 07 | Release Documentation | phases/phase-07-release-documentation.md |
| 08 | Monitoring, Cleanup & Closure | phases/phase-08-monitoring-cleanup.md |
Required Subagents Per Phase
| Phase | Required Subagents | Enforcement |
|---|
| 01 | tech-stack-detector | BLOCKING |
| 02 | (none) | N/A |
| 03 | (none) | N/A |
| 04 | deployment-engineer | BLOCKING |
| 05 | deployment-engineer, security-auditor | BLOCKING |
| 06 | (none) | N/A |
| 07 | (none) | N/A |
| 08 | (none) | N/A |
Deviation Protocol: Any skip requires explicit user consent via AskUserQuestion.
Adaptive Phase Skipping
Phase 01 classifies the project and sets SKIP_PHASES:
| Project Type | SKIP_PHASES | ACTIVE_PHASES | Rationale |
|---|
| library | [04, 05, 06, 08-monitoring] | [01, 02, 03, 07, 08-cleanup] | No deployment target |
| cli | [] | All phases | Deployable binary |
| api | [] | All phases | Deployable HTTP service |
Detection: Cargo.toml, package.json, pyproject.toml indicators (see Phase 01 steps).
Skipped Phase Protocol:
- Load reference file for the phase (MANDATORY - even skipped phases load references)
- Write skip marker with documented reason
- Record skip via CLI gate
- 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:
Reference Files Index
Local references (loaded per-phase on demand, NOT consolidated):
| Phase | Reference Files (load via Read from .claude/skills/spec-driven-release/references/) |
|---|
| 01 | parameter-extraction.md, tech-stack-detection.md, configuration-guide.md |
| 02 | build-commands.md, package-formats.md, registry-publishing.md |
| 03 | pre-release-validation.md, release-checklist.md |
| 04 | staging-deployment.md, deployment-strategies.md, platform-deployment-commands.md, smoke-testing-guide.md, post-staging-hooks.md |
| 05 | production-deployment.md, deployment-strategies.md, platform-deployment-commands.md, post-production-hooks.md |
| 06 | parallel-smoke-tests.md, post-deployment-validation.md, smoke-testing-guide.md, monitoring-metrics.md, rollback-procedures.md |
| 07 | release-documentation.md |
| 08 | monitoring-closure.md, monitoring-metrics.md |
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
