Add Concept

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