Weed
Audit `.allium` specs against implementation and reconcile drift in check, update-spec, or update-code mode.
Overview
weed is an agent skill most often used in Ship (also Build, Operate) that finds and resolves divergences between Allium `.allium` specs and implementation code.
Install
npx skills add https://github.com/juxt/allium --skill weedWhat is this skill?
- Compares Allium `.allium` specifications to implementation and lists every divergence with dual locations
- Three modes: check (report only), update spec (spec follows code), update code (code follows spec)
- Startup reads language reference, loads `.allium` files, optionally runs `allium check` for syntax
- Defaults to check mode when the caller does not specify repair direction
- Garden metaphor: continuous weeding of spec drift in Allium projects
- Three operational modes: check, update spec, update code
Adoption & trust: 1.3k installs on skills.sh; 390 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your Allium specs and the running code tell different stories, so agents and humans ship against the wrong contract.
Who is it for?
Teams using Juxt Allium who iterate quickly and need a disciplined spec–code sync pass with an explicit mode (report vs fix spec vs fix code).
Skip if: Codebases without `.allium` files or projects that do not treat Allium as the behavioral contract.
When should I use this skill?
User wants spec-code alignment, spec drift audit, compare specs against implementation, or sync specs with code or code with specs.
What do I get? / Deliverables
You get a divergence report or patched specs or code so behavior and `.allium` descriptions match the chosen source of truth.
- Divergence report with locations in spec and code
- Updated `.allium` files or patched implementation per selected mode
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is ship/review because the primary value is alignment auditing before release or after drift—same ritual as code review for specifications. Review subphase covers spec-vs-code divergence reports and guided fixes without treating specs as optional documentation.
Where it fits
After a refactor, run check mode to see which `.allium` endpoints no longer match handlers.
Pre-release check pass with divergences listed for human sign-off.
Post-hotfix update spec mode so `.allium` documents emergency behavior.
How it compares
Spec-alignment checker for Allium, not a general unit-test or ESLint substitute.
Common Questions / FAQ
Who is weed for?
Developers on Allium-backed repos who own specifications and want an agent-guided audit or repair loop.
When should I use weed?
In build when specs lag refactors, in ship before release review, or in operate after incidents when you need to verify implementation still matches `.allium`.
Is weed safe to install?
Update modes can modify specs and production code—use version control and review diffs; check the Security Audits panel on this Prism page for the package source.
SKILL.md
READMESKILL.md - Weed
# Weed You weed the Allium garden. You compare `.allium` specifications against implementation code, find where they have diverged, and help resolve the divergences. ## Startup 1. Read [language reference](../allium/references/language-reference.md) for the Allium syntax and validation rules. 2. Read the relevant `.allium` files (search the project to find them if not specified). 3. If the `allium` CLI is available, run `allium check` against the files to verify they are syntactically correct. 4. Read the corresponding implementation code. ## Modes You operate in one of three modes, determined by the caller's request: **Check.** Read both spec and code. Report every divergence with its location in both. Do not modify anything. **Update spec.** Modify the `.allium` files to match what the code actually does. The spec becomes a faithful description of current behaviour. **Update code.** Modify the implementation to match what the spec says. The code becomes a faithful implementation of specified behaviour. If no mode is specified, default to **check** and report all findings. ## How you work For each entity, rule or trigger in the spec, find the corresponding implementation. For each significant code path, check whether the spec accounts for it. Report mismatches in both directions: spec says X but code does Y, and code does Z but the spec is silent. ### Process-level checks Beyond construct-by-construct comparison, check process-level properties: - **Transition reachability in code.** For each transition declared in the spec's transition graph, verify the implementation has a code path that triggers it. If a transition is declared but no code path produces it, flag it. - **Surface-trigger coverage.** For each rule with an external stimulus trigger, verify the implementation has a corresponding entry point (API endpoint, webhook handler, message consumer). If the spec says `BackgroundCheckResultReceived` is provided by a surface, verify the code has the corresponding handler. - **Undeclared transitions in code.** Check whether the implementation produces state changes not declared in the spec's transition graph. If code can transition an entity from state A to state C but the graph only allows A → B → C, flag it. - **Invariant enforcement.** For each expression-bearing invariant in the spec, check whether the implementation enforces it (database constraint, application-level check, test assertion). If no enforcement exists, flag the gap. - **Bottom-up process reconstruction.** For entities with status fields, trace the state machine from the code: which states exist, which transitions the code produces, which actors trigger them. Compare the reconstructed process to the spec's transition graphs. Present the reconstructed process to the user for validation: "From the code, I see this lifecycle for Order: placed → paid → shipped → delivered, with cancellation possible from placed or paid. The spec's transition graph matches except it doesn't include cancellation from paid. Is this a spec gap or a code bug?" Report process-level divergences alongside construct-level ones. Read [assessing specs](../allium/references/assessing-specs.md) to understand the spec's maturity before checking — don't flag process-level gaps on a coarse spec that hasn't reached that level of development yet. ## Divergence classification When you find a mismatch, propose a classification with your reasoning. The caller confirms or overrides. Classify each divergence as one of: - **Spec bug.** The spec is wrong, code is correct. Fix the spec. - **Code