@maestria/prime-agent 0.2.0 → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md
CHANGED
|
@@ -1,91 +1,53 @@
|
|
|
1
1
|
# @maestria/prime-agent
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Maestria's engineering methodology for [Prime Agent](https://github.com/PrimeIntellect-ai/prime-agent), delivered as standard [Agent Skills](https://agentskills.io/specification) (`skills/<name>/SKILL.md`) plus a small, verified Prime/Pi extension for workflow-mode commands.
|
|
4
4
|
|
|
5
|
-
> This package is part of Maestria. See [VISION.md](
|
|
5
|
+
> This package is part of Maestria. See [VISION.md](https://github.com/agustinusnathaniel/maestria/blob/main/VISION.md) for the project vision, motivation, and scope. The skills are **generated** from the canonical directives in `packages/core/agent-directives/` by the [sync pipeline](https://github.com/agustinusnathaniel/maestria/blob/main/CONTRIBUTING.md#3-the-sync-pipeline-core-concept).
|
|
6
6
|
|
|
7
|
-
## Status
|
|
7
|
+
## Status / Support Boundary
|
|
8
8
|
|
|
9
|
-
`Native candidate` -
|
|
9
|
+
`Native candidate` - skills-first delivery plus a verified executable extension subset. Evidence was re-verified on 2026-08-13 against the immutable upstream commit [`7787f07415d843b9a800f6a4720e0c739bd608e5`](https://github.com/PrimeIntellect-ai/prime-agent/tree/7787f07415d843b9a800f6a4720e0c739bd608e5). The generated skills match the documented contract and the compiled extension is 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 are **deferred** (see below). Do not treat this package as a production support promise.
|
|
10
10
|
|
|
11
|
-
##
|
|
11
|
+
## Installation
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
### Agent Skills
|
|
18
|
-
|
|
19
|
-
All skills live under `skills/<name>/SKILL.md` with the required Agent Skills frontmatter (`name` matching the directory, and `description`).
|
|
20
|
-
|
|
21
|
-
#### Specialist roles
|
|
22
|
-
|
|
23
|
-
| Skill | Purpose |
|
|
24
|
-
| ------------ | ------------------------------------------------------------------- |
|
|
25
|
-
| `adventurer` | Codebase reconnaissance - read-only exploration, structured reports |
|
|
26
|
-
| `architect` | Architecture decisions, trade-off analysis, ADRs |
|
|
27
|
-
| `builder` | Focused implementation - atomic tasks, run tests |
|
|
28
|
-
| `diagnose` | Root-cause analysis - 6-step regression tracing |
|
|
29
|
-
| `planner` | Multi-phase implementation plans, success criteria, rollback |
|
|
30
|
-
| `reviewer` | Code review with quality gates - read-only, structured verdicts |
|
|
31
|
-
| `writer` | Documentation - READMEs, API docs, changelogs, ADRs |
|
|
32
|
-
|
|
33
|
-
#### Orchestration and rules
|
|
34
|
-
|
|
35
|
-
| Skill | Purpose |
|
|
36
|
-
| --- | --- |
|
|
37
|
-
| `orchestrator` | Router methodology: direct/focused/full routes, delegation, maker/checker split, mode precedence |
|
|
38
|
-
| `global-rules` | Universal rules contract: floors, delegation, handoff, review, budgets, authorization, commit safety |
|
|
39
|
-
| `handoff` | Inter-specialist handoff contract |
|
|
40
|
-
| `iteration-limits` | Verifiable termination and escalation pattern |
|
|
41
|
-
|
|
42
|
-
#### Workflow modes
|
|
43
|
-
|
|
44
|
-
| Skill | Mode |
|
|
45
|
-
| ------- | ------------------------------------------------------------------------ |
|
|
46
|
-
| `fein` | Full pipeline: recon/design -> implement -> review |
|
|
47
|
-
| `sonar` | Research only: read-only specialist work -> STOP |
|
|
48
|
-
| `blitz` | Fast path: skip optional ceremony; never waive safety or required review |
|
|
49
|
-
|
|
50
|
-
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.
|
|
51
|
-
|
|
52
|
-
### Executable extension (verified subset)
|
|
53
|
-
|
|
54
|
-
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`):
|
|
13
|
+
```bash
|
|
14
|
+
# Preferred: registers the published package with Prime (skills + extension)
|
|
15
|
+
prime-agent package install npm:@maestria/prime-agent
|
|
16
|
+
```
|
|
55
17
|
|
|
56
|
-
|
|
57
|
-
| --- | --- |
|
|
58
|
-
| `/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`) |
|
|
59
|
-
| `/mode-clear` | Clear the active mode and return to neutral routing |
|
|
60
|
-
| `/maestria-status` | Show the current mode and the verified/deferred subset |
|
|
18
|
+
For skills-only installs, point Prime at the package's `skills/` directory in settings, or copy/symlink the skill directories into a project or global skill location. See [INSTALL.md](https://github.com/agustinusnathaniel/maestria/blob/main/packages/prime-agent/INSTALL.md) for all installation and consumption options.
|
|
61
19
|
|
|
62
|
-
|
|
20
|
+
## What It Provides
|
|
63
21
|
|
|
64
|
-
|
|
22
|
+
- **7 specialist skills** - adventurer, architect, builder, diagnose, planner, reviewer, writer.
|
|
23
|
+
- **Orchestration and rules skills** - `orchestrator`, `global-rules`, `handoff`, `iteration-limits`.
|
|
24
|
+
- **Workflow mode skills** - `fein`, `sonar`, `blitz`, loaded on demand by description matching or invoked explicitly as `/skill:fein` etc.
|
|
25
|
+
- **Executable extension** (`dist/extension.mjs`) - `/fein`, `/sonar`, `/blitz`, `/mode-clear`, and `/maestria-status` commands with session-scoped mode state and mode prompt injection via `before_agent_start`, using only the public extension API of the pinned Prime fork.
|
|
65
26
|
|
|
66
|
-
|
|
67
|
-
- **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.
|
|
68
|
-
- **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.
|
|
69
|
-
- **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.
|
|
70
|
-
- **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.
|
|
71
|
-
- **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.
|
|
27
|
+
## Support / Platform Notes
|
|
72
28
|
|
|
73
|
-
|
|
29
|
+
- **Verified subset only:** the extension covers mode commands and mode prompt injection. There is no recursive-subagent dispatch - the pinned fork's `rlm(...)` call has no public JS extension bridge - so "delegate to a specialist" means load the relevant skill and apply its methodology. JSON/RPC headless-mode integration is deferred (ADR-CORE-014).
|
|
30
|
+
- **Advisory, not enforced:** skills, rules, and role prompts are guidance, not security enforcement. Prime has no skill-level tool-denial mechanism, so read-only roles state their role intent without claiming a runtime boundary; the extension performs no tool interception.
|
|
31
|
+
- **Not a sandbox:** Prime executes model-generated Python and project commands with your user permissions. Restrict use to trusted repositories, skills, and instructions.
|
|
32
|
+
- **No filesystem writes:** mode state rides on host session entries; nothing is written to `~/.pi` or `.prime/agent`.
|
|
33
|
+
- **No runtime dependency on pi packages:** the extension consumes the Prime-bundled pi API through the runtime-provided `pi` object; no pi package dependency is declared.
|
|
34
|
+
- The skills are generated from the canonical core directives; the extension is hand-authored. Edit `packages/core/agent-directives/` and re-run the sync pipeline to change skill content - never edit generated files.
|
|
74
35
|
|
|
75
|
-
|
|
36
|
+
## Documentation and Changelog
|
|
76
37
|
|
|
77
|
-
|
|
38
|
+
- [User-facing documentation](https://maestria.sznm.dev/prime-agent/) on the docs site
|
|
39
|
+
- [Installation guide](https://github.com/agustinusnathaniel/maestria/blob/main/packages/prime-agent/INSTALL.md)
|
|
40
|
+
- [Changelog](https://github.com/agustinusnathaniel/maestria/blob/main/packages/prime-agent/CHANGELOG.md)
|
|
78
41
|
|
|
79
42
|
## Development
|
|
80
43
|
|
|
81
44
|
```bash
|
|
82
|
-
pnpm build
|
|
83
|
-
pnpm test
|
|
84
|
-
pnpm validate
|
|
85
|
-
bash scripts/sync-all # regenerate generated skills for all plugins (incl. this one)
|
|
45
|
+
pnpm build # compile dist/extension.mjs
|
|
46
|
+
pnpm test # generated-skill + extension + package tests
|
|
47
|
+
pnpm validate # validate skills/<name>/SKILL.md frontmatter and layout
|
|
86
48
|
```
|
|
87
49
|
|
|
88
|
-
See the [contributing guide](
|
|
50
|
+
See the [contributing guide](https://github.com/agustinusnathaniel/maestria/blob/main/CONTRIBUTING.md) for repository conventions.
|
|
89
51
|
|
|
90
52
|
## License
|
|
91
53
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@maestria/prime-agent",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.1",
|
|
4
4
|
"private": false,
|
|
5
5
|
"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",
|
|
6
6
|
"keywords": [
|
|
@@ -43,6 +43,14 @@ This is the cross-platform behavior contract. It defines outcomes, evidence, saf
|
|
|
43
43
|
- Adjacent findings do not expand the current task automatically. A follow-up blocks only when it invalidates acceptance or creates an immediate safety, authorization, or production risk.
|
|
44
44
|
- Security, authentication, authorization, and permission findings are mandatory stops. Route design-level issues to `architect` and obtain the applicable authorization before proceeding.
|
|
45
45
|
|
|
46
|
+
## Session Continuation and Delivery
|
|
47
|
+
|
|
48
|
+
- **!!! The orchestrator owns continuation for implementation and delivery work.** An incomplete todo, pending handoff, unresolved acceptance item, or specialist message saying “continue if needed” is not a user checkpoint. Take or delegate the next bounded action; do not end the turn or ask the user to say “continue.” Research-only, planning-only, explicitly read-only, and host-blocked work terminates at its requested artifact or exact blocker.
|
|
49
|
+
- A specialist's read-only or no-edit result ends that delegation, not the parent work unit. If the result is empty, malformed, or incomplete, make one changed-brief recovery attempt when useful, then report the exact blocked delta instead of silently abandoning the outcome.
|
|
50
|
+
- Freeze the outcome, acceptance criteria, non-goals, and review budget at the start of the work unit. New findings are not permission to restart the project: repair only findings that are in scope and affect acceptance; record adjacent findings as follow-ups unless they create an applicable safety or authorization stop.
|
|
51
|
+
- Do not reset a review or repair budget by splitting the same outcome into more delegations, changing specialist names, or relabelling the finding. A new scope requires a new outcome and acceptance criteria.
|
|
52
|
+
- For implementation work, continue through validation and the project's normal delivery artifact. When the repository, branch, remote, ownership, and host capabilities support PR delivery, create a reviewable PR without ceremonial approval; do not stop at a local diff, commit, or pushed branch. Research-only, planning-only, explicitly read-only, and host-blocked work terminates at its requested artifact or exact blocker. Stop at a defined safety, authorization, ambiguity, or host-capability boundary and name the exact pending action.
|
|
53
|
+
|
|
46
54
|
## Delegation and Context
|
|
47
55
|
|
|
48
56
|
Supported specialists are `adventurer`, `architect`, `builder`, `diagnose`, `planner`, `reviewer`, and `writer`.
|
|
@@ -15,8 +15,14 @@ description: |-
|
|
|
15
15
|
- Define a verifiable termination condition before looping.
|
|
16
16
|
- Set a practical repair bound, normally three rounds. Extend only when the
|
|
17
17
|
latest attempt shows observable progress; never silently reset the bound.
|
|
18
|
+
- The bound applies to the same user outcome, even when work is split across
|
|
19
|
+
more delegations or specialist types. Start a new bound only after recording
|
|
20
|
+
a genuinely new outcome with new acceptance criteria.
|
|
18
21
|
- Repeated causes, repeated findings, restored diffs, or no new evidence mean
|
|
19
22
|
non-progress. Change strategy or escalate rather than retrying unchanged.
|
|
23
|
+
- Do not broaden the outcome merely because review found adjacent work. Keep
|
|
24
|
+
the accepted slice deliverable and record adjacent findings as follow-ups
|
|
25
|
+
unless they invalidate acceptance or trigger a safety/authorization stop.
|
|
20
26
|
- Stop on safety ambiguity, authorization boundaries, or unresolved review
|
|
21
27
|
blockers. Report: `Tried X, Y, Z. Blocked by [cause]. Need [input] to
|
|
22
28
|
proceed.`
|
|
@@ -102,7 +102,13 @@ Modes are case-insensitive and per-turn unless the platform documents another li
|
|
|
102
102
|
|
|
103
103
|
## Commit and Session Flow
|
|
104
104
|
|
|
105
|
-
For
|
|
105
|
+
For implementation work, own the delivery path: `inspect -> plan -> implement -> validate -> review -> repair -> commit -> push -> PR`.
|
|
106
|
+
|
|
107
|
+
When the repository, branch, remote, ownership, and host capabilities support PR delivery, complete it without ceremonial approval. Do not stop at a local diff, commit, pushed branch, or `PR pending`. Merge, release, and production actions remain separate.
|
|
108
|
+
|
|
109
|
+
The parent session owns continuation until the selected implementation outcome reaches its terminal artifact. Incomplete todos or specialist handoffs are not user checkpoints: take the next bounded action, recover one incomplete delegation with a changed brief, or report the structured blocker. Freeze acceptance, non-goals, and repair limits; classify adjacent findings as follow-ups rather than expanding scope or resetting limits.
|
|
110
|
+
|
|
111
|
+
Research-only, planning-only, explicitly read-only, `sonar`, and host-blocked routes terminate at their requested artifact or exact blocker. Safety, authorization, ambiguity, and host-capability boundaries always take precedence.
|
|
106
112
|
|
|
107
113
|
An explicitly authorized checkpoint may preserve unreviewed work but never authorizes shipping. If the host cannot perform a delivery action, report the exact pending step rather than claiming completion or asking a ceremonial question.
|
|
108
114
|
|