# ASDM Design Principles ## 1. Spec-Driven Development All outputs — documents, code, commit messages — are governed by **specs** (structural templates that define format, constraints, and validation rules). **Actions** (workflow instructions) guide AI models to follow specs, separating *what to produce* from *how to produce it*. - Specs are customizable by project managers and product owners. - Actions read applicable specs before generating any output. - Self-check validation is mandatory after generation. **Why:** Separating structure from workflow prevents AI models from drifting from expected formats and ensures consistency across all generated artifacts. **How to apply:** When creating a new toolset or extending an existing one, always define the spec first, then write the action that references it. Never embed structural rules directly into action instructions. --- ## 2. Multi-Provider Portability Every toolset must be installable and functional across three AI coding assistants: Claude Code, GitHub Copilot, and Tencent Codebuddy. Provider-specific frontmatter is concatenated with shared instruction content to produce provider-specific command files. - The framework ships a single source of truth per action. - Provider adapters handle frontmatter syntax differences (e.g., `---` headers for Claude, prompt format for Copilot, command metadata for Codebuddy). - No action logic is duplicated across providers. **Why:** Lock-in to a single AI provider limits adoption and creates maintenance burden when provider APIs change. **How to apply:** When writing a new action, author it as a standalone `.md` file in `actions/`. The installation process handles provider-specific packaging. Never write provider-specific logic inside action content. --- ## 3. Context Injection Context Builder generates workspace understanding files (architecture, data models, API, deployment, coding style, project structure) that other toolsets **read before performing their work**, ensuring alignment with the actual codebase rather than generic assumptions. - Context files reside in `.asdm/contexts/` and are referenced by downstream toolsets. - Context is generated incrementally (one file at a time) to manage token usage. - Context updates are incremental — only changed files are regenerated. **Why:** AI models produce better results when grounded in actual project state. Without context injection, generated code and documents drift from reality. **How to apply:** Every action that modifies or extends the workspace must begin by reading relevant context files from `.asdm/contexts/`. If context files don't exist, invoke Context Builder first. --- ## 4. Progressive Generation All generation tasks are performed **incrementally** — one file, one section, one task at a time. This avoids overwhelming the AI model's token window and preserves output quality. - Context files are generated one at a time. - PRD documents are generated per-feature, then per-task. - Prototype code is generated per-component with spec-reading pauses. - Each generation step is a discrete, reviewable unit. **Why:** Large single-shot generations degrade quality, exceed token limits, and are difficult to review or roll back. **How to apply:** Never ask an AI model to generate multiple files or large documents in a single invocation. Break work into steps, validate each step, and proceed incrementally. --- ## 5. Language Awareness All actions detect the workspace environment language **first** and maintain language consistency throughout the entire workflow. Supported languages include English, Chinese, and others. - Detection happens at the start of every action execution. - All generated content (comments, documents, commit messages) matches the detected language. - User-facing prompts and confirmations respect the detected language. **Why:** Mixed-language outputs confuse team members and reduce document readability. Consistency improves collaboration across multilingual teams. **How to apply:** Every action must include a language detection step as its first operation. Never default to English without checking. --- ## 6. Mandatory Spec Reading Before Generation Before generating any code or document, the AI model must **read all applicable specs**. This is enforced as a workflow gate — generation cannot proceed until specs are loaded. - Prototype Builder reads framework-specific specs (React, Vue, HTML, Mini Program) before writing code. - PRD Builder reads feature/task PRD specs before generating planning documents. - Commit actions read commit message specs before composing messages. **Why:** Skipping spec reading leads to outputs that violate structural constraints, producing inconsistent or invalid artifacts. **How to apply:** Every generation action must include an explicit "read specs" step before the "generate" step. Never allow generation to proceed with spec content assumed or cached. --- ## 7. Task Decomposition Constraints Features are decomposed into tasks with strict size limits to ensure manageable scope and predictable execution: - **Maximum 10 tasks per feature.** If exceeded, the feature must be split into sub-features. - **Task size target:** 1–2 hours of human developer effort. - Tasks follow a lifecycle: TODO → IN PROGRESS → DONE (or BLOCKED / CANCELLED). - Each task has its own PRD document stored in `.asdm/workspace/features/-/`. **Why:** Oversized features and tasks are difficult to track, validate, and complete. Small, well-defined tasks improve estimation, reduce risk, and enable parallel execution. **How to apply:** When planning a feature, count tasks immediately. If the count exceeds 10, propose sub-feature decomposition before generating task PRDs. --- ## 8. Skill-Based Code Generation The PRD Execution toolset uses **Skills** — registered code generation modules that produce implementation code from task PRDs. Skills are extensible and technology-specific. - Current skills: `java-springboot-crud`, `dotnet-crud`, `go-crud`, `python-fastapi-crud`, `sql-ddl`. - Skills are registered in a centralized registry (`.asdm/skills/skills-registry.json`). - New skills can be added without modifying the framework core. **Why:** Code generation requirements vary by technology stack. A monolithic generator would be unmaintainable; modular skills allow targeted, stack-aware generation. **How to apply:** When executing a task PRD, select the appropriate skill from the registry based on the project's technology context. When adding a new technology stack, create a new skill module and register it. --- ## 9. Workspace Directory Conventions The framework enforces a consistent directory structure across all workspaces: | Directory | Purpose | |---|---| | `.asdm/toolsets/` | Core framework toolsets (basic-tools, context-builder, prd-builder, prototype-builder) | | `.asdm/contexts/` | Generated workspace context files | | `.asdm/workspace/features/` | Feature and task PRD documents | | `.asdm/prototypes/` | Generated frontend prototypes | | `.asdm/skills/` | Skills registry and skill modules | | `.workspace/` | Project-specific workspace configuration and documents | **Why:** Consistent directory conventions enable cross-project portability and predictable toolset behavior regardless of the underlying project type. **How to apply:** All toolsets must respect these directory paths. Never introduce ad-hoc directories without updating the convention table. --- ## 10. AI-Guided Installation Every toolset ships with an `INSTALL.md` that serves as the **single source of installation instructions**. AI coding assistants follow these instructions to set up the toolset in a workspace, including creating provider-specific command files and registering actions. - Installation is performed by the AI assistant, not by a human running scripts. - INSTALL.md must be self-contained — no external dependencies or manual steps. - The installation process adapts to the detected AI provider environment. **Why:** Manual installation steps are error-prone and discourage adoption. AI-guided installation reduces friction and ensures consistent setup across environments. **How to apply:** When creating a new toolset, write INSTALL.md first. It must specify: directory structure, command file creation, and any post-install validation. Never assume the user will manually configure anything. --- ## 11. Self-Check Validation After every generation step, the AI model must perform a **self-check** — reviewing the output against the applicable spec to confirm compliance before proceeding. - Prototype Builder validates generated code against framework specs. - PRD Builder validates documents against PRD spec templates. - Git actions validate commit messages against the commit message spec. **Why:** AI models can drift from specs during generation. Self-check catches violations before they propagate downstream. **How to apply:** Every action that produces output must include a final "validate against spec" step. If validation fails, the action must report the violation and propose a correction rather than silently proceeding.