spec-driven-ci

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/, dependencies.md, coding-standards.md, architecture-constraints.md, anti-patterns.md

If ambiguous or conflicts detected: HALT and use ask the user

---

Execution Model

See .claude/rules/core/anti-skip-behavior.md for the canonical execution contract (expand inline; do not wait passively or offer execution options; honor every step of every phase; Self-Check violation taxonomy; Token-Optimization-Bias prohibition; governed by ADR-076). After invocation, execute Phase State Initialization immediately.

---

Anti-Skip Enforcement Contract

Enforced structurally outside LLM control, not by this prose — by the framework's deterministic gates wired for this workflow: the devforgeai-validate phase gates, the settings.json-registered .codex/hooks/ scripts, and .codex/hooks/phase-steps-registry.json (ADR-076). Behavioral residue: .claude/rules/core/anti-skip-behavior.md.

---

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 ask the user responses

Philosophy

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

Outputs Generated

Output File	Location	Purpose
dev-story.yml	.github/workflows/	Headless /dev execution (workflow_dispatch)
qa-validation.yml	.github/workflows/	PR quality gate (pull_request trigger)
parallel-stories.yml	.github/workflows/	Matrix parallel story execution
installer-testing.yml	.github/workflows/	Optional installer validation
github-actions.yaml	devforgeai/config/ci/	CI configuration (model, caching, limits)
ci-answers.yaml	devforgeai/config/ci/	Headless ask the user responses

---

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 ask the user.

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

Configuration Priority:

1. User-provided answers (ask the user 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

Context Marker	Set By	Description
$FORCE_FLAG	/setup-github-actions	Force overwrite existing files (boolean, default: false)

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

Secret Name	Description	Source
ANTHROPIC_API_KEY	Codex API authentication	console.anthropic.com
GITHUB_TOKEN	Repository access (auto-provided)	Automatic by GitHub Actions

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 .codex/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=.

Exit Code	Meaning	Action
0	New workflow	State file created. Set CURRENT_PHASE = "01".
1	Existing workflow	Resume. Run devforgeai-validate phase-status ${SESSION_ID} --workflow=ci --project-root=. to get CURRENT_PHASE.
2	Invalid session ID	HALT. Must match CI-YYYY-MM-DD-NNN pattern.
127	CLI not installed	Continue without enforcement (backward compatibility).

---

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: inspect `.codex/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

Phase	Name	File
01	Pre-Flight Validation	phases/phase-01-preflight.md
02	Configuration Loading	phases/phase-02-config-loading.md
03	Workflow Template Generation	phases/phase-03-workflow-generation.md
04	Cost Optimization	phases/phase-04-cost-optimization.md
05	Validation & Summary	phases/phase-05-validation-summary.md

---

Required Subagents Per Phase

Phase	Required Subagents	Enforcement
01	(none)	N/A
02	(none)	N/A
03	(none)	N/A
04	(none)	N/A
05	(none)	N/A

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 ask the user.

---

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):

Phase	Reference Files (load via Read from .codex/skills/spec-driven-ci/references/)
01	parameter-extraction.md, git-repo-validation.md, context-file-validation.md, security-prerequisites.md
02	config-file-schema.md, ci-answers-protocol.md
03	workflow-templates.md
04	cost-optimization-strategies.md
05	yaml-validation-procedures.md, security-prerequisites.md

Assets (workflow templates):

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