| name | allium-cli-check |
| description | Use when validating a folder of .allium specs with allium check. Resolves the folder to an entrypoint file, runs validation, interprets diagnostics, and defines the repair loop. |
Allium CLI Check
Use this skill whenever a user asks to validate a folder of .allium specs, after creating or editing a spec, or before moving to deeper analysis.
Primary objective
Run allium check against the resolved entrypoint file for a folder of .allium specs and interpret the result accurately.
Folder-level operating protocol
This skill is invoked against a folder containing one or more .allium files. Do not pass the folder itself to allium commands. Allium CLI commands operate on spec files, so first resolve the effective entrypoint file.
Resolve the spec folder
Treat the user's folder argument as SPEC_DIR. If no folder is provided, use the current working directory only after confirming it contains .allium files.
SPEC_DIR="${SPEC_DIR:-.}"
find "$SPEC_DIR" -type f -name '*.allium' | sort
If no .allium files are found, stop and report that the folder does not contain Allium specs.
Resolve the entrypoint
Use this order:
- If the user explicitly named an entrypoint file, use that exact file.
- If
SPEC_DIR/index.allium exists, use it.
- If
SPEC_DIR/allium/index.allium exists, use it.
- If exactly one
.allium file exists under SPEC_DIR, use that file.
- If multiple
.allium files exist and no clear entrypoint exists, inspect imports/references and choose the file that appears to aggregate the others.
- If still ambiguous, run safe per-file diagnostics where useful, then report the candidate entrypoints and ask for a project convention. Do not invent a permanent convention.
Use ENTRYPOINT for commands that need the whole model. Use a leaf file only for narrow syntax debugging with allium parse, and return to the entrypoint for validation.
ENTRYPOINT="$SPEC_DIR/index.allium"
allium check "$ENTRYPOINT"
Never do this
allium check "$SPEC_DIR"
allium analyse "$SPEC_DIR"
allium model "$SPEC_DIR"
allium plan "$SPEC_DIR"
Passing a directory produces misleading failures and does not validate the spec set.
Mandatory rule
After any .allium change, run:
allium check "$ENTRYPOINT"
Do not validate only the edited leaf file when an entrypoint exists. A leaf file may pass alone while the project-level model remains broken because imports, references, or cross-file relationships are wrong.
What check is for
Use allium check to catch:
- Syntax errors.
- Invalid declarations.
- Missing or invalid references.
- Invalid language markers.
- Structural errors visible to local validation.
- Import or entrypoint mistakes that prevent the spec set from loading.
Do not use check as the only proof that the spec is semantically complete. Use analyse for deeper behavioral analysis.
Standard workflow
SPEC_DIR="specs/allium"
ENTRYPOINT="specs/allium/index.allium"
allium check "$ENTRYPOINT"
If successful:
- Record that
check passed.
- Continue to
analyse if implementation, test generation, or semantic review is next.
If failed:
- Do not proceed to
analyse, model, or plan unless investigating the failure itself.
- Preserve the exact diagnostic.
- Use
allium-cli-diagnostics-repair.
- Patch minimally.
- Rerun the same
check command.
Folder examples
Validate canonical specs
SPEC_DIR="specs/allium"
ENTRYPOINT="specs/allium/index.allium"
allium check "$ENTRYPOINT"
Validate scratch specs
SPEC_DIR=".scratch/specs/allium"
ENTRYPOINT=".scratch/specs/allium/index.allium"
allium check "$ENTRYPOINT"
Validate a folder with one spec file
SPEC_DIR="specs/payment"
ENTRYPOINT="$(find "$SPEC_DIR" -type f -name '*.allium' | sort | head -n 1)"
allium check "$ENTRYPOINT"
Only use this single-file pattern when the folder contains exactly one .allium file.
Diagnostic interpretation
Classify failed check output before editing.
Syntax error
Likely causes:
- Missing brace.
- Misplaced block.
- Invalid field syntax.
- Invalid
requires or ensures structure.
Next action:
allium parse "$TARGET_FILE"
Then patch the smallest syntactic region and rerun:
allium check "$ENTRYPOINT"
Invalid version marker
Likely causes:
- Missing
-- allium: 3 marker.
- Wrong version marker for the current language.
- Marker not at the expected location.
Next action: patch the marker only, then rerun check.
Missing reference
Likely causes:
- Entity, rule, field, enum value, or imported symbol is misspelled.
- Leaf file is disconnected from the entrypoint.
- Import graph is incomplete.
Next action:
- Search for the declared symbol.
- Verify it is imported or visible from
ENTRYPOINT.
- Patch the reference or import.
- Rerun
check.
Directory passed instead of file
Likely symptom:
Is a directory
Next action: resolve the entrypoint and rerun against the file.
allium check "$SPEC_DIR/index.allium"
Minimal repair discipline
When check fails, do not perform a broad rewrite. Prefer this sequence:
1. Identify the failing file/span.
2. Identify the smallest invalid construct.
3. Patch only that construct.
4. Rerun the exact same check command.
5. Continue only after it passes.
Success criteria
A successful check run means:
- The CLI accepted the resolved entrypoint.
- The spec set loaded sufficiently for validation.
- No blocking validation diagnostics were reported.
It does not necessarily mean:
- Every lifecycle reaches a terminal state.
- Every rule composes into a complete process.
- Test obligations are complete.
- The spec matches implementation.
Use analyse, plan, or /allium:weed style workflows for those concerns.
Reporting requirements
When reporting command results, include:
- The exact command run.
- Whether it passed or failed.
- The resolved spec folder.
- The resolved entrypoint.
- Blocking diagnostics, if any.
- The smallest meaningful next action.
Do not claim a spec is valid unless the relevant command completed successfully against the resolved entrypoint.
Related skills
allium-cli-diagnostics-repair for failures.allium-cli-parse for confusing syntax.allium-cli-analyse after successful validation.
