git:20260922.5a5e1d6 to git:20260922.f3a2ba1

---

# SPDX-License-Identifier: Apache-2.0

# https://www.apache.org/licenses/LICENSE-2.0

name: magpie-setup-status

family: setup

mode: Meta

capability:

- capability:stats

- capability:platform

surface_hash: sha256:85dfb8b48739fc11

license: Apache-2.0

---

<!-- SPDX-License-Identifier: Apache-2.0

https://www.apache.org/licenses/LICENSE-2.0 -->

<!-- Placeholder convention (see ../../AGENTS.md#placeholder-convention-used-in-skill-files):

<project-config> → adopter's `.apache-magpie-overrides/` directory

<snapshot-dir> → `.apache-magpie/` (gitignored snapshot of the framework)

<committed-lock> → `.apache-magpie.lock` (committed — the project's pin)

<local-lock> → `.apache-magpie.local.lock` (gitignored — per-machine record)

<upstream> → adopter's public source repo (the repo this skill runs in) -->

# setup-status

Render a one-glance picture of **how apache-magpie is adopted in

this repo**, then let the user reconfigure it without leaving the

view. The dashboard answers the questions an operator actually

asks: *which install method and version are pinned, has the

snapshot drifted, which agent targets are wired, which skill

families are installed, and are the symlinks healthy.*

This skill is the **configuration** view of adoption. It is read-

only on its own; every change it offers is carried out by

delegating to [`setup`](../setup/SKILL.md) — the one skill

that owns adoption mutation. For a **deep integrity / health

check** (lock parsing, per-check ✓/✗ matrix, permission-hygiene

audit, ASF comdev MCP prerequisites, stale-worktree sweep), use

[`setup verify`](../setup/verify.md); this skill links to

it rather than duplicating its checks.

---

## Adopter overrides

Before running the default behaviour documented below, this skill

consults (in order, first hit wins):

1. `.apache-magpie-local/setup-status.md` — personal, gitignored.

2. `.apache-magpie-overrides/setup-status.md` — committed,

project-wide.

Both files are applied if present. See

[`docs/setup/agentic-overrides.md`](../../../../docs/setup/agentic-overrides.md)

for the full lookup contract.

**Hard rule**: agents NEVER modify the snapshot under

`<adopter-repo>/.apache-magpie/`. Local modifications go in the

override file. Framework changes go via PR to

`apache/magpie`.

---

## Snapshot drift

Also at the top of every run, this skill compares the gitignored

`.apache-magpie.local.lock` (per-machine fetch) against the

committed `.apache-magpie.lock` (the project pin). On mismatch the

skill surfaces the gap and proposes

[`setup upgrade`](../setup/upgrade.md). The proposal is

non-blocking; surfacing the drift is itself part of this skill's

dashboard, so the comparison feeds [Step 1](#step-1--render-the-dashboard)

rather than gating the run.

---

## Inputs

**Skill directives** (how the user invokes the skill):

| Input | Effect |

|---|---|

| (none) | Render the dashboard, then offer adjustments interactively. |

| `--no-adjust` | Render only; skip the reconfigure offer. |

| `adjust` | Skip straight to the reconfigure flow after a brief state recap. |

**Collector flags** (passed through to

[`scripts/collect_status.py`](scripts/collect_status.py)):

| Flag | Effect |

|---|---|

| `--repo <path>` | Inspect a repo other than the current git top-level. |

| `--format md` | The Markdown dashboard (default). |

| `--format json` | The raw machine-readable fields ([`collect.md`](collect.md)); add `--pretty` to indent. |

The default output is the Markdown dashboard, rendered

deterministically by the collector.

---

## Prerequisites

- A git checkout (`git rev-parse --show-toplevel` succeeds), or an

explicit `--repo <path>`.

- `python3` on `PATH` for the deterministic collector

([`scripts/collect_status.py`](scripts/collect_status.py)). No

third-party packages, no network access.

This skill reads only framework-internal, on-disk state (lock

files, symlinks, `.gitignore`, the post-checkout hook). It reads

**no external or private content**, so the prompt-injection and

Privacy-LLM gate-checks do not apply.

---

## Step 0 — Pre-flight check

1. Resolve the repo root (`--repo` if given, else

`git rev-parse --show-toplevel`).

2. Apply adopter overrides and the drift preamble above.

3. **Adopted?** If `<committed-lock>` (`.apache-magpie.lock`) is

absent, the repo is **not adopted**. Say so, point at

[`setup`](../setup/SKILL.md) to adopt, and stop — there

is no state to render.

---

## Step 1 — Render the dashboard

The collector **renders the dashboard itself**. Run it (it never

writes and never fetches):

```bash

python3 <framework>/skills/setup-status/scripts/collect_status.py

```

(From a normal adopter the script lives under the snapshot at

`.apache-magpie/skills/setup-status/scripts/`; invoke it via the

`magpie-setup-status` symlink's resolved path. The default output

is the Markdown dashboard; pass `--format json` only when tooling

needs the raw fields — see [`collect.md`](collect.md).)

> **OUTPUT CONTRACT — non-negotiable.** Present the script's

> Markdown output **verbatim** (it is already GitHub-flavoured

> Markdown — let the harness render the pipe table). Do **not**:

> re-draw it as a box-drawing/ASCII table; drop the `serves` bullet

> legend (it carries the agents each directory serves, including

> the whole `universal` cluster); add a Reads column back into the

> table (that is what made it wrap and break); recompute the

> verdict; or "prettify" the layout. The script, not the agent,

> owns the rendering, precisely because an LLM formatting pass

> reliably mangles it (drops the agents-served legend, renames

> columns, re-introduces the wide column). If you find yourself

> rebuilding the table, stop and paste the script output instead.

The renderer owns the headline, the agent-target table plus its

`serves` legend (so the `universal` cluster and every registry

vendor always appear), the family roster, and the drift /

integrity summary.

Full layout reference, the health-verdict rules, and mode-aware

interpretation: [`render.md`](render.md).

---

## Step 2 — Interpret (lightly)

After printing the verbatim dashboard, optionally add a one-line

**mode-aware** note where it helps — without re-tabulating or

contradicting the script output. Example: a `method:local`

framework checkout commits its symlinks and has no snapshot or

local lock, so the absent snapshot is healthy there but a fault

for a normal adopter ([`render.md`](render.md#mode-aware-interpretation)).

---

## Step 3 — Offer adjustments

Unless `--no-adjust` was passed, end the dashboard with the

reconfigure offer. Detect the obvious deltas (a registry target

present on disk but not wired; an opt-in family not installed;

dangling symlinks; drift) and present each as a concrete,

confirmable change. On confirmation, **delegate to

[`setup`](../setup/SKILL.md)** with the right flags

(`agents:<list>`, `skill-families:<list>`, or `upgrade`) — this

skill never edits symlinks, locks, or `.gitignore` itself.

Full gap-detection and delegation rules: [`adjust.md`](adjust.md).

---

## Hard rules

- **Read-only on its own; mutation only via setup.** This skill

never writes a symlink, a lock file, or `.gitignore`. Every

change is delegated to [`setup`](../setup/SKILL.md),

preserving the framework's single source of truth for adoption

mutation.

- **Propose before applying.** Each adjustment is a proposal the

user explicitly confirms before the delegated `setup`

run starts. No silent reconfiguration.

- **Do not duplicate `verify`.** For deep integrity, permission

hygiene, comdev-MCP prerequisites, and the stale-worktree sweep,

point the user at [`setup verify`](../setup/verify.md)

rather than re-implementing those checks here.

- **Never invent state.** Report only what the collector observed.

If a field is unknown (e.g. upstream-tip drift needs network),

say it was not checked and name the skill that does check it.

---

## References

- [`collect.md`](collect.md) — the collector's JSON field

reference.

- [`render.md`](render.md) — dashboard layout, health-verdict

rules, mode-aware interpretation.

- [`adjust.md`](adjust.md) — gap detection and the delegation

contract to `setup`.

- [`scripts/collect_status.py`](scripts/collect_status.py) — the

deterministic, read-only state collector.

- [`setup`](../setup/SKILL.md) — adoption mutation:

[`install.md`](../setup/install.md), [`upgrade.md`](../setup/upgrade.md),

the [`agents.md`](../setup/agents.md) target registry, and the

[Golden rules](../setup/SKILL.md#golden-rules).

- [`setup verify`](../setup/verify.md) — the deep

integrity / health check this dashboard complements.

- [`AGENTS.md`](../../../../AGENTS.md) — framework conventions and the

placeholder convention.

- [`docs/setup/agentic-overrides.md`](../../../../docs/setup/agentic-overrides.md)

— the override contract every skill consults.