Add Concept

load-plain-reference

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:
   plain

   - :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:
   plain

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

***definitions***

***definitions***
- :ConceptName: is a description of what it represents.

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