# Orchestrating Development Graphs > Use when starting a code change, feature, bug fix, refactor, or build/configuration task where workflow intensity may be disproportionate, or when reviewing whether development changes are necessary. - Skill: `xincheng-1999/orchestrating-development-graphs` (Agent Skill, multi-file: 6 files) - Install (CLI): `npx skillmds@latest add xincheng-1999/orchestrating-development-graphs` - Raw SKILL.md: https://api.skillmd.com/api/skills/xincheng-1999/orchestrating-development-graphs/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - License: MIT - Author: xincheng-1999 (https://skillmd.com/u/xincheng-1999) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/xincheng-1999/orchestrating-development-graphs --- # Orchestrating Development Graphs ## Overview Choose the smallest reliable workflow. Use a persistent executable graph only when concrete risks make conditional gates, failure routes, and resumable state necessary. User instructions and the nearest applicable host rule file—`AGENTS.md` in Codex or `CLAUDE.md` in Claude Code—override this Skill. Follow the host's normal rule-file discovery and precedence when both files are visible. ## When to Use Use this Skill before every code change, feature, bug fix, refactor, build, dependency, or configuration task when the correct amount of process is not yet known. It is especially relevant when a task may involve approvals, public interfaces, persistence, migrations, concurrency, permissions, security, payments, resumable execution, or delegation. For an explicit review of unnecessary changes or scope expansion, use the change-boundary and diff-review rules below without starting a development workflow. ## When Not to Use Read-only explanation, status, research, or diagnosis does not require this Skill. A review of change necessity does not authorize edits, rollback, workflow artifacts, or delegation. Do not create a development graph merely because a task has several steps; only evidence-backed Complex work gets a persistent graph. ## Establish the Change Boundary Before implementation, identify the requested outcome and expected edit areas in the existing progress update or approved Spec. This does not require another document or approval step. Keep changes that directly implement the request or are supported by evidence as necessary dependencies. For a proposed change to existing initialization, event subscriptions, history, or shared infrastructure, identify the current behavior, what fails for the requested outcome if it remains unchanged, and the source trace, reproduction, or test supporting that conclusion. Uniformity, future reuse, and hypothetical risks alone do not justify expansion. A demonstrated dependency defect may require a focused fix within the user's authorization; do not impose a blanket ban on changing existing code. Tests verify the agreed behavior and its necessary invariants. They do not introduce additional product requirements, and real failures must not be hidden by deleting tests or weakening assertions. When a user questions a change, verify the claim before agreeing, defending, or reverting it. An explanation request is not a rollback instruction. Correct unsupported explanations, retain necessary fixes, and distinguish proposed optional cleanup from work already performed. ## Classify Before Acting Use the lowest class supported by evidence and report the class, concrete signals, and route before implementation. | Class | Signals | Route | | --- | --- | --- | | Simple | Clear, local, mechanical, low risk, easy rollback | `Implement -> focused Verify` | | Standard | Bounded observable behavior change | compact `Spec -> approval -> Plan -> approval -> TDD batches -> Verify` | | Complex | Demonstrated compatibility, data, concurrency, security, or build risks whose coupled steps need conditional gates, bounded rework, or resumable state | approved Spec/Plan plus a persistent executable graph | Public API exposure, multiple files, or crossing a module boundary are inspection signals, not automatic escalation rules. A thin wrapper over existing behavior with clear inputs, easy rollback, and focused verification can be Simple; bounded new behavior is Standard. Explain the concrete failure modes that require Complex execution. Do not create speculative changes that make an otherwise bounded task appear Complex. Simple tasks must not create a graph artifact. Do not create a Spec, Plan, worktree, commit, review pipeline, or subagent unless the user requests it or evidence forces reclassification. Implement and run the smallest fresh proof. Standard tasks must not create a graph artifact. Save mutually linked documents at `/docs/superpowers/specs/YYYY-MM-DD-.md` and `/docs/superpowers/plans/YYYY-MM-DD-.md`; obtain approval after each. Keep the Plan to 3–5 acceptance-mapped steps. Do not probe runtimes for Simple or Standard tasks. Runtime selection exists only to make a Complex execution graph executable. ## Resolve Skill and Target Roots Before Standard or Complex work, resolve two distinct absolute directories: - `SKILL_ROOT`: the directory containing this `SKILL.md`. Resolve it from the loaded Skill resource, never from the current working directory. Read `references/`, run `scripts/`, and access distributed `examples/` only beneath this root. - `TARGET_ROOT`: the Git root of the repository being changed, otherwise the current directory. Write task Spec, Plan, graph JSON, runtime state, and SVG preview only beneath this root. Never assume the target repository contains this Skill's executor. Substitute the resolved absolute paths when a command below contains `` or ``. ## Execute Complex Work as a Graph For Complex work, keep orchestration artifacts under `` and invoke the executor from ``. 1. Write `/docs/superpowers/specs/YYYY-MM-DD-.md` with current behavior, goals/non-goals, user behavior, interfaces/data flow, edge cases, risks, rollback, and acceptance criteria. Obtain approval. 2. Write a 3–5 step Plan and `/docs/superpowers/graphs/YYYY-MM-DD-.json`. Link Spec, Plan, and graph both ways. Obtain approval for the Plan and graph. 3. **REQUIRED REFERENCE:** Read `/references/graph-schema.md` before authoring or changing a graph. 4. Select one executor for the task and keep using it: prefer an actually runnable Python 3.10+ with `python "/scripts/dev_graph.py"`; otherwise use Node.js 18+ with `node "/scripts/dev_graph.mjs"`. Treat a broken Windows Store Python alias as unavailable. If both runtimes are unavailable, record a blocker and stop; never replace the executable ledger with a prose-only graph. 5. Author new Complex graphs as Schema v2. After authoring or changing a graph JSON definition, run `validate -> render` with the selected executor and confirm the same-name SVG exists before approval or execution. Mutating commands automatically refresh that SVG; JSON remains the source of truth. 6. Run `init` against the approved graph, then ask `ready` which nodes may run. For actions, use `start` before work and `done` with handoff evidence afterward. For gates, use only `run-gate`; the executor runs the approved checks and selects `pass` or `fail` from their real exit status. Use `approve`/`reject` for approval nodes and `block`/`scope-change` only for their stated external conditions. 7. Follow only the node activated by the recorded edge. Do not manually rewrite runtime state, erase failed attempts, or continue down an inactive branch. 8. Before claiming completion, run `status` and require `completion: complete`, then perform the normal fresh verification pass. The JSON graph is the execution ledger. Do not duplicate changing node status in the Plan. The executor runs only the explicit local check commands declared on approved Schema v2 gate nodes. It never implements changes, runs action-node work, deploys, migrates data, or expands the user's authorization. Existing Schema v1 graphs remain ledger-only and may continue with their original manual commands. For Schema v2, the Agent must not manually call `pass`, `fail`, or `start` on a gate and must not replace `run-gate` machine evidence with a prose assertion. If the task changes the graph executor itself and no prior executor exists, the first validator node may bootstrap under an approved Spec and Plan. As soon as the executor works, initialize the graph and replay that node with fresh RED/GREEN evidence. No later node may bypass the executor. ## Route Node Handlers When a named companion Skill is available in the current host, load it as required below. When it is unavailable, perform the stated discipline directly in the current Agent; a missing optional companion name is not a blocker. - Material ambiguity: use `superpowers:brainstorming` when available; otherwise clarify goals, constraints, alternatives, and acceptance before finalizing the Spec. - Defect or unexpected behavior: **REQUIRED WHEN AVAILABLE:** use `superpowers:systematic-debugging`; otherwise reproduce, gather evidence, isolate the root cause, then propose or implement a fix. - Approved multi-step work: use `superpowers:writing-plans` when available; otherwise write the 3–5 acceptance-mapped steps directly. Reject automatic commits, worktrees, or per-task agents. - Testable Standard/Complex behavior: **REQUIRED WHEN AVAILABLE:** use `superpowers:test-driven-development`; otherwise run the same RED -> GREEN -> REFACTOR cycle directly. - Approved Plan: use `bounded-plan-execution` when available; otherwise execute the approved steps sequentially in the main Agent and record fresh verification after each batch. - Completion claim: **REQUIRED WHEN AVAILABLE:** use `superpowers:verification-before-completion`; otherwise run fresh focused and integration verification before reporting success. - Independent review: use `superpowers:requesting-code-review` when available and only for security, concurrency, permissions, migrations, or payments. - Worktrees, commits, PRs, and branch finishing: use only when requested or repository-required. Never default to `superpowers:subagent-driven-development`; use it only when the user explicitly selects its per-task multi-agent pipeline. ## Keep Host Compatibility The portable Skill consists of `SKILL.md`, `references/`, and `scripts/`. `agents/openai.yaml` supplies Codex display metadata only; Claude Code may ignore it without losing classification or graph execution. Claude Code discovers the Skill from a user or project `.claude/skills/orchestrating-development-graphs` directory and may invoke it as `/orchestrating-development-graphs` or through a matching natural-language request. Codex uses its configured Skill directory and `$orchestrating-development-graphs`. Only a runnable Python or Node.js executor is a hard dependency for Complex graph execution. Superpowers and `bounded-plan-execution` are optional companion Skills, not prerequisites. They improve individual node handling when installed; the fallback rules above keep the core classifier, state machine, evidence ledger, and SVG preview usable without them. ## Bound Delegation Default to zero subagents. Delegate only a bounded outcome independent of evolving integration context, with disjoint ownership or read-only scope and positive coordination value. A subagent statement is not gate evidence. Use at most two subagents concurrently and three per task. These are ceilings. Explain the benefit and obtain approval before exceeding them. Never create implementer/reviewer/fixer pipelines per Plan item. ## Enforce Evidence and Failure Routes Every nontrivial graph node records inputs, owner, outputs, pass condition, and failure destination. Gates and approvals cannot pass without evidence. Use test, compiler/type/lint/build, runtime, business, database, or explicit user-approval evidence. On a Schema v2 gate failure, `run-gate` records `fail` automatically. Follow the activated diagnostic or rework node, rerun the original gate, and preserve every attempt. On a material scope change, record `scope-change`, update Spec/Plan/graph, obtain approval, then reinitialize. Never weaken or bypass a gate check to make it green. Stop and simplify when a Simple or Standard task starts creating a graph, task count determines agent count, Git actions lack authority, loops exceed their bound, or success relies only on an Agent assertion. ## Review the Actual Diff Before delivery or a user-authorized commit, inspect the full task diff and new files, including tests, documentation, and process artifacts. Map each change to the requested outcome or a demonstrated dependency. For changes to existing behavior, summarize why they are needed and the focused verification evidence. Remove unsupported task-owned extras or report them as optional follow-up work without implementing them. Preserve the user's unrelated edits. Do not add a separate review pipeline or report file for this check, and do not remove necessary behavior or weaken verification merely to reduce the diff. ## Examples Classify from evidence, not from prompt length or the label "Complex": ```text Rename a local variable and run one focused test => Simple: Implement -> focused Verify Expose an existing operation through a thin public wrapper with unchanged semantics => Simple: Implement -> focused Verify; public API exposure alone does not require a graph Add bounded validation behavior to one service => Standard: Spec -> approval -> Plan -> approval -> TDD batches -> Verify Propose an event-listener rewrite solely for consistency while adding a control => Omit the rewrite; if a reproduction shows missing updates block the requested control, make the necessary focused fix Migrate persisted data while preserving a public API and rollback path => Complex: approved Spec/Plan -> executable graph -> evidence gates ``` For a Complex graph on Windows, resolve both roots first, then validate and render with one available executor: ```powershell $skillRoot = "C:\absolute\path\to\orchestrating-development-graphs" $targetRoot = "C:\absolute\path\to\target-repository" $graph = Join-Path $targetRoot "docs\superpowers\graphs\2026-07-29-migration.json" node (Join-Path $skillRoot "scripts\dev_graph.mjs") validate $graph node (Join-Path $skillRoot "scripts\dev_graph.mjs") render $graph ``` ## Limitations - Schema v2 executes only the explicit Gate checks declared in an approved graph; it does not perform Action work, deploy, migrate data, or expand authorization. - Schema v1 remains a ledger-only compatibility format and does not prove that a claimed command ran. - JSON is the source of truth; the SVG is a generated preview and cannot be used to update graph state. - Complex execution requires Python 3.10+ or Node.js 18+. Simple and Standard routing requires neither runtime. - Companion Skills improve node handling but are optional; host rules and explicit user instructions always take precedence. ## References - **REQUIRED FOR GRAPH AUTHORING:** `/references/graph-schema.md` - Optional companion Skills: `superpowers:brainstorming`, `superpowers:systematic-debugging`, `superpowers:writing-plans`, `superpowers:test-driven-development`, `bounded-plan-execution`, `superpowers:verification-before-completion`, and `superpowers:requesting-code-review`. - Distribution and installation guide: `README.md` and `README.zh-CN.md` in the repository root.