pipeline

CLoClo Pipeline

Orchestrate the full development cycle by combining existing skills with Codex review phases and interactive decision points.

CLoClo does NOT reimplement brainstorming, planning, execution, or verification. It invokes the real skills and adds Codex reviews + decision points between them.

Prerequisites — Auto-Install

At pipeline start, check and automatically fix missing dependencies.

Step 1: Check SuperPowers

# Try to invoke a SuperPowers skill to see if it's available

If SuperPowers is NOT available:

1. Read ~/.claude/settings.json
2. Add "superpowers@superpowers-marketplace": true to enabledPlugins
3. Add "superpowers-marketplace": {"source": {"source": "github", "repo": "obra/superpowers-marketplace"}} to extraKnownMarketplaces (if not already present)
4. Write back settings.json
5. Tell the user: "SuperPowers was not installed. I've added it to your settings. Please restart Claude Code and run /pipeline again."
6. STOP. SuperPowers requires a restart to load.

Step 2: Check Codex CLI

codex --version

If codex is NOT found:

1. Run: npm install -g @openai/codex
2. If npm fails, tell the user: "Could not install Codex CLI. Install it manually: npm install -g @openai/codex"
3. After install, run: codex --version to confirm

Step 3: Check Codex authentication

codex whoami

If not authenticated:

1. Tell the user: "Codex is not authenticated. Run ! codex login (the ! prefix runs it in this session)."
2. Wait for the user to confirm login is done.

Step 4: Check Codex Claude Code plugin

find ~/.claude/plugins -name codex-companion.mjs -path '*/codex/scripts/*' 2>/dev/null | head -1

If companion NOT found:

1. Read ~/.claude/settings.json
2. Add "codex@openai-codex": true to enabledPlugins
3. Add "openai-codex": {"source": {"source": "github", "repo": "openai/codex-plugin-cc"}} to extraKnownMarketplaces (if not already present)
4. Write back settings.json
5. Tell the user: "Codex plugin was not installed. I've added it to your settings. Please restart Claude Code and run /pipeline again."
6. STOP. Plugin requires a restart to load.

Degraded Mode

If Codex CLI, auth, or plugin fail but SuperPowers is available:

• WARNING: "Codex reviews will be skipped. Running in SuperPowers-only mode."
• Continue without Codex reviews (phases 2, 4, 6 are skipped).
• The pipeline still works — you just don't get the independent Codex reviews.

Session Setup

1. Ask the user what they want to build (or take their initial message).
2. Create session directory: docs/cloclo-sessions/YYYY-MM-DD-<slug>/
   • <slug> = 2-3 word kebab-case summary of the topic
3. Initialize session.log:

   [timestamp] CLoClo session started: <slug>
   [timestamp] Prerequisites: superpowers=OK, codex=OK|MISSING, auth=OK|MISSING
   

4. If the project has specific verification needs, create pipeline.config.md in the session directory (ask the user or auto-detect from project files).

Phase 1: Design — Invoke superpowers:brainstorming

Invoke Skill("superpowers:brainstorming")

This gives you the FULL SuperPowers brainstorming experience:

• One-question-at-a-time exploration
• Visual companion with HTML mockups in the browser
• Options A/B/C with pros/cons
• 2-3 approach proposals with trade-offs
• Design-for-isolation principles
• "Too simple to need a design" anti-pattern prevention
• Spec self-review (placeholders, coherence, scope, ambiguity)
• User approval gate

After brainstorming completes: The spec will be in docs/superpowers/specs/YYYY-MM-DD-*-design.md. Copy or symlink it to {session_dir}/01-spec.md for session tracking.

Log: [timestamp] Phase 1 complete: 01-spec.md

GATE: Do not proceed until the user has explicitly approved the spec.

---

Phase 2: Codex Review Spec

If Codex available: Invoke the codex-review skill with:

• review_type: spec
• input_file: {session_dir}/01-spec.md
• output_file: {session_dir}/02-codex-review-spec.md

If Codex unavailable: Skip with warning, go directly to Decision Point #1.

Log: [timestamp] Codex review spec: {status}

Decision Point #1

Present the Codex findings (raw, no filtering) and ask:

Codex a review ta spec. Voici ses findings :

[3-5 line summary of key findings from 02-codex-review-spec.md]

Fichier complet : {session_dir}/02-codex-review-spec.md

Que veux-tu faire ?

A. Integrer tous les findings et continuer
   → SuperPowers corrige la spec, ecrit 03-spec-v2.md

B. Integrer certains findings (tu precises lesquels)

C. Ignorer la review et continuer avec la spec actuelle

D. Demander a Codex de creuser un point precis
   → Codex repart en review ciblee

E. Modifier la spec toi-meme
   → Tu edites le fichier, dis "c'est bon" quand pret

Ou tape ce que tu veux — commentaire libre.

Log the user's choice in session.log.

After A or B: SuperPowers corrects the spec → {session_dir}/03-spec-v2.md. Do NOT automatically re-submit to Codex. User controls re-review via D.

---

Phase 3: Plan — Invoke superpowers:writing-plans

Invoke Skill("superpowers:writing-plans")

Input: the approved spec (01-spec.md or 03-spec-v2.md).

This gives you the FULL SuperPowers plan writing:

• Scope check with decomposition
• File structure table
• Bite-sized tasks (2-5 minutes each)
• TDD cycle (write failing test, verify failure, implement, verify pass)
• Complete code blocks (no TBD, no placeholders)
• Pre-written commit messages
• Self-review checklist
• DRY, YAGNI, frequent commits

After plan is written: The plan will be in docs/superpowers/plans/YYYY-MM-DD-*.md. Copy or symlink it to {session_dir}/04-plan.md.

Log: [timestamp] Phase 3 complete: 04-plan.md

---

Phase 4: Codex Review Plan

If Codex available: Invoke codex-review with:

• review_type: plan
• input_file: {session_dir}/04-plan.md
• output_file: {session_dir}/05-codex-review-plan.md
• spec_path: path to approved spec

If Codex unavailable: Skip with warning.

Decision Point #2

Same A-E format as Decision Point #1. If corrections: SuperPowers rewrites → {session_dir}/06-plan-v2.md.

---

Phase 5: Execute — Invoke superpowers:subagent-driven-development

Invoke Skill("superpowers:subagent-driven-development")

Input: the approved plan (04-plan.md or 06-plan-v2.md).

This gives you the FULL SuperPowers execution:

• Fresh subagent per task (no context pollution)
• Two-stage review: spec compliance then code quality
• Status handling (DONE, DONE_WITH_CONCERNS, BLOCKED, NEEDS_CONTEXT)
• Review loops until approved
• Model selection guidance (cheap for mechanical, capable for architecture)
• Process flow with decision diamonds
• Red flags and anti-patterns
• Final integration review

Log: [timestamp] Phase 5 complete: [commit list]

Record base_ref (git SHA before execution) and commit_list (all new commits).

---

Phase 6: Codex Review Implementation

If Codex available: Invoke codex-review with:

• review_type: impl
• input_file: {session_dir}/04-plan.md (or 06-plan-v2.md)
• output_file: {session_dir}/07-codex-review-impl.md
• spec_path: approved spec
• plan_path: approved plan
• base_ref: git SHA recorded before Phase 5
• commit_list: all commits from Phase 5

If Codex unavailable: Skip with warning.

Decision Point #3

Codex a review l'implementation. Voici ses findings :

[Summary of findings]

A. Integrer tous les findings → SuperPowers corrige, nouveau commit

B. Corriger certains findings (tu precises)

C. Ignorer et passer a la verification

D. Demander a Codex de creuser un bug potentiel

E. Lancer un audit complet du projet

Ou commentaire libre.

---

Phase 7: Verify — Invoke superpowers:verification-before-completion

Invoke Skill("superpowers:verification-before-completion")

This gives you the FULL SuperPowers verification:

• Iron Law: NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
• 5-step Gate Function (IDENTIFY, RUN, READ, VERIFY, ONLY THEN)
• Common Failures table
• Red Flags section
• Rationalization prevention table
• Key Patterns (tests, regression, build, requirements, delegation)

If pipeline.config.md exists in the session, use its verification commands. Otherwise, let the verification skill auto-detect or ask the user.

Log: [timestamp] Phase 7 complete: {PASSED|FAILED}

---

Phase 7.5: Visual Verification (If UI Modified)

This phase runs only if the implementation touched UI files (.tsx, .jsx, .vue, .svelte, .html, .css). If no UI files were modified, skip to Phase 8.

Prerequisite: Check agent-browser

command -v agent-browser >/dev/null 2>&1

If agent-browser is NOT found:

• WARNING: "agent-browser is not installed. Visual verification skipped. Install it for UI verification: https://github.com/vrsalis/agent-browser"
• Log: [timestamp] Phase 7.5 SKIPPED: agent-browser not available
• Continue to Phase 8. Do NOT block the pipeline.

If agent-browser IS available:

Steps

1. Detect if any commits from Phase 5 modified UI files:

   git diff --name-only {base_ref}..HEAD | grep -E '\.(tsx|jsx|vue|svelte|html|css|scss)$'
   

2. If UI files found, identify the affected pages/routes.

3. For each affected page:

   agent-browser open <url>          # Open the page
   agent-browser snapshot            # Get interactive elements
   agent-browser screenshot <path>   # Capture visual state
   

4. Read and verify EVERY screenshot immediately. Do not skip this.

   • Does the UI match the spec from Phase 1?
   • Are there visual regressions? Broken layouts? Missing elements?
   • Do interactive elements work? Click buttons, fill forms, verify modals.

5. Save verification screenshots to {session_dir}/screenshots/ for evidence.

6. If issues found:

   • Fix the code.
   • Re-run agent-browser to verify the fix.
   • New commit with fix.

Rules:

• agent-browser is the preferred visual testing tool. If available, use it exclusively.
• Screenshots are evidence. They go in the session directory and optionally in the wiki.
• Every screenshot must be READ and verified. An unread screenshot is not a verification.
• Use the project's actual port (typically from docker/dev server), never assume.

Log: [timestamp] Phase 7.5 complete: {N pages verified, M screenshots}

---

Session File Structure

docs/cloclo-sessions/YYYY-MM-DD-<slug>/
├── 01-spec.md                  ← From superpowers:brainstorming
├── 02-codex-review-spec.md     ← From codex-review skill
├── 03-spec-v2.md               ← If corrections after review
├── 04-plan.md                  ← From superpowers:writing-plans
├── 05-codex-review-plan.md     ← From codex-review skill
├── 06-plan-v2.md               ← If corrections after review
├── 07-codex-review-impl.md     ← From codex-review skill
├── screenshots/                ← Visual verification evidence (Phase 7.5)
│   ├── page-name-01.png
│   └── page-name-02.png
├── session.log                 ← All decisions + timestamps + job-ids
└── pipeline.config.md          ← Optional verification config

Session Log Format

[2026-04-06T14:30:00] CLoClo session started: auth-refactor
[2026-04-06T14:30:01] Prerequisites: superpowers=OK, codex=OK, auth=OK
[2026-04-06T14:45:00] Phase 1 complete: 01-spec.md
[2026-04-06T14:45:30] User approved spec
[2026-04-06T14:50:00] Codex review spec started (job-id: task-abc123)
[2026-04-06T14:55:00] Codex review spec complete: 02-codex-review-spec.md
[2026-04-06T14:55:30] Decision #1: A (integrate all)
[2026-04-06T14:58:00] Spec corrected: 03-spec-v2.md
[2026-04-06T15:10:00] Phase 3 complete: 04-plan.md
[2026-04-06T15:15:00] Codex review plan started (job-id: task-def456)
[2026-04-06T15:22:00] Codex review plan complete: 05-codex-review-plan.md
[2026-04-06T15:22:30] Decision #2: B (integrate findings 1,3, ignore 2)
[2026-04-06T15:25:00] Plan corrected: 06-plan-v2.md
[2026-04-06T15:26:00] Phase 5 started (base_ref: a1b2c3d)
[2026-04-06T15:45:00] Phase 5 complete: 5 commits (a1b..f6e)
[2026-04-06T15:50:00] Codex review impl started (job-id: task-ghi789)
[2026-04-06T16:02:00] Codex review impl complete: 07-codex-review-impl.md
[2026-04-06T16:02:30] Decision #3: A (fix all)
[2026-04-06T16:10:00] Phase 7: VERIFICATION_PASSED

Phase 8: Wiki Ingest (Automatic)

This phase runs automatically if a project wiki exists (wiki/schema.md). If no wiki exists, skip silently. The user can set one up later with /wiki init.

What gets ingested

The pipeline session is a rich knowledge source — decisions, trade-offs, reviews, patterns. Auto-ingest the session as a single source:

1. Check if wiki/schema.md exists. If not → skip Phase 8 entirely.
2. Read wiki/schema.md and wiki/index.md for context.
3. Create a combined session source at wiki/sources/YYYY-MM-DD-pipeline-<slug>.md:

   # Pipeline Session: <slug>
   
   ## Spec Summary
   [Key decisions and trade-offs from 01-spec.md or 03-spec-v2.md]
   
   ## Codex Findings
   [Important findings from reviews — bugs caught, patterns flagged]
   
   ## Implementation Decisions
   [Architecture choices, rejected alternatives, lessons learned]
   
   ## Verification
   [What was tested, what passed, what needed fixing]
   

4. Create a source summary page at wiki/pages/sources/YYYY-MM-DD-pipeline-<slug>.md.
5. Update/create entity and concept pages for:
   • New components, services, or modules created
   • Patterns established or changed
   • Bugs found and how they were fixed
   • Architecture decisions and their rationale
6. Update wiki/index.md with new/modified pages.
7. Append to wiki/log.md:

   ## [YYYY-MM-DD HH:MM] INGEST | Pipeline session: <slug>
   - Source: sources/YYYY-MM-DD-pipeline-<slug>.md
   - Pages created: <list>
   - Pages updated: <list>
   

8. Report:

   Wiki updated: +N pages from pipeline session
   

Log: [timestamp] Phase 8 complete: wiki updated (N pages)

---

Important Rules

1. Do NOT reimplement SuperPowers or Codex skills. Invoke them. They are the real thing.
2. After correction (A or B), do NOT auto-resubmit to Codex. User controls via option D.
3. Codex reviews are FOREGROUND. Claude waits, shows "Codex is reviewing...", reads the result.
4. If user types anything other than A-E: treat as free-form comment and adapt.
5. Each phase outputs to session dir with numbered filenames for traceability.
6. Session can be resumed. Check session.log for last completed phase and continue from there.
7. SuperPowers specs and plans are saved to their own directories (docs/superpowers/specs/, docs/superpowers/plans/). CLoClo copies or symlinks them into the session dir for session tracking.
8. Wiki ingest is automatic and silent. If no wiki exists, Phase 8 is skipped without mention. The wiki grows transparently as the user works.