Back to Details

setup-asdlc

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Setup ASDLC

搭建ASDLC

Overview

概述

Initialize a repository for ASDLC adoption by creating AGENTS.md template, directory structure (specs/, .plans/), and basic configuration. This command prepares repositories to use ASDLC patterns while remaining optional—other commands work without running setup.
通过创建AGENTS.md模板、目录结构（specs/、.plans/）和基础配置，初始化一个用于采用ASDLC的仓库。该命令为仓库准备好ASDLC模式的使用环境，但它是可选操作——其他命令无需运行此设置即可正常工作。

Definitions

定义

  • AGENTS.md: Agent Constitution file that defines project context, operational boundaries, and command registry for AI agents.
  • specs/: Directory containing permanent living specifications for features.
  • .plans/: Directory containing transient task-level implementation plans.
  • schemas/: Directory containing JSON Schema definitions for validation (Standardized Parts pattern).
  • MCP: Model Context Protocol — framework for AI agents to connect to external services.
  • Standardized Parts: ASDLC pattern for schema-enforced structure and validation.
  • AGENTS.md：Agent规则文件，用于为AI Agent定义项目上下文、操作边界和命令注册表。
  • specs/：存放功能永久规范文档的目录。
  • .plans/：存放临时任务级实现计划的目录。
  • schemas/：存放用于验证的JSON Schema定义的目录（Standardized Parts模式）。
  • MCP：Model Context Protocol（模型上下文协议）——AI Agent连接外部服务的框架。
  • Standardized Parts：ASDLC中的一种模式，用于实现基于Schema的强制结构与验证。

Prerequisites

前置条件

  • None required. This command is optional and can be run at any time.
  • MCP setup is optional — command will check MCP status but won't block if unavailable.
  • Git repository — command works best in a Git repository but doesn't require it.
  • 无强制要求。此命令为可选操作，可随时运行。
  • MCP搭建为可选操作——命令会检查MCP状态，但即使MCP不可用也不会终止流程。
  • Git仓库——此命令在Git仓库中运行效果最佳，但并非必须。

Purpose

目的

Enable teams to quickly adopt ASDLC patterns by automating initial repository setup. This command creates the foundational structure (AGENTS.md, specs/, .plans/) that supports ASDLC workflows while maintaining flexibility—teams can use other commands without running setup.
通过自动化初始仓库搭建，帮助团队快速采用ASDLC模式。该命令创建支持ASDLC工作流的基础结构（AGENTS.md、specs/、.plans/），同时保持灵活性——团队无需运行此设置即可使用其他命令。

Steps

步骤

  1. Check for existing AGENTS.md
    • Check if 
      AGENTS.md
      exists in repository root
    • If exists: Report "AGENTS.md already exists, skipping creation"
    • If missing: Proceed to generate template (Step 2)
  2. Generate AGENTS.md template (if missing)
    • Read existing 
      AGENTS.md
      from this repository as template reference (if available)
    • Create 
      AGENTS.md
      with template structure:
      • Project Mission placeholder: 
        > **Project Mission:** [Your project mission statement]
      • Core Philosophy placeholder: 
        > **Core Philosophy:** [Your core development philosophy]
      • ASDLC Alignment placeholder: 
        > **ASDLC Alignment:** [Your ASDLC alignment statement]
      • Identity & Persona section with placeholders
      • Tech Stack section with placeholders
      • Operational Boundaries (3-tier structure):
        • Tier 1 (ALWAYS): Non-negotiable standards
        • Tier 2 (ASK): High-risk operations requiring Human-in-the-Loop
        • Tier 3 (NEVER): Safety limits
      • Command Registry (empty, to be populated)
      • Development Map (placeholder)
      • Common Pitfalls section (examples)
    • Report: "Created AGENTS.md template"
  3. Create specs/ directory
    • Check if 
      specs/
      directory exists
    • If exists: Report "specs/ directory already exists, skipping creation"
    • If missing: Create 
      specs/
      directory
    • Check if 
      specs/README.md
      exists
    • If missing: Copy 
      specs/README.md
      from this repository (if available) or create basic README
    • Report: "Created specs/ directory with README.md"
  4. Create .plans/ directory
    • Check if 
      .plans/
      directory exists
    • If exists: Report ".plans/ directory already exists, skipping creation"
    • If missing: Create 
      .plans/
      directory
    • Create 
      .plans/.gitkeep
      file to ensure directory is tracked by Git
    • Report: "Created .plans/ directory"
  5. Detect if schemas/ directory is needed
    • Check if 
      schemas/
      directory exists
    • If exists: Report "schemas/ directory already exists, skipping creation"
    • If missing: Check for schema indicators:
      • If 
        AGENTS.md
        exists, search for keywords: "Standardized Parts", "schema", "validation"
      • If any keyword found: Create 
        schemas/
        directory and 
        schemas/README.md
        template
      • Report: "Detected need for schemas/ (found: {keyword} in AGENTS.md)" or "No schemas/ needed (no indicators found)"
  6. Create schemas/README.md template (if schemas/ was created)
    • Create 
      schemas/README.md
      with template explaining:
      • When schemas are needed (Standardized Parts pattern)
      • Link to ASDLC Standardized Parts pattern
      • Note: Can be added later if needed
    • Report: "Created schemas/README.md template"
  7. Optional: Verify MCP setup (non-blocking)
    • Attempt to run 
      python schemas/validate_mcps.py --list
      (if available)
    • If successful: Report "MCP setup detected"
    • If fails or unavailable: Report "MCP setup not detected (optional, can be configured later)"
    • Continue regardless of result
  8. Optional: Verify issue tracker connection (non-blocking)
    • Attempt to call lightweight MCP tool (e.g., 
      mcp_atlassian_getAccessibleAtlassianResources
      or 
      mcp_github_list_commits
      )
    • If successful: Report "Issue tracker connection verified"
    • If fails or unavailable: Report "Issue tracker connection not available (optional, can be configured later)"
    • Continue regardless of result
  9. Generate setup summary
    • Report what was created vs skipped
    • Provide next steps guidance:
      • "Next steps: Customize AGENTS.md with your project details"
      • "Configure MCP servers (see docs/reference/mcp-setup.md)"
      • "Create your first spec with /create-plan"
  1. 检查现有AGENTS.md文件
    • 检查仓库根目录是否存在
      AGENTS.md
    • 若存在：提示“AGENTS.md已存在，跳过创建”
    • 若不存在：继续执行步骤2生成模板
  2. 生成AGENTS.md模板（若不存在）
    • 读取当前仓库中已有的
      AGENTS.md
      作为模板参考（如果可用）
    • 创建包含以下结构的
      AGENTS.md
      模板：
      • 项目使命占位符：
        > **项目使命:** [填写你的项目使命宣言]
      • 核心理念占位符：
        > **核心理念:** [填写你的核心开发理念]
      • ASDLC适配占位符：
        > **ASDLC适配:** [填写你的ASDLC适配说明]
      • 身份与角色部分（含占位符）
      • 技术栈部分（含占位符）
      • 操作边界（三级结构）：
        • 第一级（必须遵守）：不可协商的标准
        • 第二级（需确认）：需要人工介入的高风险操作
        • 第三级（禁止）：安全限制
      • 命令注册表（空，待填充）
      • 开发路线图（占位符）
      • 常见问题部分（含示例）
    • 提示：“已创建AGENTS.md模板”
  3. 创建specs/目录
    • 检查
      specs/
      目录是否存在
    • 若存在：提示“specs/目录已存在，跳过创建”
    • 若不存在：创建
      specs/
      目录
    • 检查
      specs/README.md
      是否存在
    • 若不存在：从当前仓库复制
      specs/README.md
      （如果可用），或创建基础版README
    • 提示：“已创建specs/目录及README.md”
  4. 创建.plans/目录
    • 检查
      .plans/
      目录是否存在
    • 若存在：提示“.plans/目录已存在，跳过创建”
    • 若不存在：创建
      .plans/
      目录
    • 创建
      .plans/.gitkeep
      文件，确保该目录被Git追踪
    • 提示：“已创建.plans/目录”
  5. 检测是否需要schemas/目录
    • 检查
      schemas/
      目录是否存在
    • 若存在：提示“schemas/目录已存在，跳过创建”
    • 若不存在：检查是否有schema相关标识：
      • 若
        AGENTS.md
        已存在，搜索关键词：“Standardized Parts”、“schema”、“validation”
      • 若找到任意关键词：创建
        schemas/
        目录及
        schemas/README.md
        模板
      • 提示：“检测到需要schemas/目录（在AGENTS.md中找到：{关键词}）”或“无需创建schemas/目录（未找到相关标识）”
  6. 创建schemas/README.md模板（若已创建schemas/目录）
    • 创建包含以下说明的
      schemas/README.md
      模板：
      • 何时需要使用schemas（Standardized Parts模式场景）
      • ASDLC Standardized Parts模式的链接
      • 说明：后续需要时可再添加
    • 提示：“已创建schemas/README.md模板”
  7. 可选：验证MCP搭建状态（非阻塞）
    • 尝试运行
      python schemas/validate_mcps.py --list
      （如果可用）
    • 若成功：提示“检测到MCP已搭建”
    • 若失败或不可用：提示“未检测到MCP搭建（可选，后续可配置）”
    • 无论结果如何，继续执行后续步骤
  8. 可选：验证问题追踪工具连接（非阻塞）
    • 尝试调用轻量MCP工具（例如
      mcp_atlassian_getAccessibleAtlassianResources
      或
      mcp_github_list_commits
      ）
    • 若成功：提示“问题追踪工具连接已验证”
    • 若失败或不可用：提示“问题追踪工具连接不可用（可选，后续可配置）”
    • 无论结果如何，继续执行后续步骤
  9. 生成搭建总结
    • 报告已创建和已跳过的内容
    • 提供后续步骤指导：
      • “后续步骤：自定义AGENTS.md，填写你的项目详情”
      • “配置MCP服务器（参考文档：docs/reference/mcp-setup.md）”
      • “使用/create-plan命令创建你的第一个规范文档”

Tools

工具

Filesystem Tools

文件系统工具

  • read_file
    - Read existing AGENTS.md and specs/README.md as templates
  • write
    - Create new files (AGENTS.md, specs/README.md, schemas/README.md)
  • list_dir
    - Check if directories exist
  • glob_file_search
    - Find existing files
  • read_file
    - 读取已有的AGENTS.md和specs/README.md作为模板
  • write
    - 创建新文件（AGENTS.md、specs/README.md、schemas/README.md）
  • list_dir
    - 检查目录是否存在
  • glob_file_search
    - 查找已存在的文件

Terminal Tools

终端工具

  • run_terminal_cmd
    - Execute commands: 
    • python schemas/validate_mcps.py --list
      (if available) - Check MCP setup
    • git status
      (optional) - Verify Git repository
  • run_terminal_cmd
    - 执行命令： 
    • python schemas/validate_mcps.py --list
      （如果可用）- 检查MCP搭建状态
    • git status
      （可选）- 验证Git仓库状态

MCP Tools (Optional, Non-Blocking)

MCP工具（可选，非阻塞）

  • mcp_atlassian_getAccessibleAtlassianResources
    - Verify Atlassian/Jira connection
    • Parameters: None
    • Error handling: If fails, report but continue
  • mcp_github_list_commits
    - Verify GitHub connection
    • Parameters: 
      owner
      , 
      repo
      (if available)
    • Error handling: If fails, report but continue
  • mcp_atlassian_getAccessibleAtlassianResources
    - 验证Atlassian/Jira连接
    • 参数：无
    • 错误处理：若失败，仅提示并继续执行
  • mcp_github_list_commits
    - 验证GitHub连接
    • 参数：
      owner
      、
      repo
      （如果可用）
    • 错误处理：若失败，仅提示并继续执行

Expected Output

预期输出

Fresh Repository Setup

全新仓库搭建

🚀 ASDLC Setup Complete

Created:
  ✅ AGENTS.md template
  ✅ specs/ directory with README.md
  ✅ .plans/ directory
  ⚠️  schemas/ not needed (no indicators found)

MCP Status:
  ⚠️  MCP setup not detected (optional, can be configured later)
  ⚠️  Issue tracker connection not available (optional, can be configured later)

Next steps:
  1. Customize AGENTS.md with your project details
  2. Configure MCP servers (see docs/reference/mcp-setup.md)
  3. Create your first spec with /create-plan
🚀 ASDLC 搭建完成

已创建:
  ✅ AGENTS.md模板
  ✅ specs/目录及README.md
  ✅ .plans/目录
  ⚠️  无需创建schemas/目录（未找到相关标识）

MCP状态:
  ⚠️  未检测到MCP搭建（可选，后续可配置）
  ⚠️  问题追踪工具连接不可用（可选，后续可配置）

后续步骤:
  1. 自定义AGENTS.md，填写你的项目详情
  2. 配置MCP服务器（参考文档：docs/reference/mcp-setup.md）
  3. 使用/create-plan命令创建你的第一个规范文档

Partial Setup (AGENTS.md exists)

部分搭建（AGENTS.md已存在）

🚀 ASDLC Setup Complete

Skipped:
  ⚠️  AGENTS.md already exists

Created:
  ✅ specs/ directory with README.md
  ✅ .plans/ directory
  ✅ schemas/ directory (detected: Standardized Parts in AGENTS.md)

MCP Status:
  ✅ MCP setup detected
  ✅ Issue tracker connection verified

Next steps:
  1. Create your first spec with /create-plan
🚀 ASDLC 搭建完成

已跳过:
  ⚠️  AGENTS.md已存在

已创建:
  ✅ specs/目录及README.md
  ✅ .plans/目录
  ✅ schemas/目录（检测到：AGENTS.md中包含Standardized Parts）

MCP状态:
  ✅ 检测到MCP已搭建
  ✅ 问题追踪工具连接已验证

后续步骤:
  1. 使用/create-plan命令创建你的第一个规范文档

Full Setup Already Exists

完整搭建已存在

🚀 ASDLC Setup Complete

All directories and files already exist:
  ✅ AGENTS.md
  ✅ specs/ directory
  ✅ .plans/ directory
  ✅ schemas/ directory

MCP Status:
  ✅ MCP setup detected
  ✅ Issue tracker connection verified

Repository is already set up for ASDLC!
🚀 ASDLC 搭建完成

所有目录和文件均已存在:
  ✅ AGENTS.md
  ✅ specs/目录
  ✅ .plans/目录
  ✅ schemas/目录

MCP状态:
  ✅ 检测到MCP已搭建
  ✅ 问题追踪工具连接已验证

仓库已完成ASDLC搭建！

When to Use

使用场景

  • New repository - Set up ASDLC structure from scratch
  • Existing repository - Add ASDLC structure to existing project
  • Team onboarding - Standardize setup across team members
  • ASDLC adoption - Begin using ASDLC patterns and workflows
  • 全新仓库：从零开始搭建ASDLC结构
  • 现有仓库：为现有项目添加ASDLC结构
  • 团队入职：在团队成员间标准化仓库搭建流程
  • ASDLC落地：开始使用ASDLC模式与工作流

Error Handling

错误处理

If AGENTS.md template generation fails:
  • Report error but continue with directory creation
  • Provide manual creation instructions
If directory creation fails:
  • Report which directories failed
  • Provide manual creation instructions
  • Continue with other operations
If MCP verification fails:
  • Report warning but continue (MCP is optional)
  • Provide MCP setup documentation link
If file copy fails (specs/README.md):
  • Create basic README.md with minimal content
  • Report that template copy failed
若AGENTS.md模板生成失败：
  • 报告错误，但继续执行目录创建操作
  • 提供手动创建的指导说明
若目录创建失败：
  • 报告创建失败的目录
  • 提供手动创建的指导说明
  • 继续执行其他操作
若MCP验证失败：
  • 报告警告，但继续执行（MCP为可选）
  • 提供MCP搭建文档的链接
若文件复制失败（specs/README.md）：
  • 创建仅包含基础内容的README.md
  • 报告模板复制失败

Notes

注意事项

  • This command is optional — other commands work without running setup
  • Command never overwrites existing files or directories
  • MCP verification is non-blocking — command succeeds even if MCP is unavailable
  • Schema detection is intelligent — only creates schemas/ if indicators are found
  • All operations are idempotent — safe to run multiple times
  • 此命令为可选操作——其他命令无需运行此设置即可正常工作
  • 命令绝不会覆盖现有文件或目录
  • MCP验证为非阻塞——即使MCP不可用，命令仍会执行成功
  • Schema检测为智能检测——仅当在AGENTS.md中找到相关标识时才会创建schemas/目录
  • 所有操作均为幂等操作——可安全多次运行

Guidance

指导说明

Role

角色

Act as a setup assistant helping teams initialize their repository for ASDLC adoption. You are helpful, non-intrusive, and provide clear guidance.
作为搭建助手，帮助团队初始化仓库以采用ASDLC。你需要提供有用、无干扰且清晰的指导。

Instruction

指令

Execute the setup workflow to prepare a repository for ASDLC by creating AGENTS.md template, directory structure, and optional configuration checks. Always check for existing files before creating, never overwrite, and provide clear feedback on what was created vs skipped.
执行搭建工作流，通过创建AGENTS.md模板、目录结构和可选配置检查，为仓库准备好ASDLC环境。创建前务必检查文件是否已存在，绝不覆盖现有内容，并清晰反馈已创建和已跳过的内容。

Context

上下文

  • This command enables teams to quickly adopt ASDLC patterns
  • Command is optional—other commands work without running setup
  • Based on recommendations from FB-32 analysis
  • Follows skill structure standards from AGENTS.md
  • ASDLC patterns: Agent Constitution, The Spec, Standardized Parts
  • ASDLC pillars: Factory Architecture (command station), Standardized Parts (schema-enforced structure), Quality Control (validation gates)
  • 此命令帮助团队快速落地ASDLC模式
  • 命令为可选操作——其他命令无需运行此设置即可正常工作
  • 基于FB-32分析的建议
  • 遵循AGENTS.md中的技能结构标准
  • ASDLC模式：Agent规则、规范文档、Standardized Parts
  • ASDLC核心支柱：工厂架构（命令站）、Standardized Parts（基于Schema的强制结构）、质量控制（验证关卡）

Examples

示例

ASDLC: Agent Constitution — AGENTS.md implements this pattern. Standardized Parts — Schema detection aligns with this pattern.
Example: Fresh Repository
User runs: /setup-asdlc
Result: Creates AGENTS.md, specs/, .plans/, reports summary
Example: Existing Repository
User runs: /setup-asdlc
Result: Skips existing files, creates missing directories, reports what was added
ASDLC：Agent规则——AGENTS.md实现了该模式。Standardized Parts——Schema检测与该模式对齐。
示例：全新仓库
用户运行：/setup-asdlc
结果：创建AGENTS.md、specs/、.plans/，并生成总结报告
示例：现有仓库
用户运行：/setup-asdlc
结果：跳过已存在的文件，创建缺失的目录，并报告新增内容

Constraints

约束条件

Rules (Must Follow):
  1. Operational Standards Compliance: This command follows operational standards (documented in AGENTS.md if present, but apply universally):
    • File Operations: Follow best practices for file operations and directory structure
    • Safety Limits: Never commit secrets, API keys, or sensitive data in generated files
    • AGENTS.md Optional: This command creates AGENTS.md, but other commands work without it. Standards apply regardless.
    • See AGENTS.md §3 Operational Boundaries (if present) for detailed standards
  2. Never Overwrite - Always check for existing files/directories before creating
  3. Optional MCP - MCP verification must not block command execution
  4. Intelligent Detection - Only create schemas/ if indicators are found in AGENTS.md
  5. Clear Feedback - Report what was created vs skipped with clear messages
  6. Idempotent - Command must be safe to run multiple times
  7. Template-Based - Use existing AGENTS.md and specs/README.md as templates when available
Existing Standards (Reference):
  • Command structure: See AGENTS.md §6 Command Structure Standards
  • Directory conventions: specs/ for specs, .plans/ for plans
  • File naming: AGENTS.md at root, specs/README.md for specs documentation
  • MCP setup: See docs/reference/mcp-setup.md for MCP configuration
  • Schema validation: See schemas/README.md for when schemas are needed
必须遵循的规则：
  1. 操作标准合规：此命令遵循操作标准（若AGENTS.md已存在则参考其中的标准，否则应用通用标准）：
    • 文件操作：遵循文件操作和目录结构的最佳实践
    • 安全限制：绝不在生成的文件中提交密钥、API密钥或敏感数据
    • AGENTS.md可选：此命令会创建AGENTS.md，但其他命令无需依赖它。标准始终适用。
    • 若AGENTS.md已存在，参考其中的§3操作边界获取详细标准
  2. 绝不覆盖——创建前始终检查文件/目录是否已存在
  3. MCP可选——MCP验证不得阻塞命令执行
  4. 智能检测——仅当在AGENTS.md中找到相关标识时才创建schemas/目录
  5. 清晰反馈——清晰报告已创建和已跳过的内容
  6. 幂等性——命令可安全多次运行
  7. 基于模板——可用时，使用已有的AGENTS.md和specs/README.md作为模板
现有标准（参考）：
  • 命令结构：参考AGENTS.md §6命令结构标准
  • 目录约定：specs/用于存放规范文档，.plans/用于存放计划
  • 文件命名：AGENTS.md存放在根目录，specs/README.md用于specs目录的文档说明
  • MCP搭建：参考docs/reference/mcp-setup.md进行MCP配置
  • Schema验证：参考schemas/README.md了解何时需要使用schemas

Output

输出内容

  1. Setup Summary: Report of what was created vs skipped
  2. MCP Status: Optional verification results (non-blocking)
  3. Next Steps: Guidance on customizing AGENTS.md and configuring MCP
  4. Clear Feedback: Explicit messages for each operation (created, skipped, detected)
The command prepares the repository for ASDLC adoption while maintaining flexibility and never overwriting existing files.
  1. 搭建总结：报告已创建和已跳过的内容
  2. MCP状态：可选的验证结果（非阻塞）
  3. 后续步骤：自定义AGENTS.md和配置MCP的指导
  4. 清晰反馈：每个操作的明确提示（已创建、已跳过、已检测到）
该命令为仓库准备好ASDLC落地环境，同时保持灵活性，绝不覆盖现有文件。