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:

***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

• 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