ci/opencode/ci/workflows/run.md

description

description
Execute the full CI pipeline — research → plan → execute → verify → complete for the current or specified phase

CI Run

Execute the full CI pipeline from the current stage to completion. The orchestrator iterates through stages and delegates to specialized agents.

Usage: ci-run [phase_number]

If no phase number specified, continues from the current phase (detected from git log).

Step 0: Confirm Active Project

Check ci listProjects() or read .ci/config.json to determine if multi-project mode is active.

If .ci/config.json has projects[] with length > 0:

• Confirm active_project is correct for this run
• If not, set it with ci setActiveProject(<slug>)
• All commit messages must include project: <slug> in ---ci--- block

If single-project mode: proceed with existing conventions.

Step 1: Load Git Context

git log --max-count=20
git branch -a

Determine current state:

• Current phase from latest ---ci--- block
• Current milestone from latest ---ci--- block or active milestone branch
• Current pipeline stage from latest ---ci--- status field
• Completed phases from merged phase/NN-* branches

Step 2: Pre-Flight Check

Verify .ci/config.json exists. If missing: stop, run ci-init first.

Read .ci/PROJECT.md and .ci/ROADMAP.md for phase goals.

Step 3: Execute Pipeline Stages

For each stage in order (starting from current or from specify):

SPECIFY

• Parse specification from .ci/PROJECT.md
• Validate requirements exist in .ci/REQUIREMENTS.md
• Commit: docs(init): validate specification

CLARIFY

• Generate clarify questions for ambiguities
• Default-accept at full autonomy, present at supervised/guided
• Commit: decision(P##): clarification decisions

RESEARCH

• Delegate to ci-researcher
• Research domain, ecosystem, prior art
• Update .ci/ static files with conclusions
• Commit: docs(P##): research findings

PLAN

• Delegate to ci-planner
• Create vertical-slice plans with wave ordering
• Commit: docs(P##): create [N] phase plans

EXECUTE

• Create phase branch: phase/NN-slug
• Delegate to ci-executor per plan per wave
• Commit each task with ---ci--- block
• After all waves: commit phase completion

VERIFY

• Delegate to ci-verifier
• Check must_haves, requirement coverage, integration links
• Auto-generate tests for unverifiable items
• Commit: verify(P##): verification result

COMPLETE

• Merge phase branch into main (squash)
• Tag with patch version (e.g., v0.2.3 — 3rd phase in milestone v0.2)
• Create Gitea release for the tag
• Update .ci/REQUIREMENTS.md requirement statuses
• Update .ci/ROADMAP.md phase status
• Commit: docs(P##): complete [phase-name] phase

Versioning: Major = project-level refactor/schema change, Minor = milestone completion, Patch = every phase.

Phase Boundary Checkpoint

Between phases, perform a context reset:

1. Commit all work from the current phase
2. Update .ci/ files (phase status, requirement statuses)
3. Verify GitContext.reconstructState() matches expected state
4. Reset context: spawn fresh agent (opencode) or re-read git context (platforms without subagents)
5. Next phase begins with fresh context from git log only

NFR Versioning Logic

Before tagging a phase completion, check isNfrMilestone():

• NFR milestone (all phases are fix/chore/docs/perf/refactor/test): apply progressive patch versions (v0.1.1, v0.1.2, v0.1.3). No separate milestone tag.
• Feature milestone (any feat phase): apply progressive patch versions per phase, then tag minor milestone version on completion (e.g., v0.2.0).

Step 4: Error Recovery

On stage failure:

1. Retry once
2. Attempt plan revision
3. Escalate to human

Step 5: Advance or Complete

If more phases remain: advance to next phase, return to Step 3. If all phases complete:

• Tag milestone with minor version (e.g., v0.3.0)
• Create Gitea release for the milestone with full phase summary
• Report project completion

Error handling: commit escalations as ---ci--- blocks with escalation type.