Skip to content

ilandahan/AID / skills/pipeline-orchestrator

pipeline-orchestrator

Verified

Drives the Phase 4-5 dev pipeline state machine with sub-agent reviews and bounded autoresearch gates. Use when running /pipeline or executing an approved plan.

FileKindSize
SKILL.extended.mdmarkdown11.7 KB
SKILL.mdskill md70.3 KB
config.default.jsonconfig1.5 KB
gate.mjsscript38.3 KB
gate.test.mjsscript31.9 KB
references/escalation-protocol.mdmarkdown4.4 KB
references/load-bearing-assumptions.mdmarkdown3.2 KB
references/state-machine.mdmarkdown8.8 KB
test-escalation-loop.shexecutablescript13.8 KB

SKILL.extended.md

View on GitHub
---
name: pipeline-orchestrator-extended
description: Extended details for the pipeline orchestrator skill — edge cases, variable extraction, and complete transition logic.
---

# Pipeline Orchestrator — Extended Details

## Variable Extraction Guide

### For code-review-agent

**Step 1: Task Context**
```bash
# Read context
cat .aid/context.json
# Extract: task_id, task_description, current_step
```

Format for `{{TASK_CONTEXT}}`:
```
Task ID: [task_id]
Description: [task_description]
Phase: 4 - Development
Step: CODE_REVIEW
```

**Step 2: Changed Files**
```bash
# Get list of changed files (staged + unstaged)
git diff --name-only HEAD
# Also check untracked files that are part of the task
git status --porcelain
```

Read EACH changed file's full content. Concatenate as:
```
--- FILE: path/to/file1.ts ---
[file content]

--- FILE: path/to/file2.ts ---
[file content]
```

**Step 3: Tech Spec Excerpt**
```bash
# Read the tech spec
cat docs/tech-spec/*.md
```
Extract the section relevant to the current task. If unclear, include the full spec. If `docs/tech-spec/` is absent or empty (non-AID project), fall back to the frozen `.aid/pipeline/<task_id>/brief.md` (ORIGINAL_REQUEST + STATED_WHY + DEVELOP plan) as the architectural reference and note in `{{TECH_SPEC_EXCERPT}}` that no formal tech-spec exists — never review architecture against nothing.

**Step 4: Code Standards**
```bash
cat agents/code-review-agent/references/review-rules.md
```
Include verbatim — do not summarize.

### For test-review-agent

**Step 1: Task Context**
Same as code-review-agent.

**Step 2: Implementation Files**
Read ALL production source files that were modified in the current task. These are the files being tested.

**Step 3: Test Files**
Read ALL test files that correspond to the implementation files. Check common patterns:
- `src/foo.ts` → `tests/foo.test.ts`, `__tests__/foo.test.ts`, `src/foo.spec.ts`
- `src/services/UserService.ts` → `tests/services/UserService.test.ts`

**Step 4: Test Results**
Run the test command and capture output:
```bash
npm test 2>&1
```
Include full output (pass/fail counts, error messages, coverage if available).

---

## Transition Logic (Detailed)

### DEVELOP → CODE_REVIEW

**Trigger:** Developer signals implementation is ready.

**Actions:**
1. Run `git diff --name-only HEAD` to identify changed files
2. Read all changed files
3. Read tech spec excerpt
4. Read code standards reference
5. Construct code-review-agent prompt with variables
6. Spawn agent
7. Update state: `current_step: "CODE_REVIEW"`, increment `iterations.code_review`

### CODE_REVIEW → TDD (on PASS)

**Trigger:** Agent returns `verdict: "PASS"`

**Actions:**
1. Store review result in `last_review_result`
2. Log to `step_history`
3. Update state: `current_step: "TDD"`
4. Display: "Code review PASSED. Proceeding to TDD..."

### CODE_REVIEW → FIX_CODE (on FAIL)

**Trigger:** Agent returns `verdict: "FAIL"` OR `scores.overall < config.thresholds.code_review_pass`

**Actions:**
1. Check `iterations.code_review` < `max_iterations.code_review`
2. If at max → ESCALATE
3. Store FULL review result in `last_review_result` (including scores, score_justification, biggest_gaps)
4. Display full review context using the FIX_CODE template from SKILL.md:
   - Overall score and per-category scores
   - Score justification and biggest gaps
   - All `action_required` items with file:line references
   - Which categories need the most improvement (lowest scores)
5. Update state: `current_step: "FIX_CODE"`
6. Developer applies fixes, prioritizing lowest-scoring categories
7. After fixes → return to CODE_REVIEW (loop)

### TDD → VISUAL_QA (on PASS)

**Trigger:** All tests pass (exit code 0)

**Actions:**
1. Capture test output
2. Check if VISUAL_QA should run:
   - `config.visual_qa.enabled` must be `true`
   - If `config.visual_qa.skip_if_no_ui_changes` is `true`, check if any changed files are in `src/components/`, `src/pages/`, or contain JSX/TSX → if no UI files changed, skip to TEST_REVIEW
3. Check prerequisites: dev server running + Chrome DevTools MCP available
4. If prerequisites fail → skip VISUAL_QA with warning, advance to TEST_REVIEW
5. If all checks pass → Update state: `current_step: "VISUAL_QA"`, proceed to visual-qa-agent spawn

### VISUAL_QA → TEST_REVIEW (on PASS)

**Trigger:** Agent returns `verdict: "PASS"` AND `scores.overall >= config.thresholds.visual_qa_pass`

**Actions:**
1. Store review result in `last_review_result`
2. Log lighthouse scores alongside visual scores in `step_history`
3. Update state: `current_step: "TEST_REVIEW"`
4. Display: "Visual QA PASSED (X.X/10). Lighthouse: A11y X, SEO X, BP X. Proceeding to test review..."

### VISUAL_QA → FIX_VISUAL (on FAIL)

**Trigger:** Agent returns `verdict: "FAIL"` OR `scores.overall < config.thresholds.visual_qa_pass`

**Actions:**
1. Check `iterations.visual_qa` < `max_iterations.visual_qa`
2. If at max → ESCALATE
3. Store FULL review result in `last_review_result` (including scores, lighthouse, issues, testing_summary)
4. Display full review context using the FIX_VISUAL template from SKILL.md
5. Update state: `current_step: "FIX_VISUAL"`
6. Developer applies visual fixes, prioritizing functionality > craft > design quality
7. After fixes → return to VISUAL_QA (loop)

### TEST_REVIEW (unchanged) — on PASS

### TDD → FIX_TESTS (on FAIL)

**Trigger:** Tests fail (non-zero exit code)

**Actions:**
1. Check `iterations.test_fix` < `max_iterations.test_fix`
2. If at max → ESCALATE
3. Display failing test output
4. Update state: `current_step: "FIX_TESTS"`
5. Developer fixes tests
6. After fixes → re-run tests (TDD loop)

### TEST_REVIEW → PHASE_GATE (on PASS)

**Trigger:** Agent returns `verdict: "PASS"`

**Actions:**
1. Store review result
2. Update state: `current_step: "PHASE_GATE"`
3. Spawn qa-validator-agent

### PHASE_GATE → API_TESTS (on PASS)

**Trigger:** QA validator returns `verdict: "PASS"` or `can_proceed: true`

**Actions:**
1. Update state: `current_phase: 5`, `current_step: "API_TESTS"`
2. Display: "Phase 4 complete. Advancing to Phase 5: QA & Ship"
3. Reset Phase 5 iteration counters

### → DEVELOP (backward, on PHASE_GATE FAIL re-examine OR AR_ACCEPTANCE gap re-enter)

**Trigger:** Transition INTO DEVELOP from PHASE_GATE (FAIL re-examine) OR AR_ACCEPTANCE (gap re-enter)

**Actions:**
1. Reset Phase 4/5 inner iteration counters: set `iterations.code_review`, `iterations.test_fix`, `iterations.test_review`, and `iterations.ar_design` to 0
2. The OUTER counters `iterations.phase_gate_reexamine` and `iterations.ar_acceptance_rounds` PERSIST — they are the real loop bound that guarantees termination
3. This mirrors the forward "Reset Phase 5 iteration counters" rule so the backward boundary is symmetric

### Phase 5 transitions follow the same PASS/FAIL pattern.

### CERTIFICATION

**Actions:**
1. Run ALL test commands from config in sequence:
   - `npm test` (unit)
   - `npm test -- --testPathPattern=integration` (integration)
   - `npx playwright test` (e2e)
   - `npm run cucumber` (cucumber)
2. Run `npm test -- --coverage` for coverage report
3. Verify coverage >= `min_coverage_percent` threshold
4. If all pass: set `pipeline_status: "completed"`, archive to `history.json`
5. Generate certification report
6. RETRO/SYNTHESIS (terminal, CERTIFICATION → DONE):
   - Write `.aid/pipeline/<task_id>/retro.md` aggregating `step_summaries` + `final_scores` + AR gap reasons (AR_DESIGN/AR_FUNCTION/AR_ACCEPTANCE keep/revert reasons) into a short, human-readable narrative
   - Invoke the existing user-level retro skill (`~/.claude/skills/retro`) to close the loop
   - Optionally append a one-line learning to user memory `MEMORY.md`
   - Report-only — NEVER auto-commits

---

## Edge Cases

### No `.aid/context.json`

If context file doesn't exist when `/pipeline` is called:
- Display error: "No active task found. Set up a task context first with `/context-update`"
- Do not initialize pipeline

### Pipeline Already Running

If `state.json` exists with `pipeline_status: "running"`:
- Display current state
- Ask: "Pipeline already active at step [X]. Resume from here? (y/n)"

### Pipeline Already Completed

If `state.json` exists with `pipeline_status: "completed"`:
- Display: "Previous pipeline completed for task [X]. Start new pipeline? (y/n)"
- If yes, archive old state and initialize fresh

### Sub-Agent Returned No Usable Result

CORRECTED 2026-09-04. This section used to say "Treating as FAIL" and enter a fix cycle. That is
wrong, and it contradicted `gate.mjs`, whose own comment reads: *a review that produced no score has
not scored badly — it has not run*. FAIL launders a delivery failure into a quality signal and spends
one of five fix cycles on a review that scored nothing. It also hid the event from the record
entirely, which is why "3 of 4 spawned agents produced nothing this session" was uncountable.

Three different events were being conflated. Handle them apart:

| What actually happened | Correct handling |
|---|---|
| Verdict is legible but not clean JSON | Recover the JSON from the transcript and run the gate on the recovered scores. This is a real round and it counts as one. |
| Findings exist but there are no scores anywhere | ERROR. Re-spawn the agent once. Never invent a number. |
| Agent idle, reports "available", produced no message | ERROR, plus a transcript recovery attempt — the verdict is usually on disk even when delivery failed. |

`FAIL` is not one of the three, and it is not a value the gate emits. Run
`gate.mjs --step <STEP> --scores '{}'`, which returns ERROR with exit 3 and records one
`result: "ERROR"` row in `step_history` without consuming a fix cycle.

Recovery procedure: see **When a spawned agent reports no result** in `SKILL.md`.

### Config File Missing

If `.aid/pipeline/config.json` doesn't exist:
- Create with default values
- Display: "Created pipeline config with defaults. Edit `.aid/pipeline/config.json` to customize."

### Test Command Not Found

If test command fails with "command not found":
- Display: "Test command `[command]` not found. Update `.aid/pipeline/config.json` test_commands."
- Set `pipeline_status: "paused"`
- Wait for user to fix config

---

## History Archive

When pipeline completes (CERTIFICATION passes), append to `.aid/pipeline/history.json`:

```json
{
  "runs": [
    {
      "task_id": "TASK-001",
      "started_at": "ISO-8601",
      "completed_at": "ISO-8601",
      "total_steps": 12,
      "iterations": { "code_review": 2, "test_fix": 1, "test_review": 1, "api_fix": 0, "e2e_fix": 0 },
      "final_scores": {
        "code_review": { "security": 9, "code_quality": 8, "documentation": 7, "architecture": 8, "overall": 8.1 },
        "test_review": { "test_quality": 8, "coverage": 7, "independence": 9, "alignment": 8, "production_safety": 10, "mock_analysis": 8, "overall": 8.2 }
      },
      "step_history": [...],
      "narrative": "Short retro synthesis aggregating step_summaries + final_scores + AR gap reasons (mirrors .aid/pipeline/<task_id>/retro.md)."
    }
  ]
}
```

---

## Pipeline Status Display

When `/pipeline-status` is invoked, read `state.json` and display:

```
Pipeline Status
Task: [task_id] — [description]
Phase: [current_phase]
Step: [current_step]
Status: [pipeline_status]
Started: [started_at]
Last Updated: [last_updated]

Iterations:
  Code Review: [N]/[max]
  Test Fix: [N]/[max]
  Test Review: [N]/[max]
  API Fix: [N]/[max]
  E2E Fix: [N]/[max]

Step History:
  1. DEVELOP → PASS (10:00)
  2. CODE_REVIEW → FAIL — 5.8/10 [security: 4, quality: 7, arch: 7, docs: 5] (10:05)
  3. FIX_CODE → done (10:10)
  4. CODE_REVIEW → PASS — 7.6/10 [security: 8, quality: 7, arch: 8, docs: 7] (10:15)
  ...

Last Review:
  Score: [overall]/10 (threshold: [from config])
  [Per-category scores]
  [Summary of biggest_gaps]
  [Summary of action_required]
```
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall