| 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:
- :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)
Line syntax (hard rule)
Every line inside ***definitions*** must be its own list item starting with - . ***plain has no concept of bare continuation lines — indented prose without a leading - is invalid syntax and the renderer will reject it.
- Hard limit: 120 characters per line. If a sentence is too long, split it at a natural clause boundary into nested
- bullets — never wrap onto an unprefixed line.
- Nested attributes are also
- items, indented under the parent. The indentation alone is not enough; the leading - is required.
BAD — bare continuation lines (invalid ***plain syntax, will not render):
- :Task: describes an activity that needs to be done by :User:.
- Name is a short description that the user provides when creating
the task and is shown in the task list.
GOOD — every line starts with - :
- :Task: describes an activity that needs to be done by :User:.
- Name is a short description provided when creating the task.
- The name is shown in the task list.
Validation Checklist
