DOCSEARCHbyAlgolia
Submit Docs

OpenSPDD Documentation

repository·main·Indexed 20 days ago

https://github.com/gszhangwei/open-spdd

A methodology and CLI tool for Structured Prompt-Driven Development (SPDD). It uses the REASONS Canvas framework to transform AI coding prompts into executable design contracts, enabling bidirectional synchronization between design documents and implementation. OpenSPDD supports integration with AI coding environments including Cursor, Claude Code, Antigravity, GitHub Copilot, OpenCode, and Codex.

Tokens
40.8K
Snippets
97
Records
177
Agent score
69%

What's inside OpenSPDD

  1. Core Subcommands of the spdd CLI

    main

    The spdd CLI tool is designed to manage AI coding assistant command templates. It provides three primary subcommands for managing your environment and templates:

    • init: Performs environment setup.
    • list: Displays a list of available command templates.
    • generate: Creates template files based on selected templates.

    The tool uses a Cobra-based architecture where the root command automatically performs environment detection as a global pre-run hook.

  2. Compare OpenSPDD with existing AI coding context mechanisms

    main

    While OpenSPDD provides a structured approach to design intent, other tools use different methods to provide context to AI agents:

    ToolContext Mechanism
    CursorAgent mode scans codebase; Plan Mode produces structured plans with file paths and references.
    KiroUses structured artifacts divided into requirements, design, and tasks files.
    Claude CodeUses CLAUDE.md for coding standards/workflow rules and hooks for machine-verifiable constraints.
    CodexUses AGENTS.md to record project conventions and recurring error corrections.
    GitHub CopilotSupports project-level specs via copilot-instructions.md and reusable templates in copilot-prompts/.

    OpenSPDD complements these by focusing specifically on the structural gaps in design decision-making and architectural constraints that these tools may miss.

  3. What is the REASONS Canvas framework?

    main

    The REASONS Canvas is a 7-dimensional structured design framework used to create a 'Design Contract' for AI coding. It prevents AI from 'hallucinating' architecture or implementation details by providing explicit constraints.

    • R - Requirements: The essence of the requirement (the 'Why').
    • E - Entities: Domain models (e.g., Mermaid class diagrams) (the 'What concepts').
    • A - Approach: Strategy and trade-offs (the 'How to approach').
    • S - Structure: Architecture layers, inheritance, and dependencies (the 'How components are organized').
    • O - Operations: Precise sequence of implementation tasks (the 'How to implement').
    • N - Norms: Coding standards and patterns (the 'Standards').
    • S - Safeguards: Constraints and guardrails (the 'What not to do').

  4. How the Template Manager categorizes and lists templates

    main

    The TemplateManager uses a hierarchical directory structure to classify templates into three main categories: core, tools, and optional.

    • Core Templates: Located in data/core/. These are the default templates installed by the system.
    • Tool-Specific Templates: Located in data/tools/{tool_dir_name}/. These are specific to the detected AI tool (e.g., copilot, cursor, claude-code).
    • Optional Templates: Located in data/optional/. These are available for manual selection.

    Users typically interact with the ListAvailable(tool AIToolType) method, which provides a merged, sorted list of both core and the specific templates for the detected tool.

    // Example of the logical grouping used by the TemplateManager
// ListAvailable(tool) = ListCore() + ListForTool(tool)
// ListAll() = ListCore() + All Tool Templates + ListOptional()

  5. Codex skill directory structure and naming

    main

    When OpenSPDD generates skills for Codex, it follows the official Codex directory-bundle pattern. Each skill is placed in its own subdirectory within the .agents/skills/ directory of your repository.

    Structure:

    • <repo>/.agents/skills/<skill-id>/SKILL.md
    • <repo>/.agents/skills/<skill-id>/agents/openai.yaml (optional, controls invocation policy)

    Naming: The <skill-id> directory is named after the SPDD command ID (e.g., spdd-analysis/, spdd-reasons-canvas/).

  6. How the SPDD Prompt Lifecycle works

    main

    The /spdd-prompt-update command is part of an iterative refinement cycle designed to keep your specification and implementation in sync. The lifecycle follows these stages:

    1. Create: Use /spdd-reasons-canvas to transform business context into a REASONS Canvas, which generates the initial .md prompt file.
    2. Update: Use /spdd-prompt-update to modify the prompt file when requirements change, architectural refinements are needed, or bugs are found in the specification.
    3. Generate: Use /spdd-generate to turn the updated structured prompt into actual implementation code.
    4. Sync: If code changes are made manually first, use /spdd-sync to update the prompt file and maintain consistency between the specification and the codebase.
    ┌─────────────────────────────────────────────────────────────────────────┐
│                    SPDD Prompt Lifecycle                                 │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  Create: /spdd-reasons-canvas                                           │
│  ┌────────────────────────────────────────────────────────────────┐    │
│  │ Business Context → REASONS Canvas → spdd/prompt/*.md            │    │
│  └────────────────────────────────────────────────────────────────┘    │
│                              │                                          │
│                              ▼                                          │
│  Update: /spdd-prompt-update  ◄────────────────────────┐               │
│  ┌────────────────────────────────────────────────────────────────┐    │
│  │ Existing Prompt + Change Request → Updated Prompt              │    │
│  │                                                                 │    │
│  │ Triggers:                                                       │    │
│  │ - New requirements from stakeholders                           │    │
│  │ - Architectural refinements                                   │    │
│  │ - Bug fixes in specification                                    │    │
│  │ - Constraint additions                                          │    │
│  └────────────────────────────────────────────────────────────────┘    │
│                              │                                          │
│                              ▼                                          │
│  Generate: /spdd-generate                                              │
│  ┌────────────────────────────────────────────────────────────────┐    │
│  │ Structured Prompt → Implementation Code                         │    │
│  └────────────────────────────────────────────────────────────────┘    │
│                              │                                          │
│                              ▼                                          │
│  Sync: /spdd-sync (if code changes first)                               │
│  ┌────────────────────────────────────────────────────────────────┐    │
│  │ Code Changes → Update Prompt → Maintain Consistency            │    │
│  └────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────┘

  7. Understand the SPDD Workflow phases

    main

    The /spdd-analysis command is the first phase in a multi-stage workflow designed to move from business requirements to verified code:

    1. Phase 0: /spdd-analysis (Strategic)

      • Goal: Analyze "What" and "Why".
      • Process: Concept-driven codebase exploration, domain concept identification, strategic approach, and risk/gap analysis.
      • Output: An enriched context document saved to spdd/analysis/<file-name>.md.

    2. Phase 1: /spdd-reasons-canvas (Tactical)

      • Goal: Analyze "How".
      • Process: Transforms the enriched context into a structured REASONS Canvas prompt.
      • Output: A structured prompt in spdd/prompt/.

    3. Phase 2: /spdd-generate (Implementation)

      • Goal: Generate code.
      • Process: Uses the structured prompt to validate, generate, and verify implementation code.

    4. Phase 3: /spdd-sync (Maintenance)

      • Goal: Maintain consistency.
      • Process: Analyzes code changes to update prompts and ensure alignment.
    ┌─────────────────────────────────────────────────────────────────────────┐
│                           SPDD Workflow                                  │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  Phase 0: /spdd-analysis                                                │
│  ┌────────────────────────────────────────────────────────────────┐    │
│  │ Business Requirement                                            │    │
│  │   + Concept-driven Codebase Exploration (targeted, not full)    │    │
│  │   + Domain Concept Identification (conceptual, not detailed)    │    │
│  │   + Strategic Approach & Trade-offs (direction, not specifics)  │    │
│  │   + Risk & Gap Analysis (ambiguities, edge cases, risks)        │    │
│  │   = Enriched Context (Business + Strategic + Risks)             │    │
│  │                                                                 │    │
│  │ Output: spdd/analysis/GGQPA-XXX-*-[Analysis]-*.md              │    │
│  └────────────────────────────────────────────────────────────────┘    │
│                              │                                          │
│                              ▼                                          │
│  Phase 1: /spdd-reasons-canvas                                         │
│  ┌────────────────────────────────────────────────────────────────┐    │
│  │ Enriched Context → REASONS Canvas Structured Prompt             │    │
│  │                                                                 │    │
│  │ Output: spdd/prompt/GGQPA-XXX-*.md (REASONS Canvas)            │    │
│  └────────────────────────────────────────────────────────────────┘    │
│                              │                                          │
│                              ▼                                          │
│  Phase 2: /spdd-generate                                               │
│  ┌────────────────────────────────────────────────────────────────┐    │
│  │ Structured Prompt → Validate → Generate → Verify → Code                │    │
│  │                                                                 │    │
│  │ Output: Implementation code following Operations sequence       │    │
│  └────────────────────────────────────────────────────────────────┘    │
│                              │                                          │
│                              ▼                                          │
│  Phase 3: /spdd-sync                                                   │
│  ┌────────────────────────────────────────────────────────────────┐    │
│  │ Code Changes → Analyze → Update Prompt → Consistency           │    │
│  │                                                                 │    │
│  │ Output: Implementation code following Operations sequence       │    │
│  └────────────────────────────────────────────────────────────────┘    │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

  8. Understand the GenerationStrategy interface and tool archetypes

    main

    OpenSPDD uses a GenerationStrategy interface to handle different ways AI tools consume generated content. Instead of a single hardcoded dispatch logic, the system uses a registry of strategies keyed by AIToolType.

    When you run generation commands, the system selects a strategy based on the detected tool. This allows different tools to have different 'archetypes' (file structures and formats):

    • FlatMarkdownStrategy: Used for tools that expect standard markdown files.
    • CopilotInstructionFileStrategy: Used for GitHub Copilot, which requires specific instruction file structures.
    • CodexSkillStrategy: Used for OpenAI Codex, which generates project-scoped skill bundles in <repo>/.agents/skills/<id>/SKILL.md and may also emit an agents/openai.yaml file.

    Every strategy must implement the GenerationStrategy interface, which provides two primary methods: GenerateAll (for bulk generation) and GenerateOne (for single template generation).

    type GenerationStrategy interface {
    GenerateAll(workingDir string, force bool) []GenerateResult
    GenerateOne(workingDir string, tmpl TemplateMeta, force bool) []GenerateResult
}

  9. Understand Codex skill generation and invocation

    main

    When using OpenSPDD with Codex, the tool generates project-scoped skill bundles instead of flat command files. These bundles follow the agentskills.io standard.

    Skill Bundle Structure

    Generated skills are located under .agents/skills/<id>/ and include:

    • SKILL.md: The skill definition.
    • agents/openai.yaml: Configuration for invocation behavior.

    Invocation Patterns

    • Command Syntax: Inside the Codex CLI or IDE extension, invoke SPDD commands using the $ prefix (e.g., $spdd-analysis) or via the /skills menu. Do not use the /spdd-analysis syntax used by other tools.
    • Implicit Invocation: By default, generated skills are configured for explicit-only invocation (allow_implicit_invocation: false in agents/openai.yaml). To allow Codex to auto-invoke these skills, pass the --allow-implicit flag during generation.

    Troubleshooting Codex Skills

    If generated skills do not appear in your Codex environment:

    1. Trust Model: Some Codex versions ignore skills from untrusted projects. Ensure your project is marked as trusted in your ~/.codex/config.toml.
    2. Restart: If skills are missing after a successful generation run, restart the Codex application.

  10. Distinguish between Capability and Control for AI workflows

    main

    To effectively manage AI coding agents, you must distinguish between two dimensions of performance:

    1. Capability Dimension: The AI's ability to understand requirements, generate syntactically correct code, and follow project conventions. This is driven by model intelligence and context window size.
    2. Control Dimension: The ability to ensure the AI's output aligns with your specific design intent, architectural trade-offs, and constraints. This involves defining what the AI must not do and choosing between multiple 'correct' technical solutions based on human business needs.

    Effective AI development requires moving beyond relying on the model's capability and implementing structured methods to improve control.

  11. How CopilotInstructionFileStrategy works

    main

    The CopilotInstructionFileStrategy manages the GitHub Copilot generation flow. It handles two distinct behaviors:

    1. Bulk Generation (GenerateAll): Creates the .github/copilot-instructions.md file (wrapped in SPDDMarkerStart and SPDDMarkerEnd markers) and then generates individual prompt files for all core templates.
    2. Single Template Generation (GenerateOne): Generates a single prompt file located in .github/copilot-prompts/<id>.md. Note: GenerateOne does not modify the .github/copilot-instructions.md file.

    This strategy is automatically registered for the detector.GitHubCopilot tool type.

    // Example of what GenerateAll produces:
// .github/copilot-instructions.md (with markers)
// .github/copilot-prompts/template-id.md

  12. Integration of /spdd-story into the SPDD workflow

    main

    /spdd-story is the entry point of the SPDD (Story-to-Production-Deployment-Definition) pipeline. It transforms high-level requirements into implementable units of work.

    The Workflow Pipeline

    1. /spdd-story (Pre-Phase): Decomposes requirements into INVEST-compliant stories in requirements/.
    2. /spdd-analysis (Phase 0): Takes a story and enriches it with domain concepts, strategy, and risks. Output: spdd/analysis/.
    3. /spdd-reasons-canvas (Phase 1): Converts enriched context into a structured REASONS Canvas prompt. Output: spdd/prompt/.
    4. /spdd-generate (Phase 2): Uses the prompt to generate, validate, and verify code.
    5. /spdd-api-test (Phase 3): Generates API test scripts from the story's Acceptance Criteria.
    6. /spdd-sync (Phase 4): Synchronizes code changes back to the analysis and prompts.

    Separation of Concerns

    Feature/spdd-story/spdd-analysis/spdd-reasons-canvas
    AudiencePO, Scrum Master, QADev Team, ArchitectDev Team
    Focus"What to build & for whom""What & Why in codebase context""How to build it"
    LanguageBusiness languageStrategic / conceptualTechnical / implementation
    Codebase AccessNone (reads requirements/ only)Deep explorationFull exploration
    Outputrequirements/*.mdspdd/analysis/*.mdspdd/prompt/*.md