--- name: pidex description: Start a pidex pipeline run. Primary invocation is /pidex; /pd is a shortcut alias. Runs a structured pre-flight interview to define the task precisely, then starts the pidex-* pipeline in Pi direct mode using the pidex_agent tool. --- # PIDEX Orchestrator (`/pidex`) This skill is the entry point for every pidex pipeline run. The primary user-facing invocation is `/pidex`; `/pd` remains supported as a short alias. It ensures the task is precisely defined before any code is written. A vague epic is the single biggest source of wasted pipeline runs. ## Supplemental questioning skills If the fixed pre-flight interview below is not enough to remove ambiguity, use the correct grilling skill for the project state: - **New/non-existing/fresh projects:** load and apply `grill-me` (`~/.pi/agent/skills/grill-me/SKILL.md`). - **Existing projects with inspectable code/docs/context:** load and apply PIDEX `grill-with-docs` (`/skills/grill-with-docs/SKILL.md`). Use these skills to interview the user relentlessly about the plan or design until all decision branches needed for the pipeline are resolved. Rules for grilling inside pidex: - Ask questions one at a time. - For every question, provide the recommended answer. - If a question can be answered by inspecting the codebase, docs, or `/pidex/context/**`, inspect instead of asking. - For existing projects, challenge terms against `/pidex/context/CONTEXT.md` or `CONTEXT-MAP.md` when present. - If an existing project has no `/pidex/context/CONTEXT.md` or `CONTEXT-MAP.md`, initialize the single-context template first with `node /scripts/modules/run-check.mjs --capability project-context.init --agent orchestrator --phase preflight --project `. - `CONTEXT.md` follows Matt Pocock's context format exactly. Use `/skills/grill-with-docs/CONTEXT-FORMAT.md` as the single source of truth for context handling. - Put confirmed user statements and clear code/docs-evidenced project/domain terms directly into `## Language` only when they can be defined in one sentence. Do not put task specs, acceptance criteria, implementation plans, roadmap items, workflows, architecture notes, operational constraints, or release decisions in `CONTEXT.md`. - For fresh/new projects, create `pidex/context/CONTEXT.md` during the orchestrator preparation step before spawning agents so the first plan has a context home. - Agents may update context from confirmed user statements or clear code evidence; the user/domain expert owns truth. - Stop grilling once you can write a crisp 3-5 sentence epic statement with explicit acceptance criteria, constraints, and out-of-scope items. - Do not invoke `pidex-planner` before this clarity threshold is met. ## When to invoke - User types `/pidex` - User types `/pd` as a shortcut alias Do not auto-trigger pidex from natural-language phrases such as "pipeline starten", "build this", or "implement this"; those may belong to Running Pi or normal chat. ## Direct-mode operation (current supported mode) pidex currently supports direct mode as the working MVP: - The host Pi session is the orchestrator. - Specialist handoffs use the `pidex_agent` tool registered by the package extension. - `pidex_agent` honors `/config/agents.json`: default/tool-heavy agents use lean isolated Pi subprocesses; configured review/synthesis agents may route to Claude, Codex, or Gemini CLI delegates. - `pidex_agent` stores raw child JSON streams under `/state/runs/` and returns only compact tool details to avoid parent-session bloat. - `pidex_agent` records per-agent metrics under `/state/metrics/`. - For plan-id allocation, use the next available numeric plan id from `/agents.output/**` and document the selected id in the plan/brief. Do not increment `.next-id` ad hoc unless a future helper is present in the installed package. - Specialist final responses must stay short: write full artifacts to files, then return only status, output paths, next route, concise evidence, and the ROUTING block. - Generated `agents.output/**` artifacts are runtime/operator outputs and must never be committed. Do not stage them, do not use `git add -f` for them, and do not suggest them as commit candidates. Commit durable wiki/project metadata instead (for example `wiki/**` or `pidex/state/wiki-hygiene.json` when appropriate). - Gates are asked in the Pi session. Do not use Telegram reply handling unless the user explicitly asks for the scaffolded background mode. - Optional notify-only Telegram is allowed in direct mode: use `/scripts/telegram/notify.sh --optional` to alert the user that Pi needs attention and when the pipeline reaches terminal completion/failure/abort. This sends information only, no buttons, no replies, no `pending-gate.json`. Before invoking the first delegated non-Pi agent, ensure delegate auth preflight is green. `/pidex` and `/pd` run this automatically, but if continuing manually use: ```bash bash /scripts/delegate/check-auth.sh --config /config/agents.json ``` If auth/setup fails, stop and ask the user to fix auth or explicitly override affected agents to `provider=pi`. Do not silently fall back on auth/setup failure. When an `pidex-*` subprocess emits a `gate:` in its final `` block, stop and ask the user for the gate decision in the current Pi session. Then continue routing based on the answer. --- ## Pre-flight sequence The pre-flight runs in this fixed order. Every step must be resolved before proceeding. ### Low-context project reconnaissance (mandatory) Keep orchestrator context lean by default: 1. Prefer `rg`, `find`, `head`, `tail`, and narrow `read offset/limit` over full-file reads. 2. Do **not** read long artifacts (`open-items.md`, large plan docs, retros) end-to-end unless a specific gate/decision requires it. 3. When a project is mentioned by name/path, do a **roadmap-first quick look** before broader scanning: - Check `/agents.output/roadmap/product-roadmap.md` first (if present). - Reconcile it with newer roadmap/planning artifacts before answering next-work/status questions: targeted-check latest `/agents.output/roadmap/*roadmap-update*.md`, `/agents.output/planning/*brief*.md`, `/agents.output/planning/*draft*.md`, and `/agents.output/planning/*summary*.md` whose mtimes or plan IDs are newer than the canonical roadmap. - If a newer artifact proposes planned epics or next work that is not present in the canonical roadmap, say so explicitly and treat it as a pending/unpromoted roadmap update; do not answer from the older canonical roadmap alone. - Extract only current/open signals (e.g., ACTIVE/OPEN/IN PROGRESS/recent epics) with targeted grep/snippets. - Expand to other files only if roadmap data is missing, newer artifacts conflict with canonical roadmap, or the user asks for deeper detail. 4. After a project is selected, if roadmap/open-work signals exist, present a compact lettered shortlist immediately instead of asking a blank "what deliverable?" question. Include up to 5 items from canonical roadmap plus reconciled newer roadmap/planning artifacts, clearly labelling status/source such as `Interview`, `Planned (canonical)`, `Pending roadmap update`, or `Backlog candidate`. Always include options for `Other/manual task` and `Show more/open work`. If an item is `Interview`, or if the orchestrator can see unresolved user story/acceptance/scope/dependency/UI-intent ambiguity, label it interview-first and start the interview/grill phase when selected; do not route directly to planner. 5. Default summary depth: top 3-5 actionable items, then ask whether to drill deeper. ### Orchestrator write guards (mandatory) Before any direct-mode pipeline mutation or `pidex-*` spawn, load and apply: - `/rules/orchestrator/project-boundary-write-guard.md` - `/rules/orchestrator/no-direct-implementation.md` A pipeline may only mutate its declared `` / allowed write root. Other repositories, including `` when the active project is not PIDEX itself, are read-only references unless the user explicitly switches project and starts a new pipeline for that root. The orchestrator must not directly implement product/project changes. It may create coordination artifacts such as context packs and required PIDEX bootstrap context, but source/docs/config/test implementation changes must go through `pidex_agent` specialist handoffs, except for the documented repeated-stall fallback. Every specialist handoff must include a `PROJECT BOUNDARY` block naming current project root, allowed write root, read-only external reference roots, and the rule: do not edit/commit/tag/push outside allowed write root. ### Pre-spawn context pack Before every `pidex-*` spawn, use a compact context pack instead of pasting broad/full artifacts. Create a manual context pack/brief with only targeted artifact paths/snippets, and mention `CONTEXT-PACK-MANUAL` in the handoff. Budget check is soft by default: keep context lean, but do not block the pipeline on the absence of an optional helper. ### Step 0 — Recent projects shortlist Before asking "which project?", check the pidex history log and offer a shortlist of recently-touched **unique project directories**. This saves the user from typing paths they already used. ```bash node /scripts/modules/run-check.mjs --capability analysis-metrics-history.history-list --agent orchestrator --phase planning --project -- --limit 5 ``` If the script prints nothing (empty or missing `/state/history.jsonl`), skip straight to Step 1. Otherwise present its output to the user with an explicit "new" option appended: ``` Recent projects: A) last touched: 2026-05-06T09:59:46Z (direct, direct-complete) B) last touched: 2026-04-10T09:14:00Z (direct, stop) ... N) New project / different path ``` Do **not** list multiple entries for the same project just because it had multiple epics. Epics are intentionally not shown in this shortlist. Accept a letter (A-E) to select that cwd, then ask what the user wants to do next for that project. Accept "N" / "new" / any name or path to fall through to Step 1. ### Step 1 — Project directory This is always the first question when Step 0 did not resolve the project. The user does NOT need to give an exact path. Accept sloppy input and resolve it. > **Which project?** Name, path, or "new". **Resolving the project:** The user might say any of these: - An exact path: `~/projects/my-app` → use directly - A project name: "my-app", "sofafahrten", "homelab" → search for it - A vague reference: "the todo project", "that thing I started yesterday" → search and ask - "new" or "new project" → new project flow **If the user gives a name (not a full path):** 1. Search the entire home directory for a match (exclude hidden dirs and node_modules): ```bash find ~ -maxdepth 4 -type d -name "**" \ -not -path '*/\.*' -not -path '*/node_modules/*' 2>/dev/null ``` 2. If exactly one match: propose it. "Found `~/dev/my-app`. Is that the one?" 3. If multiple matches: present a lettered list and let the user pick: ``` Found multiple matches: A) ~/projects/local/my-app B) ~/projects/www/my-app-frontend C) ~/old/my-app-archive Which one? (A/B/C) ``` 4. If no matches: "I couldn't find a project matching ''. Give me the full path, or say 'new' to create it." **After resolving to a path:** 1. Verify the directory exists. If not: "This directory does not exist. Should I create it as a new project, or did you mean something else?" 2. Use bundled agents from `/agents/` through the `pidex_agent` tool. Project-local `.pi/agents/` copies are optional and not required for the MVP. 3. Check if `/agents.output/` exists. If not, create it with `.next-id` set to 0. 4. Check roadmap/open-work signals using the low-context roadmap-first reconciliation rule above even if the user only selected a project. If actionable planned/open/backlog items exist, present a compact lettered shortlist, for example: ```text Selected project: Roadmap options: A) — Interview (interview first) B) — Planned (ready for planner after quick confirmation) C) — Pending roadmap update from D) Other/manual task E) Show more/open work Which deliverable should this run take? ``` Do not force the user to ask "what is open?" when obvious roadmap options are available. Treat `Interview` as a start-interview choice, not a start-implementation choice. 5. Determine project type: does the directory have source code? A package.json / pyproject.toml / go.mod? Tests? This informs which interview flow to use. 6. Store the resolved absolute path. **If the user says "new":** 1. Ask: "What should the project be called, and where should it live? Give me a name (I'll ask where to put it) or a full path." 2. If the user gives just a name (e.g., "invoice-parser"): ask where to create it. Do NOT assume a default location — different users organize their projects differently. 3. If the user gives a full path: use that. 4. Store the path. The directory will be created during pipeline execution. 5. The interview will use the Onboarding flow. ### Step 2 — Execution mode Use **Direct mode** by default. It is the only parity-supported mode in the MVP. If the user asks for background mode, explain that background/Telegram scripts are scaffolded but not parity-complete yet, and ask whether to continue in direct mode instead. Store the choice as `direct` unless the user explicitly accepts experimental background work. ### Step 3 — Interview Walk through the appropriate interview flow to produce a crisp epic statement. The project state from Step 1 determines the scenario. **UI design interview branch (mandatory when triggered):** When the request touches UI placement, hierarchy, layout, mobile, forms, tables, navigation, modals/sheets, cards, status strips, or pattern parity ("match", "like X", "same as", "move to where X is"), ask targeted missing questions only and inspect source when possible instead of asking. Classify the UI intent as preserve / preserve-mostly / redesign / new / incidental. For UI-heavy or visually sensitive work, ask whether the user wants a designer meeting with a temporary preview before implementation (`yes`, `no`, or `only if designer finds ambiguity`). Persist the result as `agents.output/design/-ui-intent-interview.md` or as `## UI Intent Contract` plus `## UI Preservation Classification` in the first plan/design artifact. If UI intent remains ambiguous, route to `user`; do not spawn implementer. If the user requests a temporary preview, route to pidex-designer with `rules/pidex-designer/design-snippet-preview.md`; the designer should provide a disposable HTML/CSS/JS artifact and instructions to preview it with project-local tooling. If G9/user feedback rejects positioning twice, repeat this UI interview branch before any further implementer fix. **Fresh project (Step 1 = "new" or empty directory):** → Onboarding flow, and use `grill-me` for extra ambiguity resolution. **Existing project with code/docs/context:** → Ask what the user wants to do, inspect code/docs/context when useful, and use PIDEX `grill-with-docs` for extra ambiguity resolution. `grill-with-docs` uses `/pidex/context/**` for glossary/ADR context and must not default to root `CONTEXT.md` or root `docs/adr/`. Then route: 1. **Is this a fresh project or an existing codebase?** - Fresh → Onboarding flow - Existing → one of the flows below 2. **What is the scope?** - Single function or small fix → Small scope - New module or multi-file feature → Medium scope - New system, major refactor, or multi-epic initiative → Large scope Then run the matching interview below. --- ### Onboarding flow (fresh project) For projects where no code exists yet or the project is being set up for the first time. **Letter shortcuts:** Throughout the interview, when options are listed with letters (A, B, C...), the user can reply with just the letter instead of typing the full answer. Accept both uppercase and lowercase. If the user replies with a number, match it to the option at that position. **Step 1 — Language and runtime** > What language and runtime will this project use? ``` A) TypeScript + Node.js (recommended — best TDD support) B) TypeScript + Deno C) TypeScript + Bun D) Python E) Go F) Rust G) Java / Kotlin (JVM) H) C# / .NET I) Ruby J) PHP K) Elixir L) Other (specify) ``` **Step 2 — Project type** > What kind of project is this? ``` A) CLI tool B) Library / package (npm, PyPI, crate, gem...) C) REST API / backend service D) GraphQL API E) Full-stack web app (frontend + backend) F) Frontend SPA (single-page app) G) Static site / landing page H) Mobile app (React Native / Flutter / native) I) Desktop app (Electron / Tauri) J) Browser extension K) Discord / Slack / Telegram bot L) Microservice / worker / queue consumer M) Infrastructure / DevOps scripts N) Data pipeline / ETL O) Machine learning / AI project P) Game Q) Monorepo (multiple packages) R) Other (specify) ``` **Step 3 — Framework (if applicable)** Based on Step 2, ask about framework. Present only the relevant category. For REST API / backend (TypeScript/JavaScript): ``` A) Express B) Fastify C) Hono D) Koa E) NestJS F) AdonisJS G) tRPC (standalone) H) None (plain Node HTTP) ``` For REST API / backend (Python): ``` A) FastAPI B) Django + DRF C) Flask D) Litestar E) None (plain WSGI/ASGI) ``` For REST API / backend (Go): ``` A) Gin B) Echo C) Chi D) Fiber E) net/http (stdlib) ``` For REST API / backend (Rust): ``` A) Actix Web B) Axum C) Rocket D) Warp ``` For REST API / backend (Ruby): ``` A) Rails B) Sinatra C) Hanami ``` For REST API / backend (PHP): ``` A) Laravel B) Symfony C) Slim ``` For REST API / backend (Elixir): ``` A) Phoenix ``` For REST API / backend (Java/Kotlin): ``` A) Spring Boot B) Quarkus C) Ktor D) Micronaut ``` For REST API / backend (C#/.NET): ``` A) ASP.NET Core (minimal API) B) ASP.NET Core (MVC) ``` For full-stack web app: ``` A) Next.js — App Router B) Next.js — Pages Router C) Remix D) SvelteKit E) Nuxt F) Astro (with islands) G) SolidStart H) RedwoodJS I) T3 Stack (Next.js + tRPC + Prisma + Tailwind) J) Django (templates + htmx) K) Rails (Hotwire/Turbo) L) Laravel (Livewire / Inertia) M) Phoenix LiveView N) None (separate frontend + backend) ``` For frontend SPA: ``` A) React (Vite) B) Vue (Vite) C) Svelte (Vite) D) Solid (Vite) E) Angular F) Preact G) Qwik H) Vanilla (no framework) ``` For static site: ``` A) Astro B) 11ty (Eleventy) C) Hugo D) Jekyll E) Plain HTML/CSS/JS ``` For CLI: ``` A) No framework (just the language stdlib) B) Commander.js / yargs (Node) C) Click / Typer (Python) D) Cobra (Go) E) Clap (Rust) F) Thor (Ruby) ``` For mobile: ``` A) React Native (Expo) B) React Native (bare) C) Flutter D) Native iOS (Swift) E) Native Android (Kotlin) F) Capacitor (web → native) ``` For desktop: ``` A) Electron B) Tauri C) Qt (Python/C++) ``` For bot: ``` A) discord.js B) Slack Bolt C) Telegraf / grammY (Telegram) D) Custom (specify) ``` If the project type doesn't have a framework list above (e.g., data pipeline, ML project), skip this step or ask: "Any specific framework or tool? (e.g., Airflow, dbt, PyTorch, LangChain) — or 'none'." **Step 3b — Styling (only for web projects with a UI)** Skip this step for APIs, CLIs, libraries, workers, bots, and anything without a visual frontend. > How should the UI be styled? ``` A) Tailwind CSS B) Tailwind CSS + shadcn/ui (recommended for React) C) Tailwind CSS + DaisyUI D) CSS Modules E) Vanilla CSS / plain stylesheets F) styled-components / Emotion (CSS-in-JS) G) Material UI (MUI) H) Chakra UI I) Ant Design J) Mantine K) Radix UI + custom styles L) Bootstrap M) Bulma N) UnoCSS O) PandaCSS P) None / will decide later ``` **Step 3c — Design template (only for web projects with a UI)** Skip this step for APIs, CLIs, libraries, workers, bots, and anything without a visual frontend. > Want to start from a design template? These are curated design systems inspired by real products — they set colors, typography, spacing, and visual tone. The pidex-designer agent will use the template as a starting point for DESIGN.md. ``` A) Vercel — Black and white precision, Geist font, gallery-like minimalism B) Stripe — Signature purple gradients, weight-300 elegance, payment infrastructure aesthetic C) Linear — Dark-mode-first, near-black canvas, extreme precision engineering D) Supabase — Dark developer aesthetic, emerald green accents, terminal-born sophistication E) Figma — Typographic sophistication, custom variable font weights, micro-hierarchy F) None / custom — Start from scratch or bring your own DESIGN.md ``` If the user picks A-E, include in the epic: "Design template: (from /design-templates/.md — copy to agents.output/design/DESIGN.md at project init)." If the user picks F, the pidex-designer will bootstrap DESIGN.md from the existing codebase or from scratch during its first run. **Step 4 — Data layer** > Does this project need a database or persistent storage? ``` A) No (stateless / pure functions) B) SQLite (local, simple) C) PostgreSQL D) MySQL / MariaDB E) MongoDB F) Supabase (Postgres + auth + realtime) G) Firebase / Firestore H) Redis (caching / sessions / pub-sub) I) DynamoDB J) Turso (libSQL, edge SQLite) K) PlanetScale (MySQL, serverless) L) Dragonfly / Valkey (Redis-compatible) M) File-based (JSON, YAML, Markdown) N) S3 / R2 / object storage O) Vector DB (Pinecone, Qdrant, Chroma, pgvector) P) Multiple (specify) Q) Other (specify) ``` If the user picks a relational DB (C, D, F, J, K), follow up with ORM: ``` A) Prisma B) Drizzle C) Kysely D) TypeORM E) Sequelize F) SQLAlchemy (Python) G) Django ORM (Python) H) GORM (Go) I) Diesel (Rust) J) ActiveRecord (Ruby) K) Eloquent (Laravel/PHP) L) Ecto (Elixir) M) Raw SQL / query builder N) Other ``` **Step 5 — Testing** > Which test framework? ``` A) vitest (recommended for TypeScript) B) jest C) Node test runner (built-in) D) Playwright (E2E) E) Cypress (E2E) F) pytest (Python) G) unittest (Python) H) go test (Go) I) cargo test (Rust) J) RSpec (Ruby) K) PHPUnit (PHP) L) JUnit (Java/Kotlin) M) xUnit / NUnit (.NET) N) ExUnit (Elixir) O) Other (specify) ``` **Step 6 — Initial deliverable** > What is the FIRST thing the pipeline should build? Not the whole app — the first shippable increment. Help the user narrow down: "What's the smallest useful thing that proves the architecture works?" Examples: - "A single endpoint that returns health status" - "A CLI that reads one file and prints a summary" - "A function that validates one input type" **Step 7 — Synthesize, scaffold, and confirm** Compose the epic from all interview steps (1-6, including 3b and 3c if applicable) plus the project path from Pre-flight Step 1, filling in ALL values from the interview — nothing should be left as a placeholder. The epic MUST include the project setup as the first paragraph if this is a fresh project. Every choice the user made (language, framework, styling, design template, test runner, data layer, ORM, project path) must appear verbatim. Example of a completed epic (every value came from the interview, none are generic): > Create a new Python project at /invoice-parser. Initialize with: git init, pyproject.toml (name: invoice-parser, version 0.0.0, pytest as test framework), src/invoice_parser/ package directory, tests/ directory, .gitignore (venv, __pycache__, .pytest_cache). Create and activate venv, install pytest. Initial commit. > > Then build the first feature: a function parse_total(pdf_path: str) -> Decimal in src/invoice_parser/parser.py that extracts the total amount from a single-page PDF invoice. Uses pdfplumber for text extraction. Returns the first number that follows the word "Total" (case-insensitive). Edge cases: file not found raises FileNotFoundError, no "Total" found raises ValueError("no total line found"), multiple "Total" lines uses the last one. 100% coverage on src/invoice_parser/parser.py. The project scaffold is part of the epic, not a separate step. The lead's pidex-planner will incorporate it into its plan, and pidex-implementer will execute the setup before writing the feature code. Read back to the user: "Here is the epic I would send to the pipeline. Does this match your intent, or should I adjust anything?" **What the orchestrator does BEFORE starting the lead (for fresh projects only):** After the user confirms the epic, create the project directory, project context template, and minimal agents.output structure so the lead has somewhere to write, and ensure generated/runtime PIDEX folders are ignored before any agent creates files: ```bash mkdir -p /agents.output /pidex/state /pidex/rules /pidex/config /pidex/prompts node /scripts/modules/run-check.mjs --capability project-context.init --agent orchestrator --phase preflight --project printf '\n# PIDEX / agent runtime artifacts\nagents.output/\n.wiki-migration/\n' >> /.gitignore echo 0 > /agents.output/.next-id ``` If `.gitignore` already exists, append only missing entries. `agents.output/**` must remain ignored/uncommitted; `pidex/state/wiki-hygiene.json` and other durable `pidex/` metadata may be committed when explicitly appropriate. Do NOT scaffold the project code (package.json, tsconfig, etc.) — that is the lead's job as part of the epic. The orchestrator only creates the directory, initializes `pidex/context/CONTEXT.md`, initializes agents.output, and ensures `.gitignore` protects generated PIDEX artifacts. Do not copy agent files; bundled agents are invoked through `pidex_agent`. Only proceed after explicit confirmation. --- ### Feature flow (existing project) For adding new functionality to an existing codebase. **Step 1 — What and where** > What should the new feature do? Which file(s) should it live in? If the user is vague ("add user management"), dig deeper: - What specific operations? (create, read, update, delete?) - What entity? (User type with which fields?) - Where in the codebase? (new file? extend existing module?) **Step 2 — Interface definition** > What is the function signature or API contract? Push for specifics: - Function name, parameters, return type - For APIs: HTTP method, path, request body, response shape - For UI: which component, what props, what user interaction **Step 3 — Behavior and edge cases** > What are the edge cases? Prompt with examples: - What happens with empty input? - What happens with invalid input? - What happens when the dependency (DB, API, file) is unavailable? - Are there size limits? - Concurrent access considerations? The user should name at least 2-3 edge cases explicitly. **Step 4 — Constraints** > Are there constraints I should know about? - Must it be backward-compatible with an existing API? - Performance requirements? - Security considerations? (auth, input sanitization, secrets) - Existing patterns in the codebase to follow? **Step 5 — Acceptance criteria** > What does "done" look like? Propose concrete criteria: - "Function X exists in file Y and handles cases A, B, C" - "All tests pass, coverage >= N% on the new code" - "Existing tests still pass (no regressions)" **Step 6 — Synthesize and confirm** Same as onboarding Step 7. Read the epic back, get confirmation. --- ### Bugfix flow (existing project) **Step 1 — Reproduce** > Can you describe the bug? What is the expected behavior vs actual behavior? If the user can't describe it precisely: "Can you show me the error message, the failing test, or the steps to reproduce?" **Step 2 — Locate** > Do you know which file or function is involved? If unknown: "I'll include investigation in the epic so the planner can scope it." **Step 3 — Scope the fix** > Should the fix ONLY address this bug, or are there related issues to clean up? - Bug only (tight scope, preferred for pipeline) - Bug + related cleanup (wider scope, note explicitly) **Step 4 — Synthesize and confirm** Example epic: > Fix: addTodo returns a mutated input array instead of a new copy. Expected: addTodo(list, text) returns a new array; original list is unchanged. Actual: the original list has the new todo appended in-place. Root cause suspected in src/todos.ts addTodo function (uses push instead of spread). Acceptance: existing mutation test (tests/todos.test.ts "does not mutate input") passes. No other behavioral changes. --- ### Refactor flow (existing project) **Step 1 — What and why** > What do you want to refactor, and what motivates it? - Code quality (too complex, hard to test, duplicated logic) - Architecture (wrong abstraction, coupling issue) - Performance (measured bottleneck, not speculative) - Preparation for a future feature **Step 2 — Boundaries** > What should NOT change? - External API contracts? - Test behavior? - Database schema? - File structure? **Step 3 — Acceptance criteria** > How do we know the refactor succeeded without changing behavior? - "All existing tests pass unchanged" - "Coverage does not drop below N%" - "Function X is now in file Y instead of Z" - "Cyclomatic complexity of function X drops from N to M" **Step 4 — Synthesize and confirm** --- ### Migration flow (existing project, moving from one thing to another) For replacing a framework, library, language version, API, database, or any infrastructure component with a different one while preserving existing behavior. **Step 1 — Source and target** > What are you migrating FROM and TO? Push for specifics: - Framework migration: Express → Fastify? React class components → hooks? Vue 2 → Vue 3? - Language migration: JavaScript → TypeScript? Python 2 → 3? CJS → ESM? - Database migration: MySQL → PostgreSQL? REST → GraphQL? Monolith → microservice? - Infrastructure migration: Heroku → self-hosted? Docker Compose → Kubernetes? **Step 2 — Source inventory** > Where is the code that needs to migrate? How much of it? The orchestrator MUST understand the blast radius before planning: - How many files are affected? (Rough count is fine: "5 files" vs "the entire src/ tree") - Are there tests for the current implementation? - Is there configuration (env vars, config files, CI pipelines) that also needs changing? - Are there external consumers (other services, users, APIs) that depend on the current interface? If the user cannot answer these: "I'll add a reconnaissance step to the epic so pidex-analyst can inventory the migration surface before pidex-planner starts." **Step 3 — Migration strategy** > How should the migration proceed? - Big bang (replace everything in one pass, test, ship) — only viable for small surfaces - Incremental (migrate one module/endpoint/component at a time, keep both working) — recommended for medium+ scope - Strangler fig (new code uses new approach, old code stays until deprecated) — for large systems with external consumers **Step 4 — Compatibility requirements** > What must remain backward-compatible during and after migration? - Public API contracts (REST endpoints, function signatures, CLI flags) - Database schema (can you do a schema migration, or must old and new coexist?) - Configuration format (do existing env vars / config files still work?) - Test suite (must all existing tests pass with zero changes, or can tests be rewritten?) **Step 5 — Rollback plan** > If the migration breaks something, how do we undo it? - Git revert (if single commit) - Feature flag (if gradual rollout) - Database rollback script (if schema changed) - "No rollback needed, this is a dev-only tool" (acceptable for small-scope) **Step 6 — Synthesize and confirm** Example epic: > Migrate the Express REST API in src/server/ to Fastify. 12 route handlers in 4 files. All existing integration tests in tests/api/ must pass unchanged (they hit the HTTP interface, not Express internals). Middleware for auth (src/middleware/auth.ts) and validation (src/middleware/validate.ts) must be ported to Fastify equivalents. No database changes. Env vars unchanged. Incremental strategy: migrate one route file at a time, keep Express running for unmigrated routes via a compatibility adapter until all routes are ported. Rollback: git revert the migration commit(s). Coverage must not drop below 85%. --- ### Security audit flow For investigating potential vulnerabilities, hardening an existing system, or preparing for a compliance review. **Step 1 — Scope and motivation** > What triggered this security concern? - Dependency vulnerability alert (Dependabot, npm audit, Snyk) - Upcoming compliance review (SOC2, GDPR, PCI-DSS) - Incident or near-miss - Proactive hardening (no specific trigger) - New feature touching auth, payments, or PII **Step 2 — Attack surface** > What parts of the system handle sensitive data or face external input? Walk through systematically: - Authentication: how do users log in? (JWT, sessions, OAuth, API keys?) - Authorization: who can do what? (RBAC, per-resource checks, admin panel?) - User input: which endpoints accept untrusted data? (forms, file uploads, API bodies?) - Secrets management: where are credentials stored? (env vars, vault, config files, hardcoded?) - Dependencies: when was the last `npm audit` / `pip audit` / equivalent? - Network: is the service behind a firewall? TLS everywhere? CORS configured? If the user doesn't know some answers: "I'll include an inventory step so pidex-security can map the attack surface before recommending fixes." **Step 3 — Depth of audit** > How deep should the audit go? Match to the pidex-security modes: - **Full audit** — comprehensive review of all code, deps, infra config (days of pipeline time, thorough) - **Targeted** — focus on a specific area (e.g., "only auth middleware" or "only the file upload endpoint") - **Dependency-only** — just check third-party packages for known CVEs - **Pre-production gate** — quick pass on new code before a release (runs after pidex-qa, before pidex-devops) **Step 4 — Remediation expectations** > Should the pipeline FIX issues it finds, or just REPORT them? - Report only (pidex-security writes findings, user decides what to fix later) - Report + fix critical/high (pipeline fixes OWASP Top 10 level issues, defers low-risk) - Fix everything (pipeline attempts to remediate all findings — higher risk of breaking changes) **Step 5 — Synthesize and confirm** Example epic: > Security audit (targeted) on the authentication flow in src/auth/. Motivation: adding OAuth support next sprint, want to verify the existing JWT implementation is solid first. Scope: src/auth/*.ts, src/middleware/auth.ts, related tests. Check for: token expiry validation, secret rotation readiness, CSRF on state-changing endpoints, SQL injection in user lookup queries. Mode: report + fix critical/high. Acceptance: all high/critical findings have PRs or documented justification for deferral. Existing auth tests still pass. --- ### Redesign flow (UI/UX overhaul, visual refresh, or design system migration) For changing how something looks or works from a user-experience perspective, potentially with design files (Figma, screenshots, templates) as input. **Step 1 — Design inputs** > Do you have design files, mockups, or a reference to work from? ``` A) Figma / Sketch file (URL or exported images) B) Screenshots of the current UI to annotate C) A reference site or app ("make it look like X") D) Written description only (no visual reference) ``` If A or B: "Please place exported images (PNG/SVG) or the Figma export in a `design/` directory in the project root, or give me a URL. I'll include the path in the epic so pidex-designer and pidex-implementer can reference them." **Step 1b — Design template** > Want to base the redesign on a design template? These set the visual tone — colors, typography, spacing, motion. The pidex-designer agent uses the template as starting point for DESIGN.md. ``` A) Vercel — Black and white precision, Geist font, gallery-like minimalism B) Stripe — Signature purple gradients, weight-300 elegance, payment infrastructure aesthetic C) Linear — Dark-mode-first, near-black canvas, extreme precision engineering D) Supabase — Dark developer aesthetic, emerald green accents, terminal-born sophistication E) Figma — Typographic sophistication, custom variable font weights, micro-hierarchy F) Custom file — I have my own DESIGN.md or design token file (provide path) G) Generic — Start with a neutral, clean baseline (pidex-designer will create one) H) None — Keep the existing design system, only redesign within current tokens ``` If A-E: include in the epic "Design template: (from /design-templates/.md — copy to agents.output/design/DESIGN.md at project init)." If F: ask for the path. Include in the epic "Custom design template: — copy to agents.output/design/DESIGN.md at project init." If G: the pidex-designer will bootstrap a clean, neutral DESIGN.md during its first run. If H: the pidex-designer will read the existing codebase to extract the current design system into DESIGN.md and work within those constraints. **Step 2 — Scope of redesign** > What is being redesigned? - Single component (e.g., "the login form", "the navigation bar") - Single page / view (e.g., "the dashboard", "the settings page") - Multiple pages (e.g., "all public-facing pages") - Entire app (design system migration) **Step 3 — Styling framework and constraints** > What CSS/styling framework is in use (or should be)? ``` A) Tailwind CSS B) Tailwind CSS + shadcn/ui (recommended for React) C) CSS Modules / vanilla CSS D) styled-components / Emotion (CSS-in-JS) E) Material UI / Chakra UI / Ant Design F) Keep current (no change to styling framework) ``` Additional constraints: - Must it be responsive? (Mobile-first? Specific breakpoints?) - Dark mode support? - Accessibility requirements? (WCAG level?) - Animation/transition expectations? **Step 4 — Behavior changes** > Does the redesign change how things WORK, or only how they LOOK? - Visual only (same interactions, new appearance) - Visual + interaction changes (e.g., "move from tabs to accordion", "add drag-and-drop") - Full UX rethink (new information architecture, different user flows) If behavior changes: "I need to define the new behavior explicitly in the epic, not just the visual changes. Otherwise the implementer may preserve old behavior that you want changed." **Step 5 — Reference material path** > Where should I tell the pipeline to find the design inputs? Confirm the location: - `/design/` — for Figma exports, screenshots, mockups - `/design/README.md` — for written design specs - External URL — for Figma links (note: the pipeline can read screenshots but not live Figma files) **Step 6 — Acceptance criteria** > How do we know the redesign is done? - "The login page matches the Figma mockup in design/login-v2.png" - "All pages use the new color tokens from the design system" - "Lighthouse accessibility score >= 90" - "Existing E2E tests pass with updated selectors" - "The component renders correctly at 320px, 768px, and 1440px widths" **Step 7 — Synthesize and confirm** Example epic: > Redesign the dashboard page (src/pages/Dashboard.tsx). Design template: Linear (from /design-templates/linear.app.md — copy to agents.output/design/DESIGN.md at project init). Design inputs: mockup in design/dashboard-v2.png. Styling: Tailwind + shadcn/ui (migrating from custom CSS). Layout changes: replace the 3-column grid with a 2-column layout, move the stats cards from sidebar into a top row. Behavior: unchanged — same data, same interactions, new layout and styling. Must be responsive (mobile: single column, tablet: 2 columns). Dark mode: yes (Linear template is dark-mode-first). Accessibility: all interactive elements must be keyboard-navigable, WCAG AA. Acceptance: visual match to mockup at 1440px, responsive at 768px and 375px, existing Playwright E2E tests pass with updated selectors if needed. --- ### Step 8 — Task classification (decides the opening agent) Before starting the pipeline, classify the task to decide whether `pidex-architect` runs BEFORE `pidex-planner` (architecture-first), whether a specialist maintenance agent opens directly, or whether `pidex-planner` opens directly. **Why this matters:** Horizontal-slicing plan failures (Plan-014-pattern) often trace back to structural decisions that pidex-planner made without architectural context — monorepo layouts, migration ordering, dependency boundaries. Running pidex-architect first produces an ADR that constrains the plan before it exists, eliminating a class of rejection loops. **Classify into one of these buckets.** Use the heuristics; when truly in doubt, ask the user. Specialist maintenance routes take precedence over generic Bugfix / maintenance. | Category | Trigger heuristics | Opening agent | |----------|-------------------|---------------| | **Structural** | Framework migration (e.g. Next.js → TanStack), runtime swap (Node → Bun, CJS → ESM), DB engine/ORM change, monorepo restructure, auth-system replacement, new architectural pattern (event sourcing, CQRS, microservice split), major dependency version jump that breaks contracts. Epic verbs: "migrate", "switch from X to Y", "replace X with Y", "rewrite on top of", "refactor base". | `pidex-architect` → produces ADR → then `pidex-planner` | | **Cross-cutting large feature** | Touches 3+ system layers in one epic (e.g. UI + API + DB + auth), introduces a new cross-boundary contract, or spans 3+ existing epics. Epic mentions end-to-end new flows with multiple integration points. | `pidex-architect` → produces ADR → then `pidex-planner` | | **Standard feature** | Single-layer or 2-layer work, fits existing patterns, no new abstractions. Most "add endpoint X, wire UI Y" work lives here. | `pidex-planner` directly | | **Wiki hygiene / project memory maintenance** | User asks for wiki hygiene, wiki cleanup, duplicate/stale wiki files, broken wiki links, Obsidian/wiki organization, `wiki/` audit, project memory/session-memory organization, or explicitly mentions `pidex-wiki-hygienist` / `/pdwiki`. Read-only audit/report requests should not go through planner. Cleanup/apply requests must still start audit-first and ask for explicit mutation approval. | `pidex-wiki-hygienist` directly | | **Bugfix / maintenance** | Localized, no new abstractions. If root cause is unclear: open with `pidex-analyst` first. Do not use this generic bucket for wiki hygiene; use the specialist route above. | `pidex-planner` (or `pidex-analyst` if diagnostic) | **Present the classification to the user explicitly:** ``` Classification: Opening-Agent: Reason: ``` Ask the user to confirm or override. If the user overrides, record their decision in the team prompt so the lead starts with the chosen agent. **Pass the decision to the pipeline:** For architecture-first routes, the team prompt (see Rule 7 template in pidex-instructions.md) must include: ``` OPENING AGENT: pidex-architect After the pre-flight classifier determined this is a task. pidex-architect MUST run before pidex-planner and produce: - An ADR in wiki/decisions/ locking the structural decision - Findings in agents.output/architecture/--architecture-findings.md pidex-planner then reads the ADR + findings as mandatory input. ``` For wiki hygiene / project memory maintenance routes, the team prompt must include: ``` OPENING AGENT: pidex-wiki-hygienist This is a wiki hygiene / project memory maintenance task. Do not run /pdwiki or memory-wiki-hygiene.check capability from the orchestrator before invoking the specialist. Invoke pidex-wiki-hygienist as the opening agent and instruct it to run the deterministic read-only audit itself: node /scripts/modules/run-check.mjs --capability memory-wiki-hygiene.check --agent pidex-wiki-hygienist --phase maintenance --project pidex-wiki-hygienist MUST start read-only, run the audit, write a prioritized report/cleanup plan, and MUST NOT mutate /pidex/** except the deterministic audit state file /pidex/state/wiki-hygiene.json. It must not create agents.wiki.*. It must not mutate wiki files unless the user approves an explicit apply plan; future apply scope is /wiki/** only. If the user asked to execute/apply hygiene, pidex-wiki-hygienist must create a separate execution report at /agents.output/wiki-hygiene/-execution-report.md and must not overwrite the deterministic audit report. After audit/report-only wiki hygiene completes, provide a useful brief (score, counts, top findings, report path, state path, whether wiki content changed) and ask whether to commit the hygiene state. Suggested commit files must include /pidex/state/wiki-hygiene.json only for audit-only runs; never suggest committing agents.output/**. Canonical wiki path is /wiki/. ``` For standard routes, no additional directive — pidex-planner opens as usual. --- ## After confirmation: start the pipeline The execution mode the user chose at the beginning determines how the pipeline starts. --- ### Background mode Background/Telegram lead mode is **not shipped in PIDEX v0.1**. If the user asks for background mode, explain that it remains experimental and continue in direct mode unless a future package release adds documented Windows/Linux-owned service scripts. Do not reference or call legacy lead, relay, or gate-reply scripts. --- ### Direct mode In direct mode, YOU (the orchestrator session) are the lead. You drive the pipeline yourself by invoking the pidex-* agents as subagents in this session. No headless process, no scripts, no Telegram relay — everything is visible to the user in real-time. #### How to drive the pipeline After the user confirms the epic, proceed as follows. Apply Rule 4 (auto-proceed) throughout — do not ask the user for confirmation at non-gate transitions. **1. Preparation (for fresh projects only)** If the epic includes project scaffolding (onboarding flow), create the directory and initialize PIDEX runtime/metadata directories before invoking any pidex-* agent: ```bash mkdir -p /agents.output /pidex/state /pidex/rules /pidex/config /pidex/prompts printf '\n# PIDEX / agent runtime artifacts\nagents.output/\n.wiki-migration/\n' >> /.gitignore echo 0 > /agents.output/.next-id ``` If `.gitignore` already exists, append only missing entries. `agents.output/**` must remain ignored/uncommitted; durable `pidex/` metadata is not ignored by default. Do not copy agent files into the project. Use bundled agents from `/agents/` through `pidex_agent`. Then `cd` into the project (or pass the project path as `cwd` to every `pidex_agent` call). Append a history entry so this run shows up in the next `/pidex`/`/pd` Step 0 shortlist, and emit an analytics-only pipeline lifecycle event for the dashboard: ```bash node /scripts/modules/run-check.mjs --capability analysis-metrics-history.history-append --agent orchestrator --phase planning --project "" -- \ --event direct-start \ --cwd "" \ --mode direct \ --epic "" node /scripts/modules/run-check.mjs --capability analysis-metrics-history.record-event --agent orchestrator --phase planning --project "" -- \ --project "" \ --plan "" \ --event pipeline_started \ --status running \ --actor orchestrator \ --message "Started direct-mode pipeline" ``` `analysis-metrics-history.record-event` is analytics-only. It writes JSONL under `/state/pipeline-events/`; it does not drive a backend scheduler. Operators never pass SQLite `project_id`; ingest derives that from `project_path` (default `$PWD`). Before invoking the opening agent (`pidex-planner`, `pidex-architect`, `pidex-analyst`, or `pidex-wiki-hygienist`), emit the finalized project-scoped preflight operator event. This event is separate from the low-confidence `/pidex` kickoff skeleton and must use the resolved `` and plan key: ```bash node /scripts/quality/preflight.mjs record \ --project "" \ --pipeline-id "" \ --plan "" \ --task-class "" \ --grill-skill "" \ --epic-ready true \ --existing-project true \ --context-read "" \ --context-touched "" \ --acceptance-count \ --out-of-scope-count ``` If exact counts are not known, use best-effort conservative values and include the context/brief artifact path in `--context-read` or `--context-touched`. Do not spawn the opening agent before this finalized `OpPreflight` is written. After the pipeline completes (step 9 / post-retro handoffs) or if the user aborts it, append closing history and lifecycle events: ```bash node /scripts/modules/run-check.mjs --capability analysis-metrics-history.history-append --agent orchestrator --phase planning --project "" -- \ --event direct-complete \ --cwd "" \ --mode direct node /scripts/modules/run-check.mjs --capability analysis-metrics-history.record-event --agent orchestrator --phase planning --project "" -- \ --project "" \ --plan "" \ --event pipeline_completed \ --status completed \ --actor orchestrator \ --message "Direct-mode pipeline complete" ``` Terminal lifecycle events (`pipeline_completed`, `pipeline_failed`, `pipeline_aborted`, `pipeline_cancelled`) automatically run plan-scoped PDQ quality cadence unless `PIDEX_AUTO_PDQ=0` is set. The auto hook updates `state/quality/review-state.json`, writes report files, and appends `OpQualityReview`; failures are fail-soft and must not block terminal event recording. (Use `--event direct-abort` with `--reason ""` and `pipeline_aborted --status aborted` if the user stopped it mid-pipeline.) **1b. pidex_agent routing (MANDATORY before every agent spawn)** Use the `pidex_agent` tool for every specialist handoff. Do **not** use legacy `dispatch.sh` in normal direct mode; `pidex_agent` already honors `/config/agents.json`, routes to Pi/Codex/Claude/Gemini as configured, stores raw child logs under `state/runs/`, and validates ROUTING/context files. Before writing any implementation file, apply `/rules/orchestrator/no-direct-implementation.md`: the orchestrator may prepare context/coordination artifacts, but implementation changes belong to `pidex-implementer` unless the documented repeated-stall fallback is active. Before each spawn: 1. Build a compact manual context pack and mark `CONTEXT-PACK-MANUAL`. 2. Emit `pipeline_stage_started` with `node /scripts/modules/run-check.mjs --capability analysis-metrics-history.record-event ... --` (`--actor `, `--status running`). 3. Pass complete task context to `pidex_agent`: project cwd, current epic/plan, relevant artifact paths, expected output path, gate/ROUTING expectations, and the mandatory `PROJECT BOUNDARY` block from `/rules/orchestrator/project-boundary-write-guard.md`. 4. Set `cwd` to the project root (or lane worktree for implementer lanes). The `cwd` must be inside the allowed write root unless the lane worktree is explicitly declared for the same project pipeline. 5. After return, parse the final `` block. The authoritative artifact path field is `context_file:`. 6. Emit `pipeline_stage_completed` with the route/verdict summary in `--message` or `--metadata-json`; keep pipeline status `running` unless the whole pipeline is waiting/blocked. Reserve `--status completed` for `pipeline_completed`. 7. If the route blocks on user/orchestrator, emit `pipeline_waiting` or `pipeline_blocked`; if `pidex_agent` reports missing ROUTING or invalid `context_file`, treat as stall/format failure and recover per section 4b. Minimal call shape: ```text pidex_agent( agent=, cwd=, task= ) ``` Provider overrides are exceptional debugging tools only. Prefer config-driven routing. **2. Pipeline sequence** **Context-pack enforcement:** before each `pidex_agent` call, create a compact manual pack/path list and pass it in the task briefing. Mark `CONTEXT-PACK-MANUAL`. Budget warnings are non-blocking by default. **Operator decision evidence (Phase 3):** when the operator/orchestrator intentionally skips, overrides, defers, accepts risk, backfills manual evidence, or corrects a PDQ expectation, record an `OpDecision` before continuing. Use the existing finite taxonomy; do not invent free-text reasons when a standard reason fits. Minimal command: ```bash node /scripts/quality/operator-decisions.mjs record \ --project "" \ --pipeline-id "" \ --plan "" \ --decision skip_step \ --target-operator OpReview \ --target-step "pidex-security" \ --reason already-covered \ --approved-by operator \ --risk-accepted false \ --follow-up-required false \ --evidence-path "" ``` Record decisions for all intentional deviations from the conservative route, including approved Execution Profile skips, optional parallel lane skips caused by explicit minimal/cheap/single-lane user choice, manual evidence/backfills, route overrides, explicit risk acceptance, and expectation corrections. Valid skip evidence is not a generic quality gap; unrecorded skips remain missing evidence in PDQ. **Legacy plan migration:** when resuming an active plan that lacks `Execution Profile`, `Skipped Agents`, or `Retro Mode`, prefer a small pidex-planner revision before implementation; if late-stage, run the conservative full path and brief `LEGACY-PROFILE-SKIP: no skips honored`. Default direct-mode route graph: **Execution Profile handling (conservative):** after `pidex-critic` approves, read the approved plan's `Execution Profile`, `Skipped Agents`, `Retro Mode`, and critic `Execution Profile Assessment`. You may honor skipped agents only when all are true: 1. plan explicitly lists the skip in `Skipped Agents`, 2. pidex-critic verdict is `APPROVED` or `APPROVED_WITH_COMMENTS`, 3. critique has no unresolved Critical/Major finding against the skip/profile, 4. no mandatory trigger contradicts the skip (UI-heavy → designer, API/user input → security, product code → QA, UI/G9 → UAT/browser evidence, full-retro trigger → retrospective/pidex-pi), 5. you record an `OpDecision` with the skipped agent/operator, standard reason, approval source, risk/follow-up flags, and evidence path before continuing. If uncertain, ignore the skip and run the conservative default route. Never skip `pidex-qa` for product code; only downgrade/shorten based on profile if plan+critic explicitly allow it. This guidance does not override agent ROUTING blocks for rejection/failure loops. | Step | Agent / Gate | Route rule | |---|---|---| | 0W | `pidex-wiki-hygienist` | Specialist opening route for wiki hygiene / project memory maintenance. Orchestrator must not run `/pdwiki` or the hygiene script itself for this route; it invokes `pidex-wiki-hygienist`, and the specialist runs the deterministic audit. Wiki hygiene must never mutate `/pidex/**` except audit/cadence state at `/pidex/state/wiki-hygiene.json`. Audit/report-only runs must end with a brief and ask whether to commit the hygiene state. If user approves commit, orchestrator owns the commit: stage `pidex/state/wiki-hygiene.json` (use `git add -f pidex/state/wiki-hygiene.json` if ignored), never stage `agents.output/**`, then commit with a `chore(wiki): record hygiene audit`-style message. `COMPLETE` routes to user or orchestrator; cleanup implementation is not automatic. | | 1 | `pidex-planner` | Epic → implementation-ready plan. `COMPLETE` routes to `pidex-critic`; `BLOCKED` routes to `pidex-analyst`, `pidex-architect`, or user depending on reason. | | 2 | `pidex-critic` | `APPROVED*` + UI-heavy/frontend scope → `pidex-designer` unless approved profile explicitly permits skip; `APPROVED*` + no UI or approved designer skip → `pidex-implementer`; `REJECTED` → `pidex-planner` (G1). If designer is intentionally skipped, record `OpDecision` for the skipped review/design step with reason `no-ui-change`, `not-applicable`, or `already-covered` as appropriate. | | 2.5 | `pidex-designer` | UI plans only. `APPROVED*` → `pidex-implementer`; `REJECTED` → `pidex-planner`. | | 3 | `pidex-implementer` | `COMPLETE` → `pidex-code-reviewer`; `BLOCKED` → `pidex-planner`, `pidex-analyst`, or user based on blocker. | | 4 | `pidex-code-reviewer` | `APPROVED*` → `pidex-security` by default; direct `pidex-qa` only when Security Scope Assessment and approved Execution Profile both say skip. Record an `OpDecision` for any security skip before routing to QA. `REJECTED` → `pidex-implementer` or `pidex-architect`. | | 5 | `pidex-security` | `APPROVED*` → `pidex-qa`; `APPROVED_WITH_CONTROLS` / blocking verdict → `pidex-implementer` or `pidex-planner` (G5 when user decision/risk acceptance needed). | | 6 | `pidex-qa` | `COMPLETE` → `pidex-uat`; `FAILED` → `pidex-implementer` (G2); browser-smoke `BLOCKED` → orchestrator collects Playwright evidence and appends QA doc; infra/spec `BLOCKED` → `pidex-planner` or user. | | 7 | `pidex-uat` | `APPROVED` + `gate: G9` → G9 preview then `pidex-devops`; `APPROVED` + `gate: none` / G9 not applicable → `pidex-devops` directly; `REJECTED` → `pidex-implementer` or `pidex-planner` (G3). If G9 is intentionally not applicable, ensure the plan has the G9 applicability declaration or record `OpDecision` with reason `no-ui-change`/`not-applicable`. | | 7.5 | G9 Preview | Orchestrator starts dev server when applicable, asks user to approve/reject visual preview. Reject loops to `pidex-implementer`. UAT-era preview does not replace post-devops UI preview before G4. | | 8 | `pidex-devops` | Stage 1 local commit → if UI involved/uncertain, orchestrator post-devops G9 preview before G4; if non-UI, G4 directly. Stage 2 push/local/hold/abort → `pidex-retrospective` only when Retro Mode is `full` or mandatory full-retro trigger exists; otherwise record `Retro Mode Closure` in deployment/final summary and continue according to plan. If full retrospective is intentionally skipped by approved Retro Mode, record `OpDecision` for the retrospective step unless the closure artifact already records first-class skip evidence. | | 9 | `pidex-retrospective` | `COMPLETE` → `pidex-pi`, with optional `post_retro_handoffs`; skip only when approved Retro Mode is `none`/`mini` and no mandatory trigger occurred. Record `OpDecision` when skipped. | | 10 | `pidex-pi` | `COMPLETE`/`DEFERRED`/`REJECTED` → `pidex-roadmap`. | | 11 | `pidex-roadmap` | Post-pipeline update → orchestrator with G10 next-epic decision. | Optional early agents: - `pidex-analyst` — unknown APIs, unverified assumptions, RCA gaps. - `pidex-architect` — structural/core architecture decisions. - `pidex-wiki-hygienist` — wiki hygiene, project memory/wiki organization, duplicate/stale wiki files, broken wiki links. Use directly for those tasks rather than routing through `pidex-planner`. Parallel implementer lanes are optional, not default. Use them only when the plan has explicit spawn/lane markers and slice independence is clear. Otherwise use sequential implementer spawns following the plan's `Spawn` annotations. **Parallel pidex_agent safety:** When emitting multiple `pidex_agent` calls in the same assistant turn (parallel implementer lanes, configured secondary review lanes, or post-retro handoffs), pass explicit `provider`, `model`, and `effort` for every secondary call. Do not rely on default routing in same-turn parallel calls. Never force `provider=pi` while leaving a delegate model alias such as `sonnet`/`opus`; if overriding to Pi, use a Pi-qualified model from config defaults (for example `openai-codex/gpt-5.4-mini`). **Automatic configured parallel secondary review lanes:** PIDEX optional parallel agents are configured in `/config/parallel-agents.json` and are orchestrator-owned. If global config, the agent container, and a provider/model entry are enabled, the orchestrator MUST automatically launch matching secondary lanes for these triggers unless the user explicitly requested a minimal/cheap/single-lane run: - `after-plan` → with the primary `pidex-critic` lane, launch enabled secondary `pidex-critic` lanes. - `after-implementation` → with the primary `pidex-code-reviewer` lane, launch enabled secondary `pidex-code-reviewer` lanes. Before spawning `pidex-critic` or `pidex-code-reviewer`, run: ```bash node /scripts/modules/run-check.mjs --capability parallel-agents.status --agent orchestrator --phase planning --project -- eligible --agent --trigger --json ``` If `.lanes[]` is non-empty, launch the primary lane and every eligible secondary lane as separate visible `pidex_agent` calls in the same assistant turn. `pidex_agent` itself must not spawn nested agents. Lane launch rules: - Primary: call `pidex_agent` normally using configured primary routing from `/config/agents.json`. - Secondary: call the same `agent` with explicit `provider`, `model`, and `effort` from `status.mjs eligible`. Use `runner_provider` and `runner_model` when present; these map Pi-auth provider/model IDs like DeepSeek/Minimax to `provider=pi`, `model=/`. Do not pass unsupported direct providers such as `deepseek` or `minimax` to `pidex_agent`. - Each lane must receive a unique expected output path; never let secondaries write the primary artifact. - Secondary failure is advisory and non-blocking. Record it with `status.mjs warn --lane --message ` and continue. - Secondary success should be recorded with `status.mjs success --lane --message success` after its output/ROUTING is verified. Secondary artifact suffixes: - `agents.output/critic/--critique...md` - `agents.output/code-review/--code-review...md` Secondary lane brief requirements: ```text This is a configured secondary review lane for PIDEX parallel agents. Lane: . Do not overwrite the primary artifact. Write only the assigned secondary artifact file. Do not write any other path: no `wiki/open-items.md`, `wiki/**`, roadmap docs, source files, rules, configs, primary artifacts, temp helper files, or extra outputs. If you find deferred/non-blocking work, include it as a candidate in the assigned artifact; the merge/adjudication step decides whether to write follow-ups elsewhere. Do not implement changes. Do not invent findings. Every finding must include file path, line/range if possible, risk, evidence, and proposed fix. If no concrete findings exist, write NO_FINDINGS. Return a valid ROUTING block with context_file pointing to the secondary artifact. ``` After all lanes return, read every returned `context_file`, deduplicate findings, and write a required merge/adjudication summary before continuing. Suggested path: `agents.output/parallel-agents/---merge.md`. Classification values: `confirmed-by-multiple-lanes`, `primary-only`, `secondary-only`, `duplicate`, `contradicted`, `no-evidence`. Disposition values: `accepted`, `rejected-no-evidence`, `duplicate`, `deferred`, `needs-primary-review`. For agents with configured parallel lanes, do **not** send user/Telegram gate notifications from the primary lane result. Wait until every secondary lane has completed/timed out and the merge/adjudication summary exists. If the merged decision has a gate, notify/ask the user using the merge summary as the `context_file`, not the primary artifact. Initial policy: advisory execution plus mandatory merge summary. Continue when primary approves and no secondary has concrete High/Critical evidence. Route to `pidex-implementer` or ask for primary-reviewer adjudication when a secondary reports High/Critical with concrete file/path/evidence. Record secondary timeout/failure/malformed ROUTING in the merge summary and continue with the primary result during rollout. Skip secondary lanes when the primary gate already failed clearly, the diff is docs/changelog/version-only, no product diff exists, or the user requested a minimal/cheap/single-lane run. If the skip happens because the user/operator explicitly requested minimal/cheap/single-lane mode, record `OpDecision` with reason `provider-quota-limited`, `operator-approved-risk`, `docs-only`, or `not-applicable` as appropriate. Do not record decisions for lanes that were simply not eligible in config/status output. Before `pidex-security` or `pidex-qa` on JS/TS scopes, include the Fallow requirement in the brief: - `pidex-security`: read `/rules/pidex-security/fallow-structural-signal.md`; record fallow evidence or `FALLOW-SKIP`. - `pidex-qa`: read `/rules/pidex-qa/fallow-static-audit-gate.md`; do not emit QA COMPLETE without fallow evidence or `FALLOW-SKIP`. After every agent return, trust the final `` block over prose. Read `verdict`, `route_to`, `gate`, `reason`, and `context_file`; verify `context_file` exists before proceeding. `route_to: orchestrator` means deterministic internal work for this orchestrator session, not a user gate. If ROUTING contradicts an approved Execution Profile skip, treat it as a routing inconsistency: do not silently override; either follow conservative route or re-run/ask the emitting agent to resolve the contradiction. If the operator deliberately overrides the agent route anyway, record `OpDecision --decision override_route` before continuing. Special case: `pidex-qa` with `reason` containing `browser smoke BLOCKED` routes to orchestrator action, not user decision. **Post-devops UI preview before G4 (mandatory):** When `pidex-devops` Stage 1 completes or before any G4, inspect the plan for `User Preview Requirement`, visible UI/browser changes, or uncertainty. If preview is required, do NOT ask `push/local/hold/abort` yet. Start a preview from committed local HEAD using project-local tooling, show URL/routes/screens to user, ask `approve/reject` as G9. On approve, mark/brief `User Preview Before G4: APPROVED`, then ask G4 directly or re-invoke `pidex-devops` for Stage 2 with that approval context. On reject, record `MANDATORY-RETRO-TRIGGER: G9 rejection` and route to `pidex-implementer`. **3. Gate handling in direct mode** When an agent reaches a gate (G1-G9), it will report the situation in its output. In direct mode, first send a best-effort notify-only Telegram alert when configured: ```bash bash /scripts/telegram/notify.sh \ --project "" \ --needs "" \ --context "" \ --optional || true ``` This notification is informational only: no buttons, no reply handling, no `pending-gate.json`. The user still answers in the Pi session. - **G1-G3, G5 (rejection/failure gates):** Present the agent's findings to the user directly in the terminal and ask for their decision. - **G4 (release push):** Before asking, enforce post-devops UI preview: if UI involved/uncertain and preview before G4 is not approved, start G9 preview first. Only after approved preview ask the user in the terminal: "Ready to tag and release? push / local / hold / abort" - **G7 (agent instruction change):** Show the proposed changes and ask for approval in the terminal. - **G8 (destructive ops):** Ask for explicit confirmation before proceeding. - **G9 (preview verification):** Triggered either after pidex-uat approves with `gate: G9` or after pidex-devops Stage 1 for UI-involved work before G4. The orchestrator (you) starts the dev server/preview server, determines the accessible URL, and asks the user to verify visually. Only proceed after the user says "approve". On "reject", ask what's wrong, record a scoped `MANDATORY-RETRO-TRIGGER: G9 rejection`, load `/rules/orchestrator/g9-rejection-playwright-repro.md`, capture a G9 Rejection Repro Contract, and loop back to pidex-implementer. Before asking G9 again for the same flow, require live Playwright evidence from QA or orchestrator that reproduces the exact rejected browser flow and now passes. After a second rejection in the same plan, or for navigation/runtime/API-auth/browser-only issues, the orchestrator must run Playwright evidence directly when tooling is available before another broad loop. Skip G9 only for non-UI projects without a dev server (pure libraries, CLI tools). If pidex-uat emits `gate: G9` but the plan says G9 is not applicable or no dev server exists, treat it as routing inconsistency; do not start fake preview. Route to devops with documented correction or ask pidex-uat to resolve. Kill the dev server after G9 resolves. Gate decisions are direct-mode terminal prompts in PIDEX v0.1. If a gate is intentionally skipped or satisfied by manual evidence outside PIDEX instrumentation, record `OpDecision` with `--target-operator OpGate` (or the specific affected operator) before continuing. **4. Auto-proceed discipline** Between agents, do NOT ask the user "should I continue to pidex-critic now?" — just proceed. Rule 4 applies identically in direct mode. The only difference is that the user CAN see you proceeding and CAN interrupt if they want to. But do not invite interruptions. **4b. Stall detection + auto-recovery (MANDATORY after every Agent-tool return)** After every `pidex_agent` return, the orchestrator MUST perform a rate-limit pre-check and then a 3-step stall check BEFORE treating the result as complete. **Pre-check: Rate-limit abort detection (check FIRST, before the 3-step stall check)** — PROC-NEW-12 Inspect the `pidex_agent` result telemetry (`exitCode`, `durationMs`, `turnCount`, `maxTurns`, `timedOut`, `turnLimitHit`, `stderr`, `finalText`) and output doc mtime: - If no child turns executed (`turnCount: 0` or no output events) AND (output doc is unmodified OR file doesn't exist yet) AND the return contains a provider-side rate-limit/auth message like `You've hit your limit · resets HH:MM` OR returned within <60s with no content: → Classify as **RATE_LIMIT_ABORT** — the agent was rejected by the API BEFORE running, not stalled mid-run. → Action: wait for the reset time indicated (or 60s if unknown), then re-spawn with the IDENTICAL brief and pre-created skeleton. No tighter brief needed. No skeleton changes needed (none was consumed). → Do NOT count this against the 3-strike escalation rule — the agent had no agency in the failure. → After 2 consecutive RATE_LIMIT_ABORTs, notify the user: rate-limit window may be extended; consider manual pause. → Skip the 3-step stall check below — the agent simply didn't run. - If no child turns executed BUT no rate-limit message + `durationMs < 5000`: unusual empty return — fall through to stall check as "No ROUTING + empty doc" (genuine start-of-turn stall). **Empirical basis**: Plan 25 Spawn A attempt 1 returned `tool_uses: 0` with Anthropic rate-limit message `You've hit your limit · resets 1:30pm`. Orchestrator recovered ad-hoc — this pre-check formalizes it. **3-step stall check** (if pre-check did not trigger): 1. **ROUTING presence check**: grep the Agent return message for `