add-concept

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

1. Identify the target .plain file. If ambiguous, ask the user.
2. Read the file to understand existing definitions, imports, and concepts.
3. Validate the concept name against the syntax rules below.
4. Check for uniqueness — the concept name must not already exist in the file or its imports.
5. 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).
6. 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.
   

7. Insert the concept into the ***definitions*** section, after any concepts it references.
8. 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

• Name uses :CamelCase: notation
• Name is globally unique (not defined elsewhere in the file or imports)
• Definition starts with the concept name
• All referenced concepts (:OtherConcept:) are already defined above
• No circular references between concepts
• Description is clear, concise, and language-agnostic
• Placed inside a ***definitions*** section