--- name: SPECLAN Format description: >- This skill should be used when the user works with SPECLAN specification files in the speclan/ directory, asks to "read a feature", "list requirements", "create a feature", "new requirement", "update a spec", "delete a change request", "show spec hierarchy", "ID format", or references SPECLAN entity types (Goal, Feature, Requirement, ChangeRequest). Provides foundational knowledge for all speclan/ directory operations including file structure, validation rules, status lifecycle, and entity relationships. version: 0.2.0 --- # SPECLAN Format Knowledge **THIS IS FOUNDATIONAL CONTEXT.** Apply these rules to ALL speclan file operations. SPECLAN (Specification as a Living Language) manages project specifications as interlinked markdown files with YAML frontmatter in a hierarchical directory structure. ## Quick Reference (CRITICAL) ### Filename IS the Source of Truth The **directory/filename pattern** `{PREFIX}-{ID}-{slug}` is authoritative: ``` F-1049-pet-management/F-1049-pet-management.md │ │ │ └─ File MUST match directory name │ │ └─ Kebab-case slug from title │ └─ 4-digit numeric ID (randomly generated) └─ Entity prefix (F=Feature, R=Requirement, etc.) ``` **Extract ID from filename, NOT frontmatter** for indexing and collision checks. ### Entity Prefixes | Entity | Prefix | Digits | Example | Storage | |--------|--------|--------|---------|---------| | Goal | G- | 3 | G-292 | `goals/G-292-slug.md` (flat) | | Feature | F- | 4 | F-1049 | `features/F-1049-slug/F-1049-slug.md` (dir) | | Requirement | R- | 4 | R-2046 | `features/.../requirements/R-2046-slug/R-2046-slug.md` (dir) | | Change Request | CR- | 4 | CR-0731 | `{parent}/change-requests/CR-0731-slug.md` (flat) | ### Status Determines Editability | Editable (direct edit OK) | Locked (needs Change Request) | |---------------------------|------------------------------| | draft, review, approved | in-development, under-test, released, deprecated | ## Directory Structure SPECLAN specifications live in `${PROJECT}/speclan/`: ``` speclan/ ├── goals/ # G-### Business goals (flat) ├── features/ # F-#### Feature hierarchy │ └── F-1049-pet-management/ │ ├── F-1049-pet-management.md # Feature file matches directory │ ├── requirements/ # Requirements as directories │ │ ├── R-2046-health-check/ │ │ │ ├── R-2046-health-check.md │ │ │ └── change-requests/ # CRs for this requirement │ │ └── R-3272-status-tracking/ │ │ └── R-3272-status-tracking.md │ ├── change-requests/ # CRs for this feature │ │ └── CR-0731-add-feature.md │ └── F-1200-pet-health/ # Child feature (nested) │ └── F-1200-pet-health.md ├── templates/ # Templates (UUID in frontmatter, slug filename) │ ├── features/ │ └── requirements/ └── change-requests/ # Root-level change requests ``` **Key structural rules:** - **Features and Requirements use directory-based storage** - directory name must match contained markdown filename - Requirements are nested inside their parent feature's `requirements/` directory as subdirectories - Child features are subdirectories of parent features - Change requests live in `change-requests/` adjacent to the entity they modify (features OR requirements) ## Entity Hierarchy ``` Goal (G-###) └── Feature (F-####) [forms hierarchical tree via directories] └── Requirement (R-####) ``` Additional entities: - **Template** (UUID v4) - Reusable spec templates - **ChangeRequest** (CR-####) - Modifications to released entities ## ID Format Conventions | Entity | Format | Example | Storage Location | |--------|--------|---------|------------------| | Goal | `G-###` | G-292 | `goals/` (flat files) | | Feature | `F-####` | F-1049 | `features/` (hierarchical directories) | | Requirement | `R-####` | R-2046 | `features/{feature}/requirements/` (directories) | | ChangeRequest | `CR-####` | CR-0731 | `{entity}/change-requests/` (flat files) | | Template | UUID v4 | bf5cb38b-... | `templates/{type}/` (flat files) | **ID Generation:** All numeric IDs are **randomly generated** with collision detection (not sequential). Always check existing IDs before creating new ones. **ID-Based Ordering:** IDs determine artifact priority/order numerically: - **Lower IDs = Higher priority** (processed/displayed first) - **Higher IDs = Lower priority** (processed/displayed later) - Example: F-1049 has higher priority than F-2847 - This ordering applies within the same entity type (features sorted among features, requirements among requirements, etc.) ## File Naming Convention Files follow pattern: `-kebab-case-title.md` Examples: - `G-292-comprehensive-pet-retail-operations.md` (flat file in goals/) - `F-1049-pet-management/F-1049-pet-management.md` (directory-based) - `R-2046-health-check/R-2046-health-check.md` (directory-based) **Directory-based entities** (Features, Requirements): - Directory name **must match** the contained markdown filename - Example: `F-1049-pet-management/F-1049-pet-management.md` - Example: `R-2046-health-check/R-2046-health-check.md` Template filenames use **kebab-case slugs** (UUID stored in frontmatter only): - `basic-feature.md` - `functional-requirement.md` ## Markdown File Format Every spec file has YAML frontmatter followed by markdown content. The **body MUST start with an H1 heading (`# Title`) matching the `title` field** from the frontmatter: ```markdown --- id: F-1049 type: feature title: Pet Management status: draft owner: Store Manager created: "2025-12-29T09:53:49.355Z" updated: "2025-12-29T10:31:04.445Z" goals: - G-292 - G-087 --- # Pet Management ← REQUIRED: H1 must match frontmatter title ## Overview Brief description of what this feature does and why it exists. ## User Story As a **Store Manager**, I want **comprehensive tools** so that **I can track pets**. ## Scope - Pet Tracking - Status Management - Health Records ``` **Structural rules:** - First line after frontmatter MUST be `# {title}` (H1 heading) - Subsequent sections use `## Heading` (H2) and below - No content before the H1 heading ## Common YAML Frontmatter Fields **All entities share:** ```yaml id: # Required type: # Required: goal|feature|requirement|template|changeRequest title: # Required status: # Required: draft|review|approved|in-development|under-test|released|deprecated owner: # Required created: # Required updated: # Required tags: [, ...] # Optional ``` **Entity-specific fields** - See `references/entity-fields.md` for complete reference. ## Status Lifecycle Entities follow a 7-stage lifecycle: ``` draft → review → approved → in-development → under-test → released → deprecated ``` | Status | Editable | Description | |--------|----------|-------------| | `draft` | Yes | Initial creation, work in progress | | `review` | Yes | Ready for review | | `approved` | Yes | Approved, ready for development | | `in-development` | **No** | Currently being implemented | | `under-test` | **No** | Implementation complete, testing | | `released` | **No** | Deployed to production | | `deprecated` | **No** | No longer active (terminal state) | **Read-only statuses:** Entities in `in-development`, `under-test`, `released`, or `deprecated` are locked. Direct edits are not allowed - changes require a **Change Request** (`CR-####`). ## Validation Rules For complete validation rules including ID format regex, directory naming enforcement, parent-child relationship validation, status lifecycle rules, and entity-specific field validation, consult `references/validation-rules.md`. ## Linking Between Specs ### YAML Frontmatter References ```yaml # Goal references features contributors: - F-1049 - F-2247 # Feature references goals goals: - G-292 - G-087 # Requirement references parent feature feature: F-1009 ``` ### Markdown Cross-References Use relative paths in markdown content: ```markdown ## Related ### Goals - [Animal Welfare Compliance](../goals/G-087-animal-welfare-compliance.md) ### Features - [Pet Status Lifecycle](../F-1807-pet-status-lifecycle/F-1807-pet-status-lifecycle.md) ``` ## Working with SPECLAN Files ### Detecting SPECLAN Directory To find the speclan directory in a project: 1. Check common locations: `speclan/`, `specs/speclan/`, `.speclan/`, `.specs/speclan/` — any of these may be a symlink (e.g. a repo-root `speclan` symlink into a spec submodule) 2. Look for characteristic subdirectories: `features/` and/or `goals/` (requirements never appear top-level; young projects may lack `goals/`) 3. Verify markdown files with SPECLAN YAML frontmatter ### Reading Specifications When reading a spec file: 1. Parse YAML frontmatter for metadata 2. Extract entity relationships from frontmatter fields 3. Parse markdown content for documentation ### Creating New Specifications To create a new spec: 1. **Check for user templates FIRST:** ``` speclan/templates// ``` - `speclan/templates/features/` for feature templates - `speclan/templates/requirements/` for requirement templates Read available templates and choose the best fit. Templates contain the user's preferred structure. 2. **Generate a unique ID** using the speclan-id-generator: ```bash SCRIPT="${CLAUDE_PLUGIN_ROOT}/skills/speclan-id-generator/scripts/generate-id.mjs" # Generate a feature ID (collision-free, end-biased) node "$SCRIPT" --type feature --speclan-root speclan --raw # Generate a child feature ID under a parent node "$SCRIPT" --type feature --parent F-1049 --speclan-root speclan --raw # Generate a requirement ID under a feature node "$SCRIPT" --type requirement --parent F-1049 --speclan-root speclan --raw ``` 3. **Create file in correct location:** **For Goals:** `speclan/goals/G-###-slug.md` (flat file) **For Features:** Create directory AND file with matching name: ``` speclan/features/F-####-slug/F-####-slug.md ``` **For Requirements:** Create directory inside parent feature's `requirements/`: ``` speclan/features/F-####-parent/requirements/R-####-slug/R-####-slug.md ``` **For Child Features:** Nest inside parent feature directory: ``` speclan/features/F-####-parent/F-####-child/F-####-child.md ``` 4. **Write frontmatter and content:** - Use template if found, otherwise use default structure - Set all required fields (id, type, title, status, owner, created, updated) - For requirements, set `feature: F-####` to link to parent 5. **Update related entities** to establish bidirectional links ### Updating Specifications When modifying a spec: 1. Update the `updated` timestamp 2. Maintain bidirectional links (if adding feature to goal, add goal to feature) 3. Follow status transition rules ## Writing Guidelines For guidance on writing effective specifications, consult `references/writing-guide.md`. Key principles: - Write user-focused, implementation-agnostic specifications - Include clear acceptance criteria as checkbox lists in requirements (Given/When/Then logic) - Maintain traceability between entities - Use consistent terminology ## Additional Resources ### Reference Files - **`references/entity-fields.md`** - Complete YAML field reference for all entity types - **`references/writing-guide.md`** - Best practices for writing specifications ### Related Skills - **`speclan-id-generator`** - Generate collision-free unique IDs for SPECLAN entities ### Utility Scripts - **`scripts/detect-speclan.mjs`** - Detect speclan directory in a project (`SPECLAN_ROOT=$(node scripts/detect-speclan.mjs)`)