| name | add-concept |
| description | Add a concept to the ***definitions*** section of a ***plain spec file. Use when the user wants to define a new concept, entity, or domain term in a .plain file. |
Add Concept
Always use the skill load-plain-reference to retrieve the ***plain syntax rules — but only if you haven't done so yet.
Workflow
- Identify the target
.plain file. If ambiguous, ask the user.
- Read the file to understand existing definitions, imports, and concepts.
- Validate the concept name against the syntax rules below.
- Check for uniqueness — the concept name must not already exist in the file or its imports.
- Check referenced concepts — any
:ConceptName: used in the definition must already be defined above it (in this file or via import/requires). Concept references must not form cycles (e.g., A references B and B references A).
- Check for circular references — if the new concept references
:B:, then :B: must not reference the new concept (directly or indirectly). Example of a circular definition to avoid:
- :Order: is placed by :Customer: and contains :OrderItem: entries.
- :Customer: is a user who has placed at least one :Order:.
Fix by removing the back-reference:
- :Customer: is a user of the system.
- :Order: is placed by :Customer: and contains :OrderItem: entries.
- Insert the concept into the
***definitions*** section, after any concepts it references.
- Read the file again to confirm correct placement and syntax.
Concept Syntax Rules
- Wrapped in colons:
:ConceptName:
- CamelCase, starting with an uppercase letter
- Valid characters: letters, digits,
+, -, ., _
- Must be globally unique across the spec and all its imports
- Exported concepts from
requires modules are not transitive — if a concept needs to be shared across multiple requires modules, define it in a common import module instead
Definition Format
A concept definition is a bullet in ***definitions*** that starts with the concept name:
***definitions***
- :ConceptName: is a description of what it represents.
Attributes and constraints are nested sub-bullets:
***definitions***
- :Task: describes an activity that needs to be done by :User:. :Task: has:
- Name - a short description (required)
- Notes - additional details (optional)
- Due Date - completion deadline (optional)
Validation Checklist
