@maestria/prime-agent 0.1.0

package/INSTALL.md

@@ -0,0 +1,112 @@
+# Installing @maestria/prime-agent
+
+> Status: `Native candidate` - Skills-first delivery plus a verified executable extension subset. The generated skills match the documented Prime Agent Agent Skills contract and the extension (`dist/extension.mjs`) is verified against the pinned Prime fork's public extension API (verified 2026-08-13 against upstream commit `7787f07415d843b9a800f6a4720e0c739bd608e5`), but runtime behavior is **not yet tested end to end** in a live Prime session. Native recursive-subagent (`rlm`) dispatch and JSON/RPC headless-mode integration are deferred and are not part of this package.
+
+## Prerequisites
+
+- **Prime Agent** installed (see Prime's [getting started](https://github.com/PrimeIntellect-ai/prime-agent)).
+- Node.js and pnpm only if contributing to this repository (to regenerate files from the canonical core directives). Prime installs registered packages itself via npm; pnpm is not required to consume this package.
+
+## What gets installed
+
+When Prime loads this package it discovers two resource types from the `pi` manifest key in `package.json`:
+
+- **Skills** (`pi.skills: ["./skills"]`): the 14 Agent Skills (`skills/<name>/SKILL.md`).
+- **Extension** (`pi.extensions: ["./dist/extension.mjs"]`): a compiled Prime/Pi extension that registers the workflow-mode slash commands (`/fein`, `/sonar`, `/blitz`, `/mode-clear`, `/maestria-status`) and injects the active mode's prompt on every agent turn. It covers only this verified subset - there is no recursive-subagent (`rlm`) dispatch and no JSON/RPC headless mode.
+
+The extension has **no runtime dependencies**: it consumes the Prime/Pi extension API exclusively through the `pi` object Prime passes to the extension factory, with type-only local declarations (`src/pi-api.ts` mirroring the pinned fork). Prime bundles the pi packages into its runtime (see Prime's `docs/packages.md`), so nothing extra is installed.
+
+## Install
+
+Prime Agent loads skills from project/global skill directories, package `skills/` directories or `pi.skills` entries, and the `skills` array in settings. It does **not** auto-discover arbitrary installed npm packages from `node_modules`. To make Prime load this package's skills **and extension**, register the package with Prime (Option A) or point Prime at the package's `skills/` directory explicitly (Options B and C - extension requires Option A or a manual `extensions` setting entry pointing at a built `dist/extension.mjs`, see below).
+
+### Option A: register the package with Prime (preferred, required for the extension)
+
+Register the published package with Prime's package mechanism. This records the package in Prime's settings and installs it via npm:
+
+```bash
+prime-agent package install npm:@maestria/prime-agent
+```
+
+- By default the package is recorded in global settings (`~/.prime/agent/settings.json`); add `--local` to record it in project settings (`.prime/agent/settings.json`), which Prime installs automatically at startup.
+- Prime then reads the package's `pi.extensions` and `pi.skills` manifest entries to discover the extension and the skills. Option A is the only documented install path that enables the extension automatically.
+- **The npm package route ships the compiled extension**: `dist/extension.mjs` (and its sourcemap) is built before publishing, so the tarball always contains it and Option A via `npm:@maestria/prime-agent` enables both skills and the extension.
+- `prime-agent package install` also accepts git sources and local paths, so you can consume this package before it is published. **Git/local source installs are skills-only unless the package has been built.** Prime's git installs clone the repository and run `npm install` (frequently with dev dependencies omitted) but do **not** build, so `dist/extension.mjs` is absent and the extension is silently skipped. To get the extension from a source install, build the package first and point Prime at that built package directory:
+  ```bash
+  pnpm --filter @maestria/prime-agent build   # creates packages/prime-agent/dist/extension.mjs
+  prime-agent package install local:/path/to/maestria/packages/prime-agent
+  ```
+- **Installing the monorepo root Git URL (`https://github.com/agustinusnathaniel/maestria.git`) does not target this workspace package**: it clones the monorepo root, whose `package.json` has no `pi` manifest, so Prime discovers no skills or extension from it. Use a packaged release (`npm:@maestria/prime-agent`) or a local built package directory instead. See Prime's [packages documentation](https://github.com/PrimeIntellect-ai/prime-agent/blob/7787f07415d843b9a800f6a4720e0c739bd608e5/packages/coding-agent/docs/packages.md) for the full source syntax.
+
+### Option B: explicit `skills` entry in settings (skills only)
+
+Add the package's skills directory to Prime's settings (`~/.prime/agent/settings.json` for your user, or `.prime/agent/settings.json` in the project):
+
+```json
+{
+  "skills": ["/path/to/node_modules/@maestria/prime-agent/skills"]
+}
+```
+
+This is the explicitly documented settings mechanism ([skills docs](https://github.com/PrimeIntellect-ai/prime-agent/blob/7787f07415d843b9a800f6a4720e0c739bd608e5/packages/coding-agent/docs/skills.md)) and works with a local clone too:
+
+```json
+{
+  "skills": ["/path/to/maestria/packages/prime-agent/skills"]
+}
+```
+
+### Option C: copy or symlink into a skill directory (skills only)
+
+Copy or symlink the skill directories into a project or global skill location, for example:
+
+```bash
+ln -s /path/to/maestria/packages/prime-agent/skills/* ~/.prime/agent/skills/
+```
+
+### Enabling the extension manually (Option B/C users)
+
+If you installed via Option B or C and want the extension too, point the `extensions` setting at the compiled file:
+
+```json
+{
+  "extensions": ["/path/to/node_modules/@maestria/prime-agent/dist/extension.mjs"],
+  "skills": ["/path/to/node_modules/@maestria/prime-agent/skills"]
+}
+```
+
+**The artifact must exist at the configured path.** The npm package tarball includes `dist/extension.mjs` (built before publishing), so the `node_modules` path above works for npm installs. For a source clone the compiled file only exists after building the package (`pnpm --filter @maestria/prime-agent build`); a git install without a build has no `dist/extension.mjs`, and Prime silently skips a missing extension file - the `/fein`-family commands and mode prompt injection will simply not be registered.
+
+(Equivalent to what Option A's package registration configures automatically; the settings `extensions` array is Prime's documented per-user extension list.)
+
+### Dependency installs are setup only
+
+`pnpm add @maestria/prime-agent` (or `npm install`) makes the package available to your own tooling, but Prime does not scan `node_modules`; a dependency install alone does not make Prime discover the package. Use Option A to register the package, or Option B/C to point Prime at its `skills/` directory.
+
+## Verification
+
+1. Start Prime Agent from the repository or project you want it to work in.
+2. Run `/reload` to rediscover new or edited skill metadata and extension registration.
+3. Confirm the skills appear (for example, run `/skill:orchestrator` or ask the agent to load the `global-rules` skill).
+4. Confirm the extension loaded: run `/maestria-status` - it should report the current mode (`none` initially) and the verified/deferred subset. Try `/fein`, `/sonar`, `/blitz` and `/mode-clear`; while a mode is active, the mode prompt is appended to the system prompt on each agent turn, and `/maestria-status` shows the active mode.
+
+> Steps 3-4 are runtime checks that are **not yet verified** in this batch; the package-level gates are `pnpm build` (the extension compiles to the declared `dist/extension.mjs`), `pnpm validate` (frontmatter/layout), and `pnpm test` (generated-skill, extension, package-manifest, and `npm pack --dry-run` tarball-content tests).
+
+## Security
+
+Prime Agent is **not a sandbox**: it executes model-generated Python and project commands with your user permissions. Review skill and extension content before use and restrict usage to trusted repositories, skills, and instructions. The extension performs **no tool interception** and writes no files (no `~/.pi`, no `.prime/agent` writes); mode state rides on host session entries. It does not provide and does not claim recursive-subagent (`rlm`) dispatch or JSON/RPC headless mode.
+
+## Updating generated content
+
+Do not edit `skills/` by hand - it is generated from `packages/core/agent-directives/`. After changing canonical content:
+
+```bash
+scripts/sync-all          # regenerate all platform packages
+scripts/check-sync        # verify everything is in sync
+```
+
+The root pipeline auto-discovers this package via its `sync.config.ts`; there is no package-local `sync` script.
+
+## Uninstall / removal
+
+Remove the registration, settings entry, symlink, or installed package. If you used Option A, unregister it with `prime-agent package remove npm:@maestria/prime-agent`; otherwise removal is simply dropping the settings `skills`/`extensions` entries or symlink that points Prime at the package.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agustinus Nathaniel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# @maestria/prime-agent
+
+A package that encodes the Maestria engineering methodology for [Prime Agent](https://github.com/PrimeIntellect-ai/prime-agent): 7 specialist roles, an orchestrator, the global-rules contract, handoff and iteration-limits aids, and the fein/sonar/blitz workflow modes - delivered as standard [Agent Skills](https://agentskills.io/specification) (`skills/<name>/SKILL.md`), generated from the canonical directives in `packages/core/agent-directives/` - plus a small, verified Prime/Pi extension (`dist/extension.mjs`) for workflow-mode commands and mode prompt injection.
+
+> This package is part of Maestria. See [VISION.md](../../VISION.md) for the project vision, motivation, and scope. Runtime support status and evidence are tracked in [ADR-CORE-014](../../docs/adr/core/ADR-CORE-014-runtime-support-and-adapter-policy.md) and the [runtime support matrix](../../docs/runtime-support-matrix.md).
+
+## Status
+
+`Native candidate` - Skills-first delivery plus a verified executable extension subset. Prime Agent evidence (Agent Skills standard, discovery paths, frontmatter requirements, extension API, execution boundary) was re-verified on 2026-08-13 at the immutable upstream commit [`7787f07415d843b9a800f6a4720e0c739bd608e5`](https://github.com/PrimeIntellect-ai/prime-agent/tree/7787f07415d843b9a800f6a4720e0c739bd608e5). The generated skills match the documented contract, the compiled extension is verified against the pinned fork's public extension API (source inspection) and exercised by tests, but runtime behavior in a live Prime session is **not yet tested end to end**. Native recursive-subagent (`rlm`) dispatch and JSON/RPC headless-mode integration remain **deferred** (see below). Do not treat this package as a production support promise.
+
+## Install
+
+See [INSTALL.md](INSTALL.md) for installation and consumption options.
+
+## What's inside
+
+### Agent Skills
+
+All skills live under `skills/<name>/SKILL.md` with the required Agent Skills frontmatter (`name` matching the directory, and `description`).
+
+#### Specialist roles
+
+| Skill        | Purpose                                                             |
+| ------------ | ------------------------------------------------------------------- |
+| `adventurer` | Codebase reconnaissance - read-only exploration, structured reports |
+| `architect`  | Architecture decisions, trade-off analysis, ADRs                    |
+| `builder`    | Focused implementation - atomic tasks, run tests                    |
+| `diagnose`   | Root-cause analysis - 6-step regression tracing                     |
+| `planner`    | Multi-phase implementation plans, success criteria, rollback        |
+| `reviewer`   | Code review with quality gates - read-only, structured verdicts     |
+| `writer`     | Documentation - READMEs, API docs, changelogs, ADRs                 |
+
+#### Orchestration and rules
+
+| Skill | Purpose |
+| --- | --- |
+| `orchestrator` | Router methodology: direct/focused/full routes, delegation, maker/checker split, mode precedence |
+| `global-rules` | Universal rules contract: floors, delegation, handoff, review, budgets, authorization, commit safety |
+| `handoff` | Inter-specialist handoff contract |
+| `iteration-limits` | Verifiable termination and escalation pattern |
+
+#### Workflow modes
+
+| Skill   | Mode                                                                     |
+| ------- | ------------------------------------------------------------------------ |
+| `fein`  | Full pipeline: recon/design -> implement -> review                       |
+| `sonar` | Research only: read-only specialist work -> STOP                         |
+| `blitz` | Fast path: skip optional ceremony; never waive safety or required review |
+
+Modes are loaded on demand by description matching, or invoked explicitly as `/skill:fein`, `/skill:sonar`, `/skill:blitz` (when skill commands are enabled). The extension commands below activate the same modes for the session.
+
+### Executable extension (verified subset)
+
+The package ships a compiled Prime/Pi extension (`dist/extension.mjs`, declared under `pi.extensions` in `package.json`) that covers a small, verified subset of the public Prime/Pi extension API (pinned fork `7787f074...`, `packages/coding-agent/src/core/extensions/types.ts`):
+
+| Command | Behavior |
+| --- | --- |
+| `/fein`, `/sonar`, `/blitz` | Set the session workflow mode, persist it as a session custom entry, and forward an optional goal argument to the agent (`/fein implement the pipeline`) |
+| `/mode-clear` | Clear the active mode and return to neutral routing |
+| `/maestria-status` | Show the current mode and the verified/deferred subset |
+
+In addition, while a mode is active the extension appends the mode's prompt (loaded from the generated `skills/<mode>/SKILL.md`, so the injected text is exactly the sync-projected mode skill) to the system prompt on every agent turn via the `before_agent_start` event. Mode state is session-scoped (host session custom entries via `pi.appendEntry`), restored on session start/reload/resume/fork and on session-tree navigation, and persists across compaction by design (custom entries are session entries).
+
+## Platform notes and limitations
+
+- **Verified subset only, not native `rlm` dispatch:** the extension covers mode commands and mode prompt injection. There is **no** recursive-subagent dispatch: the pinned fork's `rlm(...)` call is an IPython-side tool with **no public JS extension bridge**, so this package does not and cannot spawn child agents from the extension. "Delegate to a specialist" means load the relevant skill and apply its methodology, not spawn a child agent. JSON/RPC headless-mode integration is likewise deferred (ADR-CORE-014). The `/maestria-status` command states this explicitly.
+- **Advisory, not enforced:** skills, rules, role prompts, and the extension are advisory guidance, not security enforcement. The extension performs **no tool interception** (it does not claim any control over Prime's Python/command execution path). Prime Agent has no skill-level tool-denial mechanism (the Agent Skills `allowed-tools` field is experimental and only pre-approves tools), so the read-only roles (`adventurer`, `planner`, `reviewer`) state their role intent without claiming a runtime boundary.
+- **Not a sandbox:** Prime Agent executes model-generated Python and project commands with your user permissions; worker and kernel processes are lifecycle isolation, not security sandboxing. Restrict use to trusted repositories, skills, and instructions. Review skill and extension content before use.
+- **No filesystem writes:** the extension writes nothing (no `~/.pi`, no `.prime/agent` writes); mode state rides on host session entries. Mode content is read from the package's own generated `skills/` directory.
+- **No runtime dependency on pi packages:** the Prime-compatible fork of `@earendil-works/pi-coding-agent` (`0.7.2`) is not published to npm (the registry carries only the original Pi line), and Prime bundles the pi API into its runtime. The extension consumes the API exclusively through the runtime-provided `pi` object with type-only local declarations (`src/pi-api.ts`, mirroring the pinned fork); the built `dist/extension.mjs` has zero imports of any pi package. Declaring a runtime/peer dependency on an unpublished or mismatched version would be a false claim, so none is declared.
+- **Agent Skills frontmatter:** Prime requires `name` and `description`; unknown frontmatter fields are ignored; skills with a missing description are not loaded; validation is otherwise lenient (warnings). The package ships only the required fields.
+
+## Design
+
+The skills are generated by the core sync pipeline (ADR-CORE-005). Platform-specific derivation - skill names, descriptions, and Prime-specific notes - lives in `sync.config.ts`. The canonical content stays in `packages/core/agent-directives/`; never edit generated output directly. The extension (`src/`) is hand-authored: it is a Prime-local thin extension modeled on `@maestria/pi`'s mode behavior but self-contained (it does not import `@maestria/pi` or `@maestria/shared-pi`), uses only the public extension API, and loads its mode content from the generated skills so there is a single source of truth for mode text.
+
+Every skill is emitted as `skills/<name>/SKILL.md` (directories containing `SKILL.md`) because that is the layout Prime discovers in **all** documented skill locations - project/global `.prime/agent/skills/`, `.agents/skills/`, package `skills/` directories or `pi.skills` entries, and settings `skills` arrays. (Root `.md` files are only discovered in the prime-specific paths and are ignored under `.agents/skills/`, so the directory layout is the safest projection.)
+
+## Development
+
+```bash
+pnpm build            # compile dist/extension.mjs (vp pack)
+pnpm test             # generated-skill + extension + package tests
+pnpm validate         # validate skills/<name>/SKILL.md frontmatter and layout
+bash scripts/sync-all # regenerate generated skills for all plugins (incl. this one)
+```
+
+See the [contributing guide](../../CONTRIBUTING.md) for repository conventions.
+
+## License
+
+MIT

package/dist/extension.mjs

@@ -0,0 +1,4 @@
+import{dirname as e,join as t,resolve as n}from"node:path";import{fileURLToPath as r}from"node:url";import{readFileSync as i}from"node:fs";function a(){return{mode:null}}function o(e){let t=e;return t.type===`custom`&&t.customType===`maestria_mode`}function s(e){if(typeof e!=`object`||!e)return!1;let t=e.mode;return t===null||t===`fein`||t===`sonar`||t===`blitz`}function c(e){if(!Array.isArray(e))return null;for(let t=e.length-1;t>=0;t--){let n=e[t];if(o(n)&&s(n.data))return n.data}return null}function l(e,t){e.appendEntry(`maestria_mode`,{mode:t.mode})}function u(e,t){e.mode=c(t)?.mode??null}const d=[`fein`,`sonar`,`blitz`],f={fein:`[MODE: fein]`,sonar:`[MODE: sonar]`,blitz:`[MODE: blitz]`},p={fein:`Set workflow mode to fein (full pipeline)`,sonar:`Set workflow mode to sonar (research only)`,blitz:`Set workflow mode to blitz (fast path)`},m={};function h(e,n){if(e in m)return m[e];let r=``;try{let a=i(t(n,e,`SKILL.md`),`utf8`),o=a.indexOf(`## MODE:`);if(o===-1)console.warn(`[maestria] prime-agent: mode skill "${e}" has no "## MODE:" heading; mode prompt injection disabled for this mode.`);else{let t=a.slice(o);r=`${f[e]}\n\n${t.replace(/\s+$/,``)}\n`}}catch(t){console.warn(`[maestria] prime-agent: failed to load mode skill "${e}" from ${n}; mode prompt injection disabled for this mode.`,t)}return m[e]=r,r}function g(e,t){return n=>{if(!e.mode)return;let r=h(e.mode,t);if(r)return{systemPrompt:[n.systemPrompt,``,r,``,`The user has set workflow mode to "${e.mode}". Honor this mode throughout the session until it is changed or cleared.`].join(`
+`)}}}function _(e,t){for(let n of d)e.registerCommand(n,{description:p[n],handler:async(r,i)=>{t.mode=n,l(e,t),r.trim()?e.sendUserMessage(r.trim(),{deliverAs:`steer`}):i.ui.notify(`Mode set to ${n}. Describe what you'd like to work on.`)}});e.registerCommand(`mode-clear`,{description:`Clear workflow mode and return to neutral routing`,handler:async(n,r)=>{t.mode=null,l(e,t),r.ui.notify(`Workflow mode cleared. Neutral routing is active.`)}}),e.registerCommand(`maestria-status`,{description:`Show the current maestria workflow mode and extension subset`,handler:async(e,n)=>{let r=[`# Maestria status (prime-agent)`,``,`Workflow mode: ${t.mode??`none`}`,``,`Commands: /fein, /sonar, /blitz, /mode-clear`,``,`This extension covers mode selection and mode prompt injection only.`,`Recursive-subagent (rlm) dispatch and JSON/RPC headless mode are NOT provided by this package.`].join(`
+`);n.ui.setEditorText(r)}})}function v(){return n(e(r(import.meta.url)),`../skills`)}function y(e){let t=a(),n=v();_(e,t),e.on(`before_agent_start`,g(t,n)),e.on(`session_start`,(e,n)=>{u(t,n.sessionManager.getBranch())}),e.on(`session_tree`,(e,n)=>{u(t,n.sessionManager.getBranch())})}export{y as default};
+//# sourceMappingURL=extension.mjs.map

package/dist/extension.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension.mjs","names":[],"sources":["../src/state.ts","../src/modes.ts","../src/extension.ts"],"sourcesContent":["// packages/prime-agent/src/state.ts\n// Minimal session-scoped state for the Prime extension: the active workflow\n// mode (fein/sonar/blitz) or none.\n//\n// State is persisted through the host session API (`pi.appendEntry`) as a\n// `custom` session entry with `customType: \"maestria_mode\"`. Custom entries\n// are session entries: they survive reloads, forks, and compaction, and they\n// are NOT part of LLM context. Restore reads only the current branch\n// (`sessionManager.getBranch()`), never a sibling branch of the session tree,\n// mirroring the @maestria/pi extension's state pattern. No files are written\n// (no `~/.pi`, no `.prime/agent` writes); everything rides on the host session.\n\nimport type { CustomEntry, ExtensionAPI, SessionEntry } from './pi-api.js';\n\n/** Session entry type used to persist the active mode. */\nexport const MODE_STATE_CUSTOM_TYPE = 'maestria_mode';\n\nexport interface MaestriaModeState {\n  /** Active workflow mode, or null when neutral routing is active. */\n  mode: 'fein' | 'sonar' | 'blitz' | null;\n}\n\nexport function createInitialState(): MaestriaModeState {\n  return { mode: null };\n}\n\nfunction isCustomEntry(entry: SessionEntry): entry is CustomEntry & { data?: MaestriaModeState } {\n  // SessionEntryBase.type is a plain string, so a discriminated-union narrowing\n  // on `type` does not apply; cast to read the optional customType.\n  const maybe = entry as SessionEntry & { customType?: string };\n  return maybe.type === 'custom' && maybe.customType === MODE_STATE_CUSTOM_TYPE;\n}\n\nfunction isModeState(value: unknown): value is MaestriaModeState {\n  if (typeof value !== 'object' || value === null) return false;\n  const mode = (value as Record<string, unknown>).mode;\n  return mode === null || mode === 'fein' || mode === 'sonar' || mode === 'blitz';\n}\n\n/**\n * Read the mode state from the current session branch: the most recent\n * `maestria_mode` custom entry wins. Returns null when no entry exists.\n */\nexport function readModeStateFromEntries(\n  entries: SessionEntry[] | null | undefined,\n): MaestriaModeState | null {\n  if (!Array.isArray(entries)) return null;\n  // Entries are returned in tree order; the last matching entry is the most\n  // recently appended one on the current branch.\n  for (let i = entries.length - 1; i >= 0; i--) {\n    const entry = entries[i];\n    if (isCustomEntry(entry) && isModeState(entry.data)) return entry.data;\n  }\n  return null;\n}\n\n/** Persist the current mode as a session custom entry (no LLM context). */\nexport function persistModeState(pi: ExtensionAPI, state: MaestriaModeState): void {\n  pi.appendEntry(MODE_STATE_CUSTOM_TYPE, { mode: state.mode });\n}\n\n/**\n * Restore the mode state from the current session branch into `state`.\n * When the branch has no `maestria_mode` entry, mode resets to null\n * (fail-closed: never inherit a sibling branch's mode).\n */\nexport function restoreModeState(\n  state: MaestriaModeState,\n  entries: SessionEntry[] | null | undefined,\n): void {\n  const persisted = readModeStateFromEntries(entries);\n  state.mode = persisted?.mode ?? null;\n}\n","// packages/prime-agent/src/modes.ts\n// Prime-local implementation of the Maestria workflow modes (fein/sonar/blitz).\n//\n// Behavioral model: the @maestria/pi extension's mode implementation\n// (packages/pi/src/modes.ts + packages/shared/pi/src/modes-core.ts), adapted to\n// the Prime fork's public extension API and to this package's skills-first\n// projection. This module is deliberately self-contained (Prime-local thin\n// extension): it does not import @maestria/pi or @maestria/shared-pi, and it\n// uses only the public ExtensionAPI surface mirrored in ./pi-api.ts.\n//\n// Mode content is NOT duplicated here: it is loaded from the package's\n// generated skills (`skills/<mode>/SKILL.md`, the `## MODE:` section onward),\n// so the extension's injected prompt is exactly the sync-projected mode skill\n// (canonical content lives in packages/core/agent-directives/, ADR-CORE-005).\n\nimport { readFileSync } from 'node:fs';\nimport { join } from 'node:path';\nimport type {\n  BeforeAgentStartEvent,\n  BeforeAgentStartEventResult,\n  ExtensionAPI,\n  ExtensionCommandContext,\n  ExtensionContext,\n} from './pi-api.js';\nimport type { MaestriaModeState } from './state.js';\nimport { persistModeState } from './state.js';\n\nexport const MODE_KEYWORDS = ['fein', 'sonar', 'blitz'] as const;\nexport type ModeKeyword = (typeof MODE_KEYWORDS)[number];\n\n/** Marker line prepended to injected mode content (shared with other Maestria platforms). */\nexport const MODE_MARKERS: Record<ModeKeyword, string> = {\n  fein: '[MODE: fein]',\n  sonar: '[MODE: sonar]',\n  blitz: '[MODE: blitz]',\n};\n\nconst MODE_COMMAND_DESCRIPTIONS: Record<ModeKeyword, string> = {\n  fein: 'Set workflow mode to fein (full pipeline)',\n  sonar: 'Set workflow mode to sonar (research only)',\n  blitz: 'Set workflow mode to blitz (fast path)',\n};\n\n// ---------------------------------------------------------------------------\n// Mode prompt loading (from generated skills)\n// ---------------------------------------------------------------------------\n\nconst _promptCache: Partial<Record<ModeKeyword, string>> = {};\n\n/**\n * Load the mode prompt for a keyword from the package's generated skills\n * directory: `skills/<mode>/SKILL.md`, sliced from the `## MODE:` heading\n * onward, prefixed with the `[MODE: <mode>]` marker. Returns an empty string\n * (and warns) when the skill file is missing or has no mode section, so a\n * packaging mistake degrades to \"no injection\" rather than an extension crash.\n */\nexport function getModePrompt(keyword: ModeKeyword, skillsDir: string): string {\n  if (keyword in _promptCache) return _promptCache[keyword]!;\n\n  let prompt = '';\n  try {\n    const content = readFileSync(join(skillsDir, keyword, 'SKILL.md'), 'utf8');\n    const modeIdx = content.indexOf('## MODE:');\n    if (modeIdx === -1) {\n      // A generated skill without the mode section must not leak the whole\n      // SKILL.md into the system prompt: degrade to \"no injection\" instead.\n      console.warn(\n        `[maestria] prime-agent: mode skill \"${keyword}\" has no \"## MODE:\" heading; ` +\n          `mode prompt injection disabled for this mode.`,\n      );\n    } else {\n      const body = content.slice(modeIdx);\n      prompt = `${MODE_MARKERS[keyword]}\\n\\n${body.replace(/\\s+$/, '')}\\n`;\n    }\n  } catch (error) {\n    console.warn(\n      `[maestria] prime-agent: failed to load mode skill \"${keyword}\" from ${skillsDir}; ` +\n        `mode prompt injection disabled for this mode.`,\n      error,\n    );\n  }\n  _promptCache[keyword] = prompt;\n  return prompt;\n}\n\n// ---------------------------------------------------------------------------\n// before_agent_start mode prompt injection\n// ---------------------------------------------------------------------------\n\n/**\n * Create the `before_agent_start` handler that appends the active mode prompt\n * to the chained system prompt. Returns void when no mode is active (no\n * modification), so Prime's normal prompt assembly stands as-is.\n */\nexport function createModePromptHandler(\n  state: MaestriaModeState,\n  skillsDir: string,\n): (event: BeforeAgentStartEvent, _ctx: ExtensionContext) => BeforeAgentStartEventResult | void {\n  return (event: BeforeAgentStartEvent): BeforeAgentStartEventResult | void => {\n    if (!state.mode) return;\n\n    const modePrompt = getModePrompt(state.mode, skillsDir);\n    if (!modePrompt) return;\n\n    return {\n      systemPrompt: [\n        event.systemPrompt,\n        '',\n        modePrompt,\n        '',\n        `The user has set workflow mode to \"${state.mode}\". Honor this mode throughout the session until it is changed or cleared.`,\n      ].join('\\n'),\n    };\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Commands\n// ---------------------------------------------------------------------------\n\nexport const MODE_CLEAR_COMMAND = 'mode-clear';\nexport const STATUS_COMMAND = 'maestria-status';\n\n/**\n * Install the mode slash commands (`/fein`, `/sonar`, `/blitz`, `/mode-clear`)\n * and the status/help command (`/maestria-status`). Mode selection is persisted\n * as a session custom entry; the prompt is injected on the next agent turn by\n * the `before_agent_start` handler.\n */\nexport function installCommands(pi: ExtensionAPI, state: MaestriaModeState): void {\n  for (const keyword of MODE_KEYWORDS) {\n    pi.registerCommand(keyword, {\n      description: MODE_COMMAND_DESCRIPTIONS[keyword],\n      handler: async (args: string, ctx: ExtensionCommandContext) => {\n        state.mode = keyword;\n        persistModeState(pi, state);\n        // Forward a goal argument (e.g. `/fein implement the pipeline`) so the\n        // injected mode prompt's \"if the user provided a goal, run it now\"\n        // instruction has the goal to act on.\n        if (args.trim()) {\n          pi.sendUserMessage(args.trim(), { deliverAs: 'steer' });\n        } else {\n          ctx.ui.notify(`Mode set to ${keyword}. Describe what you'd like to work on.`);\n        }\n      },\n    });\n  }\n\n  pi.registerCommand(MODE_CLEAR_COMMAND, {\n    description: 'Clear workflow mode and return to neutral routing',\n    handler: async (_args: string, ctx: ExtensionCommandContext) => {\n      state.mode = null;\n      persistModeState(pi, state);\n      ctx.ui.notify('Workflow mode cleared. Neutral routing is active.');\n    },\n  });\n\n  pi.registerCommand(STATUS_COMMAND, {\n    description: 'Show the current maestria workflow mode and extension subset',\n    handler: async (_args: string, ctx: ExtensionCommandContext) => {\n      const mode = state.mode ?? 'none';\n      const summary = [\n        '# Maestria status (prime-agent)',\n        '',\n        `Workflow mode: ${mode}`,\n        '',\n        'Commands: /fein, /sonar, /blitz, /mode-clear',\n        '',\n        'This extension covers mode selection and mode prompt injection only.',\n        'Recursive-subagent (rlm) dispatch and JSON/RPC headless mode are NOT provided by this package.',\n      ].join('\\n');\n      ctx.ui.setEditorText(summary);\n    },\n  });\n}\n","// packages/prime-agent/src/extension.ts\n// Prime Agent extension entry point (default-export factory).\n//\n// Compiled to `dist/extension.mjs` and declared in package.json under\n// `pi.extensions`; Prime loads it with its extension loader (pinned fork\n// 7787f07415d843b9a800f6a4720e0c739bd608e5, loader.ts: a jiti import of the\n// declared path calling the default export with the live ExtensionAPI).\n//\n// Verified subset (public Prime/Pi extension API only, see src/pi-api.ts):\n//   - slash commands /fein /sonar /blitz /mode-clear and /maestria-status\n//   - before_agent_start mode prompt injection (systemPrompt chaining)\n//   - session-scoped mode state via custom session entries, restored on\n//     session_start (reload/resume/fork) and session_tree (branch navigation)\n//\n// NOT provided (explicitly deferred, documented in README/INSTALL/ADR-CORE-014):\n// native recursive-subagent (`rlm`) dispatch - the pinned fork exposes no\n// public JS extension bridge for it (it is an IPython-side tool) - and\n// JSON/RPC headless mode integration. No tool interception is installed and no\n// sandbox/enforcement claim is made. This extension writes no files (no\n// `~/.pi`, no `.prime/agent` writes): state rides on host session entries.\n\nimport { dirname, resolve } from 'node:path';\nimport { fileURLToPath } from 'node:url';\nimport type { ExtensionAPI } from './pi-api.js';\nimport { createInitialState, restoreModeState } from './state.js';\nimport { createModePromptHandler, installCommands } from './modes.js';\n\n/**\n * Resolve the package's generated `skills/` directory. When running from the\n * built `dist/extension.mjs`, this is `<packageRoot>/skills`; when running from\n * source (tests), it is the same package-relative location.\n */\nfunction resolveSkillsDir(): string {\n  const moduleDir = dirname(fileURLToPath(import.meta.url));\n  return resolve(moduleDir, '../skills');\n}\n\nexport default function (pi: ExtensionAPI): void {\n  const state = createInitialState();\n  const skillsDir = resolveSkillsDir();\n\n  // Mode commands + status command (session-scoped state, persisted via\n  // pi.appendEntry custom entries).\n  installCommands(pi, state);\n\n  // Mode prompt injection on the next agent turn.\n  pi.on('before_agent_start', createModePromptHandler(state, skillsDir));\n\n  // Restore the active mode when a session starts, is reloaded, resumed, or\n  // forked, and when navigating the session tree to a different branch.\n  pi.on('session_start', (_event, ctx) => {\n    restoreModeState(state, ctx.sessionManager.getBranch());\n  });\n\n  pi.on('session_tree', (_event, ctx) => {\n    restoreModeState(state, ctx.sessionManager.getBranch());\n  });\n}\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@maestria/prime-agent",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Maestria methodology for Prime Agent - specialist roles, orchestrator, global rules, and workflow modes as Agent Skills, plus a small Prime/Pi extension for mode commands and mode prompt injection",
+  "keywords": [
+    "agent-orchestration",
+    "agents",
+    "coding-agent",
+    "maestria",
+    "pi-package",
+    "prime-agent",
+    "skills"
+  ],
+  "homepage": "https://github.com/agustinusnathaniel/maestria/tree/main/packages/prime-agent#readme",
+  "bugs": {
+    "url": "https://github.com/agustinusnathaniel/maestria/issues"
+  },
+  "license": "MIT",
+  "author": "agustinusnathaniel",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agustinusnathaniel/maestria.git",
+    "directory": "packages/prime-agent"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "INSTALL.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@types/node": "^26",
+    "typescript": "^6.0.3",
+    "vite-plus": "0.2.7",
+    "vitest": "4.1.10"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "pi": {
+    "extensions": [
+      "./dist/extension.mjs"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "scripts": {
+    "build": "vp pack",
+    "test": "vp pack && vp test",
+    "validate": "npm run validate-skills",
+    "validate-skills": "node --experimental-strip-types scripts/validate-skills.ts"
+  }
+}

package/skills/adventurer/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: adventurer
+description: |-
+  Codebase reconnaissance skill. Maps unknown territory -
+  traces call chains, maps module relationships, generates structured recon
+  reports for downstream work. Read-only role intent: exploration and reporting
+  only, never implementation or design.
+  Use for: understanding unfamiliar code, tracing dependencies, gathering context
+  before implementation, investigating module structures.
+---
+
+<!-- Auto-generated from @maestria/core. Do not edit directly.
+     Edit the canonical file at packages/core/agent-directives/ instead. -->
+
+**Read-only role (advisory):** in this skills-first package there is no runtime tool enforcement. The role intent stands: you explore, trace, map, and report; you never implement, design, or edit.
+
+You are a codebase reconnaissance agent.
+
+## Mission
+
+Map unknown territory so downstream specialists (builder, architect, diagnose) can work with full context. You don't implement, design, or debug - you **understand and report**.
+
+Pipeline position: `Explorer → Architect → Builder → Reviewer → [Output]`
+
+## Process
+
+1. **Scope** - Understand what the delegate needs to know
+2. **Explore** - Trace code paths, find key files, map relationships
+3. **Document** - Produce a structured reconnaissance report
+4. **Handoff** - Pass the report cleanly to the next agent
+
+## Exploration Techniques
+
+- **Entry point analysis** - Start from the user-facing API or entry point
+- **Call chain tracing** - Follow function calls from invocation to implementation
+- **Module mapping** - Document relationships between files and modules
+- **Pattern discovery** - Identify conventions, idioms, repeated patterns
+- **Boundary identification** - Find where data crosses module/API boundaries
+- **Dependency tracing** - Map import chains and external dependencies
+
+### Complexity Tiers
+
+| Tier   | Files    | Strategy                                              |
+| ------ | -------- | ----------------------------------------------------- |
+| Small  | <50      | Full exploration, read most files                     |
+| Medium | 50–300   | Targeted exploration, high-value areas                |
+| Large  | 300–1000 | Focused reads only, grep-first approach               |
+| Huge   | >1000    | Sampling strategy, skip generated/test/migration dirs |
+
+Stop when the map answers the downstream specialist's questions. If the evidence remains incomplete, report what was tried, what was not found, and the assumptions that remain.
+
+## Output Format & Handoff
+
+```
+# Reconnaissance Report: [Area]
+
+## Key Files
+- `path/to/file.ts` - Purpose, key exports, role in the system
+
+## Call Chains
+[Entry] → [Middleware] → [Implementation] → [Data Access]
+
+## Data Flow
+[Input] → [Transformation] → [Storage] → [Output]
+
+## Discovery Log
+- **Convention:** Pattern observed
+- **Surprise:** Unexpected behavior or deviation from conventions
+- **Risk:** Potential issue or fragile area identified
+
+## Context for Next Agent
+Specific guidance for the downstream specialist.
+
+## Assumptions
+- `[verified]` Claim confirmed by direct source observation (with evidence)
+- `[inferred]` Best guess from context, not directly confirmed (with rationale)
+```
+
+Your report should let the next agent start work immediately without re-exploring. It includes:
+
+- What was found (with file paths and line numbers)
+- What was NOT found (negative findings save downstream time)
+- What the downstream specialist should focus on first
+
+**If the scoping is unclear or the request is ambiguous, document your scope assumption in the report with rationale and proceed.** Don't ask for clarification - make the best call based on what's given.
+
+## Rules
+
+- **!!! Never edit files** - you are read-only reconnaissance
+- **!!! Never implement solutions** - that's `builder`'s job
+- **!!! Never make design decisions** - that's `architect`'s job
+- **One role per session** - don't mix exploration with building
+- Document negative findings too ("no middleware layer found")
+- Include specific file paths and line numbers in findings
+- For large codebases, use grep-first strategy to avoid token waste
+- **!!! If anything is unclear or ambiguous during reconnaissance, document it as an explicit `[inferred]` assumption with the evidence that led to your interpretation** - downstream specialists need to know where your report relies on inference vs. direct observation.
+- **Parallelization:** adventurer tasks on different modules/areas can run in parallel. Read-only is safe; duplication is wasteful.
+
+## Skill Prescription
+
+### Load on trigger
+
+- `agent-browser` - web app exploration, visual/Electron verification
+- `c4-architecture` - context/container diagrams
+- `domain-modeling` - domain concept mapping
+- `mermaid-diagrams` - sequence, flow, or ER diagrams
+- `resolving-merge-conflicts` - merge conflict investigation
+- `repo exploration tool` - external library internals
+- `session-handoff` - formal handoff artifacts
+
+### Defer to specialist
+
+- `improve-codebase-architecture` -> `architect` - architecture domain, not recon
+
+### Skip if
+
+- The task is a 1-file lookup; no skill load needed
+- The user has not asked for any diagramming output

package/skills/architect/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: architect
+description: |-
+  Architecture decisions using decision matrices and ADRs.
+  Evaluates options with weighted criteria, clarifies business context first.
+  Use for: technology choices, implementation approaches, trade-off analysis,
+  threat modeling, or ADR decisions.
+---
+
+<!-- Auto-generated from @maestria/core. Do not edit directly.
+     Edit the canonical file at packages/core/agent-directives/ instead. -->
+
+You make architecture decisions systematically.
+
+## Phase 1: Understand the Problem
+
+Clarify before options:
+
+- What is the business goal?
+- What are constraints (time, team, budget)?
+- MVP or production? Timeline?
+- Reversible or irreversible decision?
+- What expertise does the team have?
+- What are the guard rails? (what to do / what not to do)
+
+## Phase 2: Present Options
+
+Show 2-4 viable options with comparison:
+
+| Criterion  | Option A | Option B |
+| ---------- | -------- | -------- |
+| MVP Speed  | Fast     | Medium   |
+| Long-term  | Debt     | Clean    |
+| Complexity | Low      | High     |
+
+> **Build vs Buy Check:** where relevant, verify whether a mature open-source solution already exists. List it as an option with its adoption cost (integration effort, maintenance burden, license constraints).
+
+## Phase 3: Gather Sufficient Evidence Before Deciding
+
+Before forming a recommendation, gather enough evidence to distinguish the viable options. Consult each source category only where relevant:
+
+1. **Read the codebase** - existing patterns and precedents
+2. **Check ADRs and docs** - prior architectural constraints
+3. **Check `.maestria/rules.md` and `.maestria/workflow.md`** - project-specific constraints
+4. **Survey open-source solutions** - verify no library already solves this
+
+Stop when the evidence distinguishes the viable options. If relevant evidence is insufficient, make the best decision based on conventions, document every assumption as `[inferred]` with rationale, and proceed.
+
+**Exception - irreversible decisions only:** If the decision affects data migration, production deployment, or security boundaries, use one-shot escalation: present a single recommendation with documented trade-offs and stop.
+
+## Phase 4: Recommend
+
+State recommendation with clear rationale and acknowledged trade-offs.
+
+## Phase 5: Document as ADR
+
+```
+# ADR-XXX: [Title]
+
+## Status
+[Proposed | Accepted | Deprecated]
+
+## Context
+What motivates this decision?
+
+## Decision
+What change is being proposed?
+
+## Consequences
+What becomes easier or harder?
+
+## Assumptions
+- `[verified]` Assumption confirmed by codebase, ADRs, or documentation
+- `[inferred]` Assumption made due to insufficient evidence (with rationale)
+
+## Alternatives Considered
+Options evaluated and why rejected
+
+## Date
+YYYY-MM-DD
+```
+
+## Shortcut Rules
+
+- "I just need something that works" -> MVP-first option
+- "This is for production" -> Production-quality option
+- "I'm prototyping" -> Fastest option
+
+## Handoff
+
+Report the ADR path, recommendation, decision evidence, documented assumptions, validation evidence, and next step.
+
+## Rules & Constraints
+
+- **!!! Read the docs first** - before making recommendations, verify API behavior and library capabilities against official documentation. Don't guess at how a tool works.
+- Don't assume - verify against official docs and references
+- Don't oversimplify - acknowledge trade-offs honestly
+- For irreversible decisions, recommend more conservative options
+- Tag every assumption in the ADR as `[verified]` or `[inferred]`
+- **If the requirements are ambiguous, exhaust available data first, then document your assumption with supporting rationale and proceed** - the ADR should not contain open questions. Every unclear item becomes an explicit assumption with evidence.
+- **Parallelization:** architect tasks on different decisions can run in parallel. Two architects on the same decision = wasted effort. ADR is single-writer.
+
+## Skill Prescription
+
+### Always load
+
+- `architecture-decision-records` - ADR format (Phase 5)
+- `improve` - codebase survey for implementation plans
+
+### Load on trigger
+
+- `api-design-principles` - API/REST/GraphQL design
+- `architecture-decision-framework` - decision matrices, weighted scoring
+- `c4-architecture` - container/component diagrams
+- `codebase-design` - module boundaries, seam placement
+- `domain-modeling` - domain model mapping
+- `draw-io` - `.drawio` output
+- `excalidraw` - `.excalidraw` output
+- `grill-me` - interactive decision alignment
+- `grill-with-docs` - ADR/CONTEXT validation
+- `improve-codebase-architecture` - architecture improvement survey
+- `mermaid-diagrams` - sequence, flow, or ER diagrams

package/skills/blitz/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: blitz
+description: Fast implementation mode - skip optional ceremony for familiar, low-risk work; never waive safety or required review. Load when the user invokes blitz or asks for a fast route.
+---
+
+<!-- Auto-generated from @maestria/core. Do not edit directly.
+     Edit the canonical file at packages/core/agent-directives/ instead. -->
+
+[MODE: blitz]
+
+## MODE: blitz (Fast Implementation)
+
+Use direct execution for familiar, low-risk code or other work when the host permits it; otherwise delegate to the permitted specialist. Skip optional reconnaissance and design ceremony, but never waive safety, authorization, required review, or branch floors. Escalate safety exceptions to the normal route.
+
+Fast implementation mode. Load the `orchestrator` skill if coordination is needed. The `/blitz` extension command also activates this mode for the session (a goal argument is forwarded to the agent; the mode prompt is injected on every turn; clear with `/mode-clear`). If the user provided a goal after invoking `blitz`, implement that goal now.