opencode-metis 0.1.0

package/opencode/skill/specification-management/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: specification-management
+description: "Provides methodology for scaffolding, status-checking, and managing specification directories including auto-incrementing IDs, README tracking, phase transitions, and decision logging"
+license: MIT
+compatibility: opencode
+metadata:
+  category: analysis
+  version: "1.0"
+---
+
+# Specification Management
+
+Roleplay as a specification workflow orchestrator that manages specification directories and tracks user decisions throughout the PRD to SDD to PLAN workflow.
+
+SpecificationManagement {
+  Activation {
+    When to use this skill:
+    - Create a new specification directory with auto-incrementing ID
+    - Check specification status (what documents exist)
+    - Track user decisions (e.g., "PRD skipped because requirements in JIRA")
+    - Manage phase transitions (PRD to SDD to PLAN)
+    - Initialize or update README.md in spec directories
+    - Read existing spec metadata via spec.py
+  }
+
+  SupportingFiles {
+    - [readme-template.md](readme-template.md) -- README template for spec directories
+    - [reference.md](reference.md) -- Extended specification metadata protocols
+    - [spec.py](spec.py) -- Script for directory creation and metadata reading
+  }
+
+  DirectoryManagement {
+    Constraints {
+      1. Use `spec.py` to create and read specification directories
+      2. The `spec.py` script is located in this skill's directory (alongside this SKILL.md file)
+      3. Resolve `spec.py` from this skill's directory; the full path depends on your framework installation location
+    }
+
+    Commands {
+      ```bash
+      # Create new spec (auto-incrementing ID)
+      spec.py "feature-name"
+
+      # Read existing spec metadata (TOML output)
+      spec.py 004 --read
+
+      # Add template to existing spec
+      spec.py 004 --add product-requirements
+      ```
+    }
+
+    TOMLOutputFormat {
+      ```toml
+      id = "004"
+      name = "feature-name"
+      dir = "docs/specs/004-feature-name"
+
+      [spec]
+      prd = "docs/specs/004-feature-name/product-requirements.md"
+      sdd = "docs/specs/004-feature-name/solution-design.md"
+
+      files = [
+        "product-requirements.md",
+        "solution-design.md"
+      ]
+      ```
+    }
+  }
+
+  ReadmeManagement {
+    Constraints {
+      1. Every spec directory should have a `README.md` tracking decisions and progress
+      2. Create README.md when a new spec is created using the [readme-template.md](readme-template.md) template
+    }
+
+    UpdateTriggers {
+      Update README.md when:
+      - Phase transitions occur (start, complete, skip)
+      - User makes workflow decisions
+      - Context needs to be recorded
+    }
+  }
+
+  PhaseTransitions {
+    Workflow {
+      1. Check existing state -- Use `spec.py [ID] --read`
+      2. Suggest continuation point based on existing documents (evaluate top-to-bottom, first match wins)
+      3. Record decisions in README.md
+      4. Update phase status as work progresses
+    }
+
+    ContinuationTable {
+      | IF state is | THEN suggest |
+      |---|---|
+      | `plan` exists | "PLAN found. Proceed to implementation?" |
+      | `sdd` exists but no `plan` | "SDD found. Continue to PLAN?" |
+      | `prd` exists but no `sdd` | "PRD found. Continue to SDD?" |
+      | No documents exist | "Start from PRD?" |
+    }
+  }
+
+  DecisionTracking {
+    Constraints {
+      1. Log all significant decisions in README.md
+    }
+
+    Format {
+      ```markdown
+      ## Decisions Log
+
+      | Date | Decision | Rationale |
+      |------|----------|-----------|
+      | 2025-12-10 | PRD skipped | Requirements documented in JIRA-1234 |
+      | 2025-12-10 | Start with SDD | Technical spike already completed |
+      ```
+    }
+  }
+
+  WorkflowIntegration {
+    RelatedSkills {
+      - `requirements-analysis` skill -- PRD creation and validation
+      - `architecture-design` skill -- SDD creation and validation
+      - `implementation-planning` skill -- PLAN creation and validation
+    }
+
+    HandoffPattern {
+      1. Specification-management creates directory and README
+      2. User confirms phase to start
+      3. Context shifts to document-specific work
+      4. Document skill activates for detailed guidance
+      5. On completion, context returns here for phase transition
+    }
+  }
+
+  ValidationChecklist {
+    Before completing any operation:
+    - [ ] spec.py command executed successfully
+    - [ ] README.md exists and is up-to-date
+    - [ ] Current phase is correctly recorded
+    - [ ] All decisions have been logged
+    - [ ] User has confirmed next steps
+  }
+}

package/opencode/skill/specification-management/readme-template.md

@@ -0,0 +1,32 @@
+# Specification: {{SPEC_ID}}-{{SPEC_NAME}}
+
+## Status
+
+| Field | Value |
+|-------|-------|
+| **Created** | {{CREATED_DATE}} |
+| **Current Phase** | {{CURRENT_PHASE}} |
+| **Last Updated** | {{LAST_UPDATED}} |
+
+## Documents
+
+| Document | Status | Notes |
+|----------|--------|-------|
+| product-requirements.md | {{PRD_STATUS}} | {{PRD_NOTES}} |
+| solution-design.md | {{SDD_STATUS}} | {{SDD_NOTES}} |
+| implementation-plan.md | {{PLAN_STATUS}} | {{PLAN_NOTES}} |
+
+**Status values**: `pending` | `in_progress` | `completed` | `skipped`
+
+## Decisions Log
+
+| Date | Decision | Rationale |
+|------|----------|-----------|
+| {{DATE}} | {{DECISION}} | {{RATIONALE}} |
+
+## Context
+
+{{CONTEXT_NOTES}}
+
+---
+*This file is managed by the specification-management skill.*

package/opencode/skill/specification-management/reference.md

@@ -0,0 +1,115 @@
+# Specification Management Reference
+
+## Spec ID Format
+
+- **Format**: 3-digit zero-padded number (001, 002, ..., 999)
+- **Auto-incrementing**: Script scans existing directories to find next ID
+- **Directory naming**: `[NNN]-[sanitized-feature-name]`
+- **Sanitization**: Lowercase, special chars to hyphens, trim leading/trailing hyphens
+
+## Directory Structure
+
+```
+docs/specs/
+├── 001-user-authentication/
+│   ├── README.md                 # Managed by specification-management skill
+│   ├── product-requirements.md   # Created by requirements-analysis skill
+│   ├── solution-design.md        # Created by architecture-design skill
+│   └── implementation-plan.md    # Created by implementation-planning skill
+├── 002-payment-processing/
+│   └── ...
+└── 003-notification-system/
+    └── ...
+```
+
+## Script Commands
+
+### Create New Spec
+```bash
+spec.py "feature name here"
+```
+**Output:**
+```
+Created spec directory: docs/specs/005-feature-name-here
+Spec ID: 005
+Specification directory created successfully
+```
+
+### Read Spec Metadata
+```bash
+spec.py 005 --read
+```
+**Output (TOML):**
+```toml
+id = "005"
+name = "feature-name-here"
+dir = "docs/specs/005-feature-name-here"
+
+[spec]
+prd = "docs/specs/005-feature-name-here/product-requirements.md"
+sdd = "docs/specs/005-feature-name-here/solution-design.md"
+
+files = [
+  "product-requirements.md",
+  "README.md",
+  "solution-design.md"
+]
+```
+
+### Add Template to Existing Spec
+```bash
+spec.py 005 --add product-requirements
+spec.py 005 --add solution-design
+spec.py 005 --add implementation-plan
+```
+
+## Template Resolution
+
+Templates are resolved in this order:
+1. `skills/[template-name]/template.md` (primary)
+2. `templates/[template-name].md` (deprecated fallback)
+
+## README.md Fields
+
+| Field | Description |
+|-------|-------------|
+| Created | Date spec was created |
+| Current Phase | Active workflow phase |
+| Last Updated | Date of last status change |
+| Document Status | pending, in_progress, completed, skipped |
+| Notes | Additional context for each document |
+
+## Phase Workflow
+
+```
+Initialization
+    |
+PRD (Product Requirements)
+    |
+SDD (Solution Design)
+    |
+PLAN (Implementation Plan)
+    |
+Ready for Implementation
+```
+
+Each phase can be:
+- **Completed**: Document finished and validated
+- **Skipped**: User decided to skip (decision logged)
+- **In Progress**: Currently being worked on
+- **Pending**: Not yet started
+
+## Decision Logging
+
+Record decisions with:
+- **Date**: When the decision was made
+- **Decision**: What was decided
+- **Rationale**: Why (external references like JIRA IDs welcome)
+
+Example:
+```markdown
+| Date | Decision | Rationale |
+|------|----------|-----------|
+| 2025-12-10 | PRD skipped | Requirements in JIRA-1234 |
+| 2025-12-10 | Start with SDD | Technical spike completed |
+```

package/opencode/skill/specification-management/spec.py

@@ -0,0 +1,229 @@
+#!/usr/bin/env python3
+"""
+The Agentic Startup - Spec Generation Script
+Creates numbered spec directories with auto-incrementing IDs
+
+Location: ~/.config/opencode/skill/specification-management/spec.py
+Template resolution: skills/[template-name]/template.md (primary)
+                    templates/[template-name].md (fallback, deprecated)
+"""
+
+import argparse
+import re
+import sys
+from pathlib import Path
+from typing import Optional
+
+
+# Get plugin root from script location
+# This script is at: ~/.config/opencode/skill/specification-management/spec.py
+# Plugin root is: plugins/start/
+script_dir = Path(__file__).resolve().parent
+plugin_root = script_dir.parent.parent
+
+# Specs are created in the current working directory
+SPECS_DIR = Path("docs/specs")
+# Skills directory for primary template lookup
+SKILLS_DIR = plugin_root / "skills"
+# Templates directory for fallback (deprecated)
+TEMPLATES_DIR = plugin_root / "templates"
+
+
+def get_template_path(template_name: str) -> Path:
+    """
+    Resolve template path with skill-first, legacy-fallback pattern.
+
+    Resolution order:
+    1. skills/[template-name]/template.md (new location)
+    2. templates/[template-name].md (deprecated, backward compat)
+    """
+    # Primary: Look in skill directory
+    skill_template = SKILLS_DIR / template_name / "template.md"
+    if skill_template.exists():
+        return skill_template
+
+    # Fallback: Legacy templates directory (deprecated)
+    legacy_template = TEMPLATES_DIR / f"{template_name}.md"
+    if legacy_template.exists():
+        print(f"Warning: Using deprecated template location. "
+              f"Template should be at: {skill_template}", file=sys.stderr)
+        return legacy_template
+
+    raise FileNotFoundError(f"Template not found: {template_name}")
+
+
+def get_next_spec_id() -> str:
+    """Get next available spec ID by scanning existing directories."""
+    max_id = 0
+
+    if SPECS_DIR.exists():
+        # Find highest existing spec number
+        for dir_path in SPECS_DIR.iterdir():
+            if dir_path.is_dir():
+                # Extract number from pattern: 001-feature-name
+                match = re.match(r'^(\d{3})-', dir_path.name)
+                if match:
+                    num = int(match.group(1))
+                    if num > max_id:
+                        max_id = num
+
+    # Return next ID with zero-padding
+    return f"{max_id + 1:03d}"
+
+
+def sanitize_name(name: str) -> str:
+    """Convert feature name to URL-friendly directory name."""
+    # Convert to lowercase
+    name = name.lower()
+    # Replace special characters with hyphens
+    name = re.sub(r'[^a-z0-9]+', '-', name)
+    # Remove leading/trailing hyphens
+    name = name.strip('-')
+    return name
+
+
+def read_spec(spec_id: str) -> None:
+    """Read spec metadata and output TOML format."""
+    if not SPECS_DIR.exists():
+        print("Error: Specs directory not found", file=sys.stderr)
+        sys.exit(1)
+
+    # Find directory matching spec ID
+    spec_dir = None
+    for dir_path in SPECS_DIR.iterdir():
+        if dir_path.is_dir() and dir_path.name.startswith(f"{spec_id}-"):
+            spec_dir = dir_path
+            break
+
+    if not spec_dir:
+        print(f"Error: Spec {spec_id} not found", file=sys.stderr)
+        sys.exit(1)
+
+    # Extract name from directory
+    name = spec_dir.name[len(spec_id) + 1:]  # Remove "001-" prefix
+
+    # Generate TOML output
+    print(f'id = "{spec_id}"')
+    print(f'name = "{name}"')
+    print(f'dir = "{spec_dir}"')
+
+    # List spec documents
+    print()
+    print("[spec]")
+    if (spec_dir / "product-requirements.md").exists():
+        print(f'prd = "{spec_dir / "product-requirements.md"}"')
+    if (spec_dir / "solution-design.md").exists():
+        print(f'sdd = "{spec_dir / "solution-design.md"}"')
+    if (spec_dir / "implementation-plan.md").exists():
+        print(f'plan = "{spec_dir / "implementation-plan.md"}"')
+
+    # List quality gates if they exist
+    gate_files = [
+        ("definition-of-ready.md", "definition_of_ready"),
+        ("definition-of-done.md", "definition_of_done"),
+        ("task-definition-of-done.md", "task_definition_of_done"),
+    ]
+
+    gate_exists = any((spec_dir / file).exists() for file, _ in gate_files)
+    if gate_exists:
+        print()
+        print("[gates]")
+        for file, key in gate_files:
+            if (spec_dir / file).exists():
+                print(f'{key} = "{spec_dir / file}"')
+
+    # List all files
+    print()
+    print("files = [")
+    files = sorted([f.name for f in spec_dir.iterdir() if f.is_file()])
+    for i, file in enumerate(files):
+        comma = "," if i < len(files) - 1 else ""
+        print(f'  "{file}"{comma}')
+    print("]")
+
+
+def create_spec(feature_name: str, template: Optional[str] = None) -> None:
+    """Create a new spec directory with optional template."""
+    # Check if feature_name is an existing spec ID (3 digits)
+    is_spec_id = re.match(r'^\d{3}$', feature_name)
+
+    if is_spec_id and template:
+        # Try to find existing directory with this ID
+        if SPECS_DIR.exists():
+            for dir_path in SPECS_DIR.iterdir():
+                if dir_path.is_dir() and dir_path.name.startswith(f"{feature_name}-"):
+                    spec_dir = dir_path
+                    spec_id = feature_name
+                    print(f"Adding template to existing spec: {spec_dir}")
+
+                    # Copy template to existing directory using new resolution
+                    try:
+                        template_file = get_template_path(template)
+                        dest_file = spec_dir / f"{template}.md"
+                        dest_file.write_text(template_file.read_text())
+                        print(f"Generated template: {template}.md")
+                    except FileNotFoundError as e:
+                        print(f"Error: {e}", file=sys.stderr)
+                        sys.exit(1)
+                    return
+
+        # If we get here, the spec ID was not found
+        print(f"Error: Spec {feature_name} not found", file=sys.stderr)
+        sys.exit(1)
+
+    # Create new spec directory
+    spec_id = get_next_spec_id()
+    sanitized_name = sanitize_name(feature_name)
+    spec_dir = SPECS_DIR / f"{spec_id}-{sanitized_name}"
+
+    # Create spec directory
+    spec_dir.mkdir(parents=True, exist_ok=True)
+
+    print(f"Created spec directory: {spec_dir}")
+    print(f"Spec ID: {spec_id}")
+
+    # Copy template if requested
+    if template:
+        try:
+            template_file = get_template_path(template)
+            dest_file = spec_dir / f"{template}.md"
+            dest_file.write_text(template_file.read_text())
+            print(f"Generated template: {template}.md")
+        except FileNotFoundError as e:
+            print(f"Warning: {e}", file=sys.stderr)
+
+    print("Specification directory created successfully")
+
+
+def main():
+    """Main entry point."""
+    parser = argparse.ArgumentParser(
+        description="The Agentic Startup - Spec Generation Script"
+    )
+    parser.add_argument(
+        "feature_name",
+        help="Feature name or spec ID (for --read mode)"
+    )
+    parser.add_argument(
+        "--add",
+        metavar="TEMPLATE",
+        help="Add template file to spec directory"
+    )
+    parser.add_argument(
+        "--read",
+        action="store_true",
+        help="Read spec metadata and output TOML"
+    )
+
+    args = parser.parse_args()
+
+    # Handle read mode
+    if args.read:
+        read_spec(args.feature_name)
+    else:
+        # Handle spec creation
+        create_spec(args.feature_name, args.add)
+
+
+if __name__ == "__main__":
+    main()