From da528cc4937c13ea03aa7acfac3cbd8ece413dd2 Mon Sep 17 00:00:00 2001 From: Jon Chery Date: Sat, 30 May 2026 19:45:30 +0000 Subject: [PATCH] docs: add ideate workflow + update run workflow with IDEATE stage and multi-project MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ---ci--- phase: 0 milestone: v0.10 status: specify decisions: - id: D-089 decision: No separate codebase map command — subsumed by ideation rationale: Git-native + .ciagent/ covers all mapping needs; avoids tree-sitter dep confidence: 0.88 - id: D-090 decision: Milestone v0.10 for ideate + multi-project rationale: Significant features but not schema-breaking confidence: 0.95 ---/ci--- - Add opencode/ci/workflows/ideate.md: full ideation pipeline specification - Update opencode/ci/workflows/run.md: add IDEATE stage, update multi-project Step 0 --- opencode/ci/workflows/ideate.md | 288 ++++++++++++++++++++++++++++++++ opencode/ci/workflows/run.md | 22 ++- 2 files changed, 307 insertions(+), 3 deletions(-) create mode 100644 opencode/ci/workflows/ideate.md diff --git a/opencode/ci/workflows/ideate.md b/opencode/ci/workflows/ideate.md new file mode 100644 index 0000000..3c6c5a2 --- /dev/null +++ b/opencode/ci/workflows/ideate.md @@ -0,0 +1,288 @@ +--- +description: Run the CIAgent ideation pipeline — analyze project for improvement opportunities, validate recommendations with user, update long-term documents +--- + +# CIAgent Ideate + +Run the CIAgent ideation engine to discover improvement opportunities based on git-native signals, codebase analysis, and cross-project patterns. + +**Usage:** `ciagent ideate [options]` + +## Step 0: Confirm Active Project + +Check `ci listProjects()` or read `.ciagent/config.json` to determine project context. + +If `.ciagent/config.json` has `active_projects` array with length > 0: +- Use `--project ` to target a specific project +- Use `--project all` to run ideation across all active projects (deduplicate findings) +- If no `--project` flag, use first project in `active_projects` + +If `.ciagent/config.json` has `active_project` string (legacy): +- Use that project as the target +- Backwards-compatible: if both `active_project` and `active_projects` exist, `active_projects` takes precedence + +## Step 1: Load Project Context + +```bash +git log --max-count=50 +git branch -a +``` + +Read project reference files: +- `.ciagent/PROJECT.md` — Vision, requirements, constraints, key decisions +- `.ciagent/ROADMAP.md` — Phases, milestones, success criteria +- `.ciagent/REQUIREMENTS.md` — REQ-IDs, status, traceability +- `.ciagent/ARCHITECTURE.md` — Component boundaries, data flow +- `.ciagent/config.json` — Ideation configuration, autonomy level + +## Step 2: Run Ideation Tiers + +Execute tiers in order. Each tier produces `Idea[]` objects. Ideas from all tiers are merged and deduplicated before presentation. + +### Tier 1: Mechanical Analysis (Always Available) + +No backend required. All signals come from git history, `.ciagent/` files, and filesystem. + +#### 2.1 Git-Native Pattern Mining + +```bash +git log --all --grep="lessons:" --format="%B" -50 +git log --all --grep="decisions:" --format="%B" -50 -- "***confidence***0.*" +git log --all --grep="escalation:" --format="%B" -50 +git log --all --grep="compound:" --format="%B" -50 +``` + +Extract: +- **Repeated lessons** — topics appearing > 1 time → systemic issue +- **Low-confidence decisions** — confidence < 0.7 in `---ci---` blocks → improvement targets +- **Escalation types** — each type identifies a process gap +- **Compound solutions** — suggest generalizing patterns that were solved multiple times +- **Partial requirements** — `requirements: partial: [REQ-XX]` in `---ci---` blocks + +#### 2.2 Coverage Gap Analysis + +- Parse REQUIREMENTS.md for `pending` and `in_progress` status requirements +- Cross-reference with PLAN.md task completion +- Identify requirements with no corresponding implementation tasks + +#### 2.3 Verification Layer Inversion + +For each verification layer, identify what's MISSING: + +- **Structural**: Files referenced but not created, stubs, TODOs, placeholder implementations +- **Behavioral**: Test suites with < 80% coverage, missing test files for covered requirements +- **Security**: No STRIDE analysis for modified components, missing input validation patterns +- **Quality**: P1/P2 review findings unresolved, consistent style violations + +#### 2.4 Architectural Drift Detection + +- Parse ARCHITECTURE.md component tree +- Compare against actual `src/` directory structure +- Flag components documented but not implemented +- Flag components implemented but not documented +- Check import graph for unauthorized dependencies between components + +#### 2.5 Spec-Driven Improvement + +- Analyze REQUIREMENTS.md for ambiguous language ("should" vs "must", undefined terms) +- Check for contradictions between requirements +- Compare against common patterns for the project type (identified from package.json keywords) +- Flag requirements with no verification criteria + +### Tier 2: Backend-Enriched Analysis (When LLM Available) + +Requires an intelligence backend (opencode, openai, anthropic, or ollama). + +#### 2.6 Prioritization and Ranking + +- Evaluate all mechanical findings for impact and feasibility +- Rank ideas by: (1) number of signals corroborating, (2) severity of the gap, (3) ease of addressing + +#### 2.7 Novel Improvement Suggestions + +- Suggest improvements beyond pattern matching (e.g., "consider rate limiting" based on industry best practices, not just a repeated lesson) +- Generate concrete action plans for each accepted idea +- Identify bleeding-edge approaches relevant to the project's tech stack + +#### 2.8 Chaos Engineering Ideation + +- Generate failure scenarios: "What if the backend is unavailable?", "What if a requirement changes mid-implementation?", "What if test coverage drops below threshold?" +- Map failure scenarios to code that would break +- Suggest resilience improvements for each scenario + +### Tier 3: Cross-Project Pattern Transfer (When Multi-Project Registry Exists) + +#### 2.9 Cross-Project Mining + +For each project in `.ciagent/config.json` projects array: +- Read that project's `---ci---` blocks for lessons, decisions, compound solutions +- Find patterns relevant to the current project (same requirement area, same tech stack from package.json) +- Suggest adaptations of lessons learned elsewhere +- Calculate relevance score based on tech stack similarity + +## Step 3: Merge and DeduplicateIdeas + +Combine ideas from all tiers. Deduplicate by: +- Same `title` strings → keep highest confidence version +- Same `relatedReq` → merge into single idea with combined sources +- Same `category` + overlapping domains → keep most specific + +Sort by confidence (descending), then by number of corroborating signals. + +## Step 4: Interactive Validation + +Present ideas one-at-a-time to the user: + +``` +═══ Recommendation N of M ═══ + +Category: [CATEGORY] | Confidence: [0.XX] | Tier: [mechanical/backend-enriched/cross-project] +Title: [idea title] +Rationale: [idea rationale] +Related Req: [REQ-ID or "new requirement"] +Source: [source signal type] + +Actions: + 1. Accept (add to next milestone as new requirement) + 2. Skip + 3. Modify (edit title/rationale before accepting) + 4. Details (show full analysis including signal sources) +``` + +For each accepted idea: +1. Generate `IDEATE-NN` requirement ID +2. Prompt for milestone placement (append to existing or create new) +3. Add to REQUIREMENTS.md with status `pending` +4. Add to ROADMAP.md next milestone + +## Step 5: Update Long-Term Documents + +For each accepted idea: + +### REQUIREMENTS.md + +Add a new row in the appropriate milestone section: +``` +| IDEATE-NN | [idea title] | [priority] | [phase] | pending | +``` + +### ROADMAP.md + +Add the idea to the next milestone's phase structure: +- If next milestone has a matching phase category, append to that phase +- If no matching phase, suggest a new phase + +### ARCHITECTURE.md + +If the idea involves architectural changes, note the component change needed. + +### PROJECT.md + +If the idea adds new requirements or key decisions, update accordingly. + +Commit all document updates: +``` +decision(P##): ideation results — [N] accepted, [M] skipped +``` + +## Step 6: Ask-After-Validation Kickoff + +After all ideas have been validated: + +``` +Accepted: [N] recommendations +Skipped: [M] recommendations + +Would you like to kick off the run workflow for these ideas? (y/n) +``` + +If yes: Start `ciagent run` with the updated project context. The `--ideate` flag is NOT needed because the ideas are already in ROADMAP.md and REQUIREMENTS.md — the standard pipeline will pick them up. + +If no: Output summary and exit. + +## Command Flags + +| Flag | Description | +|------|-------------| +| `--category ` | Focus on specific categories: security,quality,architecture,coverage,improvement,spec,chaos (comma-separated) | +| `--affected` | Cascade impact analysis: given current changes, what else needs updating | +| `--spec` | Analyze specification completeness and ambiguity | +| `--external` | Include external signals: npm audit, OSV advisories, dependency staleness | +| `--cross-project` | Mine patterns from all projects in multi-project registry | +| `--output ` | Output format: interactive (default), json, markdown | +| `--project ` | Target project(s): slug, comma-separated, or `all` | +| `--backend ` | Override intelligence backend for enrichment tier | + +## Pipeline Integration + +When `ciagent run --ideate` is used, the IDEATE stage is inserted between RESEARCH and PLAN: + +``` +SPECIFY → CLARIFY → RESEARCH → IDEATE → PLAN → EXECUTE → TEST → VERIFY → COMPLETE +``` + +IDEATE stage commit: +``` +---ci--- +phase: [phase-number] +milestone: [milestone-version] +status: ideate +decisions: + - id: D-XXX + decision: "Accepted [N] ideation recommendations" + rationale: "[summary of accepted ideas]" + confidence: [avg confidence] +requirements: + covered: [IDEATE-NN, ...] +---/ci--- +``` + +## Output Modes + +### Interactive (default) + +Presented one-at-a-time with accept/skip/modify actions. + +### JSON + +```json +{ + "project": "[slug]", + "milestone": "[version]", + "ideas": [ + { + "id": "IDEATE-NN", + "source": "[source type]", + "category": "[category]", + "title": "[title]", + "rationale": "[rationale]", + "confidence": 0.XX, + "relatedReq": "[REQ-ID or null]", + "actions": ["[action types]"], + "tier": "[mechanical/backend-enriched/cross-project]", + "accepted": true + } + ], + "summary": { + "total": 8, + "accepted": 6, + "skipped": 2, + "by_category": { "coverage": 2, "architecture": 1, "security": 1, "quality": 1, "improvement": 1 } + } +} +``` + +### Markdown + +Formatted report suitable for PR descriptions or documentation. + +## Error Recovery + +On tier failure: +1. Mechanical tier always succeeds (git + filesystem only) +2. Backend-enriched tier: if backend unavailable, fall back to mechanical-only output +3. Cross-project tier: if no other projects in registry, skip silently + +On validation failure (no ideas generated): +- Output "No improvement ideas identified for this project." +- Suggest `ciagent ideate --spec` for specification analysis or `--external` for external signals \ No newline at end of file diff --git a/opencode/ci/workflows/run.md b/opencode/ci/workflows/run.md index 75c0d0b..e626393 100644 --- a/opencode/ci/workflows/run.md +++ b/opencode/ci/workflows/run.md @@ -14,11 +14,18 @@ If no phase number specified, continues from the current phase (detected from gi 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: -- Confirm `active_project` is correct for this run -- If not, set it with `ci setActiveProject()` +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 ` 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 +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 + If single-project mode: proceed with existing conventions. ## Step 1: Load Git Context @@ -60,6 +67,15 @@ For each stage in order (starting from current or from `specify`): - Update `.ciagent/` static files with conclusions - Commit: `docs(P##): research findings` +### 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` + ### PLAN - Delegate to ci-planner - Create vertical-slice plans with wave ordering