ci/opencode/ci/workflows/ideate.md

description

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 <slug> 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

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

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 <cats>	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 <format>	Output format: interactive (default), json, markdown
--project <slugs>	Target project(s): slug, comma-separated, or all
--backend <provider>	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

{
  "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