Visual Flow — CoddexaDEV

◈ Pipeline OS — Complete Execution Flow

Entry

User Submits Prompt

Boss types a task in dev.coddexa.media and clicks RUN PIPELINE. Pipeline OS creates a job instantly.

Output artifacts

job_id = job-{uuid[:8]} status: NEW state.json → /pipeline-os/jobs/{id}/ POST /api/jobs

Phase 1 PM Agent — Refine · Audit · Research status: PM_RUNNING

Step 1a — Sequential

Prompt Refiner

Grok · grok-3-latest · fallback: Claude Sonnet · claude-sonnet-4-6

Transforms the raw vague prompt into a precise technical specification under 300 words. Defines: what to build, where it fits in Coddexa ecosystem, key requirements, expected inputs/outputs, success criteria.

Input → Output

raw prompt → refined_prompt cost_usd += refine_cost

Fallback chain

1st: Grok grok-3-latest 2nd: Claude Sonnet (if Grok fails) both fail → BLOCKED (job stops)

Step 1b — Sequential

Server Auditor

Claude Haiku · claude-haiku-4-5-20251001

Two-phase scan: server state (disk, ports, services) + deep project scan (git log, file tree, README) for any existing project matching the request keywords.

Phase A — Server snapshot (subprocess)

df -h / ss -tlnp ls /opt/coddexa/ pip3 list systemctl (coddexa services)

Phase B — Project context (keyword match on prompt)

find /opt/coddexa — dirs matching prompt keywords git log --oneline -15 (per matching project) file structure (maxdepth 2, no venv/__pycache__) README.md / main.py / package.json (first 800 chars)

Output: audit_result JSON

relevant_existing[] project_exists (bool) project_path completed_work[] — what's already built missing_work[] — what's not done yet ports_in_use[] dependencies_available[] constraints[] recommended_base_dir reuse_opportunities[] notes

Step 1c — Sequential (after audit)

Technical Researcher

Gemini 2.5 Pro · gemini-2.5-pro

Researches implementation guidance with full project context. Knows what already exists, what's been built, what's missing — so recommendations target only the delta, not a full rebuild.

Input context

refined_prompt project_exists + project_path completed_work[] + missing_work[] ports_in_use + constraints + reuse_opportunities claude_code_constraints.md agent memory (researcher)

Output: research_packet JSON

recommended_stack[] implementation_patterns[] pitfalls[] security_notes[] estimated_complexity estimated_files summary

Step 1d — Verify

Result Verification + Memory Save

Checks if audit or research returned errors. Saves raw results. Updates agent memory. Transitions status.

if audit.error → BLOCKED if research.error → BLOCKED if ok → RESEARCH_DONE saves raw to /pipeline-os/memory/ updates agent memory (complexity, stack, reuse)

Phase 2 Council Plan Mode — 6 Seats in Parallel status: COUNCIL_PLANNING

Each seat receives: refined_prompt + audit_result + research_packet + agent memory

claude-architecture VETO

Architecture & Executor Compatibility

System design, modularity, file structure, API design, data flow, how Claude Code executor will implement this

Claude Sonnet · claude-sonnet-4-6

gpt4o-product

Product & UX

User experience, feature completeness, workflow design, success metrics, interface design

DeepSeek · deepseek-chat

gemini-validation

Research Validation

Validate libraries are current and correct, patterns are best practice, surface better alternatives

Gemini 2.5 Flash · gemini-2.5-flash

deepseek-code

Code Quality

Clean code patterns, error handling, testing, technical debt, maintainability, performance

DeepSeek · deepseek-chat

grok-devil

Devil's Advocate

Challenge every assumption, find failure modes, scope creep, unrealistic timelines, missing edge cases

DeepSeek · deepseek-chat

mistral-security VETO

Security & Privacy

Attack vectors, data exposure, auth/authz, secrets handling, GDPR, input validation

DeepSeek · deepseek-chat

Output: council_plans dict — seat → plan text (up to 8192 tokens each) · each plan saved to raw memory

Phase 3 Synthesis + Council Review Loop max 5 iterations · config.max_council_iterations

Phase 3a — Plan Maker · status: SYNTHESIZING

Master Plan Synthesis

Claude Opus · claude-opus-4-7 · max_tokens: 8192

Context injected into prompt

agent memory (plan-maker) refined_prompt 6 council plans (all seats) claude_code_constraints.md CLAUDE.md (first 2000 chars) cumulative_votes (if iter > 0)

Output

master_plan.md — saved as job artifact format: Overview · Architecture · Tasks · Security · Risks Tasks: ### Task N: Name — files, commands, success criteria

⟐ Parallel — Phase 3b: Council Review · status: COUNCIL_REVIEWING

Each seat receives: master_plan + refined_prompt + all cumulative feedback from previous iterations

claude-architecture VETO

APPROVE / REVISE / REJECT

Architectural soundness, executor compatibility, file structure

claude-sonnet-4-6

gpt4o-product

APPROVE / REVISE / REJECT

Product completeness, UX, workflow quality

deepseek-chat

gemini-validation

APPROVE / REVISE / REJECT

Library correctness, best practices validation

gemini-2.5-flash

deepseek-code

APPROVE / REVISE / REJECT

Code quality, error handling, maintainability

deepseek-chat

grok-devil

APPROVE / REVISE / REJECT

Failure modes, scope creep, missing edge cases

deepseek-chat

mistral-security VETO

APPROVE / REVISE / REJECT

Security posture, attack surface, data handling

deepseek-chat

Vote objects saved: CouncilVote(seat, model, vote, feedback, iteration) · appended to council_votes[] + cumulative_votes[]

Iteration Gate

Approve or Revise?

APPROVED — all seats approve → exit loop → status: APPROVED REVISE — any seat revises → loop back to Plan Maker with full cumulative feedback DEADLOCK — max 5 iterations reached without approval → status: BLOCKED

VETO seats (claude-architecture, mistral-security) can force block independently. Telegram sent after each iteration with vote summary.

Pre-Execution · status: APPROVED

Git Snapshot

Takes a git snapshot of the target directory before any changes are made. Creates .git if needed.

base_dir = audit_result.recommended_base_dir git init (if no .git) git add -A git commit "pipeline-os snapshot before {job_id}" git_snapshot = short hash Telegram: 🔨 Executor starting...

Phase 4 Executor — GSD Execute-Phase (Wave-Based) status: EXECUTING

Step 4a — Git Snapshot + Parse

Pre-Execution Safety

Git snapshot of project dir before any changes (init repo if needed). Parse tasks from master_plan to get tasks_total. Abort → FAILED if no tasks found.

git init (if no .git) git add -A → git commit "snapshot before {job_id}" job.git_snapshot = short hash no tasks → FAILED

Step 4b — GSD Bridge

Master Plan → GSD Execution Structure

Converts Pipeline OS master_plan into a GSD-compatible .gsd/ directory. Groups tasks into parallel waves (3 tasks/wave by default). This is the handoff point from Pipeline OS planning to GSD execution.

Writes to {base_dir}/.gsd/

PLAN.md — tasks grouped in waves with frontmatter (phase, goal) STATE.md — project name, current_phase, job_id config.json — project, base_dir, job_id, current_phase

Wave grouping logic

tasks parsed: regex ^#{2,3}\s+Task\s+\d+ grouped 3 per wave (independent by default) returns phase_slug = "pipeline-{job_id[:8]}"

⟐ GSD Execute-Phase — Wave-Based Parallel Execution via Claude Code CLI

claude --dangerously-skip-permissions --model sonnet -p "/gsd-execute-phase {phase_slug}" · cwd: base_dir · timeout: 1800s

GSD Orchestrator

Wave Coordinator

Reads .gsd/PLAN.md, groups tasks into waves, spawns gsd-executor subagents per wave. Stays lean — coordinates, never executes directly.

reads PLAN.md + STATE.md dependency analysis → wave order waves sequential, tasks within wave parallel

gsd-executor × N (per wave)

Native Tool Execution

Each executor subagent implements its task using Claude Code native tools — no regex parsing, no text-to-file conversion. Direct filesystem operations.

Native tools available

Read — reads any file directly Write / Edit — writes files atomically Bash — runs commands with full shell Grep / Glob — codebase search

After each task

git commit (atomic per task) SUMMARY.md written on completion deviation handling built-in

Step 4d — Completion Detection

Result Collection

After GSD finishes, Pipeline OS checks the outcome and records results.

SUMMARY.md exists → success signal git diff --name-only HEAD → files_changed exit code 0 → fallback success check saves raw executor log + updates agent memory no SUMMARY + exit ≠ 0 → FAILED

Pipeline OS plans · GSD executes · atomic commits per task · SUMMARY.md signals done · if failed → FAILED · else → DONE

Output — status: DONE

Pipeline Complete ✓

All tasks executed successfully. Job visible in New Job history.

🎉 Telegram: Pipeline DONE elapsed_minutes cost_usd (cumulative all phases) tasks_done / tasks_total files_changed git_snapshot hash

Output — status: FAILED

Pipeline Failed ✗

Some tasks could not be completed after 3 retries each.

❌ Telegram: Pipeline FAILED error_message: failed task names partial files_changed git snapshot allows rollback

◈ Job Status State Machine (JobStatus enum)

Status	Set by	Meaning	Next possible
NEW	create_job()	Job created, not yet started	PM_RUNNING
PM_RUNNING	pm_agent.run()	PM Agent refining + auditing + researching	RESEARCH_DONE · BLOCKED
RESEARCH_DONE	pm_agent verify pass	PM complete, moving to council	COUNCIL_PLANNING
COUNCIL_PLANNING	pipeline.py phase 2	6 seats generating plans in parallel	SYNTHESIZING
SYNTHESIZING	plan_maker.run()	Opus synthesizing council plans into master_plan.md	COUNCIL_REVIEWING
COUNCIL_REVIEWING	council.review_mode()	6 seats voting on master plan	SYNTHESIZING (revise) · APPROVED · BLOCKED (deadlock)
APPROVED	all seats APPROVE	Master plan approved, ready for execution	EXECUTING
EXECUTING	executor.run() → GSD bridge → claude CLI	GSD execute-phase running waves via Claude Code CLI (native tools)	DONE · FAILED
DONE	GSD SUMMARY.md exists + exit 0	All waves complete, files committed atomically	—
FAILED	no SUMMARY.md + exit ≠ 0 or timeout	GSD execution failed or timed out after 30min	—
BLOCKED	pm verify fail · council deadlock · veto	Pipeline stopped, blocker_reason explains why	—

Sequential flow

Phase 1 — PM Agent

Phase 2 — Council Plan Mode

Phase 3 — Synthesis loop

Phase 4 — Executor & Done

Blocked / Failed

VETO Can block independently

◈ GSD (Get Shit Done) — Project & Phase Lifecycle

Entry · /gsd-new-project

Project Initialization

Starting point for any new project. Deep questioning extracts requirements and shapes the roadmap.

/gsd-new-project /gsd-new-project --auto @doc.md

Init Config + Deep Questioning

Step 1 — Config

Project Config

AskUserQuestion collects: YOLO vs Interactive mode, phase granularity, agent toggles (researcher, plan-checker), model routing (Balanced/Quality/Budget).

YOLO — auto-approve all Interactive — confirm each step → config.json

Step 2 — Questioning

Deep Questioning

Structured questions surface scope, constraints, tech stack, success criteria, timeline, and non-goals. In --auto mode: extracted from document instead of interactive.

interactive: AskUserQuestion auto: extract from @doc.md scope + constraints + stack success criteria + non-goals

Step 3 — Optional Research

Parallel Research

4× gsd-project-researcher agents run in parallel across domain areas. gsd-research-synthesizer merges findings into RESEARCH.md.

4× gsd-project-researcher gsd-research-synthesizer → RESEARCH.md optional (user choice)

Step 4 — gsd-roadmapper

Roadmap + Requirements Generation

Produces phased roadmap with success criteria per phase, maps requirements to phases, defines constraints and quality gates.

gsd-roadmapper agent → .planning/ROADMAP.md → .planning/REQUIREMENTS.md → .planning/PROJECT.md → .planning/STATE.md → .planning/config.json

⟳ Repeat for each phase (N = 1, 2, 3 …)

Optional /gsd-discuss-phase N — Context Gathering

Assumptions Mode

Assumption Analysis

gsd-assumptions-analyzer scans codebase for hidden constraints, implicit dependencies, and risky assumptions specific to this phase.

gsd-assumptions-analyzer codebase scan hidden constraints risky assumptions

Advisor Mode

Decision Advisor

gsd-advisor-researcher compares approaches with tradeoffs. Surfaces competing variants, unresolved blockers. Boss selects preferred path.

gsd-advisor-researcher competing variants tradeoff table → CONTEXT.md

Plan /gsd-plan-phase N — Phase Planning

Gate — Pre-flight

Precondition Check

REQUIREMENTS.md exists? ROADMAP.md exists? phase N exists in roadmap? if missing → block + message

⟐ Parallel — Research + Pattern Mapping

gsd-phase-researcher

Phase Research

Investigates domain, libraries, gotchas specific to this phase. Reads CONTEXT.md + ROADMAP.md. Produces RESEARCH.md with implementation guidance.

→ phases/NN-name/NN-RESEARCH.md

gsd-pattern-mapper

Codebase Pattern Analysis

Scans existing codebase for patterns, conventions, and closest analogs to new files. Maps new files to existing patterns. Prevents style drift.

→ phases/NN-name/NN-PATTERNS.md

gsd-planner

PLAN.md Generation

Reads ROADMAP.md, REQUIREMENTS.md, RESEARCH.md, PATTERNS.md, CONTEXT.md, prior phase SUMMARYs, and TDD config. Produces one or more PLAN.md files with task breakdown, dependencies, wave assignment, and success criteria per task.

gsd-planner agent tasks with: description, files, commands, success criteria wave: 1|2|3 (dependency grouping) type: tdd (if TDD mode enabled) → NN-01-PLAN.md, NN-02-PLAN.md …

Gate — Revision Loop · max 3 iterations

gsd-plan-checker Review

Reviews PLAN.md quality: goal-backward analysis, task completeness, dependency correctness, success criteria coverage. Counts issues per iteration for stall detection.

PASS → proceed to execute REVISE → specific feedback → loop to gsd-planner stall (issue count not decreasing) → early escalation max 3 iter → Escalation Gate → human decision

Execute /gsd-execute-phase N — Wave-Based Parallel Execution

Gate — Pre-flight

Plan Existence Check

PLAN.md exists for phase N? no matching SUMMARY.md? (incomplete plan) dependency analysis → wave grouping if no PLAN.md → block

⟐ Parallel within wave — gsd-executor × N plans (one per PLAN.md)

Waves are sequential. Plans within same wave run in parallel. Each executor is an independent subagent with full context.

gsd-executor per plan

Task Executor

Reads PLAN.md fully. Executes each task: writes files, runs commands, runs tests if TDD. Creates atomic git commits after each task. Skips already-done tasks (resume support).

reads full PLAN.md task-by-task implementation git commit per task skip done tasks (resume)

Commit protocol

Git Integration

Each task gets an atomic commit. Branch strategy from config (feature branch vs main). Commit message references plan + task. If worktrees enabled: isolated branch per plan.

git add -A → git commit branch: feature/phase-N-plan-M worktrees: isolated per plan (optional) commit: "phase-N task: {name}"

Completion

SUMMARY.md Creation

After all tasks done: executor writes SUMMARY.md with decisions made, files changed, deviations from plan, concerns for next phase. This signals completion to orchestrator.

→ NN-01-SUMMARY.md decisions + files changed deviations from plan concerns for next phase

Orchestrator spot-checks: commits visible + SUMMARY.md exists → wave complete → next wave starts

Verify /gsd-verify-work N — Phase Verification (4 Gate Types)

Gate 1 — Pre-flight

Precondition Check

SUMMARY.md must exist. STATE.md must not be in error state. Context window must not be critically low.

missing SUMMARY.md → block STATE error → abort

Gate 2 — Revision

gsd-verifier Review

Checks deliverables against phase success criteria and requirements. Identifies gaps. If gaps found → patch plans via gsd-planner → re-execute gaps.

all criteria met → VERIFICATION.md gaps → patch PLAN.md → re-execute

Gate 3 — Escalation

Human Decision

Revision loop exhausted (max 3 iter) or issue is ambiguous / requires product decision. Pauses. Presents options. Waits for Boss input.

AskUserQuestion → Boss picks path resumes on selected option

Gate 4 — Abort

Emergency Stop

Continuing would cause damage or produce meaningless output. Preserves STATE.md for safe resume after root cause is fixed.

context window critically low STATE.md in error state state preserved → safe to restart

Output: VERIFICATION.md — deliverables checked · gaps addressed · phase marked COMPLETE in STATE.md

/gsd-next — Advance

Phase Complete ✓ — Advance to Next

STATE.md updated. Phase marked complete. Progress bar advanced. Routes to next appropriate action based on project state.

STATE.md: phase N → COMPLETE progress: X/Y phases if next phase ready → /gsd-plan-phase N+1 if milestone done → /gsd-complete-milestone loop back for next phase

◈ GSD Artifact Map (.planning/ directory)

Artifact	Created by	Location	Purpose
`PROJECT.md`	/gsd-new-project	.planning/PROJECT.md	Core description, requirements, constraints, key decisions log
`REQUIREMENTS.md`	/gsd-new-project	.planning/REQUIREMENTS.md	Full requirements list with IDs, mapped to phases
`ROADMAP.md`	gsd-roadmapper	.planning/ROADMAP.md	Phase breakdown with success criteria, dependencies, risk levels
`STATE.md`	/gsd-new-project	.planning/STATE.md	Live project state: current phase, progress %, recent decisions, session continuity
`config.json`	/gsd-new-project	.planning/config.json	YOLO/Interactive mode, model routing, agent toggles, branching strategy
`CONTEXT.md`	/gsd-discuss-phase	.planning/phases/NN-name/	Phase context: assumptions, advisor decisions, chosen approach
`RESEARCH.md`	gsd-phase-researcher	.planning/phases/NN-name/	Technical research: libraries, patterns, pitfalls, implementation guidance
`PATTERNS.md`	gsd-pattern-mapper	.planning/phases/NN-name/	Codebase pattern map: new files → closest existing analogs
`NN-MM-PLAN.md`	gsd-planner	.planning/phases/NN-name/	Executable plan: tasks with files, commands, success criteria, wave assignment
`NN-MM-SUMMARY.md`	gsd-executor	.planning/phases/NN-name/	Completion record: decisions made, files changed, deviations, concerns
`VERIFICATION.md`	gsd-verifier	.planning/phases/NN-name/	Verification report: criteria met/failed, gaps addressed, phase sign-off

◈ GSD Subagents

Agent	Triggered by	Role	Key output
`gsd-planner`	/gsd-plan-phase	Creates detailed PLAN.md with task breakdown, waves, dependencies	NN-MM-PLAN.md
`gsd-plan-checker`	/gsd-plan-phase revision gate	Reviews plan quality, goal-backward analysis, stall detection (max 3 iter)	pass/feedback
`gsd-phase-researcher`	/gsd-plan-phase	Researches domain, libraries, patterns for specific phase	RESEARCH.md
`gsd-pattern-mapper`	/gsd-plan-phase	Maps new files to existing codebase patterns and conventions	PATTERNS.md
`gsd-executor`	/gsd-execute-phase (per plan, per wave)	Implements tasks, writes files, runs commands, commits, writes SUMMARY.md	SUMMARY.md + code
`gsd-verifier`	/gsd-verify-work	Checks deliverables vs success criteria, triggers patch plans if gaps found	VERIFICATION.md
`gsd-project-researcher`	/gsd-new-project (×4 parallel)	Researches project-level tech decisions, domain patterns, tradeoffs	RESEARCH.md (project)
`gsd-roadmapper`	/gsd-new-project	Creates phased roadmap from requirements, maps success criteria per phase	ROADMAP.md
`gsd-assumptions-analyzer`	/gsd-discuss-phase	Scans codebase for hidden constraints and risky assumptions	CONTEXT.md (assumptions)
`gsd-advisor-researcher`	/gsd-discuss-phase	Researches competing approaches, produces scored comparison table	CONTEXT.md (decision)
`gsd-debugger`	/gsd-debug	Scientific debugging: hypothesis → test → fix. Manages checkpoint sessions.	fix + debug log