mirror of
https://github.com/juxt/allium.git
synced 2026-09-14 13:56:44 +08:00
Henry Garner
@@ -52,4 +52,4 @@ Every `.allium` file starts with `-- allium: N` where N is the current language
|
||||
|
||||
## Reference
|
||||
|
||||
See `references/language-reference.md` for the full syntax, validation rules, collection operations, surfaces and module system.
|
||||
See `skills/allium/references/language-reference.md` for the full syntax, validation rules, collection operations, surfaces and module system.
|
||||
|
||||
@@ -9,7 +9,7 @@ You tend the Allium garden. You are responsible for the health and integrity of
|
||||
|
||||
## Startup
|
||||
|
||||
1. Read [language reference](../../references/language-reference.md) for the Allium syntax and validation rules.
|
||||
1. Read [language reference](../../skills/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 before making any changes.
|
||||
4. Understand the existing domain model before proposing changes.
|
||||
@@ -53,7 +53,7 @@ When making changes, consider their effect beyond the immediate construct.
|
||||
|
||||
**Consider invariants for cross-entity constraints.** When a rule modifies entities across a relationship, consider whether a cross-entity invariant is implied. If the rule's postconditions could produce a state that seems wrong without a guard, suggest an invariant.
|
||||
|
||||
**Assess the spec before editing.** Read [assessing specs](../../references/assessing-specs.md) to understand the spec's maturity. Don't add detailed rules to an entity that doesn't have a transition graph yet — suggest adding the lifecycle first. Don't add surfaces without actors.
|
||||
**Assess the spec before editing.** Read [assessing specs](../../skills/allium/references/assessing-specs.md) to understand the spec's maturity. Don't add detailed rules to an entity that doesn't have a transition graph yet — suggest adding the lifecycle first. Don't add surfaces without actors.
|
||||
|
||||
## Boundaries
|
||||
|
||||
@@ -61,7 +61,7 @@ When making changes, consider their effect beyond the immediate construct.
|
||||
- You do not check alignment between specs and code. That belongs to `weed`.
|
||||
- You do not extract specifications from existing code. That belongs to `distill`.
|
||||
- You do not run structured discovery sessions. When requirements are unclear or the change involves new feature areas with complex entity relationships, that belongs to `elicit`. You handle targeted changes where the caller already knows what they want.
|
||||
- You do not modify `references/language-reference.md`. The language definition is governed separately.
|
||||
- You do not modify `skills/allium/references/language-reference.md`. The language definition is governed separately.
|
||||
|
||||
## Spec writing guidelines
|
||||
|
||||
@@ -86,9 +86,9 @@ When making changes, consider their effect beyond the immediate construct.
|
||||
|
||||
## Verification
|
||||
|
||||
After every edit to a `.allium` file, run `allium check` against the modified file if the CLI is available. Fix any reported issues before presenting the result. If the CLI is not available, verify against [language reference](../../references/language-reference.md).
|
||||
After every edit to a `.allium` file, run `allium check` against the modified file if the CLI is available. Fix any reported issues before presenting the result. If the CLI is not available, verify against [language reference](../../skills/allium/references/language-reference.md).
|
||||
|
||||
After edits that change rules, surfaces or transition graphs, run `allium analyse` if available and if the spec meets the criteria in [assessing specs](../../references/assessing-specs.md) (at least one entity has both witnessing rules and surfaces defined). If it produces findings, flag the most significant ones in your output with a description in domain terms. Consult [actioning findings](../../references/actioning-findings.md) for how to translate findings.
|
||||
After edits that change rules, surfaces or transition graphs, run `allium analyse` if available and if the spec meets the criteria in [assessing specs](../../skills/allium/references/assessing-specs.md) (at least one entity has both witnessing rules and surfaces defined). If it produces findings, flag the most significant ones in your output with a description in domain terms. Consult [actioning findings](../../skills/allium/references/actioning-findings.md) for how to translate findings.
|
||||
|
||||
## Output
|
||||
|
||||
|
||||
@@ -9,7 +9,7 @@ You weed the Allium garden. You compare `.allium` specifications against impleme
|
||||
|
||||
## Startup
|
||||
|
||||
1. Read [language reference](../../references/language-reference.md) for the Allium syntax and validation rules.
|
||||
1. Read [language reference](../../skills/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.
|
||||
@@ -32,7 +32,7 @@ For each entity, rule or trigger in the spec, find the corresponding implementat
|
||||
|
||||
### Process-level checks
|
||||
|
||||
Beyond construct-by-construct comparison, check process-level properties. Read [assessing specs](../../references/assessing-specs.md) to gauge spec maturity before running these — don't flag process-level gaps on a coarse spec.
|
||||
Beyond construct-by-construct comparison, check process-level properties. Read [assessing specs](../../skills/allium/references/assessing-specs.md) to gauge spec maturity before running these — don't flag process-level gaps on a coarse spec.
|
||||
|
||||
- **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, report 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.
|
||||
@@ -77,7 +77,7 @@ When code has repeated interface contracts across service boundaries (e.g. the s
|
||||
|
||||
- You do not build new specifications from scratch. That belongs to `elicit`.
|
||||
- You do not extract specifications from code. That belongs to `distill`.
|
||||
- You do not modify `references/language-reference.md`. The language definition is governed separately.
|
||||
- You do not modify `skills/allium/references/language-reference.md`. The language definition is governed separately.
|
||||
- You do not make architectural decisions. Flag wider implications and let the caller decide.
|
||||
|
||||
## Output format
|
||||
@@ -95,6 +95,6 @@ Group related divergences together. Lead with the most consequential findings.
|
||||
|
||||
## Verification
|
||||
|
||||
After every edit to a `.allium` file, run `allium check` against the modified file if the CLI is available. Fix any reported issues before presenting the result. If the CLI is not available, verify against [language reference](../../references/language-reference.md).
|
||||
After every edit to a `.allium` file, run `allium check` against the modified file if the CLI is available. Fix any reported issues before presenting the result. If the CLI is not available, verify against [language reference](../../skills/allium/references/language-reference.md).
|
||||
|
||||
If `allium analyse` is available, run it after completing divergence checks. Use findings to identify process-level gaps that construct-by-construct comparison misses. A `missing_producer` finding might indicate either a spec gap (the code handles it but the spec doesn't model it) or a code gap (nobody implemented the data path). Classify each finding by checking whether the code addresses it. Consult [actioning findings](../../references/actioning-findings.md) for how to translate findings.
|
||||
If `allium analyse` is available, run it after completing divergence checks. Use findings to identify process-level gaps that construct-by-construct comparison misses. A `missing_producer` finding might indicate either a spec gap (the code handles it but the spec doesn't model it) or a code gap (nobody implemented the data path). Classify each finding by checking whether the code addresses it. Consult [actioning findings](../../skills/allium/references/actioning-findings.md) for how to translate findings.
|
||||
|
||||
@@ -167,7 +167,7 @@ rule CircuitProbes {
|
||||
}
|
||||
```
|
||||
|
||||
The [language reference](references/language-reference.md) covers entities, rules, triggers, relationships, projections, derived values, surfaces and actor declarations. The [v1 to v2 migration guide](references/migration-v1-to-v2.md) and [v2 to v3 migration guide](references/migration-v2-to-v3.md) cover what changed between versions and how to upgrade existing specs.
|
||||
The [language reference](skills/allium/references/language-reference.md) covers entities, rules, triggers, relationships, projections, derived values, surfaces and actor declarations. The [v1 to v2 migration guide](skills/allium/references/migration-v1-to-v2.md) and [v2 to v3 migration guide](skills/allium/references/migration-v2-to-v3.md) cover what changed between versions and how to upgrade existing specs.
|
||||
|
||||
Allium has no compiler and no runtime. It is purely descriptive, defined entirely by its documentation. LLMs already function as pseudocode compilers, executing informal descriptions into working code. A well-structured behavioural language ensures that what gets compiled is what you actually meant. The behavioural model is the primary artefact; the code that implements it is secondary.
|
||||
|
||||
|
||||
+5
-5
@@ -17,7 +17,7 @@ You tend the Allium garden. You are responsible for the health and integrity of
|
||||
|
||||
## Startup
|
||||
|
||||
1. Read `${CLAUDE_PLUGIN_ROOT}/references/language-reference.md` for the Allium syntax and validation rules.
|
||||
1. Read `${CLAUDE_PLUGIN_ROOT}/skills/allium/references/language-reference.md` for the Allium syntax and validation rules.
|
||||
2. Read the relevant `.allium` files (use `Glob` 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 before making any changes.
|
||||
4. Understand the existing domain model before proposing changes.
|
||||
@@ -61,7 +61,7 @@ When making changes, consider their effect beyond the immediate construct.
|
||||
|
||||
**Consider invariants for cross-entity constraints.** When a rule modifies entities across a relationship, consider whether a cross-entity invariant is implied. If the rule's postconditions could produce a state that seems wrong without a guard, suggest an invariant.
|
||||
|
||||
**Assess the spec before editing.** Read `${CLAUDE_PLUGIN_ROOT}/references/assessing-specs.md` to understand the spec's maturity. Don't add detailed rules to an entity that doesn't have a transition graph yet — suggest adding the lifecycle first. Don't add surfaces without actors.
|
||||
**Assess the spec before editing.** Read `${CLAUDE_PLUGIN_ROOT}/skills/allium/references/assessing-specs.md` to understand the spec's maturity. Don't add detailed rules to an entity that doesn't have a transition graph yet — suggest adding the lifecycle first. Don't add surfaces without actors.
|
||||
|
||||
## Boundaries
|
||||
|
||||
@@ -69,7 +69,7 @@ When making changes, consider their effect beyond the immediate construct.
|
||||
- You do not check alignment between specs and code. That belongs to `weed`.
|
||||
- You do not extract specifications from existing code. That belongs to `distill`.
|
||||
- You do not run structured discovery sessions. When requirements are unclear or the change involves new feature areas with complex entity relationships, that belongs to `elicit`. You handle targeted changes where the caller already knows what they want.
|
||||
- You do not modify `references/language-reference.md`. The language definition is governed separately.
|
||||
- You do not modify `skills/allium/references/language-reference.md`. The language definition is governed separately.
|
||||
|
||||
## Spec writing guidelines
|
||||
|
||||
@@ -94,9 +94,9 @@ When making changes, consider their effect beyond the immediate construct.
|
||||
|
||||
## Verification
|
||||
|
||||
After every edit to a `.allium` file, run `allium check` against the modified file if the CLI is available. Fix any reported issues before presenting the result. If the CLI is not available, verify against `${CLAUDE_PLUGIN_ROOT}/references/language-reference.md`.
|
||||
After every edit to a `.allium` file, run `allium check` against the modified file if the CLI is available. Fix any reported issues before presenting the result. If the CLI is not available, verify against `${CLAUDE_PLUGIN_ROOT}/skills/allium/references/language-reference.md`.
|
||||
|
||||
After edits that change rules, surfaces or transition graphs, run `allium analyse` if available and if the spec meets the criteria in `${CLAUDE_PLUGIN_ROOT}/references/assessing-specs.md` (at least one entity has both witnessing rules and surfaces defined). If it produces findings, flag the most significant ones in your output with a description in domain terms. Consult `${CLAUDE_PLUGIN_ROOT}/references/actioning-findings.md` for how to translate findings.
|
||||
After edits that change rules, surfaces or transition graphs, run `allium analyse` if available and if the spec meets the criteria in `${CLAUDE_PLUGIN_ROOT}/skills/allium/references/assessing-specs.md` (at least one entity has both witnessing rules and surfaces defined). If it produces findings, flag the most significant ones in your output with a description in domain terms. Consult `${CLAUDE_PLUGIN_ROOT}/skills/allium/references/actioning-findings.md` for how to translate findings.
|
||||
|
||||
## Output
|
||||
|
||||
|
||||
+5
-5
@@ -17,7 +17,7 @@ You weed the Allium garden. You compare `.allium` specifications against impleme
|
||||
|
||||
## Startup
|
||||
|
||||
1. Read `${CLAUDE_PLUGIN_ROOT}/references/language-reference.md` for the Allium syntax and validation rules.
|
||||
1. Read `${CLAUDE_PLUGIN_ROOT}/skills/allium/references/language-reference.md` for the Allium syntax and validation rules.
|
||||
2. Read the relevant `.allium` files (use `Glob` 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.
|
||||
@@ -40,7 +40,7 @@ For each entity, rule or trigger in the spec, find the corresponding implementat
|
||||
|
||||
### Process-level checks
|
||||
|
||||
Beyond construct-by-construct comparison, check process-level properties. Read `${CLAUDE_PLUGIN_ROOT}/references/assessing-specs.md` to gauge spec maturity before running these — don't flag process-level gaps on a coarse spec.
|
||||
Beyond construct-by-construct comparison, check process-level properties. Read `${CLAUDE_PLUGIN_ROOT}/skills/allium/references/assessing-specs.md` to gauge spec maturity before running these — don't flag process-level gaps on a coarse spec.
|
||||
|
||||
- **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, report 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.
|
||||
@@ -85,7 +85,7 @@ When code has repeated interface contracts across service boundaries (e.g. the s
|
||||
|
||||
- You do not build new specifications from scratch. That belongs to `elicit`.
|
||||
- You do not extract specifications from code. That belongs to `distill`.
|
||||
- You do not modify `references/language-reference.md`. The language definition is governed separately.
|
||||
- You do not modify `skills/allium/references/language-reference.md`. The language definition is governed separately.
|
||||
- You do not make architectural decisions. Flag wider implications and let the caller decide.
|
||||
|
||||
## Output format
|
||||
@@ -103,6 +103,6 @@ Group related divergences together. Lead with the most consequential findings.
|
||||
|
||||
## Verification
|
||||
|
||||
After every edit to a `.allium` file, run `allium check` against the modified file if the CLI is available. Fix any reported issues before presenting the result. If the CLI is not available, verify against `${CLAUDE_PLUGIN_ROOT}/references/language-reference.md`.
|
||||
After every edit to a `.allium` file, run `allium check` against the modified file if the CLI is available. Fix any reported issues before presenting the result. If the CLI is not available, verify against `${CLAUDE_PLUGIN_ROOT}/skills/allium/references/language-reference.md`.
|
||||
|
||||
If `allium analyse` is available, run it after completing divergence checks. Use findings to identify process-level gaps that construct-by-construct comparison misses. A `missing_producer` finding might indicate either a spec gap (the code handles it but the spec doesn't model it) or a code gap (nobody implemented the data path). Classify each finding by checking whether the code addresses it. Consult `${CLAUDE_PLUGIN_ROOT}/references/actioning-findings.md` for how to translate findings.
|
||||
If `allium analyse` is available, run it after completing divergence checks. Use findings to identify process-level gaps that construct-by-construct comparison misses. A `missing_producer` finding might indicate either a spec gap (the code handles it but the spec doesn't model it) or a code gap (nobody implemented the data path). Classify each finding by checking whether the code addresses it. Consult `${CLAUDE_PLUGIN_ROOT}/skills/allium/references/actioning-findings.md` for how to translate findings.
|
||||
|
||||
@@ -58,16 +58,16 @@ function adaptBody(body) {
|
||||
body
|
||||
// Replace ${CLAUDE_PLUGIN_ROOT} paths with relative markdown links
|
||||
.replace(
|
||||
/`\$\{CLAUDE_PLUGIN_ROOT\}\/references\/language-reference\.md`/g,
|
||||
"[language reference](../../references/language-reference.md)"
|
||||
/`\$\{CLAUDE_PLUGIN_ROOT\}\/skills\/allium\/references\/language-reference\.md`/g,
|
||||
"[language reference](../../skills/allium/references/language-reference.md)"
|
||||
)
|
||||
.replace(
|
||||
/`\$\{CLAUDE_PLUGIN_ROOT\}\/references\/assessing-specs\.md`/g,
|
||||
"[assessing specs](../../references/assessing-specs.md)"
|
||||
/`\$\{CLAUDE_PLUGIN_ROOT\}\/skills\/allium\/references\/assessing-specs\.md`/g,
|
||||
"[assessing specs](../../skills/allium/references/assessing-specs.md)"
|
||||
)
|
||||
.replace(
|
||||
/`\$\{CLAUDE_PLUGIN_ROOT\}\/references\/actioning-findings\.md`/g,
|
||||
"[actioning findings](../../references/actioning-findings.md)"
|
||||
/`\$\{CLAUDE_PLUGIN_ROOT\}\/skills\/allium\/references\/actioning-findings\.md`/g,
|
||||
"[actioning findings](../../skills/allium/references/actioning-findings.md)"
|
||||
)
|
||||
// Replace Claude Code tool names with generic instructions
|
||||
.replace(/\(use `Glob` to find them if not specified\)/g, "(search the project to find them if not specified)")
|
||||
|
||||
@@ -206,7 +206,7 @@ contract Codec {
|
||||
}
|
||||
```
|
||||
|
||||
Contracts are module-level declarations referenced by name in surface `contracts:` clauses (`demands Codec`, `fulfils EventSubmitter`). See [Contracts](../../references/language-reference.md#contracts) for declaration syntax and referencing rules.
|
||||
Contracts are module-level declarations referenced by name in surface `contracts:` clauses (`demands Codec`, `fulfils EventSubmitter`). See [Contracts](./references/language-reference.md#contracts) for declaration syntax and referencing rules.
|
||||
|
||||
### Expressions
|
||||
|
||||
@@ -248,7 +248,7 @@ invariant NonNegativeBalance {
|
||||
}
|
||||
```
|
||||
|
||||
Expression-bearing invariants (`invariant Name { expression }`) assert properties over entity state. They are logical assertions, not runtime checks. Distinct from prose annotations (`@invariant Name`) in contracts, which use the `@` sigil to mark content the checker does not evaluate. See [Invariants](../../references/language-reference.md#invariants).
|
||||
Expression-bearing invariants (`invariant Name { expression }`) assert properties over entity state. They are logical assertions, not runtime checks. Distinct from prose annotations (`@invariant Name`) in contracts, which use the `@` sigil to mark content the checker does not evaluate. See [Invariants](./references/language-reference.md#invariants).
|
||||
|
||||
### Transition graph (v3)
|
||||
|
||||
@@ -302,10 +302,10 @@ open question "Admin ownership - should admins be assigned to specific roles?"
|
||||
|
||||
## Verification
|
||||
|
||||
When the `allium` CLI is installed, a hook validates `.allium` files automatically after every write or edit. Fix any reported issues before presenting the result. If the CLI is not available, verify against the [language reference](../../references/language-reference.md).
|
||||
When the `allium` CLI is installed, a hook validates `.allium` files automatically after every write or edit. Fix any reported issues before presenting the result. If the CLI is not available, verify against the [language reference](./references/language-reference.md).
|
||||
|
||||
## References
|
||||
|
||||
- [Language reference](../../references/language-reference.md) — full syntax for entities, rules, expressions, surfaces, contracts, invariants and validation
|
||||
- [Test generation](../../references/test-generation.md) — generating tests from specifications
|
||||
- [Patterns](../../references/patterns.md) — 9 worked patterns: auth, RBAC, invitations, soft delete, notifications, usage limits, comments, library spec integration, framework integration contract
|
||||
- [Language reference](./references/language-reference.md) — full syntax for entities, rules, expressions, surfaces, contracts, invariants and validation
|
||||
- [Test generation](./references/test-generation.md) — generating tests from specifications
|
||||
- [Patterns](./references/patterns.md) — 9 worked patterns: auth, RBAC, invitations, soft delete, notifications, usage limits, comments, library spec integration, framework integration contract
|
||||
|
||||
@@ -583,9 +583,9 @@ Common findings:
|
||||
- "Actually we wanted X but never built it"
|
||||
- "These two code paths should be the same but aren't"
|
||||
|
||||
Before running further checks, read [assessing specs](../../references/assessing-specs.md) to gauge the distilled spec's maturity. This tells you whether the spec is ready for process-level analysis or still needs structural work.
|
||||
Before running further checks, read [assessing specs](../allium/references/assessing-specs.md) to gauge the distilled spec's maturity. This tells you whether the spec is ready for process-level analysis or still needs structural work.
|
||||
|
||||
If the Allium CLI is available, run `allium check` on the distilled spec to catch structural issues, then `allium analyse` to identify process-level gaps. Findings from `analyse` can drive validation questions: "The distilled spec has a rule that requires `background_check.status = clear` but no surface captures background check results. Is this handled by a part of the codebase we haven't looked at?" Consult [actioning findings](../../references/actioning-findings.md) for how to translate findings into domain questions.
|
||||
If the Allium CLI is available, run `allium check` on the distilled spec to catch structural issues, then `allium analyse` to identify process-level gaps. Findings from `analyse` can drive validation questions: "The distilled spec has a rule that requires `background_check.status = clear` but no surface captures background check results. Is this handled by a part of the codebase we haven't looked at?" Consult [actioning findings](../allium/references/actioning-findings.md) for how to translate findings into domain questions.
|
||||
|
||||
## Recognising library spec candidates
|
||||
|
||||
@@ -640,7 +640,7 @@ rule PaymentReceived {
|
||||
}
|
||||
```
|
||||
|
||||
See [patterns.md Pattern 8](../../references/patterns.md) for detailed examples of integrating library specs.
|
||||
See [patterns.md Pattern 8](../allium/references/patterns.md) for detailed examples of integrating library specs.
|
||||
|
||||
## Common distillation challenges
|
||||
|
||||
@@ -810,7 +810,7 @@ The extracted spec is a starting point. If distillation reveals gaps that need s
|
||||
|
||||
## References
|
||||
|
||||
- [Language reference](../../references/language-reference.md), full Allium syntax
|
||||
- [Assessing specs](../../references/assessing-specs.md), how to assess spec maturity and choose the right level of analysis
|
||||
- [Actioning findings](../../references/actioning-findings.md), translating checker findings into domain questions
|
||||
- [Language reference](../allium/references/language-reference.md), full Allium syntax
|
||||
- [Assessing specs](../allium/references/assessing-specs.md), how to assess spec maturity and choose the right level of analysis
|
||||
- [Actioning findings](../allium/references/actioning-findings.md), translating checker findings into domain questions
|
||||
- [Worked examples](./references/worked-examples.md), complete code-to-spec examples in Python, TypeScript and Java
|
||||
|
||||
@@ -158,7 +158,7 @@ Before choosing an approach, assess what the user is bringing. The initial promp
|
||||
|
||||
**The user has existing code.** "We have a payments service and I want to capture what it does." This is distillation with elicitation. Point them to the `distill` skill, or combine both: distill the structure from code, elicit the intent from the stakeholder.
|
||||
|
||||
**The user has an existing spec.** Read the spec first. Use [assessing specs](../../references/assessing-specs.md) to determine what level of development each entity is at. Skip phases the spec has already covered — don't re-ask scope questions for a spec that already has scope comments, or re-discover processes for a spec that already has transition graphs. Start at the level each entity needs: detail elicitation for entities with lifecycles but no rules, obstacle elicitation for entities with rules but no failure paths.
|
||||
**The user has an existing spec.** Read the spec first. Use [assessing specs](../allium/references/assessing-specs.md) to determine what level of development each entity is at. Skip phases the spec has already covered — don't re-ask scope questions for a spec that already has scope comments, or re-discover processes for a spec that already has transition graphs. Start at the level each entity needs: detail elicitation for entities with lifecycles but no rules, obstacle elicitation for entities with rules but no failure paths.
|
||||
|
||||
## Elicitation methodology
|
||||
|
||||
@@ -195,7 +195,7 @@ If Phase 0 was skipped, also ask: "What are the key processes this system suppor
|
||||
|
||||
**Goal:** Trace the main journey from start to finish.
|
||||
|
||||
If Phase 0 produced a walking skeleton (see [process discovery](./references/process-discovery.md)), use it as the starting point. Otherwise, ask: "If we could only build one path through this process, what would it be?" Write the skeleton as a coarse spec and describe it back to the user in domain terms (see [assessing specs](../../references/assessing-specs.md#communicating-with-stakeholders)).
|
||||
If Phase 0 produced a walking skeleton (see [process discovery](./references/process-discovery.md)), use it as the starting point. Otherwise, ask: "If we could only build one path through this process, what would it be?" Write the skeleton as a coarse spec and describe it back to the user in domain terms (see [assessing specs](../allium/references/assessing-specs.md#communicating-with-stakeholders)).
|
||||
|
||||
Then flesh out: "What triggers each step? Who's involved? What changes?" Follow one entity through its lifecycle, capturing state transitions, actors and triggers.
|
||||
|
||||
@@ -238,7 +238,7 @@ After writing rules and exception transitions, run `allium check` if the CLI is
|
||||
|
||||
Consult [assumption checking](./references/assumption-checking.md) for techniques. Describe what the spec says in domain terms and test it against the user's mental model. Trace concrete scenarios through the spec. Test ordering assumptions. Verify actor assignments.
|
||||
|
||||
If the Allium CLI is available, run `allium check` and use diagnostics to identify structural gaps. If `allium analyse` is available and the spec has rules and surfaces, run it and use findings to surface process-level gaps. Consult [actioning findings](../../references/actioning-findings.md) for how to translate findings into domain questions.
|
||||
If the Allium CLI is available, run `allium check` and use diagnostics to identify structural gaps. If `allium analyse` is available and the spec has rules and surfaces, run it and use findings to surface process-level gaps. Consult [actioning findings](../allium/references/actioning-findings.md) for how to translate findings into domain questions.
|
||||
|
||||
Questions to ask:
|
||||
|
||||
@@ -358,9 +358,9 @@ For targeted changes where you already know what you want, use the `tend` skill.
|
||||
|
||||
## References
|
||||
|
||||
- [Language reference](../../references/language-reference.md), full Allium syntax
|
||||
- [Assessing specs](../../references/assessing-specs.md), how to assess spec maturity and choose the right level of analysis
|
||||
- [Actioning findings](../../references/actioning-findings.md), translating checker findings into domain questions
|
||||
- [Language reference](../allium/references/language-reference.md), full Allium syntax
|
||||
- [Assessing specs](../allium/references/assessing-specs.md), how to assess spec maturity and choose the right level of analysis
|
||||
- [Actioning findings](../allium/references/actioning-findings.md), translating checker findings into domain questions
|
||||
- [Process discovery](./references/process-discovery.md), techniques for when the user hasn't articulated the process yet
|
||||
- [Detail elicitation](./references/detail-elicitation.md), techniques for filling in rules, surfaces and data dependencies
|
||||
- [Obstacle elicitation](./references/obstacle-elicitation.md), techniques for exploring failure paths, timeouts and handoffs
|
||||
|
||||
@@ -18,7 +18,7 @@ Before propagating tests, you need:
|
||||
3. **Test obligations** — from `allium plan <spec>` (JSON listing every required test)
|
||||
4. **Domain model** — from `allium model <spec>` (JSON describing entity shapes, constraints, state machines)
|
||||
|
||||
If the CLI tools are not available, derive test obligations manually from the spec using the test-generation taxonomy in [`references/test-generation.md`](../../references/test-generation.md).
|
||||
If the CLI tools are not available, derive test obligations manually from the spec using the test-generation taxonomy in [`references/test-generation.md`](../allium/references/test-generation.md).
|
||||
|
||||
## Modes
|
||||
|
||||
@@ -66,7 +66,7 @@ Categories from the test-generation taxonomy:
|
||||
- **Deadlock scenario tests** — for states where `allium analyse` identifies potential deadlocks, generate tests that put the entity in the stuck state and verify whether it can progress.
|
||||
- **Cross-entity process tests** — for processes spanning multiple entities, generate integration tests that exercise the full process from start to terminal state across all participating entities.
|
||||
|
||||
If `allium analyse` is available, use its findings to prioritise test generation. A `missing_producer` or `dead_transition` finding indicates a gap worth exercising with a test. A `deadlock` finding should generate a test documenting that the entity cannot escape the stuck state. Consult [actioning findings](../../references/actioning-findings.md) for the finding type taxonomy.
|
||||
If `allium analyse` is available, use its findings to prioritise test generation. A `missing_producer` or `dead_transition` finding indicates a gap worth exercising with a test. A `deadlock` finding should generate a test documenting that the entity cannot escape the stuck state. Consult [actioning findings](../allium/references/actioning-findings.md) for the finding type taxonomy.
|
||||
|
||||
## Test output kinds
|
||||
|
||||
@@ -168,7 +168,7 @@ Deferred specifications are fully specified in separate files. When the target c
|
||||
|
||||
## Process
|
||||
|
||||
1. **Read the spec** — understand entities, rules, surfaces, invariants, transition graphs, state-dependent fields, contracts, config, defaults. Read [assessing specs](../../references/assessing-specs.md) to gauge the spec's maturity. A coarse spec (entities and transition graphs but no rules) will produce limited test obligations — mostly structural tests. If the spec is too coarse for meaningful test generation, suggest using the `elicit` or `distill` skill to develop it further before propagating tests. A spec with rules and surfaces enables the full test taxonomy including data flow chain tests and reachability tests.
|
||||
1. **Read the spec** — understand entities, rules, surfaces, invariants, transition graphs, state-dependent fields, contracts, config, defaults. Read [assessing specs](../allium/references/assessing-specs.md) to gauge the spec's maturity. A coarse spec (entities and transition graphs but no rules) will produce limited test obligations — mostly structural tests. If the spec is too coarse for meaningful test generation, suggest using the `elicit` or `distill` skill to develop it further before propagating tests. A spec with rules and surfaces enables the full test taxonomy including data flow chain tests and reachability tests.
|
||||
2. **Read test obligations** — from `allium plan` output or manual derivation
|
||||
3. **Read domain model** — from `allium model` output or manual derivation
|
||||
4. **Explore the codebase** — find existing tests, test framework, entity implementations, rule implementations
|
||||
|
||||
@@ -9,7 +9,7 @@ You tend the Allium garden. You are responsible for the health and integrity of
|
||||
|
||||
## Startup
|
||||
|
||||
1. Read [language reference](../../references/language-reference.md) for the Allium syntax and validation rules.
|
||||
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 before making any changes.
|
||||
4. Understand the existing domain model before proposing changes.
|
||||
@@ -53,7 +53,7 @@ When making changes, consider their effect beyond the immediate construct.
|
||||
|
||||
**Consider invariants for cross-entity constraints.** When a rule modifies entities across a relationship (e.g. hiring a candidate also fills the role), consider whether a cross-entity invariant is implied. If the rule's postconditions could produce a state that seems wrong without a guard, suggest an invariant.
|
||||
|
||||
**Assess the spec before editing.** Read [assessing specs](../../references/assessing-specs.md) to understand the spec's maturity. Don't add detailed rules to an entity that doesn't have a transition graph yet — suggest adding the lifecycle first. Don't add surfaces without actors.
|
||||
**Assess the spec before editing.** Read [assessing specs](../allium/references/assessing-specs.md) to understand the spec's maturity. Don't add detailed rules to an entity that doesn't have a transition graph yet — suggest adding the lifecycle first. Don't add surfaces without actors.
|
||||
|
||||
## Boundaries
|
||||
|
||||
@@ -61,7 +61,7 @@ When making changes, consider their effect beyond the immediate construct.
|
||||
- You do not check alignment between specs and code. That belongs to the `weed` skill.
|
||||
- You do not extract specifications from existing code. That belongs to the `distill` skill.
|
||||
- You do not run structured discovery sessions. When requirements are unclear or the change involves new feature areas with complex entity relationships, that belongs to the `elicit` skill. You handle targeted changes where the caller already knows what they want.
|
||||
- You do not modify `references/language-reference.md`. The language definition is governed separately.
|
||||
- You do not modify `skills/allium/references/language-reference.md`. The language definition is governed separately.
|
||||
|
||||
## Spec writing guidelines
|
||||
|
||||
@@ -90,9 +90,9 @@ Spec evolution can require many edit-validate cycles. If you anticipate a long i
|
||||
|
||||
## Verification
|
||||
|
||||
After every edit to a `.allium` file, run `allium check` against the modified file if the CLI is installed. Fix any reported issues before presenting the result. If the CLI is not available, verify against the [language reference](../../references/language-reference.md). The first time the CLI is not found, note: "I'll validate against the language reference instead. If you'd like automated checking, the CLI is available via Homebrew or crates.io — see the README for details."
|
||||
After every edit to a `.allium` file, run `allium check` against the modified file if the CLI is installed. Fix any reported issues before presenting the result. If the CLI is not available, verify against the [language reference](../allium/references/language-reference.md). The first time the CLI is not found, note: "I'll validate against the language reference instead. If you'd like automated checking, the CLI is available via Homebrew or crates.io — see the README for details."
|
||||
|
||||
After edits that change rules, surfaces or transition graphs, run `allium analyse` if available and if the spec meets the criteria in [assessing specs](../../references/assessing-specs.md) (at least one entity has both witnessing rules and surfaces defined). If it produces findings, present the most relevant one as a follow-up question rather than raw output. Consult [actioning findings](../../references/actioning-findings.md) for how to translate findings into domain questions.
|
||||
After edits that change rules, surfaces or transition graphs, run `allium analyse` if available and if the spec meets the criteria in [assessing specs](../allium/references/assessing-specs.md) (at least one entity has both witnessing rules and surfaces defined). If it produces findings, present the most relevant one as a follow-up question rather than raw output. Consult [actioning findings](../allium/references/actioning-findings.md) for how to translate findings into domain questions.
|
||||
|
||||
## Output
|
||||
|
||||
|
||||
@@ -9,7 +9,7 @@ You weed the Allium garden. You compare `.allium` specifications against impleme
|
||||
|
||||
## Startup
|
||||
|
||||
1. Read [language reference](../../references/language-reference.md) for the Allium syntax and validation rules.
|
||||
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.
|
||||
@@ -40,7 +40,7 @@ Beyond construct-by-construct comparison, check process-level properties:
|
||||
- **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](../../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.
|
||||
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
|
||||
|
||||
@@ -79,7 +79,7 @@ When code has repeated interface contracts across service boundaries (e.g. the s
|
||||
|
||||
- You do not build new specifications from scratch. That belongs to the `elicit` skill.
|
||||
- You do not extract specifications from code. That belongs to the `distill` skill.
|
||||
- You do not modify `references/language-reference.md`. The language definition is governed separately.
|
||||
- You do not modify `skills/allium/references/language-reference.md`. The language definition is governed separately.
|
||||
- You do not make architectural decisions. Flag wider implications and let the caller decide.
|
||||
|
||||
## Context management
|
||||
@@ -88,9 +88,9 @@ Spec alignment checks can require many edit-validate cycles. If you anticipate a
|
||||
|
||||
## Verification
|
||||
|
||||
After every edit to a `.allium` file, run `allium check` against the modified file if the CLI is installed. Fix any reported issues before presenting the result. If the CLI is not available, verify against the [language reference](../../references/language-reference.md). The first time the CLI is not found, note: "I'll validate against the language reference instead. If you'd like automated checking, the CLI is available via Homebrew or crates.io — see the README for details."
|
||||
After every edit to a `.allium` file, run `allium check` against the modified file if the CLI is installed. Fix any reported issues before presenting the result. If the CLI is not available, verify against the [language reference](../allium/references/language-reference.md). The first time the CLI is not found, note: "I'll validate against the language reference instead. If you'd like automated checking, the CLI is available via Homebrew or crates.io — see the README for details."
|
||||
|
||||
If `allium analyse` is available, run it after completing divergence checks. Use findings to identify process-level gaps that construct-by-construct comparison misses. A `missing_producer` finding might indicate either a spec gap (the code handles it but the spec doesn't model it) or a code gap (nobody implemented the data path). Classify each finding by checking whether the code addresses it. Consult [actioning findings](../../references/actioning-findings.md) for how to translate findings into domain questions.
|
||||
If `allium analyse` is available, run it after completing divergence checks. Use findings to identify process-level gaps that construct-by-construct comparison misses. A `missing_producer` finding might indicate either a spec gap (the code handles it but the spec doesn't model it) or a code gap (nobody implemented the data path). Classify each finding by checking whether the code addresses it. Consult [actioning findings](../allium/references/actioning-findings.md) for how to translate findings into domain questions.
|
||||
|
||||
## Output format
|
||||
|
||||
|
||||
Reference in New Issue
Block a user