diff --git a/opencode/ci/workflows/run.md b/opencode/ci/workflows/run.md index c34be9a..db2c915 100644 --- a/opencode/ci/workflows/run.md +++ b/opencode/ci/workflows/run.md @@ -1,16 +1,16 @@ --- -description: Execute the full CIAgent pipeline — research → plan → execute → verify → complete for the current or specified phase +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. +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 +## Step 0: Confirm Active Project and Session Check `ci listProjects()` or read `.ciagent/config.json` to determine if multi-project mode is active. @@ -20,13 +20,21 @@ If `.ciagent/config.json` has `projects[]` with length > 0, or `active_projects` - If `--project ` is specified: run for that project only - If no `--project` flag: use first project in `active_projects` - All commit messages must include `project: ` in `---ci---` block +- All `.ciagent/` file reads use `.ciagent//` subdirectory paths +- Branch names are prefixed with `/` (e.g., `/phase/01-auth`, `/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` -If single-project mode: proceed with existing conventions. +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 @@ -40,66 +48,173 @@ Determine current state: - 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. -Read `.ciagent/PROJECT.md` and `.ciagent/ROADMAP.md` for phase goals. +Resolve project paths based on mode: +- **Multi-project**: read `.ciagent//PROJECT.md` and `.ciagent//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 -- Parse specification from `.ciagent/PROJECT.md` -- Validate requirements exist in `.ciagent/REQUIREMENTS.md` + +- Resolve active project from `config.json` +- Parse specification from `.ciagent//PROJECT.md` (multi-project) or `.ciagent/PROJECT.md` (single-project) +- Validate requirements exist in `.ciagent//REQUIREMENTS.md` (multi-project) or `.ciagent/REQUIREMENTS.md` (single-project) - Commit: `docs(init): validate specification` +``` +---ci--- +project: +phase: 0 +milestone: v0.X +status: specify +---/ci--- +``` + ### CLARIFY -- Generate clarify questions for ambiguities -- Default-accept at `full` autonomy, present at `supervised`/`guided` -- Commit: `decision(P##): clarification decisions` + +**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//PROJECT.md` and `.ciagent//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//` paths - Delegate to ci-researcher - Research domain, ecosystem, prior art -- Update `.ciagent/` static files with conclusions +- Update `.ciagent//` static files with conclusions (ARCHITECTURE.md, PROJECT.md, etc.) - Commit: `docs(P##): research findings` +``` +---ci--- +project: +phase: [N] +milestone: [vX.X] +status: research +---/ci--- +``` + ### IDEATE (when --ideate flag is passed) -- Delegate to ci-ideation-agent -- Mine git history for patterns, analyze coverage gaps, detect drift -- If backend available: enrich with LLM suggestions -- If --cross-project: mine patterns from other projects -- Present recommendations interactively (accept/skip/modify) -- Accepted ideas update ROADMAP.md and REQUIREMENTS.md -- Commit: `decision(P##): ideation results — [N] accepted, [M] skipped` + +**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//REQUIREMENTS.md`, `.ciagent//ROADMAP.md`, `.ciagent//ARCHITECTURE.md`, `.ciagent//PROJECT.md` +- Ideation commit with `---ci---` block + +Pass the active project slug and any `--ideate` flags. Collect accepted ideas and proceed. ### PLAN -- Delegate to ci-planner + +- Resolve active project from `config.json`; use `.ciagent//` paths +- Delegate to ci-planner with full project context - Create vertical-slice plans with wave ordering +- Plans reference requirement IDs from `.ciagent//REQUIREMENTS.md` - Commit: `docs(P##): create [N] phase plans` +``` +---ci--- +project: +phase: [N] +milestone: [vX.X] +status: plan +---/ci--- +``` + ### EXECUTE -- Create phase branch: `phase/NN-slug` + +- Create phase branch: `/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: commit phase completion +- 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 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 `.ciagent/REQUIREMENTS.md` requirement statuses -- Update `.ciagent/ROADMAP.md` phase status -- Commit: `docs(P##): complete [phase-name] phase` +**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//REQUIREMENTS.md` — mark all milestone requirements as complete + - Update `.ciagent//ROADMAP.md` — mark milestone as complete + - Commit: `docs(milestone): complete [milestone-name]` + +``` +---ci--- +project: +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. @@ -108,7 +223,7 @@ Versioning: Major milestone = breaking schema changes, Feature milestone = miles Between phases, perform a context reset: 1. Commit all work from the current phase -2. Update `.ciagent/` files (phase status, requirement statuses) +2. Update `.ciagent//` 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