@garaje/base

The agent-side substrate for the garaje framework, distributed as a pi package.

A garaje runs the pi coding agent against your codebases; @garaje/base is what gives that agent its garaje-specific behavior. It ships:

• the Garaje persona, base rules, and canonical roles (planner / implementer / reviewer / doc-writer),
• the base extensions (preset/role commands, guardrails, protected-paths and command-intent guards that keep the agent from reconfiguring its own container),
• the agent skills — including park (introspect a codebase and wire it into the garaje) and upgrade-bay (re-park after upstream change),
• the generated presets.json and agents/*.md derived from the roles.

How it's consumed

A garaje pins this package declaratively — you don't install or import it by hand. Its .pi/settings.json carries a packages entry, and pi installs and loads the package (read-only) on session start:

{
  "packages": [
    {
      "source": "npm:@garaje/[email protected]",
      "extensions": ["extensions/**", "!extensions/session-name.ts"]
    }
  ]
}

garaje init writes this pin at the CLI's own version, so a fresh garaje is internally consistent by construction, and garaje upgrade bumps it.

Override-only customization

The base installs read-only. A garaje customizes by layering local resources on top — extra rules in .agent/rules/, project presets in .pi/presets.json, local roles in .pi/agents/ — which pi merges over the base at load time, with local entries winning on name collisions. Because lower layers are never edited in place, upgrading the framework is a version-pin bump rather than a merge, and garaje upgrade flags any local override that now shadows or orphans a changed base resource.

Harness portability

@garaje/base is specifically the pi adapter for garaje. The framework's harness seam is deliberately thin: targeting a different agent harness means shipping a different base package, not rewriting the framework. Role and rule content is portable Markdown, so it carries across.

A pi package contributes extensions, prompts, roles, rules, and skills to a session (packages contribute resources, not host settings). Released in lockstep with the garaje CLI.

License

MIT