ci/opencode/ci/workflows/run.md

description

description
Execute the full CIAgent pipeline — specify → clarify → research → ideate → plan → execute → ship → verify → complete for the current or specified phase

CIAgent Run

Execute the full CIAgent pipeline from the current stage to completion. The orchestrator iterates through stages and delegates to specialized agents and sub-workflows.

Usage: ciagent-run [phase_number]

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

Step 0: Confirm Active Project and Session

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

If .ciagent/config.json has projects[] with length > 0, or active_projects array exists:

• Confirm active_projects is correct for this run
• If --project all is specified: iterate over all projects in active_projects
• If --project <slug> is specified: run for that project only
• If no --project flag: use first project in active_projects
• All commit messages must include project: <slug> in ---ci--- block
• All .ciagent/ file reads use .ciagent/<slug>/ subdirectory paths
• Branch names are prefixed with <slug>/ (e.g., <slug>/phase/01-auth, <slug>/milestone/v0.2-auth)

For multi-project execution (--project all):

• Execute pipeline for each project sequentially by default
• When parallelization.enabled=true: execute projects concurrently up to max_concurrent_agents
• Each project has independent phase branches and milestone tracking
• Sessions (if configured): each project gets its own AgentSession with branch isolation per config.json sessions.session_isolation

For multi-persona execution (when config.json personas.enabled=true):

• Lead-developer persona decomposes tasks by territory file patterns and requirement IDs
• Each persona group executes tasks within their territory
• Territory enforcement runs in warn or strict mode per config.json personas.territory_enforcement

If single-project mode: proceed with existing conventions (flat .ciagent/ paths, no project prefix on branches).

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
• Active project from ---ci--- project field (multi-project mode)

Step 2: Pre-Flight Check

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

Resolve project paths based on mode:

• Multi-project: read .ciagent/<slug>/PROJECT.md and .ciagent/<slug>/ROADMAP.md for the active project
• Single-project: read .ciagent/PROJECT.md and .ciagent/ROADMAP.md

Read phase goals and milestone context from the resolved files.

Step 3: Execute Pipeline Stages

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

SPECIFY

• Resolve active project from config.json
• Parse specification from .ciagent/<slug>/PROJECT.md (multi-project) or .ciagent/PROJECT.md (single-project)
• Validate requirements exist in .ciagent/<slug>/REQUIREMENTS.md (multi-project) or .ciagent/REQUIREMENTS.md (single-project)
• Commit: docs(init): validate specification

---ci---
project: <slug>
phase: 0
milestone: v0.X
status: specify
---/ci---

CLARIFY

Delegate to ciagent-clarify workflow. Do not reimplement inline.

The clarify workflow handles:

• Multi-project active project confirmation
• Git context loading
• Ambiguity identification and question generation
• Autonomy-based resolution (full/supervised/guided)
• Clarification commits with ---ci--- blocks
• .ciagent/<slug>/PROJECT.md and .ciagent/<slug>/REQUIREMENTS.md updates

Pass the current phase number and active project slug. Collect the result and proceed.

RESEARCH

• Resolve active project from config.json; use .ciagent/<slug>/ paths
• Delegate to ci-researcher
• Research domain, ecosystem, prior art
• Update .ciagent/<slug>/ static files with conclusions (ARCHITECTURE.md, PROJECT.md, etc.)
• Commit: docs(P##): research findings

---ci---
project: <slug>
phase: [N]
milestone: [vX.X]
status: research
---/ci---

IDEATE (when --ideate flag is passed)

Delegate to ciagent-ideate workflow. Do not reimplement inline.

The ideate workflow handles:

• Multi-project context and --project flags
• All three tiers (mechanical, backend-enriched, cross-project)
• Interactive validation (accept/skip/modify)
• Updates to .ciagent/<slug>/REQUIREMENTS.md, .ciagent/<slug>/ROADMAP.md, .ciagent/<slug>/ARCHITECTURE.md, .ciagent/<slug>/PROJECT.md
• Ideation commit with ---ci--- block

Pass the active project slug and any --ideate flags. Collect accepted ideas and proceed.

PLAN

• Resolve active project from config.json; use .ciagent/<slug>/ paths
• Delegate to ci-planner with full project context
• Create vertical-slice plans with wave ordering
• Plans reference requirement IDs from .ciagent/<slug>/REQUIREMENTS.md
• Commit: docs(P##): create [N] phase plans

---ci---
project: <slug>
phase: [N]
milestone: [vX.X]
status: plan
---/ci---

EXECUTE

• Create phase branch: <slug>/phase/NN-slug (multi-project) or phase/NN-slug (single-project)
• Delegate to ci-executor per plan per wave
• Multi-persona development: if config.json personas.enabled=true:
  • Lead-developer decomposes tasks by territory file patterns and requirement IDs
  • Each persona executes tasks within their declared territory (config.json personas[].territory)
  • Territory enforcement runs in configured mode (warn or strict)
  • Primary persona (i=0) executes sequentially; review personas (i>0) execute in parallel
  • Persona constraints (frameworks, constraints arrays) guide implementation choices
• Commit each task with ---ci--- block
• After all waves complete: ship the phase by delegating to ciagent-ship workflow

Ship gate: a phase MUST be shipped before advancing to the next phase. The ship workflow handles:

• Pre-flight validation (milestone type, branch hierarchy, tag sequence, autonomy)
• Test execution (test, typecheck, build)
• PR creation and auto-merge
• Version computation and tagging
• Branch merging (phase → milestone or phase → main)
• Gitea release creation

If the ship fails: do NOT advance to VERIFY. Iterate until the phase ships successfully.

VERIFY

Delegate to ciagent-verify workflow. Do not reimplement inline.

The verify workflow handles:

• Multi-project scoping and active project confirmation
• Four verification layers (structural, behavioral, security, quality)
• Auto-generated tests for unverifiable items
• Verification commit with ---ci--- block

Pass the current phase number and active project slug. Collect the verification result and proceed.

COMPLETE (milestone completion gate)

The COMPLETE stage is reached only after ALL phases in the milestone have been shipped and verified. It orchestrates milestone-level finalization through three sub-workflows with a feedback loop:

1. Trigger ciagent-review — multi-persona code review across all phases in the milestone

   • Reviews all changes in the milestone branch
   • Auto-applies P0 fixes, flags P1+ for post-hoc review
   • If P1+ issues found: send them back to the EXECUTE stage for remediation

2. Trigger ciagent-ship (milestone) — ship the entire milestone

   • Merge milestone branch into main
   • Tag with milestone version (minor for feature, major for major milestone)
   • Create Gitea release for the milestone with full phase summary
   • Build and upload distribution packages

3. Trigger ciagent-audit — verify project health

   • Reconstruction test: verify git log matches .ciagent/ files
   • Check .ciagent/ file discipline and branch hygiene
   • Check commit discipline
   • If audit finds issues: document them, send critical issues back to EXECUTE

4. Feedback loop: if review or audit produces pending issues that require code changes, loop back to EXECUTE → SHIP → VERIFY for those fixes before re-attempting COMPLETE.

5. If no pending issues from review/audit and audit is clean: complete the milestone:

   • Update .ciagent/<slug>/REQUIREMENTS.md — mark all milestone requirements as complete
   • Update .ciagent/<slug>/ROADMAP.md — mark milestone as complete
   • Commit: docs(milestone): complete [milestone-name]

---ci---
project: <slug>
phase: 0
milestone: [vX.Y]
status: complete
requirements:
  covered: [REQ-01, REQ-02, ...]
  partial: []
---/ci---

Versioning: Major milestone = breaking schema changes, Feature milestone = milestone completion (minor), Patch = every phase.

Phase Boundary Checkpoint

Between phases, perform a context reset:

1. Commit all work from the current phase
2. Update .ciagent/<slug>/ 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

Versioning Logic

Before tagging a phase completion, check getMilestoneType() which returns "nfr" | "feature" | "major":

• 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 — the final patch IS the deliverable.
• Feature milestone (at least one feat phase): apply progressive patch versions per phase, then tag next minor milestone version on completion (e.g., v0.6.0, NOT v0.5.0).
• Major milestone (breaking schema changes or complete refactor): apply progressive minor versions per phase (v0.3.0, v0.4.0), then tag next major on completion (e.g., v1.0.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.