# Task Graph > Turn approved implementation plans into plan-isolated task files and a conservative executable DAG in .agent//. - Skill: `igorrendulic/task-graph` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add igorrendulic/task-graph` - Raw SKILL.md: https://api.skillmd.com/api/skills/igorrendulic/task-graph/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: igorrendulic (https://skillmd.com/u/igorrendulic) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/igorrendulic/task-graph --- # Task Graph ## When to use this skill Use Task Graph only when an approved implementation plan is available. - To convert that plan into task briefs, a kanban board, and a dependency-safe DAG, use `tasks`. - To execute a validated DAG from a clean repository, use `start`. - To continue an interrupted run, use `resume`. - To inspect a run, use `status`. - To inspect the completed implementation locally, use `checkout`. - To explicitly promote a successful run, use `merge`. - If the user has not yet approved an implementation plan, use the appropriate planning or brainstorming workflow first; do not create Task Graph artifacts. ## Board Paths Assume the repository root is the current working directory unless the user gives another path. - Canonical DAG: `.agent//dag.json` - Board: `.agent//kanban.md` - Task folders: `.agent//todo`, `.agent//in-progress`, `.agent//done` For every plan, read the supplied implementation plan and derive and announce a concise lowercase kebab-case `` from its goal. Reuse that slug when resuming the same plan. The target repository must contain `.agent/`; if it does not, ask before creating project workflow files. Do not use or update a legacy shared `.agent/tasks`, `.agent/kanban.md`, or `.agent/runs` layout. ### Multi-project workspaces For independently versioned projects under one parent folder, use the parent as the workspace root. It need not itself be a Git checkout. Declare only the projects Task Graph may execute in `.agent/task-graph.workspace.json`: ```json { "schemaVersion": 1, "projects": [ { "id": "frontend", "path": "apps/frontend" }, { "id": "api", "path": "services/api" } ] } ``` Every declared path must be a safe relative path to an independent Git root; undeclared folders are never touched. In a workspace DAG, every task must name one declared `project`, and `predictedPaths` are relative to that project. Inspect all declared projects while planning. Use cross-project `dependsOn` edges for contracts and delivery order; a dependent begins only after its prerequisite has been integrated into that prerequisite project’s integration worktree. ## `tasks` workflow Use this workflow when the user asks to turn an approved plan into implementation tasks. Before creating or refreshing task files, `kanban.md`, or `dag.json`, read [the DAG-generation reference](references/dag-generation.md) completely and follow it. It defines the task-file contract, canonical DAG schema, conservative scheduling rules, validation, write order, and the v1 planning-only boundary. ## `start` and `resume` workflows Use these workflows only after a validated plan DAG exists. `start` rejects a dirty repository, snapshots the DAG and task briefs, creates an isolated feature branch and worktrees, then starts a controller service in a plan-level tmux session. Invoke it with: ```sh python3 scripts/task_graph_cli.py start --max-workers ``` For a workspace, add `--workspace ` to every lifecycle command: ```sh python3 scripts/task_graph_cli.py start --workspace --max-workers python3 scripts/task_graph_cli.py resume --workspace python3 scripts/task_graph_cli.py status --workspace ``` Workspace workers are isolated in their task’s project and receive each prerequisite project’s integration worktree, project ID, and integrated commit SHA as read-only implementation context. Independent tasks in distinct projects may run concurrently. The run retains one feature branch and integration worktree per used project for review. Return the exact `tmux attach-session -t task-graph--` command printed by `start` to the current user so they can observe workers. Workers run focused task tests and create one task-scoped commit; the controller does not run a final full suite in MVP. Use `resume` with the plan slug and run ID after interruption. It reconnects to the live controller when its saved pane and PID are still valid, or starts one replacement controller from the persisted snapshot: ```sh python3 scripts/task_graph_cli.py resume ``` ## `status`, `checkout`, and `merge` workflows Use `status` to inspect the newest run, or pass a run ID for a specific run: ```sh python3 scripts/task_graph_cli.py status python3 scripts/task_graph_cli.py status --run-id ``` It reports `running`, `succeeded`, `failed`, or `already merged`. Do not infer that a worker branch is promotable: only the run's `task-graph///feature` branch can be merged. Worker-attempt branches are never merged directly. To inspect or run commands against a succeeded, unmerged run locally, check it out explicitly: ```sh python3 scripts/task_graph_cli.py checkout --run-id ``` `checkout` requires the primary checkout to be clean except for that plan's `.agent//runs/` artifacts. It also requires the generated integration worktree to be clean, then removes it without force so Git can release the run feature branch to the primary checkout. It does not change run state. The command prints the exact `git switch ` and `merge` commands to use after inspection. Promotion must name the run explicitly: ```sh python3 scripts/task_graph_cli.py merge --run-id ``` Workspace review and promotion are deliberately per project after the coordinated run succeeds: ```sh python3 scripts/task_graph_cli.py checkout --run-id --workspace --project python3 scripts/task_graph_cli.py merge --run-id --workspace --project ``` Before invoking `merge`, ensure all tasks are integrated, check out the base branch recorded at `start`, and leave the checkout clean except for `.agent//runs/` artifacts. The command performs a `--no-ff` merge; on conflict it aborts safely and leaves the target branch unchanged. A completed promotion is recorded in run state, so later attempts report `already merged`. On macOS the controller sends one best-effort desktop alert when a run completes. Success alerts include the exact `checkout` command first, then the follow-up merge command after returning to the recorded base branch; failure alerts include the status command. macOS permissions and user-session availability can prevent delivery; Task Graph records the alert outcome and any safe OS error in run state, which `status` displays for diagnosis. Alerts cannot safely paste or execute terminal commands; the operator must run the displayed command in a terminal.