telos-framework 0.9.2 → 0.10.1

package/templates/commands/quick.md

@@ -0,0 +1,143 @@
+# Telos Quick Initialization
+
+This is the fast-track initialization mode that accepts all AI-proposed specs
+without user review. Use this when you trust the AI analysis and want to get
+started immediately.
+
+## The 4-Level Hierarchy
+
+| Level | Name       | Description                                     |
+| ----- | ---------- | ----------------------------------------------- |
+| L4    | Purpose    | Why the project exists + success metrics        |
+| L3    | Experience | User journeys, UX requirements, analytics needs |
+| L2    | Contract   | API contracts, component interfaces, boundaries |
+| L1    | Function   | Individual functions with TDD scenarios         |
+
+## Process
+
+1. **Analyze codebase** silently
+2. **Generate L4 purpose spec** from README/docs
+3. **Show summary** of what was created
+
+## Step 1: Silent Analysis
+
+Analyze without user interaction:
+
+- Read README.md
+- Check package.json / pyproject.toml / Cargo.toml
+- Scan src/ or lib/ directory
+- Detect testing and linting tools
+
+## Step 2: Auto-Generate L4 Purpose
+
+Generate `telos/specs/L4-purpose/purpose.md` based on analysis:
+
+```markdown
+<!-- telos-metadata
+id: L4:purpose
+level: 4
+title: [Project Name]
+-->
+
+# L4: Purpose
+
+## Why This Project Exists
+
+[Inferred from README]
+
+## Beneficiaries
+
+[Inferred from README or package description]
+
+## Success Metrics
+
+- [Inferred metric 1]
+- [Inferred metric 2]
+- [Inferred metric 3]
+
+## Constraints
+
+- [Any detected constraints]
+
+## Technology Stack
+
+- **Languages**: [Detected]
+- **Frameworks**: [Detected]
+- **Testing**: [Detected]
+- **Linting**: [Detected]
+
+## Initialization
+
+- **Date**: [Current date]
+- **Method**: /telos:quick
+```
+
+## Step 3: Display Summary
+
+Once complete, show:
+
+---
+
+⚡ **Telos quick initialization complete!**
+
+**Your project now has:**
+
+```
+telos/
+├── TELOS.md                 # Entry point
+├── .telosrc.json            # Configuration
+├── index.json               # Spec registry
+└── specs/
+    ├── L4-purpose/
+    │   └── purpose.md       # [Generated purpose]
+    ├── L3-experience/       # Ready for user journey specs
+    ├── L2-contract/         # Ready for API/component specs
+    └── L1-function/         # Ready for function specs
+```
+
+**Generated L4 Purpose:**
+
+| Field         | Value               |
+| ------------- | ------------------- |
+| Purpose       | [Purpose statement] |
+| Beneficiaries | [Who benefits]      |
+| Stack         | [Detected tech]     |
+
+**How Spec-Driven Development works:**
+
+1. **Before coding**: Create a spec at the appropriate level
+2. **Write tests**: Generate tests from spec scenarios
+3. **Implement**: Write code with `@telos` annotation
+4. **Validate**: Run `/telos:validate` before commits
+
+**Available commands:**
+
+- `/telos:validate` - Validate specs, links, tests
+- `/telos:status` - Show current configuration
+- `/telos:sdd-discover` - Generate specs from existing code
+- `/telos:sdd-context` - Load spec context before changes
+
+**Next steps:**
+
+1. Review `telos/specs/L4-purpose/purpose.md` and refine if needed
+2. For existing code: Run `/telos:sdd-discover` to generate specs
+3. For new features: Create specs before coding
+
+**Not satisfied?** Run `/telos:init` for interactive mode with full
+customization.
+
+---
+
+## When to Use Quick Mode
+
+✅ **Use quick mode when:**
+
+- Starting a new project with clear conventions
+- The codebase already has comprehensive README
+- You want to iterate quickly and refine later
+
+❌ **Use full `/telos:init` when:**
+
+- Project has unique or nuanced purpose
+- Strategic direction needs human input
+- Initial setup must be carefully reviewed

package/templates/commands/reset.md

@@ -0,0 +1,96 @@
+# Telos Reset
+
+This command removes all existing Telos configuration and allows you to start
+fresh.
+
+## What Gets Removed
+
+This command will **delete** the following:
+
+- `.telos/TELOS.md`
+- `.telos/agents/` directory (all L1-L9 agent files)
+- `logos/orchestrator.js` (if present)
+- Telos sections in `AGENTS.md` and `CLAUDE.md` (if present)
+
+## Safety Check
+
+Before proceeding, ask the user:
+
+---
+⚠️  **Warning: This will delete all Telos configuration files.**
+
+**Files to be removed:**
+- `.telos/TELOS.md`
+- `.telos/agents/l1-*.md` through `l9-*.md`
+- `logos/orchestrator.js`
+- Telos references in AGENTS.md / CLAUDE.md
+
+**Are you sure you want to reset?** (yes/no)
+---
+
+If user responds "no" or anything other than "yes", abort with message: "Reset
+cancelled. Your Telos configuration is unchanged."
+
+## Reset Process
+
+If user confirms "yes":
+
+### Step 1: Remove Files
+
+Delete the following files (if they exist):
+
+```bash
+rm -rf .telos/TELOS.md
+rm -rf .telos/agents/
+rm -rf logos/orchestrator.js
+```
+
+### Step 2: Clean Memory Files
+
+If `AGENTS.md` exists:
+
+- Remove any sections with headers containing "Telos" or "L1-L9"
+- Keep all other content intact
+
+If `CLAUDE.md` exists:
+
+- Remove any sections referencing Telos
+- Keep all other project-specific content
+
+### Step 3: Clean State
+
+Remove any initialization state files:
+
+```bash
+rm -f .telos-init-state.json
+```
+
+### Step 4: Confirm Completion
+
+Display:
+
+---
+✅ **Telos reset complete.**
+
+**Removed:**
+- All Telos content and agent files
+- Telos references in AGENTS.md / CLAUDE.md
+- Initialization state
+
+**Next steps:**
+- Run `/telos-init` for full interactive setup
+- Run `/telos-quick` for fast auto-generation
+- Run `telos init` (CLI) to reinstall slash commands if needed
+---
+
+## Edge Cases
+
+**If no Telos files found:** Display: "No Telos installation detected. Nothing
+to reset."
+
+**If only partial installation found:** Remove what exists and notify: "Partial
+Telos installation found. Removed existing files. Run `/telos-init` to complete
+setup."
+
+**If git repository has uncommitted Telos files:** Warn: "You have uncommitted
+Telos files. Consider running `git status` before resetting."

package/templates/commands/sdd-context.md

@@ -0,0 +1,64 @@
+# Telos-SDD Context
+
+Load recursive context for a spec ID to understand its full lineage.
+
+## Usage
+
+When you need to understand a piece of code or make changes, load its context:
+
+```bash
+npx telos context <spec-id>
+```
+
+Example:
+
+```bash
+npx telos context L1:function:src/auth/validation:validateToken
+```
+
+## What Context Includes
+
+1. **TELOS.md** - Project entry point (always loaded)
+2. **Lineage** - All ancestor specs from L4 down to target
+3. **Target Spec** - Full content of the requested spec
+4. **Siblings** - Adjacent specs with same parent (metadata only)
+5. **Implementation** - Source file and test file paths
+
+## Output Format
+
+Default is markdown, suitable for AI consumption:
+
+```bash
+npx telos context L1:function:src/auth:validate --format=markdown
+```
+
+For JSON output:
+
+```bash
+npx telos context L1:function:src/auth:validate --format=json
+```
+
+## When to Use
+
+Use context loading when:
+
+1. Before modifying code - understand its purpose
+2. Before creating specs - see the hierarchy
+3. Reviewing code - trace back to requirements
+4. Writing tests - understand scenarios
+
+## Example Workflow
+
+```bash
+# 1. Find the spec for a file
+npx telos coverage
+
+# 2. Load context for the spec
+npx telos context L1:function:src/auth/validation
+
+# 3. Make changes aligned with purpose
+# (edit code)
+
+# 4. Validate changes
+npx telos validate
+```

package/templates/commands/sdd-discover.md

@@ -0,0 +1,59 @@
+# Telos-SDD Discover
+
+Scan the existing codebase and generate spec structure (brownfield).
+
+## What This Does
+
+1. Scans source directories for modules and functions
+2. Detects routes, components, and API endpoints
+3. Proposes a spec hierarchy based on code structure
+4. Generates spec files for review
+
+## Instructions
+
+Run the discovery command:
+
+```bash
+npx telos discover
+```
+
+For a dry run (preview without generating files):
+
+```bash
+npx telos discover --dry-run
+```
+
+## Review Process
+
+After discovery, review the generated specs:
+
+1. **L4:purpose** - Edit to reflect actual project purpose
+2. **L3:experience** - Rename journeys to match your terminology
+3. **L2:contract** - Verify API contracts match implementation
+4. **L1:function** - Add missing scenarios for TDD
+
+## Adding Annotations
+
+After specs are generated, add @telos annotations to code:
+
+```typescript
+// @telos L1:function:src/auth/validation:validateToken
+export function validateToken(token: string): boolean {
+  // implementation
+}
+```
+
+## Validation
+
+After adding annotations, validate coverage:
+
+```bash
+npx telos validate
+```
+
+This checks:
+
+- All specs have valid structure
+- All annotations point to existing specs
+- All L1 specs have tests
+- No orphaned code (functions without annotations)

package/templates/commands/sdd-generate-tests.md

@@ -0,0 +1,85 @@
+# Telos-SDD Generate Tests
+
+Generate test skeletons from spec scenarios.
+
+## Usage
+
+Generate tests for a spec:
+
+```bash
+npx telos spec generate-tests <spec-id>
+```
+
+Example:
+
+```bash
+npx telos spec generate-tests L1:function:src/auth/validation
+```
+
+## Dry Run
+
+Preview generated tests without writing files:
+
+```bash
+npx telos spec generate-tests L1:function:src/auth/validation --dry-run
+```
+
+## Test Framework
+
+Specify a framework (default: auto-detected):
+
+```bash
+npx telos spec generate-tests L1:function:src/auth/validation --framework=vitest
+npx telos spec generate-tests L1:function:src/auth/validation --framework=jest
+npx telos spec generate-tests L1:function:src/auth/validation --framework=pytest
+```
+
+## Scenario Format in Specs
+
+Scenarios in your spec should follow this format:
+
+```markdown
+### Scenario: Valid token
+
+- GIVEN a properly signed JWT
+- WHEN validateToken is called
+- THEN return { valid: true }
+
+### Scenario: Expired token
+
+- GIVEN a JWT with expired `exp` claim
+- WHEN validateToken is called
+- THEN return { valid: false, error: 'TOKEN_EXPIRED' }
+```
+
+## Generated Test Format
+
+The generator creates:
+
+```typescript
+// @telos-test L1:function:src/auth/validation:validateToken
+describe("validateToken", () => {
+  // @telos-scenario L1:function:src/auth/validation:validateToken:valid-token
+  it("Valid token", () => {
+    // GIVEN a properly signed JWT
+    // TODO: Set up test conditions
+
+    // WHEN validateToken is called
+    // TODO: Execute the action
+
+    // THEN return { valid: true }
+    // TODO: Add assertions
+    expect(true).toBe(true);
+  });
+});
+```
+
+## TDD Workflow
+
+1. **Create spec with scenarios**
+2. **Generate test skeletons**: `telos spec generate-tests <spec-id>`
+3. **Run tests** → They fail (Red)
+4. **Implement code** with @telos annotation
+5. **Run tests** → They pass (Green)
+6. **Validate**: `telos validate`
+7. **Commit** (pre-commit hook verifies)

package/templates/commands/sdd-init.md

@@ -0,0 +1,46 @@
+# Telos-SDD Initialize
+
+Initialize the Spec-Driven Development (SDD) structure for this project.
+
+## What This Does
+
+1. Creates the telos/specs/ directory hierarchy (L4-L1)
+2. Generates an initial L4:purpose spec from project metadata
+3. Creates TELOS.md entry point
+4. Initializes the spec index
+
+## Instructions
+
+Run the CLI command to initialize SDD:
+
+```bash
+npx telos spec init
+```
+
+Then help the user refine their L4:purpose by:
+
+1. Reading telos/specs/L4-purpose/purpose.md
+2. Asking clarifying questions about:
+   - The ultimate purpose of the project
+   - Success metrics (KPIs)
+   - Target users
+   - Constraints (technical, regulatory, etc.)
+3. Updating the spec with their answers
+
+## Spec Level Overview
+
+| Level | Name       | Description                               |
+| ----- | ---------- | ----------------------------------------- |
+| L4    | Purpose    | Why the project exists + success metrics  |
+| L3    | Experience | User journeys, UX requirements, analytics |
+| L2    | Contract   | API contracts, component interfaces       |
+| L1    | Function   | Individual functions with TDD scenarios   |
+
+## Next Steps
+
+After initialization, guide the user to:
+
+1. Run `telos discover` to generate specs from existing code
+2. Run `telos spec create 3 <name>` to add user journeys
+3. Add `@telos` annotations to their code
+4. Run `telos validate` to check coverage

package/templates/commands/sdd-validate.md

@@ -0,0 +1,78 @@
+# Telos-SDD Validate
+
+Validate all specs, code-spec links, tests, and orphaned code.
+
+## Full Validation
+
+Run complete validation:
+
+```bash
+npx telos validate
+```
+
+This checks:
+
+1. **Specs** - Structure, parent-child integrity, no circular refs
+2. **Links** - All @telos annotations point to existing specs
+3. **Tests** - All L1 specs have @telos-test annotations
+4. **Orphans** - All functions have @telos annotations
+
+## Selective Validation
+
+Validate specific aspects:
+
+```bash
+npx telos validate --specs     # Spec structure only
+npx telos validate --links     # Code-spec links only
+npx telos validate --tests     # Test coverage only
+npx telos validate --orphans   # Orphaned code only
+```
+
+## Exit Codes
+
+- `0` - All validations passed
+- `1` - One or more validations failed
+
+Use in CI/CD:
+
+```yaml
+- name: Validate Telos-SDD
+  run: npx telos validate
+```
+
+## Fixing Issues
+
+### Invalid Annotation
+
+```
+✗ src/auth/legacy.ts:12 → L2:auth-legacy:oldValidate (spec deleted)
+```
+
+Fix: Update annotation to point to existing spec, or remove the code.
+
+### Missing Tests
+
+```
+⚠ L1:function:src/payment:formatCurrency - missing tests
+```
+
+Fix: Run `telos spec generate-tests L1:function:src/payment` to create test
+skeletons.
+
+### Orphaned Code
+
+```
+✗ src/utils.ts:45 - helper function has no @telos annotation
+```
+
+Fix: Add `// @telos L1:function:src/utils:helper` above the function.
+
+## Pre-commit Hook
+
+Install automatic validation:
+
+```bash
+npx telos hooks install
+```
+
+This blocks commits that fail validation.