package-review

name

package-review

description

Survey one Flight package and write its review.md — the independent observation layer of the per-package knowledge tree under agents/packages/<name>/. Reads evidence from EITHER the live worktree OR an incoming bundle under incoming/<worktree>-<sha>/, ingests the status.md, source and tests, and reasons against the package's charter.md and the contract (falling back to the codebase-map AAA standard where the charter is silent). Surfaces both how well the package lives up to the contract and where the contract/admin docs themselves need revising. Use when asked to "review a package", "survey <package>", "review the incoming bundle", "ingest the status docs", or to (re)generate review.md before assessment/approval. Read agents/packages/index.md first.

Package Review

You are the survey layer. Your output is agents/packages/<name>/review.md: a clear, honest observation of where the package is. You observe; you do not decide what to do next (that is the assessment layer) and you do not set vision (that is the charter). Read agents/packages/index.md and CONTRACT.md once before starting.

Evidence source — live or bundle

Decide where the package's code evidence comes from before you start:

• Live worktree (default): read packages/<name>/src/ directly. Use when reviewing work that is already in this worktree.
• Incoming bundle (incoming/ is at the repo root, not under agents/): when reviewing work pulled from another worktree, read from incoming/<worktree>-<sha>/head/packages/<name>/ and the bundle's changes.patch instead of the live tree. The bundle is git-free and self-contained; its MANIFEST.json › packages tells you which packages changed and which carry a status doc, and head/packages/<name>/dist/*.d.ts is the realized public API surface. Reference findings as <sha>:<path>.

Everything below is identical either way — only the root of the source paths changes.

Inputs to ingest

Read all of these before writing a word:

1. agents/packages/<name>/charter.md — the rubric. The vision, North star, Boundaries, Decisions, and Open directions. This is what you judge the package against.
2. the status doc — agents/packages/<name>/status.md (live) or head/agents/status/<name>.md (bundle). The developer handoff: what was just changed, what is in-flight, what to watch. A primary signal, not gospel — verify its claims against the source.
3. the source — packages/<name>/src/ (live) or incoming/<worktree>-<sha>/head/packages/<name>/ (bundle), plus colocated *.test.ts. Ground every claim here.
4. agents/packages/CONTRACT.md and index.md — the artifact contract and architecture. You judge the package against the charter and against these.

The rubric rule

Judge the package against its charter, not a generic ideal.

• Where the charter speaks (a North-star principle, a Boundary, a Decision): measure the package against that, and call out any place the code contradicts the charter — that is the highest-value finding a review can produce.
• Where the charter is silent or a stub: fall back to the codebase-map standard — AAA completeness for the domain, the OpenFL/Lime feature target, and the design constraints in agents/index.md. Then flag the silence: each thing you had to assume because the charter did not say becomes a candidate Open direction (collected in a closing section), so a thin charter gets thicker over time. Do not invent vision — surface the question.

What review.md contains

Write the file with the front matter from CONTRACT.md (package, status from stub|partial|solid|authoritative, score 0-100 directional, updated, ingested), then prose — structure it for the domain, but cover:

• Verdict — one line: <status> — <score>/100, and a sentence of why.
• Present capabilities — what genuinely exists, grounded in source. Be specific (function names, files). This is the evidence base the assessment will reason over.
• Gaps — what a mature library in this domain has that this one lacks. Name them concretely; do not yet prescribe the fix or sequence it (that is the assessor's job).
• Charter contradictions — anywhere the code violates a stated North-star principle, Boundary, or Decision. Empty is a fine and good result; say so.
• Contract & docs fit — two directions: (a) how well the package lives up to the contract — @flighthq/types-first types, full unabbreviated names, out-params, sentinels-not-throws, single root export, sideEffects: false, Rust-crate mirror; and (b) where the contract or admin docs themselves are wrong or stale against the shape the work has taken — a Package Map line that no longer matches, a convention the package outgrew, a missing entry. Flag these as candidate revisions; acting on them is the user's gate, not yours.
• Candidate open directions — questions the charter does not answer that you had to assume to review. These feed the charter's Open directions for the user to settle.

Boundaries of this skill

• Do not write assessment.md (Recommended/Backlog/Approved), edit charter.md, or touch status.md. You produce exactly one file: review.md.
• Do not prescribe a Bronze/Silver/Gold plan or sequence work — observation only. The assessment layer turns your gaps into recommendations.
• Ground every claim in source. A review that cannot be traced to code or tests is worthless to the layers downstream.