DOCSEARCHbyAlgolia
Submit Docs

GSD Core

repository·next·Indexed 27 days ago

https://github.com/open-gsd/gsd-core

A meta-prompting, context engineering, and spec-driven development system for AI coding agents. GSD Core prevents context degradation by offloading research, planning, and execution to fresh-context subagents through a structured five-step phase loop. It includes an Embeddable Orchestration Engine (EoS), skill surface budgeting, and a framework for managing Architecture Decision Records (ADRs) and third-party capabilities.

Tokens
202.6K
Snippets
401
Records
1.1K
Agent score
91%

What's inside @opengsd/gsd-core

  1. Overview of the GSD Core phase cycle

    next

    GSD Core operates using a disciplined five-step cycle for every milestone to prevent context rot and maintain high-quality output:

    1. Discuss: Capture implementation decisions before planning.
    2. Plan: Research, decompose, and verify the plan fits within a clean context window.
    3. Execute: Run plans in parallel waves; each executor starts with a clean 200k token context.
    4. Verify: Review what was built, diagnose issues, and correct them before completion.
    5. Ship: Create the PR, archive the phase, and move to the next.

  2. Overview of the GSD Core Phase Loop

    next

    GSD Core operates using a disciplined 5-step phase loop for every milestone to prevent "context decay" (the degradation of AI output quality as the context window fills up). The loop consists of:

    1. Discuss (議論): Record implementation decisions before planning.
    2. Plan (計画): Research and decompose tasks, ensuring the plan fits within a fresh context window.
    3. Execute (実行): Execute the plan in parallel waves. Each executor starts with a clean 200k token context.
    4. Verify (検証): Diagnose and fix the built components to verify them before declaring completion.
    5. Ship (出荷): Create a PR, archive the phase, and proceed to the next phase.

  3. Understand AI Evaluation Core Concepts

    next

    AI systems are non-deterministic, meaning the same input may produce different outputs. Evals are the continuous process of assessing if system behavior meets expectations.

    Key Distinctions:

    • Model vs. Product Evaluation: Model evals (e.g., MMLU) measure general capability. Product evals measure behavior within your specific system, data, and domain rules. Focus 80% of effort on Product evals.
    • The Three Components of an Eval:
      1. Input: Query, history, retrieved docs, system prompt, and config.
      2. Expected: Desired behavior defined via rubrics.
      3. Actual: The system's output, including intermediate steps, tool calls, and reasoning traces.

    Measurement Approaches:

    1. Code-based metrics: Deterministic checks (JSON validation, performance thresholds). Fast and reliable; use these first.
    2. LLM judges: Using one model to evaluate another against a rubric. Best for subjective qualities (tone, reasoning).
    3. Human evaluation: The gold standard for nuance, used for calibration and high-stakes decisions.

  4. Understand the GSD Capability Ecosystem architecture

    next

    GSD Core uses a Capability model where features are organized into folders (capabilities/<id>/capability.json). Each capability declares its skills, agents, lifecycle hooks, federated configuration slices, and loop-extension registrations (such as step, contribution, or gate).

    As of version 1.6.0, the ecosystem supports third-party authoring through a runtime overlay, moving away from a build-time-only registry to a live loading system. This allows third-party capabilities to provide the same executable surfaces as first-party ones, including hooks, MCP servers, and command modules, mediated by a trust and consent gate.

  5. Understand the Multi-Runtime GSD Setup

    next

    GSD Core is designed to work across multiple AI coding runtimes. As of May 2026, the setup involves a single source of truth (the gsd-core repository) which synchronizes workflows, skills, and agents to various local installation paths.

    Key Installation Locations:

    • Core Workflows/Tools: ~/.agents/gsd-core/ (contains gsd-tools.cjs, bin/, etc.)
    • Skills: ~/.agents/skills/gsd-* (core GSD skills)
    • Agents: ~/.agents/agents/ (GSD sub-agents using .md and .toml formats)
    • Claude Code: ~/.claude/skills/, ~/.claude/gsd-core/, and ~/.claude/agents/
    • Grok Build: ~/.grok/skills/ (currently limited to official bundled skills)

    To keep these environments aligned, use the gsd-sync-skills skill located in ~/.agents/skills/gsd-sync-skills/.

  6. Understand GSD Core versioning and stability tiers

    next

    GSD Core follows Semantic Versioning 2.0.0. The stability of a version is communicated via its suffix and its npm tag:

    TierVersion Formatnpm tagStability Description
    Patch1.27.1latestBug fixes only
    Minor1.28.0-rc.1nextFixes + enhancements (Release Candidate)
    Major2.0.0-beta.1nextBreaking changes + features (Beta)

    Semver Increment Rules:

    • PATCH (1.27.x): Bug fixes, typo corrections, or test additions.
    • MINOR (1.x.0): Non-breaking enhancements, new commands, or new runtime support.
    • MAJOR (x.0.0): Breaking changes to config formats, CLI flags, runtime APIs, or features that alter existing behavior.

  7. Understand the GSD Core directory layout

    next

    GSD Core uses a .planning/ directory as a shared memory for projects. This directory contains root-level artifacts for project identity and configuration, as well as phase-specific directories that track the lifecycle of implementation.

    Key directory structures include:

    • .planning/: Contains root artifacts like PROJECT.md, ROADMAP.md, REQUIREMENTS.md, STATE.md, and config.json.
    • .planning/phases/<NN>-<slug>/: Contains artifacts for a specific phase, such as CONTEXT.md, RESEARCH.md, PLAN.md, and VERIFICATION.md.
    • .planning/onboarding/: Contains SUMMARY.md for brownfield projects.
    • .planning/intel/: Contains a queryable symbol index (if intel.enabled is set).
    • .planning/codebase/: Contains maps like architecture.md and stack.md.

  8. Understand Whole-Set Composition Failure Fallback

    next

    If the entire set of overlays fails to compose (e.g., due to a topological cycle or format mismatch during buildRegistry), GSD performs an uncompromising fallback to ensure system stability:

    • Discard Overlays: Every overlay is discarded.
    • First-Party Fallback: The system returns the frozen first-party registry.
    • Command Root Clearing: Every accepted overlay's command root is cleared to prevent the runtime dispatcher from attempting to require() modules from dropped overlays.
    • Gate Visibility: Even though the overlays are dropped, their gates are recorded as blocked. This ensures that missing gates still surface loud warnings via stderr and the JSON envelope warnings array, rather than vanishing silently.

  9. Understand the GSD Capability Ecosystem

    next

    GSD Core operates as a platform where capabilities (features/modules) can be authored and distributed independently of the core maintainers. This ecosystem allows for third-party authoring, versioned manifests, and decentralized distribution via URL imports.

    Key Ecosystem Concepts:

    • Third-party Authoring: Authors can ship capabilities independently. Users can install, upgrade, or remove them without requiring maintainer PRs.
    • Versioned Manifests: Capabilities use versioned manifests to provide a formal version surface and make compatibility explicit.
    • Decentralized Distribution: Capabilities can be imported via URLs or Git, avoiding the need for a centralized registry during initial distribution.
    • Runtime Overlay & Ledger: A runtime registry overlay and a capability ledger ensure that installations are reversible and crash-safe. This allows for granular removal of specific capabilities rather than relying on a whole-product --uninstall command.

  10. Understand the Emitted-Artifact Attribution system

    next

    The emitted-artifact attribution system replaces committed parity fixtures with a computed conservation law to manage derived files (artifacts). This system ensures that changes to source files and their corresponding emitted files are tracked via provenance rules rather than manual regeneration.

    Key behaviors:

    • Zero manual regeneration: Editing a copied shipped file (e.g., gsd-core/workflows/*.md) requires no manual fixture regeneration; the parity gate validates the change automatically.
    • Provenance Guard: Every emitted path across all 19 runtime manifests must match exactly one provenance rule. If a rule is removed or a path is unmatched, a totality guard fails and names the unmatched paths.
    • Simulated Ripple Detection: If an unrelated emitted file is corrupted, the system fails and identifies the unattributable paths.
    • Converter Changes: Changes to a converter require a committed acknowledgment entry to pass.
    • Size Ratchet: Growth in a workflow or agent file is reported with its exact byte delta and requires an acknowledgment entry to pass.

  11. Understand the GSD Core File System Layout

    next

    GSD Core uses a dual-layer file system structure: Installation Files (managed by the runtime) and Project Files (managed within your repository via the .planning/ directory).

    Installation Files

    These files are stored in the runtime's configuration directory (e.g., ~/.claude/ for Claude Code or ~/.cursor/ for Cursor) and include:

    • skills/: Concrete skills for the agent.
    • commands/: Slash commands (used by local Claude installs).
    • gsd-core/: Core logic including bin/gsd-tools.cjs, workflows, references, and templates.
    • agents/: Agent definitions.
    • hooks/: Node.js (.js) and Shell (.sh) hooks for status lines, guards, and monitors.
    • settings.json: Hook registrations.

    Project Files (.planning/)

    This directory acts as the 'living memory' of your project and should be committed to your repository. Key files include:

    • PROJECT.md: Vision, constraints, and evolution rules.
    • REQUIREMENTS.md: Scoped requirements.
    • STATE.md: Current position, decisions, and blockers.
    • config.json: Workflow configuration.
    • research/: Domain research (Stack, Features, Architecture, etc.).
    • codebase/: Mapping of the existing codebase.
    • phases/: Execution artifacts for specific phases (Context, Research, Plan, Summary, etc.).
    • threads/: Persistent context threads.
    • debug/: Active and resolved debug sessions.

  12. Understand GSD as an Embeddable Orchestration Engine

    next

    GSD is designed to function as an embeddable orchestration engine rather than just a collection of tools. It manages the core execution loop, which includes dispatching tasks, managing hooks, handling the model, and maintaining state.

    To integrate GSD into a host environment, developers interact with six irreducible interface points:

    1. Integration Surface: How the host connects to GSD.
    2. Command Surface: The interface for triggering actions (e.g., slash commands, CLI flags, or prose).
    3. Dispatch: How tasks are routed and nested (e.g., nested foreground/background tasks).
    4. Model: How the LLM is managed (active vs. passive).
    5. Hook Bus: The event system for intercepting engine lifecycle events.
    6. MCP (Model Context Protocol): The transport layer for capabilities.
    7. Runtime: The execution environment (e.g., Node.js, Bun, or sandboxed web).