### Install MSL Tools with pip Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/guides/quick-start.md Installs the msl-tools package globally using pip. This provides command-line utilities for working with MSL specifications. ```bash pip install msl-tools ``` -------------------------------- ### MSL Progressive Detail Example Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/guides/quick-start.md Illustrates the MSL approach of starting with simple requirements and progressively adding more detail as needed, showing a simple requirement followed by a more detailed version. ```markdown ## Requirements - User login ``` ```markdown ## Requirements - REQ-001: User login - Email or username - Password validation - Remember me option - OAuth support ``` -------------------------------- ### Basic MSL Specification Example Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/guides/quick-start.md A simple MSL specification file for User Authentication. It uses basic markdown headings and lists to define requirements. ```markdown # User Authentication ## Summary Basic authentication system for web application. ## Requirements - Users can register with email and password - Email verification required - Password reset via email - Session timeout after 30 minutes ``` -------------------------------- ### Extended Specification Example (MSL Level 2) Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/getting-started.md An example of a Level 2 MSL specification for an 'Admin API' that extends a 'User API' specification. It shows how to override existing requirements and add new ones using inheritance. ```markdown --- id: admin-api extends: user-api --- # Admin API ## Requirements - REQ-006: [NEW] DELETE /users/{id} removes user - REQ-007: [NEW] PUT /users/{id}/ban bans user - REQ-004: [OVERRIDE] Requires admin API key ``` -------------------------------- ### MSL Specification for Test Coverage Tracking Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/guides/quick-start.md An example MSL specification showing how to track test coverage directly within requirements, using markers like [x] for completed and referencing test file locations. ```markdown ## Requirements - REQ-001: [x] Login with email (test: auth.test.js:15) - REQ-002: [ ] Login with username - REQ-003: [x] Password reset (test: auth.test.js:45) ``` -------------------------------- ### API Specification Example (MSL Level 1) Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/getting-started.md This snippet shows a Level 1 MSL specification for a 'User API'. It includes metadata in the frontmatter and numbered requirements for API endpoints, demonstrating structured documentation for APIs. ```markdown --- id: user-api version: 1.0 tags: [api, rest, json] --- # User API ## Requirements - REQ-001: GET /users returns user list - REQ-002: GET /users/{id} returns single user - REQ-003: POST /users creates new user - REQ-004: All endpoints require API key - REQ-005: Responses use JSON format ``` -------------------------------- ### Simple Feature Spec Example (MSL Level 0) Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/getting-started.md A Level 0 MSL specification for a 'User Profile Feature'. It uses simple markdown to outline requirements, suitable for straightforward feature descriptions. ```markdown # User Profile Feature ## Requirements - Users can upload profile photo - Users can set display name - Users can write bio (max 500 chars) - Profile is public by default - Users can make profile private ``` -------------------------------- ### MSL Specification from User Story Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/guides/quick-start.md Demonstrates converting a user story into an MSL specification, including a feature title and nested requirements that outline the 'Given-When-Then' scenario. ```markdown # Feature: User Login ## Requirements - REQ-001: Users can log in with valid credentials - Given a registered user - When they provide correct email/password - Then they are authenticated ``` -------------------------------- ### MSL Tools Docker Installation Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/tools.md Dockerfile snippet for setting up an environment to use MSL tools, including installing globally and setting a default command. ```dockerfile FROM node:16-alpine RUN npm install -g msl-tools WORKDIR /specs CMD ["msl-validate", "."] ``` -------------------------------- ### MSL Render Usage Example Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/tools.md Example command demonstrating how to use msl-render with a custom HTML template to generate an output file. ```bash msl-render spec.md -t template.html -o output.html ``` -------------------------------- ### Clone MSL Repository and Lint Specification Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/guides/quick-start.md Clones the msl-specification repository and demonstrates how to use the msl-lint tool directly from the cloned repository to check a specification file. ```bash git clone https://github.com/chrs-myrs/msl-specification.git cd msl-specification python tools/cli/msl-lint your-spec.md ``` -------------------------------- ### MSL Validation with msl-lint Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/guides/quick-start.md Command-line examples for using msl-lint to validate MSL specification files. This includes linting a single file, a directory, and checking for ID conflicts. ```bash # Lint a single file msl-lint user-auth.md # Lint all specs in directory msl-lint specs/ # Check for ID conflicts msl-lint --check-ids specs/ ``` -------------------------------- ### MSL Specification with Metadata and Markers Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/guides/quick-start.md An MSL specification that includes frontmatter for metadata (id, tags, priority, status) and uses quick markers like [!] for critical priority. ```markdown --- id: user-auth tags: [security, backend] priority: high status: draft --- # User Authentication ## Requirements - REQ-001: [!] Users can register with email and password - REQ-002: [!] Email verification required - REQ-003: Password reset via email - REQ-004: Session timeout after 30 minutes ``` -------------------------------- ### Create Payment Processing Spec (MSL Level 0) Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/getting-started.md An example of a Level 0 MSL specification, utilizing only standard markdown features. This level is suitable for quick notes, early drafts, and simple projects where advanced structuring is not required. ```markdown # Payment Processing ## Requirements - Accept credit cards - Support refunds - Send receipts ``` -------------------------------- ### Setup MSL Validation Tools (Bash) Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/workflows/solo.md Installs the 'msl-tools' package as a development dependency, configures an npm script for validation, and runs the initial validation command. This ensures specifications adhere to defined rules. ```bash # Install MSL tools locally npm init -y npm install --save-dev msl-tools # Add validation script npm set-script validate "msl-validate ./specs/" # Run first validation npm run validate ``` -------------------------------- ### Create Advanced Payment Spec (MSL Level 2) Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/getting-started.md An example of an MSL Level 2 specification, demonstrating inheritance using the 'extends' keyword in the frontmatter. This level is ideal for complex systems, large projects, and managing specifications with shared elements. ```markdown --- id: payment-v3 extends: payment-v2 --- # Payment Processing V3 ## Requirements - REQ-001: [OVERRIDE] Accept cards and crypto - REQ-004: [NEW] Support installment payments ``` -------------------------------- ### MSL Template Definition Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/guides/quick-start.md Defines a reusable MSL template (`api-base.md`) with placeholders for dynamic content, using frontmatter to declare it as a template. ```markdown --- id: api-template type: template --- # ${service_name} API ## Requirements - REQ-001: RESTful endpoints - REQ-002: JSON request/response - REQ-003: Rate limiting ``` -------------------------------- ### Suggested MSL Project File Structure Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/guides/quick-start.md A recommended directory structure for organizing MSL specification files within a project, separating features, APIs, templates, and high-level documents. ```treeview project/ ├── specs/ │ ├── features/ # Feature specifications │ ├── apis/ # API specifications │ └── templates/ # Reusable templates ├── requirements.md # High-level requirements └── architecture.md # System architecture ``` -------------------------------- ### Global MSL Tools Installation (npm) Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/tools.md Commands for globally installing MSL tools using npm, including installing all tools at once or individually. ```bash # Install all MSL tools globally npm install -g msl-tools # Or install individually npm install -g msl-validate msl-lint msl-render msl-batch-validate # Verify installation msl-validate --version ``` -------------------------------- ### MSL Specification Using Inheritance Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/guides/quick-start.md An MSL specification (`payment-api.md`) that extends a template (`api-template`). It shows how to inherit, override, and add new requirements. ```markdown --- extends: api-template variables: service_name: Payment --- # ${service_name} API ## Requirements - REQ-001: [INHERIT] RESTful endpoints - REQ-002: [INHERIT] JSON request/response - REQ-003: [OVERRIDE] Rate limiting: 100 req/min - REQ-004: [NEW] PCI compliance required ``` -------------------------------- ### Anti-Pattern: Starting Too Complex Example Source: https://github.com/chrs-myrs/msl-specification/blob/master/AGENTS.md Highlights the anti-pattern of starting with excessive complexity (L2, templates, markers) when a simpler approach (L0) would suffice. Emphasizes starting simple and adding complexity as needed. ```markdown Bad: Starting with L2, templates, and markers Good: Starting with L0, adding features as needed ``` -------------------------------- ### Claude Code Agent: MSL Validation Agent - Fix Suggestions Example Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/tools.md Shows an example of invoking the MSL Validation Agent to get specific suggestions for improving the testability of requirements, including 'Before' and 'After' examples. ```markdown @claude-code suggest fixes Request: "How can I improve the testability of my requirements?" Response: "Here are specific improvements for testability: Before: 'System should be fast' After: 'API responds within 200ms for 95th percentile' Before: 'Good error handling' After: 'Returns 400 with specific error message for invalid input' Before: 'Secure authentication' After: 'Requires valid JWT token with exp claim < 1 hour'" ``` -------------------------------- ### Global MSL Configuration Example (YAML) Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/workflows/solo.md An example YAML configuration file for global MSL settings. It demonstrates how to set default values like minimum score and author, and configure project-specific paths for specifications. ```yaml # ~/.msl-global.yml defaults: minScore: 80 author: "Your Name" projects: project-a: path: ~/projects/a/specs project-b: path: ~/projects/b/specs ``` -------------------------------- ### Python Development Environment Setup (Bash) Source: https://github.com/chrs-myrs/msl-specification/blob/master/CONTRIBUTING.md Commands for setting up a Python virtual environment, installing development dependencies, and running tests and linters for MSL development. ```bash # Create virtual environment python3 -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate # Install development dependencies pip install -r requirements-dev.txt # Run tests python -m pytest tools/tests/ # Run linter on examples ./tools/cli/msl-lint examples/ ``` -------------------------------- ### Create Initial Login System Spec (MSL Level 0) Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/getting-started.md This snippet demonstrates the creation of a basic MSL specification using pure markdown. It includes a title and a 'Requirements' section, which is the minimum requirement for a valid MSL document. ```markdown # Login System ## Requirements - Users can log in with username and password - System remembers users for 30 days - Password reset via email ``` -------------------------------- ### Validate MSL Specification (CLI) Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/getting-started.md This command-line snippet shows how to validate an MSL specification file using the 'msl-lint' tool, which requires Node.js to be installed. It checks the structure and syntax of the MSL document. ```bash # If you have Node.js: npx msl-lint login-system.md ``` -------------------------------- ### MSL CLI Help and Version Information Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/tools.md Provides instructions on how to display help messages for any MSL command, check the installed version of MSL tools, and verify the installation using the 'doctor' command. ```bash # Show help for any command msl-validate --help msl-lint --help msl-render --help # Show version msl-validate --version # Check installation msl-tools doctor ``` -------------------------------- ### Custom HTML Template Example Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/tools.md An example of a custom HTML template used with msl-render to define the structure and styling of the output. ```html {{title}}
{{header}}
{{content}}
``` -------------------------------- ### MSL Validator CLI Example Workflows Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/tools.md Provides practical examples of using the msl-validate CLI tool for common workflows like basic validation, enforcing quality scores, batch processing, and CI integration. ```bash # Validate and show results msl-validate user-auth.md # Output: # ✓ user-auth.md # Quality Score: 85/100 # DRY Compliance: 90/100 # Testability: 82/100 # No critical issues found # Require minimum score of 90 msl-validate spec.md --min-score 90 # Check specific rules only msl-validate spec.md --rules dry,testability # Strict mode (fail on warnings) msl-validate spec.md --strict # Validate all specs with JSON output msl-validate ./specs/ -r -f json -o results.json # Fix common issues automatically msl-validate ./specs/ -r --fix # Silent mode for CI msl-validate ./specs/ -r -q || exit 1 # Generate markdown report msl-validate ./specs/ -r -f markdown -o validation-report.md ``` -------------------------------- ### MSL Specification with Requirement IDs Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/guides/quick-start.md An MSL specification demonstrating the use of unique IDs (e.g., REQ-001) for requirements, enabling easier referencing and tracking. ```markdown # User Authentication ## Requirements - REQ-001: Users can register with email and password - REQ-002: Email verification required - REQ-003: Password reset via email - REQ-004: Session timeout after 30 minutes ``` -------------------------------- ### MSL Validation Configuration Example (.yml) Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/tools.md Example configuration file (.msl-validate.yml) for MSL validation tools, defining rules, file patterns, quality thresholds, and validation behavior. ```yaml # .msl-validate.yml version: 1 rules: # Validation rules dry-compliance: enabled: true threshold: 85 testability: enabled: true min-score: 90 inheritance-depth: enabled: true max-depth: 3 # File patterns include: - "specs/**/*.md" - "requirements/**/*.md" exclude: - "**/*.draft.md" - "**/archive/**" # Quality thresholds quality: min-overall-score: 80 min-dry-score: 85 min-testability: 90 min-cohesion: 80 # Output settings output: format: text colors: true verbose: false # Validation behavior validation: fail-on-warning: false fix-automatically: false check-references: true check-inheritance: true ``` -------------------------------- ### Project MSL Tools Installation (npm) Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/tools.md Commands for adding MSL tools as development dependencies to a project and configuring npm scripts for validation and linting. ```bash # Add to project npm install --save-dev msl-tools # Add npm scripts { "scripts": { "validate": "msl-validate ./specs/ -r", "lint": "msl-lint ./specs/ -r", "validate:ci": "msl-validate ./specs/ -r -q --min-score 85" } } ``` -------------------------------- ### Complete Specification with Code Links Example Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/user-guide.md A comprehensive Markdown example of a specification module ('Authentication Module') demonstrating nested requirements with bidirectional and forward code links, including specific file paths and line ranges. ```markdown # Authentication Module [MSL] ## Requirements ### Core Authentication - REQ-001: [↔ src/auth/core.py:45-120] User authentication via OAuth 2.0 - REQ-001.1: [→ src/auth/oauth.py:15-45] OAuth token generation - REQ-001.2: [→ src/auth/oauth.py:50-75] Token refresh mechanism - REQ-001.3: [← tests/auth_test.py:100-200] Token validation tests ### Security Features - REQ-002: [!|security|↔ src/auth/security.py] Security controls - REQ-002.1: [→ src/auth/security.py:25-40] Password hashing with bcrypt - REQ-002.2: [→ src/auth/security.py:45-60] Rate limiting implementation - REQ-002.3: [→ src/auth/security.py:65-90] Session timeout handling ### API Endpoints - REQ-003: [→ src/api/auth.js:100-150] REST API authentication endpoints - REQ-003.1: [→ src/api/auth.js:100-110] POST /auth/login - REQ-003.2: [→ src/api/auth.js:115-125] POST /auth/logout - REQ-003.3: [→ src/api/auth.js:130-140] POST /auth/refresh ``` -------------------------------- ### MSL Invalid Syntax Examples Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/implementation-reference.md Examples highlighting common errors and invalid syntax in MSL documents. These include missing requirement markers, incorrect ID formatting, unrecognized inheritance markers, and undefined template variables, serving as a guide to avoid pitfalls. ```markdown ## Requirements REQ-001 Users must authenticate # Missing dash - REQ001: Wrong format # Wrong ID format (needs REQ-) - [INVALID] Unknown marker # Unknown inheritance marker - ${undefined_var} Template variable # Undefined variable ``` -------------------------------- ### Create Structured Payment Spec (MSL Level 1) Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/getting-started.md This snippet illustrates an MSL Level 1 specification, which includes frontmatter for metadata (id, version, assignee) and structured requirements with IDs. This level is beneficial for tracking requirements and team collaboration. ```markdown --- id: payment-v2 version: 2.0 assignee: payments-team --- # Payment Processing ## Requirements - REQ-001: Accept credit cards - REQ-002: Support refunds within 30 days - REQ-003: Email receipts immediately ``` -------------------------------- ### Context Loading and AI Processing (TypeScript) Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/tools.md Demonstrates how to load an MSL context and then process it using an AI service. This example shows asynchronous operations for loading context and performing tasks. ```typescript // Load MSL context const context = await mcp.loadContext('msl', { directory: './specs', maxSize: 100000 }); // Process with AI const result = await ai.process(context, { task: 'validate', options: { detailed: true } }); ``` -------------------------------- ### Quick Start Template L0 Markdown Source: https://github.com/chrs-myrs/msl-specification/blob/master/AGENTS.md A basic Markdown template for creating simple specifications. It includes a title, summary, and a list of requirements. This is the recommended starting point for most specifications. ```markdown # [Component/Feature Name] [MSL] ## Summary [One clear sentence describing what this specifies] ## Requirements - [Specific, testable requirement] - [Another requirement focused on WHAT, not HOW] - [Keep requirements high-level when possible] ``` -------------------------------- ### Setup MSL Tools and CI/CD (Bash/YAML) Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/workflows/team.md Commands for setting up the MSL environment, including creating a specifications directory, adding it to Git, installing MSL tools via npm, and copying CI/CD pipeline templates. ```bash # Repository setup mkdir specs/ git add specs/ npm install --save-dev msl-tools # CI/CD pipeline cp templates/msl-ci.yml .github/workflows/ ``` -------------------------------- ### MSL Linter CLI Example Output Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/tools.md Illustrates the typical output format of the msl-lint tool, showing warnings and errors with line numbers, rule violations, and fixability information. ```bash $ msl-lint user-auth.md user-auth.md line 3:1 warning File should use kebab-case kebab-case-files line 15:1 error Duplicate requirement ID unique-req-ids line 22:1 warning Missing priority marker require-priority ✖ 3 problems (1 error, 2 warnings) 1 error and 0 warnings potentially fixable with --fix ``` -------------------------------- ### MSL Specification Structure Example Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/workflows/ai.md An example of how to structure a prompt for generating an MSL specification, including context, task, constraints, format, examples, and desired output. ```markdown ## Optimal Prompt Structure 1. **Context**: "We're building an e-commerce platform" 2. **Task**: "Create an MSL specification for shopping cart functionality" 3. **Constraints**: "Must support guest checkout, save for later, and bulk discounts" 4. **Format**: "Use MSL Level 1 with REQ-XXX format" 5. **Examples**: "Similar to our existing order-api.md specification" 6. **Output**: "Include error cases and performance requirements" ``` -------------------------------- ### Install MSL Tools via npm Source: https://github.com/chrs-myrs/msl-specification/blob/master/RELEASE_CHECKLIST.md This command installs the MSL tools globally on the system using npm, specifying version 1.2.0. Global installation makes the MSL CLI commands available from any directory in the terminal. The `@1.2.0` tag ensures the specific release version is installed. ```bash npm install -g msl-tools@1.2.0 ``` -------------------------------- ### Initialize Project and Create First Specification (Bash) Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/workflows/solo.md Sets up a new project directory, initializes Git, creates a basic directory structure, and writes the initial content for a 'login.md' specification file. This is the first step in organizing project specifications. ```bash # Create project structure mkdir -p my-project/specs cd my-project # Initialize git git init echo "specs/" >> .gitignore # Initially ignore specs # Create first spec echo "# Login Feature ## Requirements - Users can log in with email - Session lasts 24 hours - Show error for wrong password" > specs/login.md ``` -------------------------------- ### Example Usage of MSLParser - Python Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/implementation-reference.md This Python code snippet demonstrates the usage of the MSLParser class. It includes an example MSL string with various requirement formats and markers, then parses it using the parser instance. The output shows the parsed specification's level, metadata ID, and a count of requirements, along with truncated text for each requirement. This example requires the MSLParser class to be defined and imported. ```python # Example usage if __name__ == "__main__": parser = MSLParser() example = '''--- id: example-spec extends: base-spec --- # Example Specification ## Requirements - [!] [@alice] REQ-001: [NEW] Critical requirement - [x] REQ-002: [INHERIT] Completed requirement - [progress:60%|coverage:85%] REQ-003: Composite markers - Simple requirement without ID or markers ''' result = parser.parse(example) print(f"Level: {result['level']}") print(f"ID: {result['metadata'].get('id')}") print(f"Requirements: {len(result['requirements'])}") for req in result["requirements"]: print(f" - {req.get('id', 'NO-ID')}: {req['text'][:50]}...") ``` -------------------------------- ### Set Up Node.js Development Environment Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/contributing.md This bash snippet outlines the initial steps for setting up the MSL development environment. It includes checking the Node.js version, installing project dependencies using npm, and globally installing MSL tools for development use. ```bash # Node.js 14+ required node --version # Install dependencies npm install # Install MSL tools globally npm install -g msl-tools ``` -------------------------------- ### Basic MSL Specification Example Source: https://github.com/chrs-myrs/msl-specification/blob/master/README.md A fundamental example of an MSL specification demonstrating the structure for a project, including a title and a list of requirements. ```markdown # Your Project Specification ## Requirements - REQ-001: Clear requirement statement - REQ-002: Another requirement ``` -------------------------------- ### MSL Level 0 - Simple Specification Example Source: https://github.com/chrs-myrs/msl-specification/blob/master/specs/README.md An example of a basic MSL specification using only markdown and a requirements section. This level is human-friendly and requires no specific tools. ```markdown # My Feature [MSL] ## Requirements - System does X - Users can Y - Performance is Z --- *Specified using [MSL](https://github.com/chrs-myrs/msl-specification)* ``` -------------------------------- ### MSL Quickstart: Create, Validate, and Implement Source: https://github.com/chrs-myrs/msl-specification/blob/master/README.md This bash script demonstrates the initial steps of using MSL. It shows how to create a simple specification file in markdown, validate it using the 'msl-validate' command, and then pass it to an AI for implementation. ```bash # MSL is a specification language - no installation needed! # Just write markdown with requirements: # Create your first specification echo '# Login Feature ## Requirements - Users authenticate with email/password - Sessions expire after 24 hours - Lock account after 5 failed attempts' > login.md # Validate your specification msl-validate login.md # Give to AI for implementation # "Claude, implement the login feature from login.md" # → Receive precise, tested implementation ``` -------------------------------- ### Anti-Pattern: Over-specification Example Source: https://github.com/chrs-myrs/msl-specification/blob/master/AGENTS.md Demonstrates an anti-pattern of over-specifying details versus stating high-level requirements. The 'Good' example focuses on the outcome, not the implementation specifics. ```markdown Bad: "Button must be exactly 120px wide with #007bff color" Good: "Submit button must be clearly visible" ``` -------------------------------- ### Minimal Personal Spec Example (Markdown) Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/spec/v1.1/specification.md A basic MSL specification example demonstrating a title, the '## Requirements' section, and inline markers for requirement status. ```markdown # Weekend Project ## Requirements - [!] Fix login bug - Add dark mode - [ ] Write tests ``` -------------------------------- ### Bidirectional and Forward Code Links Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/user-guide.md Examples of Markdown syntax for creating bidirectional (↔, <->) and forward (→, ->) links from requirements to specific code locations, including line number ranges and whole files. ```markdown - REQ-001: [↔ src/auth.js:45-67] Authentication implementation - REQ-002: [<-> lib/validator.py:100] Input validation logic - REQ-003: [→ app/main.java:25] Entry point implementation - REQ-004: [-> tests/integration.test.js] Integration test coverage ``` -------------------------------- ### Build and Serve Local Documentation Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/contributing.md This bash snippet details how to build the project's documentation and serve it locally. 'npm run docs:build' generates the documentation files, and 'npm run docs:serve' starts a local server, typically accessible at http://localhost:3000. ```bash # Generate documentation npm run docs:build # Serve documentation locally npm run docs:serve # Visit http://localhost:3000 ``` -------------------------------- ### Integrate MSL Validation into Jenkins Pipeline Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/tools.md This Jenkinsfile defines a declarative pipeline for MSL validation. It includes stages for setup (installing MSL tools), linting, validation with a configurable minimum score, and report generation. It archives generated reports as artifacts. ```groovy // Jenkinsfile pipeline { agent any environment { MSL_MIN_SCORE = '85' } stages { stage('Setup') { steps { sh 'npm install -g msl-tools' } } stage('Lint') { steps { sh 'msl-lint ./specs/ -r' } } stage('Validate') { steps { sh 'msl-validate ./specs/ -r --min-score ${MSL_MIN_SCORE}' } } stage('Report') { steps { sh 'msl-batch-validate ./specs/ -f json -o report.json' publishHTML([ reportDir: '.', reportFiles: 'report.html', reportName: 'MSL Validation Report' ]) } } } post { always { archiveArtifacts artifacts: 'report.*', fingerprint: true } } } ``` -------------------------------- ### MSL Batch Validation Report Example Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/tools.md An example of a comprehensive batch validation report generated by msl-batch-validate, including summary, metrics, and issue details. ```markdown # MSL Batch Validation Report **Date:** 2024-01-15 **Directory:** ./specs/ **Files Analyzed:** 47 ## Summary - ✅ Valid Specifications: 43/47 (91.5%) - ⚠️ Warnings: 12 - ❌ Errors: 4 ## Quality Metrics | Metric | Average | Min | Max | |--------|---------|-----|-----| | Overall Score | 82.3 | 68 | 95 | | DRY Compliance | 86.1 | 72 | 98 | | Testability | 78.9 | 65 | 92 | ## Inheritance Analysis ```mermaid graph TD base-api --> user-api base-api --> admin-api user-api --> premium-api ``` ## Issues by Severity ### Critical (4) 1. `payment-api.md:15` - Circular inheritance detected 2. `auth-spec.md:23` - Missing Requirements section ### Warnings (12) 1. `user-profile.md` - Low testability score (65%) 2. `data-schema.md` - DRY violations detected ``` -------------------------------- ### Minimal Compliant llms.txt Example Source: https://github.com/chrs-myrs/msl-specification/blob/master/specs/context7-optimization/msl-llms-txt-spec.md A basic example of an llms.txt file that adheres to the specified requirements. It includes an overview, core language specifications, an implementation guide, a quick example, search topics, and metadata. This file is designed to be both human-readable and AI-parseable. ```markdown # MSL - Markdown Specification Language MSL enables precise requirement specifications using plain markdown, progressing from simple lists to validated, inheritable specifications with templates. It bridges human intent and AI implementation. ## Core Language Specifications (Read in Order) 1. [Level 0 Foundation](specs/msl-l0-foundation.md) - Pure markdown with requirements 2. [Level 1 Structure](specs/msl-l1-structure.md) - Adds IDs and frontmatter 3. [Level 2 Advanced](specs/msl-l2-advanced.md) - Full features with formal grammar ## Implementation Guide Complete implementation details: [Implementation Reference](docs/implementation-reference.md) - BNF grammar for parsing - Python validator implementation - Runnable examples - Quality metrics ## Quick Example ```markdown # Login System ## Requirements - Users can authenticate with email/password - Sessions expire after 30 minutes ``` Topics: specification, requirements, markdown, validation, inheritance, templates, msl Version: 1.2.1 | Updated: 2025-01-05 | Repo: github.com/chrs-myrs/msl-specification ``` -------------------------------- ### Install MSL Validator CLI Tool Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/tools.md Installs the msl-validate command-line tool globally or as a development dependency using npm or yarn. This tool is used for validating MSL specifications. ```bash # npm (global) npm install -g msl-validate # npm (project) npm install --save-dev msl-validate # yarn yarn add -D msl-validate ``` -------------------------------- ### MSL Resource Links and Output Mapping Example Source: https://github.com/chrs-myrs/msl-specification/blob/master/specs/msl-l2-advanced.md Demonstrates how MSL supports resource links for documentation, tutorials, configuration files, and API specifications using specific arrow notations (→, ←, ↔). It also shows traditional resource links. ```markdown ## Requirements ### Documentation Generation - REQ-101: [!] MUST generate [→ comprehensive user guide](docs/user-guide.md) - REQ-102: MUST include tutorials: - [→ Getting started tutorial](tutorials/getting-started.md) - [→ Advanced features tutorial](tutorials/advanced.md) - REQ-103: Tool configuration from [← config file](config.yaml) - REQ-104: API specification [↔ OpenAPI schema](api/openapi.yaml) ### Traditional Resource Links (still supported) - REQ-201: Implementation references [→ auth.ts:45-67] - REQ-202: Follows pattern from [← design-patterns.md] ``` -------------------------------- ### AI Prompt for Cross-AI Verification (Markdown) Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/tutorials/ai-implementation.md A strategy involving two different AI models (e.g., ChatGPT and Claude) to verify each other's implementations against a specification. This snippet shows example prompts for each AI, asking them to review the other's output for compliance, missing requirements, and potential improvements. ```markdown # To ChatGPT: "Review this Claude-generated implementation against the specification. Identify any missing requirements or deviations." # To Claude: "Review this ChatGPT-generated implementation against the specification. Suggest improvements for requirement compliance." ``` -------------------------------- ### Troubleshooting: 'Command not found' (Bash) Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/tools.md Provides solutions for the 'msl-validate: command not found' error. It suggests installing the package globally or using 'npx' to run the command without a local installation. ```bash $ msl-validate bash: msl-validate: command not found **Solution:** Install globally or use npx ```bash npm install -g msl-tools # or npx msl-validate spec.md ``` ``` -------------------------------- ### Prompt AI for Implementation with Markdown Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/tutorials/first-spec.md This snippet provides an example prompt for an AI assistant to implement the task management system based on a completed MSL specification. It includes pasting the specification and suggesting a frontend framework (React). ```markdown Prompt: "Please implement this task management system according to the specification in task-manager.md: [Paste your complete specification] Use React for the frontend." ``` -------------------------------- ### AI Prompt for Incremental Specification Implementation Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/tutorials/ai-implementation.md This prompt is designed for AI assistants with shorter context windows, like GitHub Copilot. It asks the AI to implement a specific range of requirements (e.g., REQ-001 through REQ-005) from a provided specification snippet, focusing on core functionality. ```markdown "Implement requirements REQ-001 through REQ-005 from this specification: ### Core Functionality - REQ-001: Users can create tasks with title (required) and description (optional) - REQ-002: Tasks have three states: todo, in-progress, done - REQ-003: Users can update task state following valid transitions - REQ-004: Users can permanently delete tasks - REQ-005: Tasks display in list sorted by creation date (newest first)" ``` -------------------------------- ### Define Product Service from Template Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/tutorials/templates.md Creates a 'Product Catalog' service, also extending 'microservice-template', but with different configurations for database ('MongoDB') and authentication ('API Key'). ```markdown --- id: product-service extends: microservice-template variables: service_name: "Product Catalog" port: 8083 database: "MongoDB" # Different database! auth_method: "API Key" --- # Product Catalog Service ## Requirements ### Product-Specific Requirements - REQ-020: [NEW] Service manages product inventory - REQ-021: [NEW] Service supports product categories - REQ-022: [NEW] Service handles product images - REQ-023: [NEW] Service implements full-text search ``` -------------------------------- ### Component Specification Template (Markdown) Source: https://github.com/chrs-myrs/msl-specification/blob/master/examples/MSL-CONFIG.md This Markdown template outlines the structure for component specifications. It includes frontmatter for metadata, the component name, summary, and detailed requirements categorized into Interface, Behavior, and Performance. It also supports extending base components. ```markdown --- id: {component-name} tags: [component, {layer}] extends: {base-component} # if applicable --- # {Component Name} [MSL] ## Summary {Component responsibility} ## Requirements ### Interface - REQ-101: Public API surface - REQ-102: Input validation ### Behavior - REQ-201: Core functionality - REQ-202: Error handling ### Performance - REQ-301: Response time requirements - REQ-302: Resource constraints ``` -------------------------------- ### Basic Usage of MSL Renderer CLI Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/tools.md Demonstrates fundamental commands for the msl-render CLI tool to convert MSL specifications into different output formats like HTML, PDF, or generate documentation sites. ```bash # Render to HTML msl-render spec.md -o spec.html # Render to PDF msl-render spec.md -f pdf -o spec.pdf # Generate documentation site msl-render ./specs/ -f site -o ./docs/ ``` -------------------------------- ### CLI Usage Examples (Bash) Source: https://github.com/chrs-myrs/msl-specification/blob/master/specs/applications/msl-tools-spec.md Demonstrates common command-line invocations for MSL tools, including linting, rendering, and validation with various options. ```bash # Lint all MSL files in specs directory msl-lint specs/*.md # Render template with variables msl-render template.md -v service=UserAPI -v version=2.0 # Validate inheritance chains msl-validate --check-inheritance specs/ ``` -------------------------------- ### REST API Production-Ready Template Example Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/tutorials/templates.md This markdown snippet defines a comprehensive template for creating RESTful API services. It includes standard configurations for API name, version, port, authentication, rate limiting, response format, and optional features like pagination, filtering, and sorting. The template uses variables for customization and outlines common requirements and error handling patterns. ```markdown --- id: rest-api-template type: template variables: api_name: \"REST API\" version: \"v1\" port: 3000 auth_type: \"Bearer Token\" rate_limit_rpm: 600 response_format: \"JSON\" enable_pagination: true page_size: 20 enable_filtering: true enable_sorting: true enable_versioning: true --- # {{api_name}} {{version}} ## Summary RESTful API service implementing {{api_name}} with standard patterns. ## Requirements ### API Configuration - REQ-001: API runs on port {{port}} - REQ-002: API version {{version}} accessible at /{{version}}/ - REQ-003: API returns {{response_format}} responses ### Authentication & Security - REQ-010: API requires {{auth_type}} authentication - REQ-011: API rate limits to {{rate_limit_rpm}} requests/minute - REQ-012: API implements CORS for browser access - REQ-013: API sanitizes all input to prevent injection ### Standard Endpoints - REQ-020: GET /{{version}}/health returns service status - REQ-021: GET /{{version}}/info returns API metadata - REQ-022: OPTIONS requests return allowed methods {{#if enable_pagination}} ### Pagination - REQ-030: List endpoints support ?page and ?limit parameters - REQ-031: Default page size is {{page_size}} items - REQ-032: Response includes total count and page metadata {{/if}} {{#if enable_filtering}} ### Filtering - REQ-040: List endpoints support field-based filtering - REQ-041: Filters use query parameters: ?field=value - REQ-042: Multiple filters combine with AND logic {{/if}} {{#if enable_sorting}} ### Sorting - REQ-050: List endpoints support ?sort parameter - REQ-051: Sort format: ?sort=field:asc or field:desc - REQ-052: Multiple sort fields supported {{/if}} ### Error Handling - REQ-060: Errors return appropriate HTTP status codes - REQ-061: Error responses include code, message, details - REQ-062: Validation errors list all field issues ### Performance - REQ-070: API responds within 200ms for 95th percentile - REQ-071: API handles 100 concurrent connections - REQ-072: API implements request timeout of 30 seconds ``` -------------------------------- ### Generate To-Do List from Specification (Bash) Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/workflows/solo.md Extracts lines starting with 'REQ-' from a specification file and formats them as 'TODO' items in a separate file. This is useful for creating actionable tasks from defined requirements. ```bash # Generate todo list from spec grep "REQ-" specs/new-feature.md | sed 's/.*REQ/TODO REQ/' > TODO.md ``` -------------------------------- ### AI Prompt for Full Specification Implementation (React/TypeScript) Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/tutorials/ai-implementation.md This prompt instructs an AI assistant to implement an entire system based on a provided MSL specification, specifically requesting a React application with TypeScript. It emphasizes including all requirements and providing comments referencing requirement IDs and basic styling. ```markdown "Please implement a task management system according to this MSL specification. Create a complete React application with TypeScript. --- id: task-manager version: 1.0 --- # Task Management System ## Summary A simple task management system for tracking work items through defined states. ## Requirements ### Core Functionality - REQ-001: Users can create tasks with title (required) and description (optional) - REQ-002: Tasks have three states: todo, in-progress, done - REQ-003: Users can update task state following valid transitions - REQ-004: Users can permanently delete tasks - REQ-005: Tasks display in list sorted by creation date (newest first) ### Validation & Error Handling - REQ-006: Empty task titles are rejected with error message "Title is required" - REQ-007: Invalid state transitions return error "Invalid transition from {current} to {next}" - REQ-008: Deleted tasks return 404 error when accessed ### Performance & Limits - REQ-009: All task operations complete within 100ms - REQ-010: System supports maximum 1000 tasks - REQ-011: UI updates immediately (<16ms) on state change ### Data Persistence - REQ-012: Tasks persist in browser localStorage - REQ-013: Tasks survive page refresh without data loss - REQ-014: localStorage errors display "Unable to save tasks" with retry option Please include: 1. Complete implementation of all requirements 2. Comments referencing requirement IDs 3. Basic styling for usability" ``` -------------------------------- ### MSL Valid Markdown Syntax Examples Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/implementation-reference.md Examples demonstrating valid MSL syntax, ranging from basic Markdown to full-featured specifications including frontmatter, requirement IDs, and inheritance markers. These illustrate correct usage of the MSL grammar. ```markdown # My Specification ## Requirements - Users must authenticate - Sessions expire after 30 minutes ``` ```markdown --- id: auth-spec --- # Authentication ## Requirements - REQ-001: Users must authenticate - REQ-002: Sessions expire after 30 minutes ``` ```markdown --- id: payment-api extends: api-base --- # Payment API ## Requirements - [!] [@alice] REQ-001: [OVERRIDE] Process payments within 2 seconds - [x] [#mvp] REQ-002: [NEW] Support card payments - [progress:60%|coverage:85%] REQ-003: Implement refunds ``` -------------------------------- ### Add Mandatory Requirements Section (MSL Level 0) Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/getting-started.md This code shows the essential structure for any MSL specification: a title and a 'Requirements' section. Without this section, the markdown file is not considered a valid MSL document. ```markdown # My System ## Requirements - At least one requirement here ``` -------------------------------- ### Node.js API for MSL Tools (JavaScript) Source: https://github.com/chrs-myrs/msl-specification/blob/master/docs/tools.md Provides examples of using the 'msl-tools' library programmatically in Node.js for validation, linting with auto-fixing, and rendering specifications to HTML. It includes functions for validating individual files or directories. ```javascript const { validate, lint, render } = require('msl-tools'); // Validate programmatically async function validateSpecs() { const result = await validate('./specs/user-auth.md', { minScore: 85, rules: ['dry', 'testability'] }); console.log(`Score: ${result.score}/100`); console.log(`Issues: ${result.issues.length}`); result.issues.forEach(issue => { console.log(`${issue.file}:${issue.line} - ${issue.message}`); }); } // Lint with auto-fix async function lintAndFix() { const results = await lint('./specs/', { recursive: true, fix: true }); console.log(`Fixed ${results.fixed} issues`); } // Render to HTML async function generateDocs() { await render('./specs/', { format: 'site', output: './docs/', theme: 'default', includeToC: true }); } ```