Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions docs/mode-economics.md
Original file line number Diff line number Diff line change
Expand Up @@ -122,7 +122,7 @@ special-token spellings counted as ordinary text.
Coverage: **75 of 75 local `skills/*/SKILL.md` files**.
External `source.md` redirects and harness symlinks are excluded.

Measurement manifest SHA-256: `7c599897a5d9035cf4d0f8dd1977844aeb5cdf73e81a490a15093f4add2c595f`.
Measurement manifest SHA-256: `85d0fe4f7152f2d8e57b5a92ee1b2f23bf4af93606409da954d15db39e095b40`.

| Skill file | Measured tokens | Source SHA-256 (first 16 characters) |
|---|---:|---|
Expand Down Expand Up @@ -188,16 +188,16 @@ Measurement manifest SHA-256: `7c599897a5d9035cf4d0f8dd1977844aeb5cdf73e81a490a1
| [security-model-update](../skills/security-model-update/SKILL.md) | 4,845 | `8aa3f1ae8efc8c19` |
| [security-model-verify](../skills/security-model-verify/SKILL.md) | 5,544 | `9af92dbe2cdcab1c` |
| [security-tracker-stats-dashboard](../skills/security-tracker-stats-dashboard/SKILL.md) | 3,819 | `078bcd7b2771c6a9` |
| [setup](../skills/setup/SKILL.md) | 4,972 | `c961c449fcd539ff` |
| [setup-isolated-setup-doctor](../skills/setup-isolated-setup-doctor/SKILL.md) | 4,897 | `d72e5d3db5478b31` |
| [setup](../skills/setup/SKILL.md) | 4,187 | `006eed3cbc2a8cce` |
| [setup-isolated-setup-doctor](../skills/setup-isolated-setup-doctor/SKILL.md) | 4,720 | `f24d416c966167f7` |
| [setup-isolated-setup-install](../skills/setup-isolated-setup-install/SKILL.md) | 3,879 | `9c7d49c9e7ff947d` |
| [setup-isolated-setup-update](../skills/setup-isolated-setup-update/SKILL.md) | 4,356 | `d931796db4ed4bfa` |
| [setup-isolated-setup-verify](../skills/setup-isolated-setup-verify/SKILL.md) | 4,967 | `2de9c2cd4bf4d24b` |
| [setup-override-upstream](../skills/setup-override-upstream/SKILL.md) | 3,960 | `8ab7b08f5fe58452` |
| [setup-isolated-setup-update](../skills/setup-isolated-setup-update/SKILL.md) | 4,017 | `0ff14e482853f519` |
| [setup-isolated-setup-verify](../skills/setup-isolated-setup-verify/SKILL.md) | 4,556 | `5c50d8fd6d5f0df4` |
| [setup-override-upstream](../skills/setup-override-upstream/SKILL.md) | 3,681 | `968f51a19ccd4d10` |
| [setup-privacy-llm](../skills/setup-privacy-llm/SKILL.md) | 2,055 | `b89f1f5e421df5cc` |
| [setup-shared-config-sync](../skills/setup-shared-config-sync/SKILL.md) | 4,185 | `716c989013526bf0` |
| [setup-shared-config-sync](../skills/setup-shared-config-sync/SKILL.md) | 3,836 | `d8715462e3c23f38` |
| [setup-status](../skills/setup-status/SKILL.md) | 2,321 | `e1c73a7cc0c75001` |
| [setup-upstream-fix](../skills/setup-upstream-fix/SKILL.md) | 4,614 | `3f9a676cd13ad64c` |
| [setup-upstream-fix](../skills/setup-upstream-fix/SKILL.md) | 4,245 | `8b6a749129fdd3fd` |
| [skill-reconciler](../skills/skill-reconciler/SKILL.md) | 4,438 | `d431fd5ba5712980` |
| [workflow-security-audit](../skills/workflow-security-audit/SKILL.md) | 3,177 | `66b5e868e918b76b` |
| [write-skill](../skills/write-skill/SKILL.md) | 2,458 | `a7275014b55d13e0` |
Expand Down
2 changes: 1 addition & 1 deletion docs/setup/marketplace.md
Original file line number Diff line number Diff line change
Expand Up @@ -155,7 +155,7 @@ can say so, because it is the floor everything else is managed from.
| Family plugin | Skills | ~Always-on tokens |
|---|---|---|
| `magpie-security` | 15 | ~2.0k |
| `magpie-setup` | 10 | ~0.8k |
| `magpie-setup` | 10 | ~0.7k |
| `magpie-release-management` | 10 | ~1.3k |
| `magpie-pr-management` | 8 | ~1.0k |
| `magpie-issue` | 8 | ~0.8k |
Expand Down
234 changes: 78 additions & 156 deletions plugins/magpie-setup/skills/isolated-setup-doctor/SKILL.md

Large diffs are not rendered by default.

393 changes: 121 additions & 272 deletions plugins/magpie-setup/skills/isolated-setup-update/SKILL.md

Large diffs are not rendered by default.

418 changes: 127 additions & 291 deletions plugins/magpie-setup/skills/isolated-setup-verify/SKILL.md

Large diffs are not rendered by default.

296 changes: 95 additions & 201 deletions plugins/magpie-setup/skills/override-upstream/SKILL.md

Large diffs are not rendered by default.

293 changes: 95 additions & 198 deletions plugins/magpie-setup/skills/setup/SKILL.md

Large diffs are not rendered by default.

4 changes: 2 additions & 2 deletions plugins/magpie-setup/skills/setup/agents.md
Original file line number Diff line number Diff line change
Expand Up @@ -118,7 +118,7 @@ always wires the `magpie-*` set the same way: canonical in
Every adoption rule is "canonical link, then relays", not
"per-target independent link":

- **`magpie-` prefix** ([`SKILL.md` Golden rule 6](SKILL.md#golden-rules))
- **`magpie-` prefix** ([`snapshot-model.md` Golden rule 6](snapshot-model.md#the-golden-rules-that-bind-only-here))
— unchanged. Every framework skill is `magpie-<skill>` in
*every* active target dir, so it never collides with an
adopter's own skills regardless of agent.
Expand All @@ -135,7 +135,7 @@ Every adoption rule is "canonical link, then relays", not
`goose`, …) gets a per-skill relay `magpie-<n>` →
`../../.agents/skills/magpie-<n>`. See
[`install.md` Step 8](install.md#step-8--wire-up-the-framework-skill-symlinks).
- **Committed bootstrap** ([`SKILL.md` Golden rule 6](SKILL.md#golden-rules))
- **Committed bootstrap** ([`snapshot-model.md` Golden rule 6](snapshot-model.md#the-golden-rules-that-bind-only-here))
— the one committed framework artefact, `magpie-setup`, lives at
the **canonical** `.agents/skills/magpie-setup/` (a committed
copy for adopters; a committed symlink under self-adoption).
Expand Down
6 changes: 3 additions & 3 deletions plugins/magpie-setup/skills/setup/install.md
Original file line number Diff line number Diff line change
Expand Up @@ -527,7 +527,7 @@ How it differs from a remote adoption:
narrow the set.
- **`magpie-setup` is itself a symlink** (→ `../../skills/setup/`),
not a committed copy. The copy-vs-symlink rule of
[`SKILL.md` Golden rule 6](SKILL.md#golden-rules) exists only
[`snapshot-model.md` Golden rule 6](snapshot-model.md#the-golden-rules-that-bind-only-here) exists only
because adopter snapshots disappear on clone; the framework's
own source is always present, so the bootstrap is linked like
every other skill.
Expand Down Expand Up @@ -700,7 +700,7 @@ fetch produced an unexpected layout — surface and stop.

## Step 3b — Reconcile the committed `setup` with the new snapshot + reload in-flight

Per [`SKILL.md` Golden rule 9](SKILL.md#golden-rules), the
Per [`snapshot-model.md` Golden rule 9](snapshot-model.md#the-golden-rules-that-bind-only-here), the
adopter-side committed `setup` skill must match the
snapshot's version before the rest of this run executes —
otherwise we finish adoption against the *old* bootstrap
Expand Down Expand Up @@ -1106,7 +1106,7 @@ outside the framework tree points `$MAGPIE_GUARD_DIRS` at them.
**Symlink entries — one uniform block per active target
([`agents.md`](agents.md)), no per-layout variation.** Every
framework skill is symlinked under the `magpie-` prefix (see
[`SKILL.md` Golden rule 6](SKILL.md#golden-rules)), so a single
[`snapshot-model.md` Golden rule 6](snapshot-model.md#the-golden-rules-that-bind-only-here)), so a single
`magpie-*` glob covers them all in each target dir — no per-family
lines. The canonical target (`.agents/skills/`) and every relay
target (`.claude/skills/`, `.github/skills/`, any present holdout)
Expand Down
18 changes: 18 additions & 0 deletions plugins/magpie-setup/skills/setup/overrides.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,24 @@ mechanism) lives in
[`docs/setup/agentic-overrides.md`](../../../../docs/setup/agentic-overrides.md)
in the framework. This file is the operational helper.

**Golden rule 7 — agentic overrides are read at run-time.**
Every framework skill that supports overrides starts its run
by consulting **two** directories in precedence order (first
hit wins):

1. `.apache-magpie-local/<this-skill>.md` — personal,
gitignored. Per-developer overrides that are never
committed.
2. `.apache-magpie-overrides/<this-skill>.md` — committed,
project-wide. Overrides shared with every contributor.

Both files are plain markdown the agent interprets — no
templating engine, no patch tool. The additive-only guardrail
applies to both: neither may weaken the framework's safety,
confidentiality, or privacy baseline. See
[`docs/setup/agentic-overrides.md`](../../../../docs/setup/agentic-overrides.md)
for the full contract including the lookup protocol.

## Inputs

- `<framework-skill>` — required. The skill name to scaffold
Expand Down
21 changes: 20 additions & 1 deletion plugins/magpie-setup/skills/setup/snapshot-model.md
Original file line number Diff line number Diff line change
Expand Up @@ -118,7 +118,7 @@ Gitignored in the adopter repo:
potentially).
- `<local-lock>` (per-machine state).
- `.apache-magpie-local/` (personal, per-developer override
directory — see Golden rule 7).
directory — see [Golden rule 7](overrides.md)).
- The `magpie-*` symlinks `setup install` creates in every active
target dir — the canonical ones in `.agents/skills/` (they
target the gitignored snapshot) and the relays in
Expand Down Expand Up @@ -156,3 +156,22 @@ maintenance hazard: copies drift from the framework's source-
of-truth, and the drift-detection mechanism (which assumes
the framework version is the one in `<snapshot-dir>`)
silently mis-applies.

**Golden rule 9 — reload `setup` in-flight after a
self-update.** When a sub-action changes or creates the
content of the committed `setup` skill (in practice:
`adopt` recovering an out-of-date bootstrap, or `upgrade`'s
overwrite-from-snapshot step), the agent **re-reads the
modified files of this skill before continuing** the rest of
the current run. Concretely: after the copy lands on disk,
re-load `SKILL.md` and the sub-action file you are
currently executing (and any helper file you have already
opened, such as `agents.md` or `overrides.md`), then
resume from the step after the overwrite. The reload runs as
the **first thing** that happens after the overwrite, before
any further reconciliation, symlink work, or doc updates.
The reason: the snapshot's skill version may have renamed
steps, added new sub-actions, or changed the symlink
contract; finishing the run against the *old* in-memory
copy of the skill would silently mis-apply the new
framework version the project just pinned to.
2 changes: 1 addition & 1 deletion plugins/magpie-setup/skills/setup/upgrade.md
Original file line number Diff line number Diff line change
Expand Up @@ -244,7 +244,7 @@ This step **must run before Steps 5+** so the remainder of
this upgrade executes against the framework version the
project just pinned to, not against the pre-upgrade
bootstrap logic. It implements
[`SKILL.md` Golden rule 9](SKILL.md#golden-rules).
[`snapshot-model.md` Golden rule 9](snapshot-model.md#the-golden-rules-that-bind-only-here).

1. Compute the diff between the canonical committed copy
`.agents/skills/magpie-setup/` and the snapshot's
Expand Down
2 changes: 1 addition & 1 deletion plugins/magpie-setup/skills/setup/verify.md
Original file line number Diff line number Diff line change
Expand Up @@ -362,7 +362,7 @@ snapshot's `.apache-magpie/skills/setup/`.
version, **reloads the skill in-flight** so the rest of
the upgrade run executes against the new bootstrap
content (per
[`SKILL.md` Golden rule 9](SKILL.md#golden-rules)),
[`snapshot-model.md` Golden rule 9](snapshot-model.md#the-golden-rules-that-bind-only-here)),
surfaces local modifications first if any exist, and
lands the change in `git status` for the user to commit.
- **Committed copy is newer than the snapshot** (the
Expand Down
Loading