GSD Path

A disk-backed project pipeline for AI coding agents. It turns a raw idea into shipped code through gated phases — inspect, define, research, decide, roadmap, plan, build, and ship — with every handoff written to .project/ so any session can resume from disk alone. A single milestone or a full multi-milestone program: program flow adds a charter and roadmap above the milestone loop. While a milestone builds, the next one can be planned in parallel under .project/next/ (lookahead); a building milestone can also be abandoned on an explicit ruling, archiving its partial work for a re-slice.

Supported hosts: Codex, Claude Code, Grok, OpenCode, GitHub Copilot CLI, Qwen Code, Antigravity CLI, Cursor, Zed, Kiro, and Kimi Code. Support means the installer and dispatch contract exist. See the host trust matrix for live milestone proof and each host's guard tier.

Latest npm release: @opengsd/[email protected] — release notes

Recent highlights

• describe untracked legacy migration in help
• preserve older untracked runtimes during migration
• Clarify legacy runtime backup guidance
• Consolidate legacy runtime migration guidance
• prepare 1.3.1 patch candidate

Documentation

Start at DOCS.md — install, use, understand, and update in one hub.

| Guide | Use when | | --- | --- | | DOCS.md | Full map + FAQ (recommended) | | QUICK.md | First run checklist (~5 min) | | FULL.md | Complete install-to-ship walkthrough | | UPDATE.md | Refresh skills, hooks, or contracts | | WORKFLOW.md | Phase-by-phase agent SOP | | HOOKS.md | Optional archive/git guard hooks | | Jev screening | Optional evidence screening; disabled by default, no SDK required | | daemon/README.md | Dashboard, menu-bar app, and monitoring setup | | CHANGELOG.md | Published release notes | | RELEASE.md | Maintainer CI and npm release cycle | | GUIDE.md | Pointer to the guides above |

What's new — September 19, 2026

These changes are merged into the source checkout; npm installs use the latest published release.

• Dashboard settings and history: edit Path settings, browse project files and Git versions, and load full recorded evidence. See the dashboard guide.
• Model and effort policy: set user, project, host, and task choices through one resolver. Recorded assignments stay pinned; unsupported explicit choices stop the affected dispatch. See the model policy.
• External worktrees and pinned runtimes: new parallel task, verification, and integration worktrees live outside project checkouts. Projects pin runtime versions by content digest, with explicit upgrade, restore, and legacy migration commands. See worktree locations and runtime versions.
• Clearer project updates: the dashboard shows project runtime versions and update results. After verified integration, ordinary branches can resume product work while archived milestones remain protected. See update guidance.
• Optional Jev screening: reviewers can request advisory checks of selected criteria and evidence. It is disabled by default and never replaces recorded verification or review gates. See Jev screening.

Install from npm

Requires Node.js 18.17+ for the npm installer and Python 3.9+ for project contracts and pipeline helpers. Install and sign in to a supported coding-agent host separately; GSD Path installs its skills, not the host itself. The public npm package is @opengsd/gsd-path.

# Interactive installer: choose hosts, install scope, contracts, and hooks
npx @opengsd/gsd-path@latest

# Or preview and install skills for all supported hosts
npx @opengsd/gsd-path@latest --all --dry-run
npx @opengsd/gsd-path@latest --all

# Add contracts and the status runtime to your project
npx @opengsd/gsd-path@latest --all --project /path/to/your-repo

# Update existing installs
npx @opengsd/gsd-path@latest --update
npx @opengsd/gsd-path@latest --update --project /path/to/your-repo

Use host flags such as --claude --codex instead of --all to select hosts. For project-local skills, run from your project directory and add --local to install and update commands. --project PATH selects where contracts are written; it does not change the directory used by --local. Run npx @opengsd/gsd-path@latest --help for all options. After installing, invoke $path in Codex or /path on slash-command hosts to start the pipeline. See Install (summary) for the host list and source-checkout commands. The npm command installs the latest published release; a source checkout may contain newer changes.

Start your first project

1. Open your project folder in your coding-agent host. Existing repositories need Git; GitHub repository creation and pull-request operations also need an authenticated GitHub CLI (gh).
2. Start or reload the host session so it discovers the installed skills.
3. Invoke $path in Codex, or /path on slash-command hosts. The router identifies the project and guides you through the required inputs and approvals.
4. Resume later from the same folder with the router. Use $path status (Codex) or /path status to inspect progress without advancing.

For a missing skill or an install problem, run:

npx @opengsd/gsd-path@latest --doctor --project /path/to/your-repo

Add --local when checking project-local skills, from that project directory. See QUICK.md for the first-run checklist and HOOKS.md for optional Git and host guard hooks.

For project-owned model and effort choices, see the dispatch model policy.

Use $path config (Codex) or /path config to view and change user defaults or project settings. Dashboard users can open Settings → Path settings for the same shipping, model/effort, and future review-panel controls. See Path settings for precedence and locks.

Dashboard and menu-bar toolbar

The optional OpenGSD Path monitor shows your projects without opening each project's .project/ files. It watches the folders you choose and reads project state without advancing phase gates. Explicit Path settings saves use the validated configuration helper; background monitoring remains read-only. The monitor is a separate install from the npm skills package.

Dashboard

The project board shows blocked, active, and shipped work, with milestone and phase progress, task counts, last activity, and available usage data. Use the dashboard controls to filter or search projects, switch between Board and Milestones, refresh status, and manage settings.

Click a project to see its milestone roadmap, tasks, success criteria, review results, verification history, and activity. Usage includes tokens and turns from supported host session logs; cost estimates require model prices in the daemon configuration.

Dashboard screenshots captured from the current source on September 19, 2026, using the repository's sample projects.

Open History & files to browse project files and archived milestones, preview Markdown, or read a file at a selected Git commit. Relative document links keep that selected version. Records & sources → Load full records loads recorded usage, verification, activity, and indexed host turns on demand, with coverage details that make missing or invalid data visible.

Open Settings → Path settings to change user defaults or project overrides for shipping mode, model and effort choices, and future review panels. Each setting shows its source and any lock reason; changes are saved explicitly.

The Plugin settings page shows each watched project's runtime version and provides an explicit Update action with progress and failure details. Updating global skills does not update a project's pinned runtime.

macOS menu bar

Click the OpenGSD Path menu-bar icon for a compact project list with phase meters and task progress. Click a project to open its dashboard page. The bottom toolbar opens the dashboard, plugin settings, and watched folders; it also provides rescan, appearance, and quit controls. The daemon row shows its running state and provides restart and stop controls. Option-click the menu-bar icon to open the dashboard directly.

Screenshots show the current UI with sample project data. The native panel is captured in its preview window.

Install the monitor

The monitor requires Python 3.9+. From a source checkout, preview the setup, then install (macOS/Linux shell):

git clone https://github.com/open-gsd/gsd-path.git
cd gsd-path
PYTHONPATH=daemon python3 -m gsd_daemon install --dry-run
PYTHONPATH=daemon python3 -m gsd_daemon install

On Windows, after cloning and entering gsd-path, use PowerShell:

$env:PYTHONPATH = "daemon"
python -m gsd_daemon install --dry-run
python -m gsd_daemon install

On Windows, launch the installed shortcut for this session before opening the dashboard. It starts automatically at future logins:

Start-Process "$env:APPDATA\Microsoft\Windows\Start Menu\Programs\Startup\gsd-path-daemon.lnk"

Open http://127.0.0.1:8765, then use Settings → Watched folders to add your project folders. The installer creates an isolated Python environment and configures autostart. On macOS it also builds and installs the native menu-bar app; this requires macOS 12+ and Xcode Command Line Tools (swiftc). On macOS, use --no-tray for the dashboard only. Linux autostart runs the dashboard; launch the optional tray separately with ~/.gsd-path/venv/bin/gsd-path-daemon tray. Windows uses a tray-and-dashboard Startup shortcut; see the daemon guide for platform details.

See the daemon guide for configuration, usage pricing, manual startup, and platform setup, or the macOS guide for native menu-bar details.

Skills

Canonical explicit-only skills are installed. Invoke the router by default; use phase skills for one step only, or use a sidecar to discuss, diagnose, or undo without advancing.

| Skill | Role | | --- | --- | | path | Router short name — same as gsd-path (/path, $path) | | gsd-path | Router — detects state, runs next phase (status reports without advancing) | | gsd-path-inspect | Phase 0 — brownfield codebase map + doc audit | | gsd-path-define | Phase 1 — intent definition | | gsd-path-research | Phase 2 — parallel evidence researchers | | gsd-path-decide | Phase 3 — evidence → decisions | | gsd-path-roadmap | Phase 3.5 — program: slice charter into milestone roadmap | | gsd-path-plan | Phase 4 — waves and task contracts | | gsd-path-build | Phase 5 — parallel coders + serial task landing | | gsd-path-ship | Phase 6 — verify, approve, archive, and ship | | gsd-path-discuss | Any-phase discussion with durable dialogue and answers | | gsd-path-docs-audit | Standalone doc-vs-code drift check | | gsd-path-loop | Standalone bounded loop runner driven by a LOOP.md spec | | gsd-path-forensics | Read-only stuck-pipeline diagnosis | | gsd-path-migrate | Import GSD Core work and review hook coexistence | | gsd-path-undo | Helper-owned undo of unpublished pipeline work |

See invocation by host. Phase names keep the gsd-path- prefix.

The flow

flowchart TD
    R{"gsd-path router"} --> I["0 · inspect (brownfield)"]
    R --> D["1 · define → INTENT.md / CHARTER.md"]
    I --> D
    D -->|"standard / program lane"| RE["2 · research → evidence files"]
    D -->|"quick lane"| P
    RE --> DE["3 · decide → SYNTHESIS.md"]
    DE -->|"program scope"| RM["3.5 · roadmap → ROADMAP.md"]
    RM -->|"approved → checkpoint commit"| DM["define (milestone mode)"]
    DM --> MQ{"roadmap entry has open questions?"}
    MQ -->|"yes"| RE
    MQ -->|"no"| P["4 · plan → PLAN.md + task contracts"]
    DE -->|"milestone / single-project scope"| P
    P -->|"approved → checkpoint commit"| B["5 · build"]
    B --> W{"wave loop"}
    W -->|"briefs linted at base SHA"| C["parallel coders, isolated worktrees"]
    C -->|"streaming: dependents dispatch as deps land"| V{"wave review"}
    V -->|"full / verify-only / deep"| F{"verdict"}
    F -->|"blocked → criterion triage"| W
    F -->|"pass → next wave"| W
    F -->|"all waves pass"| S["6 · ship — final review"]
    C -.->|"NEEDS-ORCHESTRATOR question"| O["orchestrator answers from artifacts, or asks you"]
    O -.-> C
    B -.->|"lookahead: next milestone in .project/next/"| MI["inspect current code + docs"]
    MI --> MB["define (milestone + brownfield mode)"]
    MB --> MQ
    B -->|"explicit ruling: abandon milestone"| AB["archive partial work → re-slice roadmap"]
    AB --> RM
    S -->|"approved → archive + ship commit"| MG["direct merge or user-merged PR + tag"]
    MG -->|"validate-integrated passes"| A["shipped"]
    A -->|"another program milestone → bind next gsd-path/M00N"| MI
    A -->|"single-milestone restart → bind next gsd-path/M00N"| I
    A -->|"program complete"| PC["stop"]

Starting in an empty folder without Git leaves that folder unchanged until repository setup. The router asks whether to create a new GitHub repository or use an existing repository. For a new repository, approve the exact owner/name, visibility, default-checkout path, gsd-path/M001 branch, and linked-worktree path before creation. The starting folder is proposed as the linked worktree, with a distinct default checkout beside it, so the agent keeps working where it started. Only an approved empty directory can be reused; nonempty folders and symlinks remain protected. Pipeline state is created after repository setup. See the repository setup procedure.

For an existing Git repository, initialization writes STATE.md first. Before entering inspect or define, the router fetches origin/main, creates or adopts gsd-path/M001 there, and records the binding in state. Build only uses that recorded milestone branch; it never creates or selects one. See the phase workflow.

At any non-shipped phase, /gsd-path-discuss (or $gsd-path-discuss in Codex) records the conversation in .project/discuss/ without advancing or editing the phase handoff. Required decisions carry a named owner and remain pending until that phase records how it applied them; the router will not advance past an unresolved required follow-up.

Build, under the hood:

• For intent corrections or structural plan repair during a blocked build, follow the build recovery contract.
• Task briefs are linted against the real base tree (check_task_briefs.py) before any agent is dispatched, and every coder runs a preflight — paths exist or are declared, interface contracts match siblings verbatim — so a wrong map dies in the first minute.
• Task isolation and landing go through isolation.py: named branches only, never a detached HEAD. A serial dispatch round works on the bound branch; a parallel round gets gsd-path-task/<id>.
• Dispatch streams: a dependent task starts the moment its dependencies land, never idling behind unrelated in-flight tasks. Task landing stays serial and every Verify reruns in the isolated worktree.
• Wave review depth is full, verify-only, or deep; findings carry forward by criterion across fix cycles. Each depth's writer and evidence rules live in the canonical build contract. Optional skeptic triage for blocked deep reviews is defined in WORKFLOW.md.
• A coder with an ambiguous contract asks NEEDS-ORCHESTRATOR instead of guessing; on hosts with a blocking ask/reply channel the worker stays alive for the answer.
• Roadmap and plan approvals are checkpoint commits, so planning work never sits uncommitted until build.

Invoke the router explicitly to start or advance a phase. Once a project has an owned .project/STATE.md, a plain prompt such as “continue the project” answers read-only with the current handoff and uses the runtime’s handoff.next; it never advances a phase or edits state. An active router continues across completed phases until required input, approval, or a block. A phase invoked directly stops at its handoff; invoke the router again to continue. Chat and the dashboard use the same executable phase handoff from the status runtime. The discussion sidecar is the exception: it can be invoked at any non-shipped phase and returns only a durable conversation record.

The router classifies brownfield, greenfield, owned, and orphaned project state before routing; see DOCS.md. Brownfield → inspect then define. Greenfield → define. It does not infer the verdict from a directory listing. Quick lane (tiny scope) may skip research/decide — see FULL.md.

For an explicit new-GitHub request, the router previews the owner, visibility, default checkout, gsd-path/M001 branch, and sibling linked worktree. A journaled helper performs the approved creation and safely resumes a matching partial remote/clone/worktree transaction; the default checkout stays clean.

Handoff contract

.project/
  STATE.md                    phase, branch, archive transaction
  REPOSITORY.md               persistent new-GitHub checkout/worktree binding
  CHARTER.md                  program scope and vetoes; never archives
  ROADMAP.md                  milestone slicing; never archives
  SYNTHESIS.md                program decisions (top level); never archives
  next/                       lookahead track: next milestone's artifacts during build
  intent/INTENT.md            goal, vetoes, constraints, surfaces
  research/
    evidence-codebase.md      brownfield ground truth (inspect)
    DOCS-AUDIT.md             doc verdicts + remediation queue
    RESEARCH.md               dispatch manifest (dimensions researched/skipped)
    evidence-domain.md        domain evidence
    evidence-stack.md         stack evidence
    evidence-pitfalls.md      pitfalls evidence
    evidence-similar.md       similar projects evidence
    SYNTHESIS.md              gated decisions
  plan/PLAN.md                waves, dependencies, surface contract, verify
  tasks/T###-slug.md          task contract: files, interface, criteria, base SHA, status
  review/                      review evidence; see WORKFLOW.md#handoff-contract
  discuss/DIALOGUE.md         any-phase dialogue transcript
  discuss/ANSWERS.md          durable discussion answers and decisions
  LESSONS.md                  optional carried-forward planning lessons
  archive/<NNN>-<slug>/       shipped milestones (read-only after ship)

Shipping moves milestone artifacts into archive/ with a MANIFEST. It then either merges the milestone's gsd-path/M00N branch into main directly or opens/reuses a GitHub PR and waits for its user-controlled merge. Path reports shipped only after a two-parent merge and the milestone tag validate. Before any next-milestone files change, the router binds a new gsd-path/M00N at the updated origin/main. STATE.md, REPOSITORY.md, LESSONS.md, next/, and the program artifacts (CHARTER.md, ROADMAP.md, top-level SYNTHESIS.md) remain active project metadata.

Install (summary)

Node 18.17+ for the Node installer; Python 3.9+ for project installs and pipeline helpers. Validates package, backs up existing skills, and rolls back on failure. Always --dry-run first when unsure.

The commands below run from a source checkout. For npm, replace node scripts/install.mjs with npx @opengsd/gsd-path@latest.

node scripts/install.mjs --all --dry-run
node scripts/install.mjs --all
node scripts/install.mjs --claude --cursor
node scripts/install.mjs --all --local
node scripts/install.mjs --all --project /path/to/project
node scripts/install.mjs --update
node scripts/install.mjs --all --update --project /path/to/project   # refresh .gsd-path/; keeps contracts

| Flag | User skills root | Invoke | | --- | --- | --- | | --codex, --zed | ~/.agents/skills | Codex: $path or $gsd-path; Zed: /path or /gsd-path | | --claude | ~/.claude/skills | /path or /gsd-path | | --cursor | ~/.cursor/skills (+ subagent) | /path or /gsd-path | | --grok | ~/.grok/skills | /path or /gsd-path | | --opencode | OpenCode config skills/ | /path or /gsd-path (OpenCode v2 host) | | --copilot | ~/.copilot/skills | /path or /gsd-path | | --qwen | ~/.qwen/skills | /path or /gsd-path | | --antigravity | Antigravity skills dir | /path or /gsd-path | | --kiro | ~/.kiro/skills | /path or /gsd-path | | --kimi | ~/.kimi-code/skills | /path or /gsd-path |

OpenCode stable: ask to load and use the gsd-path skill. gsd-path remains the canonical router name; path is its short menu alias. For a single phase, use $gsd-path-plan in Codex or /gsd-path-plan on slash hosts.

scripts/install.py — Python install, including --local and --update. The Node CLI remains the interactive and npm entry point. See FULL.md and UPDATE.md for --hooks, --hooks-refresh, --local, and host notes.

Optional --hooks with --project — HOOKS.md.

Something off? node scripts/install.mjs --doctor [--project PATH] — read-only health check of installs, guard hooks, and pipeline state.

Agent execution

Define and build orchestrators run in the main task. Researchers, deciders, planners, coders, and reviewers delegate via host-specific adapters. See FULL.md — Agent execution for the authoritative host API table and delegation rules.

platforms/ is installer-only — not user-invoked skills.

Testing

Contributors and CI use one offline gate. See TEST_ENVIRONMENT.md for prerequisites, tiers, fixtures, and troubleshooting.

make install && make verify    # same path as GitHub Actions CI

Repository layout

| Path | Purpose | | --- | --- | | DOCS.md | Documentation hub | | QUICK.md | Quick start | | FULL.md | Full guide | | UPDATE.md | Updating | | HOOKS.md | Guard hooks | | skills/ | Canonical skills and generated aliases declared in the resource manifest | | platforms/ | Host dispatch adapters | | daemon/ | Project monitor, dashboard, and tray apps | | scripts/install.mjs | Installer (npm gsd-path bin) | | scripts/install.py | Python installer | | AGENTS.md | Operating rules (installed to projects) | | WORKFLOW.md | Phase SOP (installed to projects) | | TEST_ENVIRONMENT.md | Local/CI test setup and tiers | | fixtures/ | Sample .project/ pipeline for manual runs | | LICENSE | MIT |