Policy Algebra
Freeze governance invariants as Starlark blocks for skills, plans, and rule files, then drift-check candidates before you ship agent workflows.
Overview
Policy-algebra is an agent skill most often used in Ship (also Build agent-tooling, Operate infra) that generates frozen Starlark governance blocks and verifies candidate rules for drift against them.
Install
npx skills add https://github.com/camacho/ai-skills --skill policy-algebraWhat is this skill?
- Adaptive DEEP (intent string + /grill-me interview) vs SHALLOW (readable plan/skill file) input modes
- Generates fenced Starlark rule blocks for injection into downstream skills and plans
- `--verify <frozen> <candidate>` for canonicalized drift detection against a frozen block
- Explicit invocation only — not for casual rule brainstorming without generating or verifying blocks
- Optional `--write <path>` to persist the raw frozen block to disk
- Two input modes: DEEP interview vs SHALLOW file read
- CLI supports generate, `--write`, and `--verify` drift check
Adoption & trust: 524 installs on skills.sh; 1 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You have governance intent or a growing plan file but no frozen, comparable rule artifact to inject into skills and no way to catch when live rules drift from what you approved.
Who is it for?
Solo builders shipping agent skills or plans who need Starlark-shaped invariants, variable holes, and repeatable drift checks before merging policy changes.
Skip if: Open-ended policy debates without generating a block, or teams that do not want Starlark/frozen governance as the source of truth.
When should I use this skill?
A skill, plan, or rule file needs a frozen Starlark governance rule block generated, or an existing frozen block drift-checked against a candidate—not for general rule discussion.
What do I get? / Deliverables
You get a fenced Starlark block (optionally written to disk) and can run `--verify` so downstream agent work only proceeds when candidates match the frozen canonical rules.
- Fenced Starlark governance block
- Optional persisted raw block via `--write`
- Drift verification result from `--verify`
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is Ship because frozen rules and drift verification are governance gates before production agent behavior is trusted. Security subphase fits invariant enforcement, scope boundaries, and what must never happen in governed artifacts.
Where it fits
Freeze combinator and scope rules into Starlark before embedding them in a new SKILL.md for your coding agent.
Run `--verify` on a candidate plan edit to ensure shipping changes did not violate approved invariants.
Re-verify evolved rule files against the on-disk frozen block after a dependency or workflow refactor.
How it compares
Use for executable frozen governance blocks and drift verify—not for generic security linting or ad-hoc bullet-point rules in chat.
Common Questions / FAQ
Who is policy-algebra for?
Indie and solo builders formalizing agent skills, plans, and rule files who want frozen Starlark governance and drift detection instead of informal prose rules.
When should I use policy-algebra?
At Ship when locking security invariants before release, in Build when authoring agent-tooling rule packs, and in Operate when re-checking that updated skills still match an approved frozen block.
Is policy-algebra safe to install?
Review the Security Audits panel on this Prism page and inspect the skill repo before granting filesystem or shell access used by `--write` and file-based SHALLOW mode.
Workflow Chain
Requires first: grill me
SKILL.md
READMESKILL.md - Policy Algebra
# /policy-algebra Generates frozen, drift-checkable governance rules from thin intent strings (deep interview) or rich plan inputs (shallow confirmation). Produces fenced Starlark blocks callers can inject into downstream work, and exposes `--verify` for canonicalized drift detection. ## Invocation ``` /policy-algebra <target> # generate rules /policy-algebra <target> --write <path> # generate + persist raw block /policy-algebra --verify <frozen> <candidate> # drift check ``` `<target>` is a readable file path (SHALLOW mode) or an intent string (DEEP mode). ## Adaptive input detection ``` if target is a readable file path: mode = SHALLOW input = read(target) else: mode = DEEP input = target ``` ## Deep flow 1. Construct framing prompt for `/grill-me`: > "Interview the user to extract rule invariants for: > \<target prompt\> > > Focus questions on: > - Scope: what artifacts/events/phases does this rule govern? > - Invariants: what must always be true? what must never happen? > - Variable holes: what changes between instances? > - Combinators: are existing operators (+, diff, intersect, method calls) > enough, or do we need new helpers? > - Failure modes: what happens when a rule can't be satisfied? > > Return a structured list of predicates in natural language. > /policy-algebra will draft Starlark from your output." 2. Invoke `/grill-me` via the `Skill` tool with that prompt. 3. Capture `/grill-me`'s output as the invariant list. 4. Continue to drafting (step 5 of shallow flow). ## Shallow flow 1. Read file contents. 2. Scan for invariant declarations — headings like "Invariants", "Rules", "Constraints"; bullets with MUST / NEVER / ALWAYS; predicate-looking code blocks. 3. Extract those as the invariant list. 4. If extraction yields fewer than 2 invariants OR content is ambiguous: fall through to DEEP mode with the file contents as target. 5. Draft Starlark from the invariant list per `notation.md` conventions. 6. Pass draft to `/review` (no panel hint — `/review` assembles). 7. `/review` converges → frozen, OR caps → inherit `/review` escalation. ## Drafting conventions Group by subject (DEFAULTS, then named functions); keep each function body to 5 lines or fewer; one prose comment per function; no mutation. See `notation.md` for the full ruleset. ## Freeze and return After `/review` APPROVE, capture the exact Starlark text as the FROZEN block. Do **not** canonicalize at freeze time — canonicalization is a compare-time operation only, keeping freeze/return simple. Output format: ``` ALGEBRA: ```starlark <raw frozen starlark block, as /review approved> ``` REVIEW_ROUNDS: <n> PANEL: <comma-separated reviewers> STATUS: CONVERGED FILE: <path> (only when --write was used) NOTE: <non-obvious decision> (optional) ``` If `--write <path>` was supplied, write the raw Starlark block to that path and include `FILE: <path>` in the return block. ## `--verify` flow 1. Read both files. 2. Extract first ` ```starlark ` fenced block from each file. 3. Normalize both blocks (strip trailing whitespace, collapse blank lines, trim edges). 4. If equal → print `MATCH`, exit 0. Else → print `DRIFT` + unified diff, exit 1. Use the following bash to verify drift — no external dependencies needed: ```bash # policy-algebra verify — inline, no dependencies # Usage: bash verify.sh <frozen_file> <candidate_file> normalize() { sed 's/[[:space:]]*$//' | sed '/^$/d'; } extract_starlark() { sed -n '/^```starlark/,/^```$/p' "$1" | sed '1d;$d'; } FROZEN=$(extract_starlark "$1" | normalize) CANDIDATE=$(extract_starlark "$2" | normalize) if [ "$FROZEN" = "$CANDIDATE" ]; then echo "