Spec-Driven CI

Generate CI/CD pipeline workflows with structural anti-skip enforcement for headless DevForgeAI execution.

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.

Core Capabilities

1. Headless /dev Execution - workflow_dispatch triggered story development via GitHub Actions
2. PR Quality Gates - Automated /qa validation on pull requests
3. Parallel Story Matrix - Concurrent story development with configurable max-parallel
4. Installer Testing - Optional workflow to validate DevForgeAI installer
5. Cost Optimization - Prompt caching, Haiku model preference, max-turns limits
6. Headless Answers - ci-answers.yaml pre-configures AskUserQuestion responses

Philosophy

"Automate with Confidence, Optimize for Cost, Enforce Every Phase"

Outputs Generated

Parameter Extraction

Extract configuration from conversation context. Skills cannot accept runtime parameters -- all information is extracted from conversation state, existing config files, or user responses to AskUserQuestion.

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

Configuration Priority:

1. User-provided answers (AskUserQuestion responses)
2. Existing devforgeai/config/ci/github-actions.yaml values
3. Skill defaults: max_parallel_jobs: 5, enable_prompt_caching: true, prefer_haiku: true

Extraction methods: Conversation context scanning, YAML file parsing, explicit user statements.

Command Integration

The /setup-github-actions command handles argument parsing and sets $FORCE_FLAG before invoking this skill. The skill reads this marker from the conversation context.

Security Prerequisites

All generated workflows require GitHub Secrets configured before execution.

Required Secrets

Setup Instructions

1. Navigate to repository Settings > Secrets and variables > Actions
2. Click New repository secret
3. Name: ANTHROPIC_API_KEY
4. Value: Your API key from console.anthropic.com
5. Click Add secret

Security Validation

Workflows fail-fast if secrets are missing:

• Missing ANTHROPIC_API_KEY: "Error: ANTHROPIC_API_KEY secret not configured"
• Check GitHub Actions logs for validation errors

Best Practices

• Never commit API keys to repository
• Use repository secrets for sensitive values
• Rotate keys periodically
• Use environment protection rules for production deployments

See .claude/skills/spec-driven-ci/references/security-prerequisites.md for complete security guidance.

Phase State Initialization [MANDATORY FIRST]

Generate a session ID using the pattern CI-{YYYY-MM-DD}-{NNN} (e.g., CI-2026-03-19-001).

devforgeai-validate phase-init ${SESSION_ID} --workflow=ci --project-root=.

Phase Orchestration Loop

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

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

    2. LOAD: Read(file_path=".claude/skills/spec-driven-ci/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 ${SESSION_ID} --workflow=ci --phase={phase_id} --project-root=.

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

Required Subagents Per Phase

This skill requires no subagent delegation. All 5 phases are executed inline by the orchestrator.

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

State Persistence

Location: devforgeai/workflows/${SESSION_ID}-ci-phase-state.json

Lifecycle:

1. Phase Init - CLI creates state file with session metadata
2. Each Phase - Status updated to "in_progress" at entry, "completed" at exit
3. Resume - Phase 01 detects existing state file and resumes from last completed phase
4. Completion - All 5 phases marked "completed"

Workflow Completion Validation

expected_phases = 5
IF completed_count < expected_phases: HALT "WORKFLOW INCOMPLETE - {completed_count}/{expected_phases} phases"
IF completed_count == expected_phases: "All 5 phases completed - CI workflow generation passed"

Success Criteria

CI workflow generation complete when:

• 4 workflow files created with valid YAML syntax
• 2 config files created (github-actions.yaml, ci-answers.yaml)
• All 5 acceptance criteria covered by workflows
• Cost optimization enabled (prompt caching, Haiku)
• ANTHROPIC_API_KEY documented in setup steps
• max-parallel configured appropriately
• All workflow triggers configured
• Artifact uploads configured for test results
• Summary displayed with next steps

Reference Files Index

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

Assets (workflow templates):

• .claude/skills/spec-driven-ci/assets/templates/dev-story-workflow.yml
• .claude/skills/spec-driven-ci/assets/templates/qa-validation-workflow.yml
• .claude/skills/spec-driven-ci/assets/templates/parallel-stories-workflow.yml
• .claude/skills/spec-driven-ci/assets/templates/installer-testing-workflow.yml
• .claude/skills/spec-driven-ci/assets/templates/github-actions-config.yaml
• .claude/skills/spec-driven-ci/assets/templates/ci-answers-config.yaml