diff --git a/CHANGELOG.md b/CHANGELOG.md index 0947da5..b59f3c4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 --- +## [0.9.7] - 2025-11-22 + +### 🎯 Metadata & Navigation Enhancements + +**1. Simplified slash_commands Format** +- Changed from verbose TOML tables to concise array format +- Matches `cli_commands` style for consistency +- Reduced boilerplate by 80% (50+ lines → ~10 lines) + +**2. Standardized SD-X Naming Convention** +- Replaced `"generic"` with `"custom"` for non-SD-X commands +- Enforced consistent `sd` pattern for all SD-X systems +- Examples: `sds`, `sdd`, `sdm`, `sdt`, `sdo` +- Benefits: Clear distinction between SD-X and custom systems + +**3. Precision-Guided Navigation for Long Commands** ⭐ NEW +- Added guidance in `implement.md.j2` for generating navigation tables +- Threshold: Commands >500 lines need navigation +- Token savings: 70-90% when AI reads commands +- Includes: Template, guidelines, calculation rules, examples +- Applies to: All future generated speckits + +**Documentation Updates**: +- `metaspec-metadata-examples.md`: Updated all 5 examples +- `implement.md.j2`: Added 75-line navigation guidance section +- `pyproject.toml.j2`: Simplified generation logic +- Navigation table: Updated all line numbers (file +74 lines) + +**Benefits**: +- ✅ Consistent metadata format across all speckits +- ✅ Clear SD-X system classification +- ✅ Massive token savings for long commands +- ✅ Best practices baked into generation + +--- + ## [0.9.6] - 2025-11-22 ### 🎯 Speckit Metadata Support in pyproject.toml diff --git a/docs/metaspec-metadata-examples.md b/docs/metaspec-metadata-examples.md index 64be0a7..8c2a54c 100644 --- a/docs/metaspec-metadata-examples.md +++ b/docs/metaspec-metadata-examples.md @@ -21,38 +21,31 @@ | Field | Type | Description | |-------|------|-------------| | `lifecycle` | string | Development phase: "greenfield" (0→1) \| "brownfield" (1→n) \| custom | -| `sd_type` | string \| array | Slash command system type: "generic" \| "sds" \| "sdd" \| mixed | +| `sd_type` | string \| array | Slash command system type: SD-X ("sds" \| "sdd" \| "sdm"...) \| "custom" \| "none" | | `slash_commands` | array | Slash commands this speckit provides for AI agents | --- ## 📝 Example Outputs -### Example 1: Domain-Specific Speckit (MCP Spec Kit) +### Example 1: Custom Commands Speckit (MCP Spec Kit) ```toml [tool.metaspec] -generated_by = "0.9.5" +generated_by = "0.9.6" domain = "mcp" # CLI commands this speckit provides cli_commands = ["init", "validate", "generate", "info"] -# Custom domain-specific slash commands -sd_type = "generic" +# Custom domain-specific slash commands (not SD-X system) +sd_type = "custom" -[[tool.metaspec.slash_commands]] -name = "show-spec" -description = "Display MCP specification reference" -source = "generic" - -[[tool.metaspec.slash_commands]] -name = "get-template" -description = "Get MCP server template" -source = "generic" +# Slash commands for AI agents +slash_commands = ["show-spec", "get-template"] ``` -**Scenario**: Domain-specific speckit with custom AI commands tailored to MCP domain +**Scenario**: Domain-specific speckit with custom AI commands (not following SD-X pattern) --- @@ -60,7 +53,7 @@ source = "generic" ```toml [tool.metaspec] -generated_by = "0.9.5" +generated_by = "0.9.6" domain = "api-testing" lifecycle = "greenfield" @@ -71,20 +64,7 @@ cli_commands = ["init", "validate", "test"] sd_type = "sdd" # Slash commands from library/sdd/spec-kit -[[tool.metaspec.slash_commands]] -name = "specify" -description = "Create API test specification" -source = "sdd/spec-kit" - -[[tool.metaspec.slash_commands]] -name = "plan" -description = "Plan test implementation" -source = "sdd/spec-kit" - -[[tool.metaspec.slash_commands]] -name = "implement" -description = "Execute test implementation" -source = "sdd/spec-kit" +slash_commands = ["specify", "plan", "implement"] ``` **Scenario**: Speckit adopts spec-kit workflow pattern for greenfield API test development @@ -95,66 +75,59 @@ source = "sdd/spec-kit" ```toml [tool.metaspec] -generated_by = "0.9.5" +generated_by = "0.9.6" domain = "meta-specification" lifecycle = "greenfield" +# CLI commands +cli_commands = ["init", "search", "install", "contribute", "list", "info"] + # Command system type (auto-detected) sd_type = ["sds", "sdd"] # Deployed slash commands (19 total) -[[tool.metaspec.slash_commands]] -name = "sds.specify" -description = "Define domain specification" -source = "sds" - -[[tool.metaspec.slash_commands]] -name = "sds.plan" -description = "Plan specification architecture" -source = "sds" - -[[tool.metaspec.slash_commands]] -name = "sdd.specify" -description = "Define toolkit specification" -source = "sdd" - -[[tool.metaspec.slash_commands]] -name = "sdd.implement" -description = "Build toolkit code" -source = "sdd" - -# ... (15 more commands) +slash_commands = [ + "sds.specify", "sds.plan", "sds.tasks", "sds.implement", + "sds.clarify", "sds.analyze", "sds.checklist", "sds.constitution", + "sdd.specify", "sdd.plan", "sdd.tasks", "sdd.implement", + "sdd.clarify", "sdd.analyze", "sdd.checklist", "sdd.constitution", + "proposal", "apply", "archive" +] ``` **Scenario**: MetaSpec itself - generates both specifications and toolkits --- -### Example 4: SD-Marketing (Custom Domain, No Lifecycle) +### Example 4: SD-Marketing (Custom Domain with Custom System) ```toml [tool.metaspec] -generated_by = "0.9.5" +generated_by = "0.9.6" domain = "marketing" # CLI commands for marketing operations -cli_commands = ["init", "validate", "analyze", "report"] - -# Custom marketing-specific AI commands -sd_type = "generic" - -[[tool.metaspec.slash_commands]] -name = "campaign.create" -description = "Create marketing campaign specification" -source = "generic" - -[[tool.metaspec.slash_commands]] -name = "campaign.analyze" -description = "Analyze campaign performance against KPIs" -source = "generic" +cli_commands = ["info", "init", "validate"] + +# Custom marketing-specific command system (SDM) +sd_type = "sdm" + +# SDM (Spec-Driven Marketing) commands +slash_commands = [ + "marketspec.constitution", + "marketspec.specify", + "marketspec.clarify", + "marketspec.plan", + "marketspec.tasks", + "marketspec.implement", + "marketspec.review", + "marketspec.optimize", + "marketspec.analyze", + "marketspec.checklist", +] ``` -**Scenario**: Marketing toolkit with domain-specific commands - "lifecycle" doesn't apply to this domain +**Scenario**: Marketing toolkit with custom SDM command system - first SD-X extension example --- @@ -162,36 +135,21 @@ source = "generic" ```toml [tool.metaspec] -generated_by = "0.9.5" +generated_by = "0.9.6" domain = "api" lifecycle = "greenfield" # CLI commands for API development cli_commands = ["init", "validate", "generate", "test"] -# Mixed command system: custom + spec-kit -sd_type = ["generic", "sdd"] - -# Custom API-specific commands -[[tool.metaspec.slash_commands]] -name = "discover" -description = "Discover API structure from OpenAPI/Swagger" -source = "generic" - -# Spec-kit workflow commands -[[tool.metaspec.slash_commands]] -name = "specify" -description = "Define API endpoint specification" -source = "sdd/spec-kit" - -# Custom code generation -[[tool.metaspec.slash_commands]] -name = "generate" -description = "Generate API client/server code" -source = "generic" +# Mixed command system: custom commands + spec-kit workflow +sd_type = ["custom", "sdd"] + +# Mix of custom and spec-kit commands +slash_commands = ["discover", "specify", "plan", "implement", "generate"] ``` -**Scenario**: API speckit combining domain-specific discovery with spec-kit workflow +**Scenario**: API speckit combining custom domain-specific commands with spec-kit workflow --- @@ -205,18 +163,26 @@ Based on `slash_commands[].source`: | Source Pattern | Detected Type | Meaning | |----------------|---------------|---------| -| `sdd/spec-kit` | `"sdd"` | Uses spec-kit workflow pattern | -| `sdd/openspec` | `"sdd"` | Uses OpenSpec evolution pattern | -| `sds/*` | `"sds"` | Uses SDS (Spec-Driven Specification) pattern | -| `generic` | `"generic"` | Custom domain-specific commands | -| Mixed sources | `["generic", "sdd"]` | Combines multiple patterns | +| `sdd/spec-kit` | `"sdd"` | Spec-Driven Development (spec-kit workflow) | +| `sdd/openspec` | `"sdd"` | Spec-Driven Development (openspec evolution) | +| `sds/*` | `"sds"` | Spec-Driven Specification | +| `sdm` | `"sdm"` | Spec-Driven Marketing | +| `sdt` | `"sdt"` | Spec-Driven Testing | +| `custom` | `"custom"` | Custom commands (not SD-X system) | +| Mixed sources | `["custom", "sdd"]` | Combines multiple patterns | | No slash commands | `"none"` | No AI command system | **Detection Logic**: -1. Collect all unique source prefixes from `slash_commands` -2. Map to types: `sdd/*` → sdd, `sds/*` → sds, `generic` → generic +1. Collect all unique source values from `slash_commands` +2. Map to types: + - `sdd/*` → sdd + - `sds/*` → sds + - `sdm`, `sdt`, `sdo`, etc. → keep as-is (SD-X systems) + - `custom` → custom (non-SD-X) 3. If single type: `sd_type = "sdd"` -4. If multiple types: `sd_type = ["generic", "sdd"]` +4. If multiple types: `sd_type = ["custom", "sdd"]` + +**Naming Convention**: SD-X systems follow pattern `sd` where domain is 1-3 letter abbreviation ### `lifecycle` Usage @@ -250,7 +216,7 @@ print(f"Slash Commands: {len(metadata.get('slash_commands', []))}") if "validate" in metadata["cli_commands"]: print("✅ Supports validation") -if metadata["sd_type"] in ["sdd", ["generic", "sdd"]]: +if metadata["sd_type"] in ["sdd", ["custom", "sdd"]]: print("✅ Uses spec-kit workflow") ``` diff --git a/pyproject.toml b/pyproject.toml index 9f2b7c5..581662c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "meta-spec" -version = "0.9.6" +version = "0.9.7" description = "Meta-specification framework for generating Spec-Driven X (SD-X) toolkits for AI agents" readme = "README.md" requires-python = ">=3.11" diff --git a/src/metaspec/__init__.py b/src/metaspec/__init__.py index e4bffd9..f327460 100644 --- a/src/metaspec/__init__.py +++ b/src/metaspec/__init__.py @@ -5,7 +5,7 @@ from YAML definitions. """ -__version__ = "0.9.6" +__version__ = "0.9.7" __all__ = ["__version__"] diff --git a/src/metaspec/templates/README.md b/src/metaspec/templates/README.md index 85d9b49..104d4af 100644 --- a/src/metaspec/templates/README.md +++ b/src/metaspec/templates/README.md @@ -115,7 +115,7 @@ Development methodologies organized by lifecycle: **Note**: This library has no commands (commands optional, templates required) -**Usage**: Used by `create-new-feature.sh` script, specify `source: "generic"` if needed +**Usage**: Used by `create-new-feature.sh` script, specify `source: "custom"` if needed --- @@ -270,8 +270,8 @@ my-speckit/ Templates are selected dynamically based on `slash_commands[].source`: - `source: "dev"` → `library/sdd/` -- `source: "generic"` → `library/generic/` -- Default: `"generic"` +- `source: "custom"` → `library/generic/` +- Default: `"custom"` (maps to `library/generic/`) ### 3. Clear Separation of Concerns diff --git a/src/metaspec/templates/base/pyproject.toml.j2 b/src/metaspec/templates/base/pyproject.toml.j2 index 126f5b0..8dd24cd 100644 --- a/src/metaspec/templates/base/pyproject.toml.j2 +++ b/src/metaspec/templates/base/pyproject.toml.j2 @@ -59,7 +59,7 @@ cli_commands = [] {% endif %} # Slash command system type (auto-detected from sources) -# Values: "generic" | "sds" | "sdd" | ["sds", "sdd"] | "none" +# Values: SD-X systems ("sds", "sdd", "sdm", "sdt", etc.) | "custom" | "none" {% if slash_commands %} {% set sd_types = namespace(list=[]) %} {% for sc in slash_commands %} @@ -67,8 +67,12 @@ cli_commands = [] {% set _ = sd_types.list.append('sdd') %} {% elif sc.source.startswith('sds/') and 'sds' not in sd_types.list %} {% set _ = sd_types.list.append('sds') %} - {% elif sc.source == 'generic' and 'generic' not in sd_types.list %} - {% set _ = sd_types.list.append('generic') %} + {% elif sc.source == 'custom' and 'custom' not in sd_types.list %} + {% set _ = sd_types.list.append('custom') %} + {% elif sc.source not in ['custom'] and not sc.source.startswith('sdd/') and not sc.source.startswith('sds/') %} + {% if sc.source not in sd_types.list %} + {% set _ = sd_types.list.append(sc.source) %} + {% endif %} {% endif %} {% endfor %} {% if sd_types.list|length == 1 %} @@ -80,13 +84,7 @@ sd_type = "none" {% endif %} # Slash commands provided by this speckit (for AI agents) -{% for sc in slash_commands %} -[[tool.metaspec.slash_commands]] -name = "{{ sc.name }}" -description = "{{ sc.description }}" -source = "{{ sc.source }}" - -{% endfor %} +slash_commands = [{% for sc in slash_commands %}"{{ sc.name }}"{% if not loop.last %}, {% endif %}{% endfor %}] {% else %} sd_type = "none" # No slash commands defined diff --git a/src/metaspec/templates/library/README.md b/src/metaspec/templates/library/README.md index b7a6cb1..e610edf 100644 --- a/src/metaspec/templates/library/README.md +++ b/src/metaspec/templates/library/README.md @@ -108,7 +108,7 @@ Select via interactive wizard when generating speckit: ```yaml # Universal SD-X toolkit -source: "generic" +source: "custom" # Or software development toolkit source: "sdd/spec-kit" # Greenfield diff --git a/src/metaspec/templates/library/generic/README.md b/src/metaspec/templates/library/generic/README.md index 9c354fc..1b1031d 100644 --- a/src/metaspec/templates/library/generic/README.md +++ b/src/metaspec/templates/library/generic/README.md @@ -134,15 +134,15 @@ When generating a speckit, if you need to create a **universal SD-X toolkit** (n ```yaml # Select via metaspec init interactive wizard -source: "generic" +source: "custom" # Or specify in internal configuration slash_commands: - - source: "generic" + - source: "custom" name: "constitution" - - source: "generic" + - source: "custom" name: "specify" - - source: "generic" + - source: "custom" name: "proposal" # ... ``` diff --git a/src/metaspec/templates/meta/sdd/commands/implement.md.j2 b/src/metaspec/templates/meta/sdd/commands/implement.md.j2 index 8fcc1aa..de3d31a 100644 --- a/src/metaspec/templates/meta/sdd/commands/implement.md.j2 +++ b/src/metaspec/templates/meta/sdd/commands/implement.md.j2 @@ -28,43 +28,47 @@ You **MUST** consider the user input before proceeding (if not empty). |------|-------|------|----------|-----------------| | 1-5. Prerequisites & Setup | 86-232 | 146 lines | 🔴 MUST READ | `read_file(target_file, offset=86, limit=146)` | | 6. Execute Implementation | 233-274 | 41 lines | 🔴 MUST READ | `read_file(target_file, offset=233, limit=41)` | -| **7. Task Execution Details** ⭐ | 275-464 | 189 lines | 🔴 **KEY** | See subsections below ⬇️ | -| 8-10. Checkpoints & Reporting | 465-556 | 91 lines | 🟡 Important | `read_file(target_file, offset=465, limit=91)` | -| 11-13. Validation & Saves | 557-681 | 124 lines | 🟡 Important | `read_file(target_file, offset=557, limit=124)` | -| 14-15. Propagation & Validation | 682-808 | 126 lines | 🟡 Important | `read_file(target_file, offset=682, limit=126)` | -| 16. Final Report | 809-1096 | 287 lines | 🟢 Reference | `read_file(target_file, offset=809, limit=287)` | +| **7. Task Execution Details** ⭐ | 275-525 | 251 lines | 🔴 **KEY** | See subsections below ⬇️ | +| 8-10. Checkpoints & Reporting | 526-617 | 91 lines | 🟡 Important | `read_file(target_file, offset=526, limit=91)` | +| 11-13. Validation & Saves | 618-742 | 124 lines | 🟡 Important | `read_file(target_file, offset=618, limit=124)` | +| 14-15. Propagation & Validation | 743-869 | 126 lines | 🟡 Important | `read_file(target_file, offset=743, limit=126)` | +| 16. Final Report | 870-1158 | 288 lines | 🟢 Reference | `read_file(target_file, offset=870, limit=288)` | -**📋 Section 7: Task Execution Details by Language** (189 lines): +**📋 Section 7: Task Execution Details by Language** (251 lines): | Component | Lines | Size | Usage | |-----------|-------|------|-------| -| **Python Implementation** ⭐ | 306-446 | 141 lines | `read_file(target_file, offset=306, limit=141)` | +| **Python Implementation** ⭐ | 306-508 | 203 lines | `read_file(target_file, offset=306, limit=203)` | | **TypeScript Implementation** | 315-323 | 8 lines | `read_file(target_file, offset=315, limit=8)` | | **Go Implementation** | 324-332 | 8 lines | `read_file(target_file, offset=324, limit=8)` | | **Rust Implementation** | 333-341 | 8 lines | `read_file(target_file, offset=333, limit=8)` | -**Note**: Python section (141 lines) includes overview (8 lines) + detailed `pyproject.toml` structure (97 lines) with `[tool.metaspec]` metadata, CLI commands, slash commands, sd_type calculation, and 3 example scenarios. +**Note**: Python section (203 lines) includes overview (8 lines) + `pyproject.toml` structure (97 lines) + **long command navigation guidance (74 lines)** with template and examples. **🎯 Phase-Specific Reading** (By component type): | Phase | Lines | Size | Usage | |-------|-------|------|-------| -| Setup & pyproject.toml | 136-207, 306-446 | 211 lines | `read_file(target_file, offset=136, limit=71)` + `offset=306, limit=141` | +| Setup & pyproject.toml | 136-207, 306-508 | 273 lines | `read_file(target_file, offset=136, limit=71)` + `offset=306, limit=203` | | Language-Specific Impl | 306-341 | 35 lines | `read_file(target_file, offset=306, limit=35)` | -| Checkpoints & Validation | 465-556 | 91 lines | `read_file(target_file, offset=465, limit=91)` | -| Progress & Error Handling | 489-556 | 67 lines | `read_file(target_file, offset=489, limit=67)` | -| Completion & Reporting | 557-681 | 124 lines | `read_file(target_file, offset=557, limit=124)` | +| Command Navigation | 433-508 | 75 lines | `read_file(target_file, offset=433, limit=75)` | +| Checkpoints & Validation | 526-617 | 91 lines | `read_file(target_file, offset=526, limit=91)` | +| Progress & Error Handling | 550-617 | 67 lines | `read_file(target_file, offset=550, limit=67)` | +| Completion & Reporting | 618-742 | 124 lines | `read_file(target_file, offset=618, limit=124)` | **💡 Typical Usage Patterns**: ```python # Quick start: Read Prerequisites only (146 lines) read_file(target_file, offset=86, limit=146) -# Python implementation: Read Python guidance + pyproject.toml update (141 lines) -read_file(target_file, offset=306, limit=141) +# Python implementation: Read Python guidance + pyproject.toml + navigation (203 lines) +read_file(target_file, offset=306, limit=203) + +# Command navigation: Read long command optimization guidance (75 lines) +read_file(target_file, offset=433, limit=75) # Validation phase: Read validation guidance (124 lines) -read_file(target_file, offset=557, limit=124) +read_file(target_file, offset=618, limit=124) # Specific language: Jump to language section read_file(target_file, offset=315, limit=8) # TypeScript @@ -73,11 +77,12 @@ read_file(target_file, offset=333, limit=8) # Rust ``` **Token Savings**: -- Full file: 1097 lines (~3800 tokens) -- Prerequisites only: 146 lines (~500 tokens) → **87% savings** +- Full file: 1158 lines (~4050 tokens) +- Prerequisites only: 146 lines (~500 tokens) → **88% savings** - Language-specific: 8 lines (~30 tokens) → **99% savings** 🏆 -- Python + pyproject.toml: 141 lines (~490 tokens) → **87% savings** -- Phase-specific: 67-211 lines (~230-730 tokens) → **81-94% savings** +- Python + metadata + navigation: 203 lines (~710 tokens) → **82% savings** +- Command navigation only: 75 lines (~260 tokens) → **94% savings** +- Phase-specific: 67-273 lines (~230-950 tokens) → **77-94% savings** --- @@ -365,19 +370,11 @@ grep -A 30 "^## Implementation" specs/toolkit/001-*/spec.md # CLI commands this speckit provides cli_commands = ["init", "validate", "generate", "info"] - # Slash command system type (auto-detected from sources) - sd_type = "generic" # See calculation rules below + # Slash command system type (see calculation rules below) + sd_type = "custom" # Slash commands this speckit provides (for AI agents) - [[tool.metaspec.slash_commands]] - name = "show-spec" - description = "Display domain specification" - source = "generic" - - [[tool.metaspec.slash_commands]] - name = "get-template" - description = "Get entity template" - source = "generic" + slash_commands = ["show-spec", "get-template"] ``` **Update Procedure**: @@ -387,56 +384,50 @@ grep -A 30 "^## Implementation" specs/toolkit/001-*/spec.md - Or list from `[project.scripts]` entrypoints - Update: `cli_commands = ["cmd1", "cmd2", ...]` - 2. **Slash Commands**: Scan `.metaspec/commands/` for actual `.md` files + 2. **Slash Commands**: List all `.md` files in `.metaspec/commands/` - Each `.md` file = one slash command - Extract name from filename (e.g., `show-spec.md` → `show-spec`) - - Extract description from frontmatter `description:` field - - Determine source: - * From `library/sdd/` → `source = "sdd/spec-kit"` or specific sub-library - * From `library/sds/` → `source = "sds"` - * Custom domain-specific → `source = "generic"` + - Update: `slash_commands = ["cmd1", "cmd2", ...]` - 3. **sd_type**: Auto-calculate from slash command sources - - Only `"sdd/*"` sources → `sd_type = "sdd"` - - Only `"sds/*"` sources → `sd_type = "sds"` - - Only `"generic"` sources → `sd_type = "generic"` - - Mixed sources → `sd_type = ["generic", "sdd"]` (array) - - No slash commands → `sd_type = "none"` + 3. **sd_type**: Classify the command system + - **SD-X systems** (following `sd` pattern): + * `"sdd"` - Spec-Driven Development (from library/sdd/) + * `"sds"` - Spec-Driven Specification (from library/sds/) + * `"sdm"` - Spec-Driven Marketing (custom marketing workflow) + * `"sdt"`, `"sdo"`, etc. - Other SD-X extensions + - **Non-SD-X**: + * `"custom"` - Custom commands not following SD-X pattern + * `"none"` - No slash commands + - **Mixed**: `["custom", "sdd"]` or `["sdm", "sdd"]` (array) **Example Scenarios**: - **Scenario 1: Domain-Specific Speckit** (MCP) + **Scenario 1: Custom Commands** (MCP - not SD-X) ```toml cli_commands = ["init", "validate", "generate"] - sd_type = "generic" - - [[tool.metaspec.slash_commands]] - name = "show-spec" - source = "generic" # Custom MCP command + sd_type = "custom" + slash_commands = ["show-spec", "get-template"] ``` - **Scenario 2: Spec-Kit Pattern Speckit** + **Scenario 2: SDD System** (Spec-Kit Pattern) ```toml cli_commands = ["init", "validate"] sd_type = "sdd" + slash_commands = ["specify", "plan", "implement"] + ``` - [[tool.metaspec.slash_commands]] - name = "specify" - source = "sdd/spec-kit" # From library + **Scenario 3: SDM System** (Spec-Driven Marketing) + ```toml + cli_commands = ["info", "init", "validate"] + sd_type = "sdm" + slash_commands = ["marketspec.constitution", "marketspec.specify", "marketspec.plan", ...] ``` - **Scenario 3: Mixed Pattern Speckit** + **Scenario 4: Mixed Systems** ```toml cli_commands = ["init", "validate", "analyze"] - sd_type = ["generic", "sdd"] - - [[tool.metaspec.slash_commands]] - name = "discover" - source = "generic" # Custom - - [[tool.metaspec.slash_commands]] - name = "specify" - source = "sdd/spec-kit" # From library + sd_type = ["custom", "sdd"] + slash_commands = ["discover", "specify", "plan", "generate"] ``` **Purpose**: This metadata enables community to: @@ -444,7 +435,82 @@ grep -A 30 "^## Implementation" specs/toolkit/001-*/spec.md - Understand AI command system type (what workflow pattern?) - Search/filter speckits by capabilities -3. **Verify task**: +3. **Optimize Long Slash Commands** ⭐ NEW + + **When**: Slash command files in `.metaspec/commands/` or `templates/*/commands/` exceed 500 lines + + **Why**: Save 70-90% token consumption when AI reads commands + + **How**: Add precision-guided navigation at file start (after frontmatter) + + **Navigation Template**: + + ```markdown + --- + name: command-name + description: Command description + --- + + # /command-name + + 📖 **Navigation Guide** (Token Optimization) + + **File Size**: {line_count} lines (~{token_estimate} tokens) + **Recommended**: Read specific sections to save 70-90% tokens + + | Section | Lines | Size | Usage | + |---------|-------|------|-------| + | 1. Purpose & Usage | 1-100 | 100 lines | `read_file(target, offset=1, limit=100)` | + | 2. Input Analysis | 101-250 | 150 lines | `read_file(target, offset=101, limit=150)` | + | 3. Processing Rules | 251-500 | 250 lines | `read_file(target, offset=251, limit=250)` | + | 4. Output Format | 501-750 | 250 lines | `read_file(target, offset=501, limit=250)` | + | 5. Examples | 751-{end} | {size} lines | `read_file(target, offset=751, limit={size})` | + + **💡 Typical Usage**: + ```python + # Quick reference: Read purpose only (100 lines) + read_file(target, offset=1, limit=100) + + # Specific section: Read processing rules (250 lines) + read_file(target, offset=251, limit=250) + + # Full understanding: Read all sections sequentially + ``` + + **Token Savings**: + - Full file: {line_count} lines (~{token_estimate} tokens) + - Single section: 100-250 lines (~350-850 tokens) → **70-90% savings** 🏆 + + --- + + [Actual command content starts here...] + ``` + + **Guidelines**: + - **Threshold**: Add navigation for commands >500 lines + - **Sections**: 4-6 logical sections, each 100-300 lines + - **Line Numbers**: Calculate actual boundaries (use `wc -l`) + - **Token Estimate**: ~3.5 tokens per line average + - **Savings**: Emphasize 70-90% for section reads + + **Section Design**: + - Section 1: Purpose, usage, quick reference + - Section 2-N: Major logical blocks (input, rules, output, etc.) + - Last section: Examples and edge cases + + **Example Calculation**: + ```bash + # For 847-line command + Section 1: Purpose & Usage (1-100, 100 lines) + Section 2: Input Analysis (101-250, 150 lines) + Section 3: Processing Rules (251-500, 250 lines) + Section 4: Output Format (501-700, 200 lines) + Section 5: Examples (701-847, 147 lines) + + Token savings: 847 lines → 150 lines = 82% savings + ``` + +4. **Verify task**: - **SETUP**: Files created, configs valid, dependencies installable - **MODELS**: Models instantiable, match specification entities - **PARSER**: Can parse valid/invalid specs, error handling works @@ -453,11 +519,11 @@ grep -A 30 "^## Implementation" specs/toolkit/001-*/spec.md - **TESTS**: Tests pass, coverage adequate - **DOCS**: Documentation complete, examples work -4. **Mark complete**: +5. **Mark complete**: - Update tasks.md: `- [ ] T001` → `- [x] T001` - Report: "✅ T001 complete: Created directory structure" -5. **Handle errors**: +6. **Handle errors**: - If task fails: Report error, suggest fix - If sequential task fails: Halt phase - If parallel task fails: Continue others, report at end