Introduction to Open GSD Core and Pi

Long agent sessions rot. The model contradicts itself, drops constraints you stated clearly, and drifts away from the conventions you set at the start. It degrades quietly — the answers keep arriving confidently while getting worse, and nothing raises an error. A 1M-token window moves that line. It doesn't remove it.

Open GSD is a context engineering discipline with two toolchains behind it. Core drives the coding agent you already run — Claude Code, Codex, Cursor, Copilot and others — through a five-step loop per phase: discuss, plan, execute, verify, ship. Each step catches a failure the one before it cannot. Plans are grouped into dependency waves, every executor starts on a fresh context window reading only its own plan, and everything shared lives in .planning/ as plain markdown on disk. Pi is its own agent runtime, built to run unattended: slices instead of phases, Git worktree isolation so your checkout stays reviewable, SQLite for runtime state with markdown projected out for review, and a flat rate on the Claude plan you already pay for rather than a per-token bill.

The talk covers what each toolchain is for and how to pick between them, how greenfield and brownfield repos enter, what autonomous mode does well and where it should hand control back (the auto trap quadrant), how each feeds learnings back into future work, and why I review from outside Open GSD before shipping a milestone.

For this room specifically: Pi's polyrepo setup needs the repos nested under one parent workspace, which is a different shape from what Nx Polygraph does — Pi coordinates repos you already assembled, Polygraph discovers and relates them for you. And the curated skill catalog has no Nx pack yet. That one is open if anyone wants it.

Slides 1–19 are the talk. Slide 20 onward is an appendix meant for reading rather than presenting: vertical slicing and TDD mode, the code review fixer loop, what Pi commits versus what stays on one machine, the Windows arm64 install failure and the fork that works around it, a Core-to-Pi command reference, polyrepo layout, and the full skill catalog.

No demo. Both installers are one command, and everything else is plain text you can read.

Core: npx @opengsd/gsd-core@latest
Pi: npx @opengsd/gsd-pi@latest — this adds the `gsd` command to your shell

https://docs.opengsd.net · https://github.com/open-gsd · MIT licensed.

Git. Ship. Done.

Presented at the Nx Champions meeting in September 2026.

Transcript

1. Open GSD Git. Ship. Done. Core and Pi, two toolchains for the same discipline Lars Gyrup Brink Nielsen
2. Context rot Open GSD was built for a 200K window. That limit shaped the whole design. Contradicts itself Reverses a decision it agreed to twenty messages ago. Requirements go missing Plans drop constraints you stated clearly early on. This is how attention behaves over a long sequence. Style drifts The conventions you set at the start stop being applied. Signatures drift File names and function signatures it had right before.
3. What 1M changed A bigger window moves the line. It does not remove it. Core reads context_window from config. Set it to 1000000 for a 1M model. config At 500K and above, adaptive context enrichment switches on. context_window: 1000000 smart_zone_tokens: 100000 Executors also get prior wave summaries. Verifiers get every plan. Plans are still split above the smart zone budget. Quality degrades before the advertised window is full, and the real ceiling depends on the model and the task. So you clear less often. You still plan in phases.
4. The phase loop Five steps per phase. Each catches a failure the step before it cannot. Discuss Plan Execute Verify Discuss Settles decisions a planner would otherwise guess. Plan Research, plans, dependency waves, then a plan-checker. Execute Each plan runs in its own fresh context window. Verify Confirms the requirements and decisions were covered. Ship Opens the PR, archives the phase, updates STATE.md. Ship
5. Plans, waves, fresh contexts One plan per unit of work. Waves group the plans by dependency. Wave 1 Plan 01 Plan 02 Wave 2 Plan 04 Plan 05 Wave 3 Plan 06 Plans inside a wave run in parallel. Waves run in order. Every executor starts on a clean window and reads only its own plan. The orchestrator routes and collects. It never opens a source file. Everything shared sits in .planning/ as plain markdown on disk. Plan 03
6. Open GSD Core A context engineering framework that drives the agent you already run. Agent skills you invoke, each spawning its own subagents install npx @opengsd/gsd-core@latest Markdown in .planning/ is the source of truth Heavy work runs in fresh-context subagents Runs on Claude Code · Codex · Cursor Windsurf · Copilot · OpenCode Antigravity · Kimi · Kilo Artifacts survive context resets and restarts 30+ agents 70+ skills into the runtime you already run 40+ capabilities Use the installer. Copying the agents directory by hand breaks it.
7. Getting a project in Greenfield and brownfield enter through different doors. Greenfield Brownfield /gsd-new-project /gsd-onboard Writes PROJECT.md, REQUIREMENTS.md, ROADMAP.md, STATE.md Routes you through the three steps below, then summarises /gsd-map-codebase /gsd-ingest-docs /gsd-new-project 4 mapper agents write .planning/codebase/ optional: existing ADRs, PRDs, SPECs then writes onboarding/SUMMARY.md A complete map is required before new-project, even with --fast. After the first release, /gsd-new-milestone opens each version cycle.
8. Open GSD Pi Its own agent runtime, built to run unattended. Its own runtime A terminal TUI and gsd --web, with routing across providers. Milestones, slices, tasks Slices are the unit auto mode plans, executes and advances. Worktree isolation Work happens in a Git worktree so your checkout stays reviewable. SQLite holds runtime state Markdown in .gsd/ is projected from it for review and for git. Child repos nest inside one project root as a parent workspace.
9. Two loops Core runs a loop per phase. Pi runs one per slice, then reassesses. Core, per phase Pi, per slice Discuss Plan (research inside) Plan Execute each task Execute Complete and commit Verify Reassess the roadmap Ship Next slice Core stops to ask you. Pi folds research in and keeps going. When the slices run out, Pi validates the milestone and closes it.
10. Pi and your Claude plan Pi runs on the Claude subscription you already pay for. Pi drives the claude CLI you are already signed in to, through the Claude Agent SDK. A Pro, Max or Team plan covers the work at its flat rate, with no per-token bill. It checks claude --version and claude auth status, then hands the work over. Prefer pay-per-token? Pi also takes an API key, Bedrock, Vertex or Foundry. GitHub Copilot and cursor-agent are providers too, each with its own sign-in. An unattended milestone run costs nothing beyond your existing plan.
11. Polyrepo setup Pi needs the repos nested. Polygraph finds them for you. Pi parent workspace Nx Polygraph my-product/ |-- .git/ |-- .gsd/ |-- frontend/ | '-- .git/ |-- backend/ | '-- .git/ '-- workers/ '-- .git/ Discovers every repo you can access Infers relations from packages One PR per repo, consumers tested Hosted, and free during early access Run gsd at the project root. You clone the children yourself. GSD registers, verifies and commits them. Sibling layouts are not supported. Nest the repos and run gsd from the parent.
12. Core or Pi Two toolchains. Pick the one that matches how much you want to steer. Core Pi Shape Drives the agent you already run Its own agent runtime Units Milestones and phases Milestones and slices State Markdown is authoritative SQLite, markdown projected Your role In the loop at every step Review at PR boundaries Pi is closer to a software factory. Core keeps you in the loop.
13. Running it unattended Both have an autonomous mode. They hand back control differently. Core Pi /gsd-discuss-phase --analyze /gsd next Adds a trade-off table to each question. Steps one unit of work, then hands back. /gsd-discuss-phase --auto /gsd auto Takes the recommended default everywhere. Plans, executes, commits, reassesses, repeats. /gsd-discuss-phase --chain /gsd stop Chains discuss into plan into execute. Take control back. /gsd steer edits plans mid-run. /gsd pause Core also ships /gsd-autonomous for the remaining phases, /gsd-next to route one step, and /gsd-manager as a dashboard.
14. The auto trap quadrant Rate every gray area on two axes before you let auto mode lock it. Confidence high High impact Auto-lock is fine Low impact Auto-lock is fine Confidence not high Do not auto-decide Record an UNRESOLVED blocker in CONTEXT.md Impact is high when the choice is hard to reverse or freezes a contract. Confidence drops when the pick is a bare default or contradicts research. Auto-lock is fine
15. Review before you ship My recommendation for Core and Pi alike: review from outside Open GSD. /code-review Claude Code's own reviewer, over the diff /thermos Branch audit plus a code-quality pass /pr-review-toolkit:review-pr Several specialist agents over one PR A second toolchain catches what the one that wrote the code will not. Run them per milestone, before the release, whichever toolchain built it. Then clear the findings with /gsd-quick, or /gsd quick on Pi.
16. Cross-unit learnings Both extract learnings from finished work. Only one does it on its own. Core Pi Per phase, and you trigger it Per milestone, and it runs itself Writes LEARNINGS.md per phase Kept in a memories table global_learnings pools it into ~/.gsd/knowledge/ Projected into KNOWLEDGE.md for review Injected into the planner prompt, up to 10 Injected into every unit, ranked by confidence Core sends what it learned to the planner. Pi sends it to every unit.
17. Quick and fast The main loop plans a whole milestone. Small work has its own two skills. /gsd-quick /gsd-fast An ad-hoc task that still gets atomic commits and state tracking. Inline and trivial. No subagents, no planning overhead. add a rate limit to the upload endpoint fix typo in README add .env to gitignore --discuss, --research and --validate compose. --full is all three. Reach for quick instead once research or verification matters. list, status and resume track them. One /gsd-quick task is the right size for clearing a milestone's findings.
18. The wider ecosystem Core and Pi are two of eight surfaces. Three are not released yet. gsd-core stable The phase loop inside your own agent gsd-pi stable Vector graph of code, ADRs and history gsd-path not yet Gated pipeline with handoffs on disk released Rust browser daemon with MCP tools gsd-graph released Works a labelled GitHub issue queue Standalone agent harness and runtime gsd-browser gsd-loop gsd-workbench not yet Desktop and mobile control plane released gsd-cloud Hosted cross-device project state not yet
19. Getting started Both installers are one command. Everything else is plain text you can read. Open GSD Core Open GSD Pi npx @opengsd/gsd-core@latest npx @opengsd/gsd-pi@latest into the runtime you already run adds the gsd command to your shell docs.opengsd.net github.com/open-gsd opengsd.net First command /gsd-new-project for a new repo /gsd-onboard for an existing one MIT licensed. Maintained by the open-gsd community. Git. Ship. Done.
20. Appendix Reference material for afterwards.
21. What the mapper writes Four agents in parallel, seven documents under .planning/codebase/. STACK.md CONVENTIONS.md Language, runtime, framework versions Naming, error handling, code style INTEGRATIONS.md TESTING.md External services and SDK imports Test patterns and configuration ARCHITECTURE.md CONCERNS.md Layering and how the modules relate Technical debt and fragile areas STRUCTURE.md Plans for this repo then follow what CONVENTIONS.md observed, and CONCERNS.md is the one to read before new feature work. Directory layout and entry points new-project adds PROJECT.md, REQUIREMENTS.md, ROADMAP.md and STATE.md. ingest-docs adds INGEST-CONFLICTS.md. onboard adds onboarding/SUMMARY.md.
22. Slicing and TDD mode Vertical slicing is the default now. Horizontal layers are the opt-out. /gsd-plan-phase leads every plan with one production-quality tracer slice. /gsd-plan-phase --no-tracer plans horizontal layers, the old default. /gsd-plan-phase --mvp frames the goal as a user story, emits SKELETON.md. /gsd-plan-phase --tdd starts each behavior-adding task with a failing test. /gsd-plan-phase --mvp --tdd gives slices that go red then green. /gsd-mvp-phase collects the user story, runs a SPIDR check, then calls plan-phase.
23. Code review and the fixer Core runs review inside execute-phase. Pi runs it from a hook you declare. When the code-review capability is active, execute-phase auto-invokes review on the phase's changes. It is advisory. Findings never block the run, and a failure in review never stops execution. Find something and it points you at /gsd-code-review N --fix, where a separate fixer agent commits each fix. --depth quick, standard or deep. --fix --auto loops review and fix up to three times. Pi has no built-in step: declare a post_unit_hooks entry with after execute-task. Pi's hook can force rework: retry_on NEEDS-REWORK.md re-runs the task.
24. Pi state across machines The database never travels. Git carries the projections. Committed Local only PREFERENCES.md gsd.db PROJECT.md STATE.md REQUIREMENTS.md state.json DECISIONS.md metrics.json .gsd/phases/ worktrees/ Sharing gsd.db across machines or over a network share is unsupported. mode: team turns on unique milestone ids, branch pushes and a pre-merge check.
25. gsd init and skills Setup detects your stack and offers matching skill packs. gsd init Fill the gaps yourself Detection is automatic on an existing repo. Greenfield asks you to pick. The catalog is curated, so your stack may want packs it does not carry. Offered for an Nx Angular workspace: Add your own: npx skills add Frontend Design & UX React & Web Frontend Document Handling Re-run gsd init later and choose Suggest and install skills. Commit rules to .agents/skills/ Core's gsd-* skills stay out of Pi
26. Windows arm64 Installing Pi on Windows arm64 fails, and the error names the wrong package. No win32-arm64 build exists for gsd-browser, which is a hard dependency of gsd-pi with a postinstall step. The install aborts there, and the error that surfaces names typebox instead. At runtime gsd-browser is only the preferred engine. Playwright is the fallback. My fork carries 28 patches on tag v1.15.0 and is reached through npm link. Windows path and race fixes, plus auto-mode lease and recovery fixes, carry a milestone end to end. LayZeeDK/open-gsd__gsd-pi, branch LayZeeDK/dev. Each patch is one commit with tests.
27. Command reference The same job, named differently in each toolchain. Core Pi Start a project /gsd-new-project the interactive setup flow Onboard a repo /gsd-onboard /gsd migrate Settle decisions /gsd-discuss-phase /gsd discuss Plan /gsd-plan-phase folded into auto mode Run the work /gsd-execute-phase /gsd auto Step once /gsd-next /gsd next Review /gsd-code-review --fix /gsd code-review --fix Capture learnings /gsd-extract-learnings automatic at closeout Pi puts everything behind one gsd skill. Core ships each step as its own skill.
28. Gates, design and UI Retroactive audits, and the design steps that come before code. Core What it does Pi /gsd-secure-phase Checks threat mitigations reached the code /gsd secure-phase /gsd-validate-phase Audits coverage gaps and writes the tests /gsd validate-phase /gsd-sketch Throwaway HTML mockups, 2 to 3 variants Core only /gsd-ui-phase A UI design contract before any code /gsd ui-phase /gsd-ui-review Six-pillar visual audit of the frontend /gsd ui-review
29. Investigating and shipping Working out what to build, keeping your place, and closing a milestone. Core What it does Pi /gsd-debug Hypothesis testing down to a root cause /gsd debug /gsd-explore Socratic ideation, routed to an artifact Core only /gsd-spike Feasibility experiments with a verdict Core only /gsd-pause-work Saves a handoff when you stop mid-phase /gsd pause /gsd-resume-work Restores context from your last session /gsd resume-work /gsd-audit-milestone Checks the milestone's definition of done /gsd audit-milestone /gsd-complete-milestone Archives the milestone, tags the release Core only /gsd-ship Opens the PR with a generated body /gsd ship Pi's /gsd fast is unrelated to Core's: it toggles the model service tier.