Spec: g-stack, a harness-neutral skill layer

Start by reading the checkpoint 1 implementation decisions and the user stories to understand the initial scope; the issue does not name source files, tests, or entry points. Map the specified CLI, harness adapters, content, model configuration, and checks to the repository before choosing a bounded part. Done means the selected checkpoint 1 requirements are implemented and verified; later checkpoints are explicitly deferred.

Problem Statement

I want one set of agent workflows (explain how something works, investigate why something happened, plan, reflect on a session) that I can use in whichever coding harness I'm in. Today I mostly use Claude Code, but I want to move towards lean harnesses like pi.

The workflow packs I've studied are tied to one harness. They assume that harness's subagent tool, its model list, its config files, its transcript format and its way of injecting instructions. Porting one means rewriting it. They also tend to:

• Put rules in prose. They pack "you must never…" rules into a large router prompt that every subagent re-reads, so they cost a lot and still can't enforce anything.
• Need hand-wiring to use other model families. Running subagents on a different model family (for example a reviewer that isn't from the same family as the writer) only works where the harness happens to allow any model. Elsewhere it needs custom work.

Lean harnesses make this worse: pi has no built-in subagents. A workflow that fans out to explorers or investigators has nothing to call.

Solution

g-stack is a harness-neutral skill layer, made of two parts:

1. Markdown content written once against a small contract of verbs (spawn, todo, ask, wake, transcript). It contains:
   • a slim router (the single entry point, /g)
   • playbooks
   • workflow skills
   • subagent role briefs
   • principles that are loaded only on demand
2. A small gstack CLI that does what markdown can't:
   • install the content into a given harness
   • run a subagent on any supported agent CLI and model, returning a fixed-format report
   • resolve which model each role uses
   • check that the content is consistent

Per-harness adapters (Claude Code and pi first) describe how each verb maps to that harness, and provide whatever glue the harness lacks. For pi, that glue is an extension that exposes a spawn tool backed by gstack spawn.

From my side, the experience is:

• Run gstack install --harness pi (or claude-code).
• Type /g <task>.
• The workflow picks a playbook, turns it into a todo list, and fans out to subagents on whichever models my config names, including models from other families.
• It comes back with a synthesis whose claims are labelled measured, inferred or guess.

g-stack shapes intent. It does not enforce rules. A rule that must always hold belongs in enforcement tooling (hooks, checks, CI), not in g-stack's prose.

User Stories

Installing

1. As a developer, I want to run one install command per harness, so that I don't have to wire skills, commands and config by hand.
2. As a developer, I want to install for Claude Code, so that /g works in my current main harness.
3. As a developer, I want to install for pi, so that /g works in the lean harness I'm moving towards.
4. As a developer, I want to choose between a user-level install and a project-level install, so that I can use g-stack everywhere or only in one repo.
5. As a developer, I want a dry run that lists every file it would write, so that I can see what will change before anything does.
6. As a developer, I want installing twice to change nothing the second time, so that I can re-run install safely after upgrading.
7. As a developer, I want a re-install to update files g-stack owns and leave my own files alone, so that upgrading never destroys my edits elsewhere.
8. As a developer, I want install to tell me clearly when the harness I named isn't supported, so that I don't end up with a half-installed pack.
9. As a developer, I want install to print a short summary of what was written and where, so that I know where to look if something misbehaves.
10. As a developer, I want machine-readable install output as an option, so that I can script it.

Using the router

11. As a developer, I want a single entry point (/g), so that I don't have to remember which of many skills to call.
12. As a developer, I want the router to pick the playbook that fits my request, so that the right workflow runs without my choosing it.
13. As a developer, I want the chosen playbook's steps copied into my todo list, so that I can see the whole plan and track its progress.
14. As a developer, I want a skipped step to stay visible with its reason, so that skipping is a decision I can see rather than something silently dropped.
15. As a developer, I want the router kept small, so that it costs little context in harnesses with small system prompts.
16. As a developer, I want only the router to be discoverable by the model, so that every other skill's description doesn't use up context on every turn.
17. As a developer, I want principles loaded only when a playbook step calls for them, so that I pay for guidance only when it's relevant.

Playbooks (checkpoint 1)

18. As a developer, I want an "explain" playbook, so that I can ask how a part of a codebase works and get an answer grounded in the code.
19. As a developer, I want an "investigate" playbook, so that I can ask why something happened and get evidence from each available source.
20. As a developer, I want a "build" playbook, so that a change is planned, made and checked in a consistent order.
21. As a developer, I want each playbook step to have a stable id, so that todo items, logs and later reflection can refer to the same step.

Workflow skills

22. As a developer, I want the "how" skill to fan out to read-only explorers and then hand their findings to a synthesizer, so that explanations cover more ground than one context can.
23. As a developer, I want the "why" skill to run one investigator per evidence source and then synthesize, so that each line of evidence is examined on its own before being weighed.
24. As a developer, I want synthesized answers to label each claim as measured, inferred or guess, so that I know how much to trust each one.
25. As a developer, I want measured claims to name what was run or read, so that I can reproduce them.

Roles and briefs

26. As a developer, I want each subagent to receive a self-contained role brief rather than the whole router, so that subagent context stays small and fixed.
27. As a developer, I want every brief to follow one template (goal, scope, context, acceptance, report, plus optional timebox and forbidden actions), so that subagents get the same kind of instructions every time.
28. As a developer, I want explorer and synthesizer roles in the first version, so that the "how" and "why" workflows can run.
29. As a developer, I want a role to state what kind of report it must return, so that the synthesizer gets inputs it can combine.

Spawning subagents

30. As a developer, I want gstack spawn to run a role with a brief on a named backend and model, so that any harness can fan out to subagents, including ones with no built-in subagent tool.
31. As a developer, I want backends for claude -p and pi -p in the first version, so that subagents can run on Claude Code or pi.
32. As a developer, I want to run a subagent on a different model family from the one I'm chatting with, so that judgment roles get a different perspective from the one that produced the work.
33. As a developer, I want spawn to return a report in one fixed format, so that workflows can read results without caring which backend produced them.
34. As a developer, I want spawn to enforce a timeout, so that a stuck subagent can't stall a workflow forever.
35. As a developer, I want distinct exit codes for "the subagent ran but failed or timed out" and "the invocation or config was wrong", so that a workflow can decide whether to retry or to stop and tell me.
36. As a developer, I want a clear error when the requested backend's CLI isn't installed, so that I know what to install instead of seeing a confusing failure.
37. As a developer, I want spawn to pass the role brief and task brief to the backend without changing them, so that what the subagent sees is exactly what the files say.
38. As a developer, I want Claude Code to use its native subagent tool when the role's model is a Claude model, so that I don't pay for an extra process when the native tool can do the job.

Model configuration

39. As a developer, I want g-stack to work with no config at all, so that the first run doesn't need setup.
40. As a developer, I want a user-level config that maps roles to a backend and model, so that I set my preferences once.
41. As a developer, I want a repo-level config that overrides the user config, so that a project can use different models.
42. As a developer, I want gstack models get <role> to print the resolved backend and model, so that skills read config through the CLI instead of parsing prose rules.
43. As a developer, I want a model value that means "use the backend's own default", so that I don't have to name a model I don't care about.
44. As a developer, I want a clear error that names the file and the field when config is invalid, so that I can fix it quickly.

Verb contract and adapters

45. As a skill author, I want one document that defines every verb a skill may use, so that I write skills once for all harnesses.
46. As a skill author, I want each adapter to document how each verb maps to its harness, so that I know how a skill will behave there.
47. As a skill author, I want each adapter to say what a skill should do when its harness lacks a verb, so that skills degrade in a known way instead of failing silently.
48. As a pi user, I want a pi extension that exposes a spawn tool backed by gstack spawn, so that fan-out workflows work in pi.
49. As a pi user, I want /g registered as a command in pi, so that I start workflows the same way as in Claude Code.

Content checks

50. As a skill author, I want gstack check to confirm that every file the router, playbooks and skills refer to exists, so that a renamed file can't break a workflow unnoticed.
51. As a skill author, I want gstack check to flag core content that names a specific harness or uses a verb outside the contract, so that the core stays harness-neutral.
52. As a skill author, I want gstack check to confirm that every role has the sections the brief template requires, so that subagents always get complete instructions.
53. As a skill author, I want gstack check to report the router's size, so that I notice when it grows beyond its budget.

Later checkpoints

54. As a developer, I want a "reflect" skill that reviews a past session and proposes lessons, so that mistakes become changes to playbooks, principles or enforcement tooling.
55. As a developer, I want reflect to read Claude Code and pi transcripts through one normalised format, so that it works the same in either harness.
56. As a developer, I want each lesson reflect proposes to be filed as an issue for a human to decide on, so that no lesson changes the system without my approval.
57. As a developer, I want a decision log command that appends one row per decision (time, step, decision, reason, evidence, result), so that I can see later why a workflow did what it did.
58. As a developer, I want more backends (for example codex exec and opencode run), so that I can use more model families.
59. As a developer, I want the "architect" and "interrogate" skills, so that design and requirements work run through the same structure.
60. As a developer, I want the wake verb mapped for each harness, with a documented fallback where none exists, so that long-running workflows can resume.

Implementation Decisions

Checkpoints

Checkpoint 1 (the smallest useful first version) delivers:

• the verb contract document
• the router with three playbooks: explain, investigate and build
• the "how" and "why" skills
• the explorer and synthesizer roles
• gstack install for claude-code and pi
• gstack spawn with claude -p and pi -p backends and the fixed report format
• gstack models with built-in defaults
• gstack check
• the pi extension (the spawn tool and the /g command)
• the Claude Code adapter

Done when: one cross-family how/why workflow runs end to end on both Claude Code and pi.

Checkpoint 2 adds:

• the "reflect" skill
• a transcript normaliser for Claude Code and pi session files
• a command that files lessons as issues labelled for human decision
• the decision log command

Checkpoint 3 adds:

• the codex exec and opencode run backends
• the architect and interrogate skills
• the principles library
• a wake mapping per harness

Modules

• Core content is harness-neutral markdown: the router, playbooks, skills, roles, principles and the verb contract.
  • Core content never names a harness.
  • Skills use only contract verbs.
  • Playbook steps carry stable ids.
  • Skills follow the agent-skills SKILL.md convention with name and description frontmatter.
  • Only the router is discoverable. Every other skill is reached by relative path and marked so the harness doesn't advertise it to the model, where the harness supports that.
• Adapters, one per harness, each containing:
  • a verb-mapping document
  • an install map that says where each kind of content goes for user and project installs
  • any glue code that harness needs (pi: an extension; Claude Code: none required, with an optional session-start hook)
• The gstack CLI (TypeScript, Node, ESM) with these commands:
  • install:
    • Options: --harness, --user or --project, --dry-run, --json.
    • Running it twice changes nothing.
    • It writes only files g-stack owns, and records which those are so a re-install can update them.
  • spawn:
    • Options: --role, --brief (a file), and optional --backend, --model and --timeout.
    • Without overrides, backend and model come from model resolution.
    • It builds the subagent's input from the role brief followed by the task brief, runs the backend's CLI headlessly, and prints a report.
  • models get <role>:
    • It prints the resolved backend and model.
    • It also has a JSON output option.
  • check:
    • It validates content integrity: references resolve, core is harness-neutral, and roles contain the required brief sections.
    • It reports the router's size.
• Backends sit behind one internal interface: build the command line from role, brief and model; run it with a timeout; turn stdout and the exit status into a report. Adding a backend means adding one implementation of this interface.

Contracts

• Verbs:
  • spawn(role, brief, model?)
  • todo(steps)
  • ask(question)
  • wake(after) (mapped in checkpoint 3)
  • transcript(session) (mapped in checkpoint 2)
• Brief template sections:
  • required: GOAL, SCOPE, CONTEXT, ACCEPTANCE and REPORT
  • optional: TIMEBOX and FORBIDDEN
• Spawn report (JSON on stdout) has these fields:
  • status: ok, failed or timeout
  • role
  • backend
  • model
  • durationMs
  • output: the subagent's final answer as text
• Spawn exit codes:
  • 0: the subagent finished.
  • 1: the subagent ran but failed or timed out. A report is still printed.
  • 2: the invocation or config was wrong, or the backend CLI is missing. No subagent ran, and the error goes to stderr.
• Model resolution: built-in defaults, overridden by user config in g-stack's home directory, overridden by repo config at the project root.
  • Each role resolves to a backend and a model.
  • The model value default means the CLI passes no model flag, so the backend uses its own default.
  • The built-in default backend is the first of pi, then claude, found on PATH.
  • The g-stack home directory can be overridden by an environment variable so that tests can isolate it.
• Claude Code mapping: spawn uses the native subagent tool when the resolved model is a Claude model, and gstack spawn otherwise.
• pi mapping: spawn uses the extension's tool, which calls gstack spawn.

Architecture

• g-stack has no runtime dependency on any other agent tooling. Enforcement tooling may consume its outputs (for example the evidence labels) through files and conventions only.
• No enforcement prose goes in core content. A rule that must always hold belongs in enforcement tooling, not in the router.

Testing Decisions

• One seam: the gstack CLI boundary. Each test calls the CLI with:

  • argv
  • a temporary home directory (set through the override variable) and a temporary project directory
  • a PATH holding fake harness binaries

  Then it checks the exit code, stdout, stderr and the files left behind. No test reaches into internal modules.

• A good test describes behaviour I'd notice as a user, such as:

  • "install twice writes nothing the second time"
  • "spawn with a missing backend exits 2 and names the CLI to install"
  • "repo config overrides user config"

  It should not describe how the code is organised. Refactors that keep behaviour shouldn't break tests.

• Fake backends are small claude and pi executables placed on PATH for each test. They record the arguments and stdin they received, and they can be told to print a canned answer, fail, or hang (to exercise timeouts).

• What's covered:

  • install:
    • files land in each harness's expected locations for user and project installs
    • running it twice changes nothing
    • a dry run writes nothing
    • an unsupported harness is rejected
    • re-installing leaves user files alone
  • spawn:
    • the right backend is chosen
    • the role brief and task brief reach the backend unchanged
    • the report format is correct for ok, failed and timeout
    • exit codes are correct
    • a missing backend gives a clear error
  • models get:
    • defaults with no config
    • user config overriding defaults
    • repo config overriding user config
    • default passes no model flag
    • invalid config errors name the file and field
  • check:
    • it passes on the shipped content
    • it fails on a broken reference, a harness name in core content, or a role missing a required section

• The pi extension is a thin wrapper over gstack spawn and gets no automated test of its own. Checkpoint 1 includes a manual smoke test in a real pi session: /g starts the router and a fan-out step reaches gstack spawn.

• Prior art: none in this repo yet. The model to follow is CLI-boundary testing with an in-process runner and fake collaborators injected through the environment (PATH and home directory).

Out of Scope

• Enforcement. g-stack doesn't block tool calls, gate stops, merge code or change ticket state. That belongs to separate enforcement tooling.
• Parallel swarms and multi-worker orchestration with coordinators, inboxes or stacking.
• Cloud or remote sandboxes for subagents.
• A Cursor adapter and adapters for harnesses other than Claude Code and pi (later, through the same adapter shape).
• A wake or loop daemon. Checkpoint 3 maps wake to what each harness already offers, and documents a fallback where none exists.
• An MCP server, a GUI and hosted services.
• Choosing models automatically by cost or quality. Model choice is config only.

Further Notes

• Design origin. The design comes from analysing Cursor's pstack plugin. It keeps pstack's useful structure:

  • a single router
  • playbooks copied into the todo list
  • a closed skill graph
  • role briefs
  • evidence labels

  It drops what tied pstack to one harness or cost too much: a 20KB router that every subagent re-reads, enforcement written as prose, and model routing that depended on one harness accepting any model slug.

• Unverified pi details. Where pi expects skill files, and how its extension API registers a tool and a command, haven't been checked yet. Confirm both against pi's current documentation before building the pi adapter. If pi can't register a command, the fallback is a prompt template or a documented first message.

• The cross-family point. Being able to give judgment roles (synthesizer, later reviewer) a different model family from the one doing the work is the main reason gstack spawn exists. It should stay simple to configure.