Skip to content

LiorCohen/sdd / plugin/core/skills/external-spec-integration

external-spec-integration

Verified

Process external specifications through transformation, classification, gap analysis, component discovery, and decomposition. Creates workflow items with classified context.

External Spec Integration Skill

Processes external specification files into the SDD workflow structure. Transforms product specs into classified tech spec context - specs are created interactively one at a time.

Purpose

When a user provides an external specification via /sdd I want to import an external spec:

  • Archive the external spec to sdd/archive/external-specs/ (single copy, yyyymmdd-HHmm-filename format)
  • TRANSFORM the spec: classify information, identify gaps, ask clarifying questions
  • DISCOVER required components through targeted questions
  • DECOMPOSE into workflow items with classified context
  • Create workflow items with context in sdd/workflows/<id>-<name>/
  • DO NOT create SPEC.md or PLAN.md files - those are created interactively

CRITICAL: External specs are product specs (WHAT/WHY). This skill transforms them into tech spec context (HOW) before decomposition.

Key Insight: External Specs Are Inherently Incomplete

Always assume external specs are lacking:

  • Details not thought through by product people
  • Technical implications not considered by non-engineers
  • Missing edge cases, error handling, and non-functional requirements
  • Implicit assumptions never made explicit

Critical asymmetry:

AreaTypical Detail LevelAction Required
User-Facing InterfaceHighExtract and classify
UX/DesignHighExtract and classify
Integration ContractsLowMust be DERIVED from interface
Business LogicVery LowMust be extracted through questions
Persistence/DataVery LowMust be discovered from interface + actions
Non-FunctionalAbsentMust be explicitly asked

When to Use

  • During /sdd I want to import an external spec when external spec is provided

Input

Schema: schemas/input.schema.json

Accepts path to external spec file, target directory, workflow ID, and optional domain.

Output

Schema: schemas/output.schema.json

Returns archived spec path, workflow ID, hierarchical flag, and list of created workflow items.

Workflow Overview

  1. Archive external spec to sdd/archive/external-specs/ via system CLI
  2. Detect large specs (>15K tokens) and chunk if needed
  3. Transform product spec: classify information, identify gaps, ask clarifying questions
  4. Discover components via component-discovery skill (once for entire spec)
  5. Present outline to user with hierarchical decomposition if applicable
  6. Thinking step — domain analysis, specs impact, gap analysis, API-first ordering
  7. Display thinking output for user review
  8. Create workflow items via workflow-state skill
  9. Create context files (context.md) for each leaf item
  10. Return summary with transformation, components, items, and thinking output

Resource Files

For detailed guidance, read these on-demand:

Key Differences from Previous Version

BeforeAfter
Created SPEC.md + PLAN.md immediatelyCreates workflow items with context only
Archived to archive/Archives to sdd/archive/external-specs/
No domain analysisComprehensive thinking step with domain extraction
No transformationNEW: Transformation classifies and identifies gaps
No component discoveryNEW: Component discovery before decomposition
Order in session onlyOrder persisted in workflow.yaml
All specs created upfrontSpecs created one at a time through solicitation
Modal dialogs for questionsNEW: Non-blocking conversational questions

Dependencies

This skill orchestrates:

  • workflow-state - Creates workflow and items
  • component-discovery - Identifies needed components (NEW)
  • spec-decomposition - Analyzes spec structure with thinking step

Trigger: /sdd I want to import an external spec command.

Workflow Steps Summary

StepActionOutput
1Archive External Specsdd/archive/external-specs/...
2Detect Large SpecsSize estimation, chunking plan
3TransformationClassification, gaps, clarifications
4Component DiscoveryComponents list (not applied)
5Present OutlineUser reviews structure
6Thinking StepDomain analysis, dependencies
7Display ThinkingUser confirms analysis
8Create Workflow ItemsItems in workflow.yaml
9Create Context Filescontext.md for each item
10Return SummaryComplete output

Notes

  • External specs are product specs - they are transformed, not copied
  • Transformation happens BEFORE decomposition
  • Component discovery runs ONCE for entire spec (not per-item)
  • Questions are non-blocking and conversational (no modal dialogs)
  • All Q&A is preserved and flows into SPEC.md Requirements Discovery section
  • Context files contain classified content for use during solicitation
  • Items are processed one at a time - user reviews each spec before moving to next
  • Hierarchical decomposition is mandatory for specs meeting criteria (2+ H1 with H2+)
  • Numbers indicate implementation order based on API-first dependency sort
  • Large specs (>15K tokens) use chunked processing with per-section progress
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 319kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 196kUpdated Claude CodeCodexVerifiedInstall