@mod-computer/cli 0.1.1 → 0.2.2

package/commands/review.md

@@ -1,151 +0,0 @@
----
-version: 2.0.0
-updated: 2026-01-03
-description: Review specification and add traceability comments
----
-
-# Specification Review & Traceability Agent
-
-Given this specification file: ".mod/specs/<optional-folder>/$ARGUMENTS"
-
-## Branch Context and Specification Setup
-
-**Automatic Branch Detection and Context Gathering:**
-
-**If no specification argument provided:**
-1. **Check active branch** for linked specification:
-   ```bash
-   mod branch status
-   # Should show active branch and linked specification
-   ```
-2. **Error handling** for lightweight branches:
-   ```bash
-   # If current branch has no specification:
-   # > Current branch "fix-auth-timeout" is a lightweight branch with no specification
-   # > Options:
-   # > 1. Link specification: mod branch spec-link <spec-file>
-   # > 2. Create specification branch: mod branch create feature-<name> --spec <spec-file>
-   # > 3. Switch to specification branch: mod branch switch <spec-branch>
-   ```
-
-**If specification argument provided (e.g., `branching-cli.spec.md`):**
-1. **Auto-switch to specification branch**:
-   ```bash
-   # Check if corresponding branch exists
-   mod branch list | grep "feature-.*branching-cli"
-
-   # If exists, switch to it
-   mod branch switch feature-mod-cli-branching-cli
-
-   # If doesn't exist, create it
-   mod branch create feature-mod-cli-branching-cli --spec mod-cli/branching-cli.spec.md
-   ```
-2. **Verify branch setup**:
-   ```bash
-   mod branch status
-   # Should confirm specification branch is active and linked
-   ```
-
-**Review Context Gathering (Automatic):**
-1. **Implementation Progress**: `mod branch status` shows current implementation changes
-2. **Specification Requirements**: `mod status <spec-name>.spec.md` shows requirements and traceability
-3. **Coverage Analysis**: `glassware` shows detailed traceability information
-4. **Code Structure**: Analyzes functions, classes, and existing glassware traces per file
-
-### Trace Writing Instructions
-- Use **glassware annotations** for all traceability
-- Every implementation trace must use: `// glassware[type=implementation, id=unique-id, requirements=REQ-ID]`
-- Add traces directly in the implementation files that satisfy the requirement
-- Do **not** invent requirement IDs; only use ones defined in the provided spec
-- Each implementation must have a unique `id` attribute
-
-## Review Process
-
-**Automated review agent that analyzes implementation against specification:**
-
-1. **Read and parse the complete specification** including all requirements
-2. **Run initial status check**: `glassware` to assess current traceability
-3. **Understand branch changes**: Use `mod branch status` to see what code changes exist on this branch
-4. **Scan all implementation files** in the codebase for related code
-5. **Add missing glassware traces** where implementation matches requirements
-6. **Update specification** where implementation has diverged but makes sense
-7. **Verify progress**: Re-run `glassware` to confirm improvements
-8. **Leave untraced code** that doesn't match any requirements (for IDE flagging)
-
-## Primary Tasks
-
-### 1. Audit Spec Coverage Granularity
-- **Analyze function complexity** using automated detection (lines, conditionals, business logic patterns)
-- **Flag under-specified complex functions** that need line-level traces but only have method-level
-- **Flag over-specified simple functions** that have line-level traces when method-level is appropriate
-- **Verify business logic traceability** - ensure all business logic has detailed line-level traces
-
-### 2. Add Missing Traceability
-- **Scan implementation files** for code that fulfills spec requirements but lacks glassware traces
-- **Add appropriate glassware references** with correct granularity based on complexity analysis
-- **Use confidence thresholds** - only add traces where match is ≥95% certain
-
-### 3. Specification Updates
-- **Identify implementation patterns** that extend beyond original requirements
-- **Update specifications** to include discovered functionality that makes sense (including if implementation means parts of spec are no longer relevant)
-- **Add new sub-requirements** (e.g., BEH-AUTH-1.1a) for legitimate extensions
-- **Document rationale** for each specification update
-
-### 4. Flag Non-Compliant Code
-- **Leave code without glassware traces** when it doesn't match any requirement
-- **Identify implementation gaps** where spec requirements have no code
-- **Report architectural violations** where code contradicts spec patterns
-
-## Output Actions
-
-**File Updates:**
-- **Implementation files**: Add glassware traces with appropriate granularity where code matches requirements
-- **Specification files**: Update specs to reflect legitimate implementation extensions
-- **Summary report**: List of granularity improvements, changes made, and issues flagged
-
-**Quality Standards:**
-- **Appropriate Granularity**: Apply method-level traces to simple functions, line-level to complex functions
-- **Business Logic Priority**: Always ensure business logic has detailed line-level traceability
-- **Conservative tracing**: Only add glassware traces with high confidence
-- **Sensible spec updates**: Only update specs for logical extensions, not violations
-- **Clear flagging**: Leave obvious gaps and violations untraced for developer attention
-
-### Spec Granularity Review Rules
-**For each function, assess current glassware traces:**
-
-1. **Count Current Traces**:
-   - 1 glassware comment = method-level coverage
-   - 2+ glassware comments = line-level coverage
-
-2. **Apply Complexity Rules**:
-   - **Business Logic** (validate/auth/pay/charge/encrypt/save/persist): MUST have line-level traces
-   - **Complex Functions** (>10 lines OR conditionals): SHOULD have line-level traces
-   - **Simple Functions** (≤10 lines, no conditionals): Method-level traces OK
-
-3. **Review Actions**:
-   - **Under-specified**: Complex function with only method-level trace → Add line-level traces
-   - **Over-specified**: Simple function with line-level traces → Consider consolidating to method-level
-   - **Missing Business Logic**: Business function without detailed traces → Flag as critical gap
-
-### Glassware Format Reference
-
-**In Markdown specs (requirements):**
-```markdown
-The system must validate user credentials. <glassware type="requirement" id="REQ-AUTH-1" />
-```
-
-**In TypeScript (implementations):**
-```typescript
-// glassware[type=implementation, id=auth-login, requirements=REQ-AUTH-1]
-export function login(email: string, password: string) { ... }
-```
-
-## Review Completion Validation
-
-**Before completing review, run final verification:**
-- Execute `glassware` to verify improved traceability coverage
-- Use `mod branch status` to verify what code changes exist on branch
-- Ensure all requirements show as "implemented" when code is properly traced
-- Document coverage improvements achieved
-
-**Result**: Complete bidirectional traceability with updated specifications that reflect actual implementation while flagging non-compliant code.

package/commands/spec.md

@@ -1,169 +0,0 @@
----
-version: 1.0.0
-updated: 2025-12-13
-checksum: d4e5f6g7h8i9j0k1
-description: Create comprehensive spec from feature description
----
-
-# ModSpec Creation Guide
-
-Given this high-level feature description: "$ARGUMENTS"
-
-## Branch Creation and Setup
-
-**BEFORE writing the specification:**
-
-**Automatic Specification Branch Creation:**
-1. **Extract spec title** from the feature description arguments
-2. **Check for existing branch** that matches the specification:
-   ```bash
-   # Check if specification branch already exists
-   mod branch list | grep "feature-[package-]spec-name"
-   ```
-3. **Create or switch to specification branch**:
-   ```bash
-   # If branch exists, switch to it
-   mod branch switch feature-mod-cli-branching-cli
-   
-   # If branch doesn't exist, create it with package prefix
-   mod branch create feature-mod-cli-branching-cli --spec mod-cli/branching-cli.spec.md
-   ```
-4. **Verify branch setup**:
-   ```bash
-   mod branch status
-   # Should show: Active branch: feature-mod-cli-branching-cli [spec] (specification)
-   # Should show: ✓ Linked to specification: .mod/specs/mod-cli/branching-cli.spec.md
-   ```
-
-**Package-Prefixed Branch Naming:**
-- **Pattern**: `feature-{package}-{spec-name}`
-- **Examples**: 
-  - `feature-mod-cli-branching-cli`
-  - `feature-mod-core-workspace-management`
-  - `feature-mod-ui-component-library`
-- **Benefits**: Clear package ownership, avoids name collisions
-
-**Background Sync Integration:**
-- The mod sync daemon automatically tracks specification file changes
-- Branch switching preserves working directory state
-- Real-time change monitoring enables seamless development flow
-
-## Pre-Specification Research
-
-**BEFORE writing the specification:**
-1. Research existing codebase for related functionality and patterns
-2. Check `.mod/specs/` for similar specifications  
-3. Identify reusable code, services, and integration points
-4. Understand the target package's architecture and conventions
-
-## ModSpec Structure
-
-Include:
-
-**Required Header:**
-```markdown
----
-title: [feature-name]
-type: specification
----
-# [Feature Name] Specification
-```
-
-**Core Sections:**
-1. **Abstract** - One concise sentence describing key capabilities
-2. **Motivation** - Problems and impact in bullet points
-3. **Approach** - Technical decisions and integration points
-4. **UX Requirements (UX-*)** - UI components, user flows, and accessibility
-5. **Business Logic Requirements (BUS-*)** - Business logic, workflows, and validation rules
-6. **Data Model Requirements (DATA-*)** - TypeScript interfaces, data structures, and service extensions (be conservative - prefer extending existing over creating new)
-7. **Integration Requirements (INT-*)** - APIs, external services, and data exchange
-8. **Infrastructure Requirements (INFRA-*)** - System architecture, deployment, and scaling
-9. **Quality Requirements (QUAL-*)** - Testing, performance, and security criteria
-
-### Quality Requirements Playbook
-Default to four numbered blocks so every spec documents the same test tiers; add REQ-QUAL-5+ if the feature needs specialty coverage (security, privacy, chaos, compliance, etc.). Keep every entry succinct and include the test type + success metric in the requirement text. Under each block, add sub-numbered requirements (REQ-QUAL-X.Y.Z) that describe the specific test case so it can be traced back to automation or manual checklists.
-
-1. **REQ-QUAL-1: Unit Quality** — Core modules and invariants guarded by unit tests (coverage targets, fixtures, failure injection).
-2. **REQ-QUAL-2: Integration Quality** — Extension/service interactions, persistence, external APIs validated through integration harnesses.
-3. **REQ-QUAL-3: End-to-End / Scenario Quality** — Real workflows (happy + negative), manual UX steps, plus the evidence reviewers must archive.
-4. **REQ-QUAL-4: Performance & Telemetry** — Bench methodology, latency/throughput budgets, soak expectations, telemetry metrics + alert thresholds.
-5. **REQ-QUAL-5+: Optional Specialty** — Security, resilience, localization, etc., only when needed.
-
-Reference `mod-ide-plugin/12-spec-branch-creation-and-change-tracking.spec.md` for tone and structure when in doubt.
-
-**Critical Requirements for Agent Execution:**
-- Use hierarchical numbered requirements with concise, clear descriptions:
-  - REQ-{CATEGORY}: Top-level category (REQ-UX, REQ-BUS, REQ-DATA, REQ-INT, REQ-INFRA, REQ-QUAL)
-  - REQ-{CATEGORY}-N: User story-level groupings (REQ-UX-1: Dashboard access with recent activity)
-  - REQ-{CATEGORY}-N.N: Feature sections within user story (REQ-UX-1.1: Default State)
-  - REQ-{CATEGORY}-N.N.N: Granular implementation details (REQ-UX-1.1.1: Available dashboard view)
-- Write concisely: remove redundant words, use bullet points, avoid verbose descriptions
-- Include exact implementation details (bcrypt cost=12, not "hash securely")
-- Specify concrete behavior that agents can implement directly
-- Be direct and scannable - eliminate wordy, repetitive language
-
-## Specification Output Location and Chronological Ordering
-
-**IMPORTANT**: Create the specification file at:
-`.mod/specs/<appropriate-folder>/<feature-name>.spec.md`
-
-**Chronological Ordering System:**
-1. **Use Creation Date**: Specs are ordered by creation date for stable, conflict-free sequencing
-2. **Add Created Frontmatter**: Include `created: YYYY-MM-DD` in the YAML frontmatter for explicit ordering
-3. **Fallback to File Stats**: If no `created` field exists, use file system creation time as backup
-4. **Display Numbers**: Show position numbers (1., 2., 3.) in navigation UI based on chronological order
-
-**Directory Selection:**
-Choose the appropriate folder based on the feature's primary domain. If unsure, use the package name that will contain the primary implementation.
-
-**Frontmatter Template:**
-```markdown
----
-title: feature-name
-type: specification  
-created: 2024-01-15
----
-```
-
-**Benefits of Date-Based Ordering:**
-- **No file renaming**: New specs don't affect existing filenames
-- **Merge conflict free**: Multiple developers can create specs simultaneously
-- **Stable references**: Spec filenames never change after creation
-- **Natural chronology**: Order reflects development timeline
-
-## Quality Checklist
-
-Before finalizing your specification, ensure:
-
-✅ **Concise**: Abstract is one sentence, motivation uses bullet points, requirements are direct
-✅ **Traceability**: Every requirement maps to specific implementation files
-✅ **Testability**: Every requirement can be validated through testing  
-✅ **Measurability**: Performance targets include specific metrics
-✅ **Completeness**: All user workflows are covered by requirements
-✅ **Clarity**: Each requirement has unambiguous acceptance criteria
-✅ **Implementation Ready**: Developers know exactly what to build and where
-✅ **File Location**: Spec is saved to `.mod/specs/<appropriate-folder>/<feature-name>.spec.md`
-
-## Examples
-
-### Hierarchical Requirements Structure:
-```markdown
-## REQ-UX: User Experience Requirements
-
-### REQ-UX-1: Real-time email validation feedback for error correction
-
-**REQ-UX-1.1: Form Components**
-- REQ-UX-1.1.1: Email input with real-time validation feedback
-- REQ-UX-1.1.2: Password input with strength indicator
-- REQ-UX-1.1.3: Submit button with loading/disabled states
-- REQ-UX-1.1.4: Error display areas with ARIA attributes
-
-**REQ-UX-1.2: Validation Logic**
-- REQ-UX-1.2.1: Email format validation on blur event
-- REQ-UX-1.2.2: Password strength calculation with visual feedback
-- REQ-UX-1.2.3: Form submission validation with error handling
-- REQ-UX-1.2.4: Success state with redirect to verification
-
-```
-
-Now generate your specification following this template, ensuring every requirement is traceable from business value to implementation code and can be validated through testing.