{
"canonical_name": "Fission-AI/OpenSpec",
"compilation_id": "pack_5ea653a1e31f45509c6a2e1e5dd5ae23",
"created_at": "2026-05-19T19:06:03.428249+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=skill, recipe, host_instruction, eval, preflight",
"recommended_asset_types=skill, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `npm install -g @fission-ai/openspec@latest` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "npm install -g @fission-ai/openspec@latest",
"sandbox_container_image": "node:22-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_5fca58814d86463394995ec6a159ed26"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_2402bf5c472be4371984b8f412cc63c7",
"canonical_name": "Fission-AI/OpenSpec",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/Fission-AI/OpenSpec",
"slug": "openspec",
"source_packet_id": "phit_57ee38eceb074f479dd359d04c2cbc29",
"source_validation_id": "dval_bf038cb8d2444b7e9b33261fa07cd526"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 local_cli的用户",
"github_forks": 3320,
"github_stars": 47431,
"one_liner_en": "Spec-driven development (SDD) for AI coding assistants.",
"one_liner_zh": "Spec-driven development (SDD) for AI coding assistants.",
"primary_category": {
"category_id": "software-development",
"confidence": "high",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "matched_keywords:coding, development, test"
},
"target_user": "使用 local_cli 等宿主 AI 的用户",
"title_en": "OpenSpec",
"title_zh": "OpenSpec 能力包",
"visible_tags": [
{
"label_en": "Knowledge Retrieval",
"label_zh": "知识检索",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-knowledge-retrieval",
"type": "product_domain"
},
{
"label_en": "Knowledge Base Q&A",
"label_zh": "知识库问答",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-knowledge-base-q-a",
"type": "user_job"
},
{
"label_en": "Structured Data Extraction",
"label_zh": "结构化数据提取",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-structured-data-extraction",
"type": "core_capability"
},
{
"label_en": "Node-based Workflow",
"label_zh": "节点式流程编排",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-node-based-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Open Source Tool",
"label_zh": "开源工具",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-open-source-tool",
"type": "selection_signal"
}
]
},
"packet_id": "phit_57ee38eceb074f479dd359d04c2cbc29",
"page_model": {
"artifacts": {
"artifact_slug": "openspec",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "npm install -g @fission-ai/openspec@latest",
"label": "Node.js / npm · 官方安装入口",
"source": "https://github.com/Fission-AI/OpenSpec#readme",
"verified": true
}
],
"display_tags": [
"知识检索",
"知识库问答",
"结构化数据提取",
"节点式流程编排",
"开源工具"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 local_cli的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Spec-driven development (SDD) for AI coding assistants."
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "local_cli",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "skill, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：/opsx:apply suggests openspec-continue-change which is not installed on core profile",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_41aca88207aa4e70bba9c2ebaef629c7 | https://github.com/Fission-AI/OpenSpec/issues/963 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：/opsx:apply suggests openspec-continue-change which is not installed on core profile",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Support schema extension or partial overrides to avoid full shadowing of built-in schemas",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_34110f57274440d4bbc5492e3b4f3bee | https://github.com/Fission-AI/OpenSpec/issues/1074 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Support schema extension or partial overrides to avoid full shadowing of built-in schemas",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：open:sync messed up my spec.md files",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_ef1856d2856b49f5a7ed758bfc4099c8 | https://github.com/Fission-AI/OpenSpec/issues/911 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：open:sync messed up my spec.md files",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Codex generated assets reference unsupported AskUserQuestion/TodoWrite/Task tools",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_35b315a2b1a74564be1fb71d1f08359c | https://github.com/Fission-AI/OpenSpec/issues/1103 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Codex generated assets reference unsupported AskUserQuestion/TodoWrite/Task tools",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：First steps don't work",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_51f62d023b734ba59978cc70908c01c3 | https://github.com/Fission-AI/OpenSpec/issues/820 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：First steps don't work",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.1.0 - Cross-Platform Fixes, Nix Improvements",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_016f567cecd44fbf96ffd635e1ec43bf | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.1.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.1.0 - Cross-Platform Fixes, Nix Improvements",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.3.1 - Path & Telemetry Fixes",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_e641868122bb43938d6ff8a83b71e3d3 | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.3.1 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.3.1 - Path & Telemetry Fixes",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Incomplete artifacts marked as \"done\" after workflow interruption",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_a0677545a17b433ca6e6561c5056ee46 | https://github.com/Fission-AI/OpenSpec/issues/1084 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Incomplete artifacts marked as \"done\" after workflow interruption",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：OpenCode sync missing",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_0076a9fb05a1443eb3e2a7c9185247e6 | https://github.com/Fission-AI/OpenSpec/issues/1007 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：OpenCode sync missing",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.22.0 - Project Configuration",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_1a526029491b40e38c20ba075f311169 | https://github.com/Fission-AI/OpenSpec/releases/tag/v0.22.0 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.22.0 - Project Configuration",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.0.0 - The OPSX Release",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_b60a0c136c0347e9a034197f65844e1b | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.0.0 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.0.0 - The OPSX Release",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:1032459340 | https://github.com/Fission-AI/OpenSpec | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.0.1",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_006cb659e21c431290fe448ddabc453c | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.0.1 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.0.1",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.0.2",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_c7797487985047fba066bd58cba094ae | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.0.2 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.0.2",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Feedback: Deep verification test - PUA mode v3 active",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_d3d2fc07081648f796e477458600a95f | https://github.com/Fission-AI/OpenSpec/issues/1094 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Feedback: Deep verification test - PUA mode v3 active",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1032459340 | https://github.com/Fission-AI/OpenSpec | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 22 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：/opsx:apply suggests openspec-continue-change which is not installed on core profile。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 59,
"forks": 3320,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 47431
},
"source_url": "https://github.com/Fission-AI/OpenSpec",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Spec-driven development (SDD) for AI coding assistants.",
"title": "OpenSpec 能力包",
"trial_prompt": "# OpenSpec - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for Fission-AI/OpenSpec.\n\nProject:\n- Name: OpenSpec\n- Repository: https://github.com/Fission-AI/OpenSpec\n- Summary: Spec-driven development (SDD) for AI coding assistants.\n- Host target: local_cli\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: Spec-driven development (SDD) for AI coding assistants.\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Spec-driven development (SDD) for AI coding assistants.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. introduction: Introduction to OpenSpec. Produce one small intermediate artifact and wait for confirmation.\n2. getting-started: Getting Started. Produce one small intermediate artifact and wait for confirmation.\n3. architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n4. slash-commands: Slash Commands. Produce one small intermediate artifact and wait for confirmation.\n5. workflows: Workflows. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/Fission-AI/OpenSpec\n- https://github.com/Fission-AI/OpenSpec#readme\n- README.md\n- docs/concepts.md\n- docs/getting-started.md\n- docs/installation.md\n- package.json\n- src/core/init.ts\n- src/index.ts\n- src/cli/index.ts\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: Codex generated assets reference unsupported AskUserQuestion/TodoWrite/T（https://github.com/Fission-AI/OpenSpec/issues/1103）；github/github_issue: Incomplete artifacts marked as \"done\" after workflow interruption（https://github.com/Fission-AI/OpenSpec/issues/1084）；github/github_issue: /opsx:apply suggests openspec-continue-change which is not installed on （https://github.com/Fission-AI/OpenSpec/issues/963）；github/github_issue: Feedback: Deep verification test - PUA mode v3 active（https://github.com/Fission-AI/OpenSpec/issues/1094）；github/github_issue: Protect OpenSpec from AI slop PRs（https://github.com/Fission-AI/OpenSpec/issues/1087）；github/github_issue: open:sync messed up my spec.md files（https://github.com/Fission-AI/OpenSpec/issues/911）；github/github_issue: Incomplete artifacts marked as \"done\" after workflow interruption（https://github.com/Fission-AI/OpenSpec/issues/1084）；github/github_issue: Support schema extension or partial overrides to avoid full shadowing of（https://github.com/Fission-AI/OpenSpec/issues/1074）；github/github_issue: [Feature Request/Suggestion] Extension to package for custom schemas, as（https://github.com/Fission-AI/OpenSpec/issues/1081）；github/github_issue: First steps don't work（https://github.com/Fission-AI/OpenSpec/issues/820）；github/github_issue: OpenCode sync missing（https://github.com/Fission-AI/OpenSpec/issues/1007）；github/github_release: v1.3.1 - Path & Telemetry Fixes（https://github.com/Fission-AI/OpenSpec/releases/tag/v1.3.1）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "Codex generated assets reference unsupported AskUserQuestion/TodoWrite/T",
"url": "https://github.com/Fission-AI/OpenSpec/issues/1103"
},
{
"kind": "github_issue",
"source": "github",
"title": "Incomplete artifacts marked as \"done\" after workflow interruption",
"url": "https://github.com/Fission-AI/OpenSpec/issues/1084"
},
{
"kind": "github_issue",
"source": "github",
"title": "/opsx:apply suggests openspec-continue-change which is not installed on ",
"url": "https://github.com/Fission-AI/OpenSpec/issues/963"
},
{
"kind": "github_issue",
"source": "github",
"title": "Feedback: Deep verification test - PUA mode v3 active",
"url": "https://github.com/Fission-AI/OpenSpec/issues/1094"
},
{
"kind": "github_issue",
"source": "github",
"title": "Protect OpenSpec from AI slop PRs",
"url": "https://github.com/Fission-AI/OpenSpec/issues/1087"
},
{
"kind": "github_issue",
"source": "github",
"title": "open:sync messed up my spec.md files",
"url": "https://github.com/Fission-AI/OpenSpec/issues/911"
},
{
"kind": "github_issue",
"source": "github",
"title": "Incomplete artifacts marked as \"done\" after workflow interruption",
"url": "https://github.com/Fission-AI/OpenSpec/issues/1084"
},
{
"kind": "github_issue",
"source": "github",
"title": "Support schema extension or partial overrides to avoid full shadowing of",
"url": "https://github.com/Fission-AI/OpenSpec/issues/1074"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Feature Request/Suggestion] Extension to package for custom schemas, as",
"url": "https://github.com/Fission-AI/OpenSpec/issues/1081"
},
{
"kind": "github_issue",
"source": "github",
"title": "First steps don't work",
"url": "https://github.com/Fission-AI/OpenSpec/issues/820"
},
{
"kind": "github_issue",
"source": "github",
"title": "OpenCode sync missing",
"url": "https://github.com/Fission-AI/OpenSpec/issues/1007"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.3.1 - Path & Telemetry Fixes",
"url": "https://github.com/Fission-AI/OpenSpec/releases/tag/v1.3.1"
}
],
"status": "已收录 12 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "Spec-driven development (SDD) for AI coding assistants.",
"effort": "安装已验证",
"forks": 3320,
"icon": "code",
"name": "OpenSpec 能力包",
"risk": "可发布",
"slug": "openspec",
"stars": 47431,
"tags": [
"知识检索",
"知识库问答",
"结构化数据提取",
"节点式流程编排",
"开源工具"
],
"thumb": "gray",
"type": "Skill Pack"
},
"manual": {
"markdown": "# https://github.com/Fission-AI/OpenSpec 项目说明书\n\n生成时间：2026-05-18 02:52:58 UTC\n\n## 目录\n\n- [Introduction to OpenSpec](#introduction)\n- [Getting Started](#getting-started)\n- [System Architecture](#architecture)\n- [Slash Commands](#slash-commands)\n- [Workflows](#workflows)\n- [Artifact Graph System](#artifact-graph)\n- [Schemas](#schemas)\n- [Configuration](#configuration)\n- [Validation System](#validation-system)\n- [Supported AI Tools](#supported-tools)\n\n\n\n## Introduction to OpenSpec\n\n### 相关页面\n\n相关主题：[Getting Started](#getting-started), [System Architecture](#architecture)\n\n\nRelevant Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n- [CHANGELOG.md](https://github.com/Fission-AI/OpenSpec/blob/main/CHANGELOG.md)\n- [docs/getting-started.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/getting-started.md)\n- [docs/concepts.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/concepts.md)\n- [docs/workflows.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/workflows.md)\n- [docs/commands.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/commands.md)\n- [docs/supported-tools.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/supported-tools.md)\n \n\n# Introduction to OpenSpec\n\nOpenSpec is a lightweight specification framework designed to bring structure and alignment to AI-assisted software development. It establishes a shared understanding between human developers and AI coding assistants before any code is written, reducing unpredictability and improving project organization.\n\n## Purpose and Scope\n\nAI coding assistants are powerful but often unpredictable when project requirements exist only in chat history. OpenSpec adds a lightweight spec layer that ensures human and AI align on specifications before code gets written.\n\nThe framework operates under a core philosophy:\n\n```text\n→ fluid not rigid\n→ iterative not waterfall\n→ easy not complex\n→ built for brownfield not just greenfield\n→ scalable from personal projects to enterprises\n```\n\n**资料来源：** [README.md:1-20]()\n\n## Core Features\n\nOpenSpec provides several key capabilities:\n\n| Feature | Description |\n|---------|-------------|\n| **Agree Before Build** | Human and AI align on specs before code gets written |\n| **Stay Organized** | Each change gets its own folder with proposal, specs, design, and tasks |\n| **Work Fluidly** | Update any artifact anytime, no rigid phase gates |\n| **Tool Integration** | Works with 25+ AI assistants via slash commands |\n\n**资料来源：** [README.md:21-30]()\n\n## Architecture Overview\n\nOpenSpec uses an artifact-guided workflow where changes are organized into structured folders. The system tracks dependencies between artifacts and automatically manages state transitions.\n\n```mermaid\ngraph TD\n A[User Request] --> B[Proposal]\n B --> C[Specs]\n C --> D[Design]\n D --> E[Tasks]\n E --> F[Implementation]\n F --> G[Archive]\n G --> C\n \n H[Config.yaml] --> A\n H --> B\n H --> C\n \n style A fill:#e1f5fe\n style G fill:#c8e6c9\n```\n\n**资料来源：** [CHANGELOG.md:1-30]()\n\n## The Change Structure\n\nEvery change in OpenSpec follows a consistent folder structure:\n\n```\nopenspec/\n├── specs/ # Source-of-truth specifications\n│ └── /\n│ └── spec.md\n├── changes/\n│ ├── / # Active change folder\n│ │ ├── proposal.md # Why and what changes\n│ │ ├── tasks.md # Implementation checklist\n│ │ ├── design.md # Technical decisions (optional)\n│ │ └── specs/\n│ │ └── /\n│ │ └── spec.md # Delta showing additions/modifications\n│ └── archive/ # Completed changes\n│ └── YYYY-MM-DD-/\n└── config.yaml # Project configuration\n```\n\n**资料来源：** [README.md:200-230]()\n\n## Workflow System\n\nOpenSpec supports multiple workflow approaches:\n\n### Standard Workflow\n\nThe traditional linear approach:\n\n1. **Propose** - Create a change proposal that captures spec updates\n2. **Review** - Review the proposal with AI assistant until agreement\n3. **Implement** - Implement tasks that reference agreed specs\n4. **Archive** - Archive the change to merge approved updates back into source specs\n\n### Experimental Workflow\n\nThe new artifact-guided workflow using slash commands:\n\n| Command | Purpose |\n|---------|---------|\n| `/opsx:propose` | Start a new change |\n| `/opsx:new` | Start a new change (alternative) |\n| `/opsx:continue` | Create one artifact at a time (step-through) |\n| `/opsx:ff` | Fast-forward to completion |\n| `/opsx:verify` | Verify artifact integrity |\n| `/opsx:bulk-archive` | Archive multiple changes |\n| `/opsx:onboard` | Initialize OpenSpec in a project |\n\n**资料来源：** [README.md:150-170]()\n\n## Instruction System\n\nOpenSpec dynamically assembles instructions from three layers:\n\n```mermaid\ngraph LR\n A[Context] --> D[Enriched Instruction]\n B[Rules] --> D\n C[Template] --> D\n \n A1[project.yaml] --> A\n B1[Artifact-specific] --> B\n C1[Schema template] --> C\n```\n\n### Context Layer\nProject background from `config.yaml` including tech stack and conventions. Applied to **all artifacts**.\n\n### Rules Layer\nArtifact-specific constraints (e.g., \"propose spike tasks for unknowns\"). Applied only to **matching artifacts**.\n\n### Template Layer\nThe actual structure for the output file, sourced from schemas.\n\n**资料来源：** [CHANGELOG.md:40-70]()\n\n## Supported AI Tools\n\nOpenSpec integrates with 25+ AI coding assistants through slash commands or natural language:\n\n### Native Slash Commands\n\n| Tool | Commands | Configuration Path |\n|------|----------|-------------------|\n| **Claude Code** | `/opsx:propose`, `/opsx:apply`, `/opsx:archive` | Built-in |\n| **Amazon Q Developer** | `@openspec-proposal`, `@openspec-apply`, `@openspec-archive` | `.amazonq/prompts/` |\n| **CodeBuddy Code** | `/opsx:propose`, `/opsx:apply`, `/opsx:archive` | `.codebuddy/commands/` |\n| **Cursor** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.cursor/commands/` |\n| **Roo Code** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.roo/commands/` |\n\n### Workflow-Based Tools\n\n| Tool | Workflow Location |\n|------|-------------------|\n| **Cline** | `.clinerules/workflows/` |\n| **Windsurf** | `.windsurf/workflows/` |\n| **Kilo Code** | `.kilocode/workflows/` |\n\n**资料来源：** [README.md:80-120]()\n\n## Installation and Setup\n\n### Prerequisites\n\n- **Node.js >= 20.19.0** - Check with `node --version`\n\n### Installation Methods\n\n**Option A: npm (Global)**\n\n```bash\nnpm install -g @fission-ai/openspec@latest\n```\n\n**Option B: nix (NixOS)**\n\n```bash\nnix run github:Fission-AI/OpenSpec -- init\n```\n\nOr install to profile:\n\n```bash\nnix profile install github:Fission-AI/OpenSpec\n```\n\n**资料来源：** [README.md:50-80]()\n\n### Quick Start\n\n```bash\n# Navigate to project\ncd your-project\n\n# Initialize OpenSpec\nopenspec init\n\n# Start a new change\n/opsx:propose \n\n# Or use CLI directly\nopenspec new \n```\n\n**资料来源：** [README.md:40-55]()\n\n## Command Reference\n\n| Command | Description |\n|---------|-------------|\n| `openspec list` | View active change folders |\n| `openspec view` | Interactive dashboard of specs and changes |\n| `openspec show ` | Display change details |\n| `openspec validate ` | Check spec formatting and structure |\n| `openspec archive [--yes]` | Archive completed change |\n| `openspec config profile` | Select workflow profile |\n\n**资料来源：** [README.md:180-200]()\n\n## Telemetry\n\nOpenSpec collects anonymous usage statistics to understand usage patterns:\n\n- **Collected:** Command names and version only\n- **NOT collected:** Arguments, paths, content, or PII\n- **Auto-disabled:** In CI environments\n\n**Opt-out:**\n\n```bash\nexport OPENSPEC_TELEMETRY=0\n# or\nexport DO_NOT_TRACK=1\n```\n\n**资料来源：** [README.md:220-240]()\n\n## Contributing to OpenSpec\n\n```bash\n# Install dependencies\npnpm install\n\n# Build\npnpm run build\n\n# Test\npnpm test\n\n# Develop CLI locally\npnpm run dev\npnpm run dev:cli\n```\n\n**Commit convention:**\n\n```text\ntype(scope): subject\n```\n\n**资料来源：** [README.md:250-260]()\n\n## License\n\nOpenSpec is released under the **MIT License**.\n\n---\n\n\n\n## Getting Started\n\n### 相关页面\n\n相关主题：[Introduction to OpenSpec](#introduction), [Slash Commands](#slash-commands)\n\n\nRelevant Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n- [docs/getting-started.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/getting-started.md)\n- [docs/workflows.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/workflows.md)\n- [docs/cli.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/cli.md)\n- [docs/commands.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/commands.md)\n- [docs/installation.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/installation.md)\n- [openspec/changes/archive/2025-12-28-add-instruction-loader/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-12-28-add-instruction-loader/design.md)\n \n\n# Getting Started\n\n## Overview\n\nOpenSpec is a lightweight specification framework designed to help development teams align on requirements before writing code. It provides a structured approach to capturing proposals, specifications, designs, and implementation tasks in organized change folders that integrate seamlessly with AI coding assistants.\n\nThe \"Getting Started\" documentation serves as the entry point for new users, covering prerequisites, installation methods, project initialization, and the fundamental workflows that define how OpenSpec operates. This guide ensures users can quickly set up OpenSpec in their development environment and begin using its artifact-guided workflow for managing changes systematically.\n\n## Prerequisites\n\n### System Requirements\n\nOpenSpec has specific version requirements that must be met before installation:\n\n| Requirement | Minimum Version | Notes |\n|------------|-----------------|-------|\n| Node.js | 20.19.0 or higher | Check with `node --version` |\n| Package Managers | npm, pnpm, yarn, bun, or nix | Alternative installation options available |\n\n资料来源：[README.md:1]()\n\nTo verify your Node.js installation, run:\n\n```bash\nnode --version\n```\n\nIf the version is below 20.19.0, you must upgrade Node.js before proceeding with OpenSpec installation.\n\n## Installation\n\nOpenSpec can be installed through multiple methods depending on your development environment and preferences.\n\n### Method 1: npm (Global Installation)\n\nThe standard installation method uses npm to install OpenSpec globally:\n\n```bash\nnpm install -g @fission-ai/openspec@latest\n```\n\nAfter installation, verify the installation by checking the version:\n\n```bash\nopenspec --version\n```\n\n资料来源：[README.md:1]()\n\n### Method 2: Nix Package Manager\n\nFor NixOS or Nix package manager users, OpenSpec can be run directly without explicit installation:\n\n```bash\nnix run github:Fission-AI/OpenSpec -- init\n```\n\nAlternatively, install to your user profile:\n\n```bash\nnix profile install github:Fission-AI/OpenSpec\n```\n\nOr add to your Nix configuration for persistent access.\n\n### Method 3: Development Installation\n\nFor contributors or those who want to work with the source code:\n\n```bash\n# Clone the repository\ngit clone https://github.com/Fission-AI/OpenSpec.git\ncd OpenSpec\n\n# Install dependencies\npnpm install\n\n# Build the project\npnpm run build\n\n# Run tests\npnpm test\n\n# Develop CLI locally\npnpm run dev\n```\n\n资料来源：[README.md:1]()\n\n## Project Initialization\n\nOnce OpenSpec is installed, navigate to your project directory and initialize the OpenSpec structure:\n\n```bash\ncd your-project\nopenspec init\n```\n\nThe initialization process creates the necessary directory structure for OpenSpec artifacts:\n\n```text\nopenspec/\n├── config.yaml # Project configuration and context\n├── specs/ # Schema definitions and templates\n└── changes/ # Individual change proposals\n```\n\n### What `openspec init` Creates\n\n| Artifact | Purpose |\n|----------|---------|\n| `config.yaml` | Project context, tech stack, conventions |\n| `openspec/schemas/` | Schema definitions (spec-driven, etc.) |\n| `openspec/changes/` | Directory for change proposals |\n\n### Legacy Cleanup\n\nWhen running `openspec init` in an existing project that previously used OpenSpec, the initialization process detects and handles legacy artifacts:\n\n- Old slash command directories (`.claude/commands/openspec/`)\n- Config files with OpenSpec markers (`CLAUDE.md`, `.cursorrules`, `.windsurfrules`)\n- Legacy `openspec/AGENTS.md` files\n\nUsers are prompted for confirmation before removing these legacy artifacts.\n\n资料来源：[README.md:1]()\n资料来源：[openspec/changes/archive/2026-02-17-merge-init-experimental/design.md:1]()\n\n## Core Workflow: Artifact-Guided Approach\n\nOpenSpec uses an experimental artifact-guided workflow centered on creating structured changes. The workflow revolves around four key artifacts that capture different aspects of a change:\n\n```mermaid\ngraph TD\n A[Propose Change] --> B[Create Proposal]\n B --> C[Write Specs]\n C --> D[Design Solution]\n D --> E[Define Tasks]\n E --> F[Implement]\n F --> G[Verify]\n G --> H[Archive]\n \n I[Iterate on Any Artifact] -.-> A\n I -.-> B\n I -.-> C\n I -.-> D\n I -.-> E\n```\n\n### The Four Core Artifacts\n\n| Artifact | Purpose | Generated By |\n|----------|---------|--------------|\n| **Proposal** | Why the change is needed, what's changing | `/opsx:propose` |\n| **Specs** | Requirements and acceptance scenarios | Sequential creation |\n| **Design** | Technical approach and architecture | Sequential creation |\n| **Tasks** | Implementation checklist | Sequential creation |\n\nEach change folder under `openspec/changes//` contains these artifacts organized in a predictable structure.\n\n资料来源：[README.md:1]()\n\n## Supported AI Coding Assistants\n\nOpenSpec integrates with over 25 AI coding assistants through slash commands. The supported tools include:\n\n| Tool Category | Examples |\n|--------------|----------|\n| Claude Code | `/openspec/proposal`, `/openspec/apply`, `/openspec/archive` |\n| Cursor | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |\n| CodeBuddy | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |\n| Codex | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |\n| RooCode | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |\n| Kilo Code | `.kilocode/workflows/` with `/openspec-proposal.md` |\n| Windsurf | `.windsurf/workflows/` with `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |\n| Continue | `.continue/` with custom configuration |\n| Cline | `CLAUDE.md` compatible |\n| Other | Works with natural language requests |\n\nTo check if your tool is supported, view the [full list of supported tools](docs/supported-tools.md).\n\n资料来源：[README.md:1]()\n资料来源 [docs/supported-tools.md]()\n\n## Essential Commands\n\n### Quick Command Reference\n\n| Command | Description |\n|---------|-------------|\n| `openspec list` | View active change folders |\n| `openspec view` | Interactive dashboard of specs and changes |\n| `openspec show ` | Display change details |\n| `openspec update` | Refresh slash command files |\n| `openspec config profile` | Switch between standard and experimental workflows |\n| `openspec archive ` | Archive a completed change |\n\n资料来源：[README.md:1]()\n资料来源 [docs/cli.md]()\n\n## The Experimental Workflow\n\nOpenSpec offers an experimental artifact-guided workflow that provides a more flexible, iterative approach to managing changes.\n\n### Enabling Experimental Features\n\n```bash\nopenspec experimental\n```\n\n### Experimental Slash Commands\n\n| Command | Purpose |\n|---------|---------|\n| `/opsx:propose` | Start a new change |\n| `/opsx:new` | Create a new change folder |\n| `/opsx:continue` | Create the next artifact in sequence |\n| `/opsx:ff` | Fast-forward through completed tasks |\n| `/opsx:verify` | Verify implementation against specs |\n| `/opsx:bulk-archive` | Archive multiple completed changes |\n| `/opsx:onboard` | Set up OpenSpec in a new project |\n| `/opsx:explore` | Think through ideas before committing |\n\n资料来源 [docs/opsx.md]()\n\n### Workflow Comparison\n\n| Aspect | Standard Workflow | Experimental Workflow |\n|--------|------------------|----------------------|\n| Artifact creation | Manual/guided | Sequential with dependencies |\n| State tracking | File-based | Dynamic artifact graph |\n| Flexibility | Phase-locked | Action-based |\n| Iteration | Limited | Full iteration support |\n\n## Telemetry\n\nOpenSpec collects anonymous usage statistics to understand usage patterns. Only command names and version numbers are collected—no arguments, paths, content, or personally identifiable information.\n\n**To opt out:**\n\n```bash\nexport OPENSPEC_TELEMETRY=0\n```\n\nOr set the `DO_NOT_TRACK` environment variable:\n\n```bash\nexport DO_NOT_TRACK=1\n```\n\nTelemetry is automatically disabled in CI environments.\n\n资料来源：[README.md:1]()\n\n## Next Steps\n\nAfter completing the initial setup:\n\n1. **Review Documentation**\n - [Workflows](docs/workflows.md) - Combos and patterns\n - [Commands](docs/commands.md) - Slash commands & skills\n - [Concepts](docs/concepts.md) - How OpenSpec fits together\n\n2. **Try the Workflow**\n - Create your first proposal using `/opsx:propose`\n - Work through the artifact sequence\n - Archive and review the result\n\n3. **Configure Your Tool**\n - Set up slash commands for your preferred AI assistant\n - Run `openspec update` to refresh command files\n\n4. **Explore Advanced Features**\n - Multi-language support: [docs/multi-language.md](docs/multi-language.md)\n - Customization options: [docs/customization.md](docs/customization.md)\n - Community schemas: Browse the catalog in customization docs\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| Node.js version too low | Upgrade to 20.19.0 or higher |\n| Command not found | Verify installation with `openspec --version` |\n| Legacy artifacts remain | Run `openspec init` with `--force` flag |\n| Tool not responding | Check supported tools list and use natural language |\n\n### Getting Help\n\n- Join the [OpenSpec Discord](https://discord.gg/YctCnvvshC) for questions\n- Follow [@0xTab on X](https://x.com/0xTab) for updates\n- Review archived changes in `openspec/changes/archive/` for examples\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Introduction to OpenSpec](#introduction), [Artifact Graph System](#artifact-graph), [Workflows](#workflows)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [openspec/changes/archive/2026-02-17-project-config/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-config/design.md)\n- [openspec/changes/archive/2025-12-28-add-instruction-loader/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-12-28-add-instruction-loader/design.md)\n- [openspec/changes/archive/2026-02-17-project-local-schemas/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-local-schemas/design.md)\n- [schemas/spec-driven/schema.yaml](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/schema.yaml)\n- [openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md)\n- [openspec/changes/archive/2025-08-06-add-init-command/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-08-06-add-init-command/design.md)\n \n\n# System Architecture\n\nOpenSpec is a lightweight specification framework designed to add a spec layer between human-AI alignment and code implementation. The system architecture enables teams to agree on what to build before any code is written, maintaining organization through structured change folders and dynamic instruction generation.\n\n## Architecture Overview\n\nOpenSpec follows a modular architecture with clear separation between CLI interface, core business logic, and artifact management. The framework is designed to be tool-agnostic, supporting 25+ AI assistants through slash commands and natural language processing.\n\n```mermaid\ngraph TD\n subgraph \"CLI Layer\"\n CLI[CLI Entry Point]\n Commands[Slash Commands]\n end\n \n subgraph \"Core Layer\"\n Config[Project Config]\n Schemas[Schema System]\n Artifacts[Artifact Graph]\n Instructions[Instruction Loader]\n end\n \n subgraph \"Change Management\"\n Changes[Change Folders]\n Proposals[Proposals]\n Specs[Specs]\n Designs[Designs]\n Tasks[Tasks]\n end\n \n CLI --> Commands\n Commands --> Artifacts\n Artifacts --> Instructions\n Instructions --> Config\n Instructions --> Schemas\n Artifacts --> Changes\n Changes --> Proposals\n Changes --> Specs\n Changes --> Designs\n Changes --> Tasks\n```\n\n## Core Components\n\n### CLI Interface\n\nThe CLI serves as the entry point for all OpenSpec operations. It handles initialization, change management, and command execution across supported tools.\n\n| Command | Purpose |\n|---------|---------|\n| `openspec init` | Initialize OpenSpec in a project directory |\n| `openspec update` | Refresh generated instruction files |\n| `openspec list` | View active change folders |\n| `openspec show ` | Display change details |\n| `openspec archive ` | Archive completed changes |\n\n资料来源：[openspec/changes/archive/2025-08-06-add-init-command/design.md:1-50]()\n\n### Schema System\n\nSchemas define the workflow structure and artifact templates for OpenSpec changes. The system supports three schema sources:\n\n| Source | Path | Priority |\n|--------|------|----------|\n| Project | `openspec/schemas//` | Highest |\n| User | `~/.local/share/openspec/schemas//` | Middle |\n| Package | Built-in `@fission-ai/openspec` | Lowest |\n\n资料来源：[openspec/changes/archive/2026-02-17-project-local-schemas/design.md:1-30]()\n\n**Schema Resolution Order:**\n1. CLI `--schema` flag (explicit override)\n2. `.openspec.yaml` in change directory (change-specific binding)\n3. `openspec/config.yaml` schema field (project default)\n4. `\"spec-driven\"` (hardcoded fallback)\n\nThe default `spec-driven` schema includes artifacts: proposal, specs, design, and tasks.\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md:1-50]()\n\n## Artifact Graph System\n\nThe artifact graph tracks dependencies between different artifacts and manages their creation state. This system replaces the old phase-locked workflow with a flexible action-based model.\n\n### Artifact Types\n\n| Artifact | Generates | Dependencies |\n|----------|-----------|--------------|\n| proposal | proposal.md | None |\n| specs | specs/*.md | proposal |\n| design | design.md | proposal |\n| tasks | tasks.md | specs, design |\n\n### Instruction Loading\n\nInstructions are dynamically assembled from three layers:\n\n```mermaid\ngraph LR\n A[Context] --> D[Enriched Instruction]\n B[Rules] --> D\n C[Template] --> D\n \n subgraph \"Instruction Components\"\n A\n B\n C\n end\n```\n\n资料来源：[openspec/changes/archive/2025-12-28-add-instruction-loader/design.md:1-30]()\n\n**Instruction Structure:**\n\n```xml\n\n[Project context from config.yaml]\n\n\n\n- Rule 1 for specific artifact\n- Rule 2 for specific artifact\n\n\n\n[Schema's specs template]\n\n```\n\nRules only appear for the **specific artifact** they're configured for. Artifacts without rules (e.g., design, tasks) don't get a `` section.\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md:50-100]()\n\n## Project Configuration\n\nProject configuration is stored in `openspec/config.yaml` and provides shared context and rules across the entire project.\n\n### Configuration Structure\n\n```yaml\ncontext: |\n Tech stack: TypeScript, React\n Key conventions: ...\n\nschema: spec-driven\n\nrules:\n proposal:\n - Include rollback plan\n specs:\n - Use Given/When/Then format for scenarios\n```\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md:100-150]()\n\n### Design Decisions\n\n1. **Config file location**: `openspec/config.yaml` in project root\n - Mirrors structure used by other tools (e.g., `.github/`)\n - Keeps OpenSpec-related files under one directory\n\n2. **XML tags vs Markdown sections**: Use XML-style tags `` and ``\n - Clear delimiters that don't conflict with Markdown\n - Agents can easily parse structure\n\n3. **Rules validation**: Warn on unknown artifact IDs, don't error\n - Future-proof for new artifact types\n - Non-breaking change for existing configs\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md:150-200]()\n\n## Command Workflow\n\n### Modern Workflow (opsx)\n\nThe new artifact-guided workflow provides flexible action-based interactions:\n\n| Command | What it does |\n|---------|--------------|\n| `/opsx:propose` | Start a new change with proposal |\n| `/opsx:continue` | Create one artifact at a time |\n| `/opsx:ff` | Fast-forward to next ready artifact |\n| `/opsx:verify` | Verify specs and update tasks |\n| `/opsx:bulk-archive` | Archive multiple changes |\n| `/opsx:onboard` | Initialize project for OpenSpec |\n\n资料来源：[README.md:1-50]()\n\n### Legacy Commands\n\nThe legacy slash commands have been removed:\n\n- `/openspec:proposal` - **Removed**\n- `/openspec:apply` - **Removed**\n- `/openspec:archive` - **Removed**\n\nTool-specific instruction files (`CLAUDE.md`, `.cursorrules`, `AGENTS.md`, `project.md`) are no longer generated.\n\n资料来源：[CHANGELOG.md:1-30]()\n\n## Change Lifecycle\n\n```mermaid\ngraph TD\n A[Create Change] --> B[Write Proposal]\n B --> C[Create Specs]\n C --> D[Write Design]\n D --> E[Implement Tasks]\n E --> F[Archive Change]\n \n G[Explore Ideas] -.-> A\n \n style A fill:#e1f5fe\n style F fill:#fff3e0\n```\n\n### Change Directory Structure\n\n```\nopenspec/\n├── config.yaml # Project configuration\n├── schemas/ # Project-local schemas\n│ └── /\n│ └── templates/\n└── changes/\n ├── /\n │ ├── proposal.md\n │ ├── specs/\n │ │ └── *.md\n │ ├── design.md\n │ ├── tasks.md\n │ └── .openspec.yaml\n └── archive/\n └── -/\n```\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:1-30]()\n\n## Data Flow Architecture\n\n### Instruction Generation Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant CLI\n participant Config\n participant Schema\n participant Loader\n participant Output\n \n User->>CLI: openspec instructions \n CLI->>Config: readProjectConfig()\n Config-->>CLI: context + rules\n CLI->>Schema: resolveSchemaForChange()\n Schema-->>CLI: schema name\n CLI->>Loader: loadInstructions(change, artifact)\n Loader->>Schema: getTemplate(artifact)\n Schema-->>Loader: baseInstructions\n Loader->>Config: getRulesForArtifact(artifact)\n Config-->>Loader: artifactRules\n Loader->>Output: enrichInstruction(context, rules, template)\n Output-->>User: Enriched instruction with XML sections\n```\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md:200-250]()\n\n### Schema Loading Priority\n\nWhen loading schemas, the system checks multiple locations in order:\n\n```mermaid\ngraph TD\n A[Schema Request] --> B{Project schemas dir?}\n B -->|Yes| C[Return project-local schema]\n B -->|No| D{User schemas dir?}\n D -->|Yes| E[Return user schema]\n D -->|No| F[Return package schema]\n \n C --> G[Schema found]\n E --> G\n F --> G\n```\n\n资料来源：[openspec/changes/archive/2026-02-17-project-local-schemas/design.md:50-80]()\n\n## Extensibility Points\n\n### Slash Command Configuration\n\nSlash commands are managed through a `SlashCommandConfigurator` that handles multiple files per tool:\n\n- `getTargets()`: Expose targets with path and kind\n- `generateAll(projectPath, openspecDir)`: For init\n- `updateExisting(projectPath, openspecDir)`: For update\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:50-80]()\n\n### Template System\n\nTemplates are brief, actionable, and sourced from `openspec/README.md`. Each command body includes:\n\n- Guardrails: Ask 1-2 clarifying questions if needed\n- Step list tailored to workflow stage\n- Pointers to troubleshooting tips\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:30-50]()\n\n## Security Considerations\n\nThe implementation includes several security measures:\n\n| Concern | Mitigation |\n|---------|------------|\n| Path Traversal | Sanitize all user-provided paths |\n| File Permissions | Check write permissions before operations |\n| Existing Files | Never overwrite without explicit `--force` flag |\n| Template Injection | Sanitize user inputs in templates |\n\n资料来源：[openspec/changes/archive/2025-08-06-add-init-command/design.md:50-70]()\n\n## Performance and Caching\n\nProject config is read multiple times during a single command execution:\n\n1. **Schema resolution** - To know which schema to use\n2. **Instruction loading** - To inject context and rules\n\nRules are validated lazily during instruction loading (not at config load time) because:\n- Schema isn't known at config load time (circular dependency)\n- Warnings shown when user actually uses the feature (better UX)\n- Validation warnings cached per session to avoid spam\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md:250-280]()\n\n## Technology Stack\n\n| Component | Technology |\n|-----------|------------|\n| Runtime | Node.js 20.19.0+ |\n| Package Manager | npm, pnpm, yarn, bun, nix |\n| License | MIT |\n| Package | `@fission-ai/openspec` |\n\n资料来源：[README.md:50-80]()\n\n---\n\n\n\n## Slash Commands\n\n### 相关页面\n\n相关主题：[Workflows](#workflows), [Getting Started](#getting-started), [Supported AI Tools](#supported-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/commands.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/commands.md)\n- [docs/opsx.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/opsx.md)\n- [README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n- [openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md)\n- [openspec/changes/archive/2025-09-29-add-slash-command-support/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/design.md)\n- [openspec/changes/archive/2025-10-14-add-codex-slash-command-support/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-10-14-add-codex-slash-command-support/proposal.md)\n \n\n# Slash Commands\n\nSlash Commands provide a convenient shorthand mechanism for invoking OpenSpec workflows directly from AI coding assistants. Instead of typing verbose natural language instructions, users can trigger specific OpenSpec actions through a single slash command invocation, streamlining the specification-driven development workflow.\n\n## Overview\n\nOpenSpec integrates with over 20 AI coding assistants through native slash command support. These commands serve as shortcuts that invoke predefined workflow templates, allowing AI assistants to execute OpenSpec operations without requiring manual CLI invocation.\n\nThe slash command system is built on two fundamental principles:\n\n1. **Centralized Templates**: Command bodies are defined once and reused across all supported tools, ensuring consistency while allowing minimal per-tool adaptations.\n2. **Per-Tool Organization**: Each AI assistant receives its commands in the format and location that tool natively recognizes.\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:1-20]()\n\n## Supported Tools and Command Formats\n\nDifferent AI coding assistants use varying conventions for slash command naming and organization. The following table summarizes the supported tools and their respective command formats.\n\n| Tool | Commands | Storage Location |\n|------|----------|------------------|\n| **Claude Code** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` | `.claude/commands/openspec/` |\n| **Cursor** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.cursor/commands/` |\n| **Amazon Q Developer** | `@openspec-proposal`, `@openspec-apply`, `@openspec-archive` | `.amazonq/prompts/` |\n| **CodeBuddy Code** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` | `.codebuddy/commands/` |\n| **Antigravity** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.agent/workflows/` |\n| **Auggie** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.augment/commands/` |\n| **Roo Code** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.roo/commands/` |\n| **Windsurf** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.windsurf/workflows/` |\n| **Cline** | Workflows with `openspec-*` prefix | `.clinerules/workflows/` |\n\n资料来源：[README.md:1-80]()\n\n## Core Commands\n\nOpenSpec defines three primary slash commands that cover the essential workflow stages.\n\n### Proposal Command\n\nThe proposal command initiates a new change specification. When invoked, the AI assistant creates a dedicated change folder with the necessary artifact structure.\n\n```\nYou: /openspec:propose add-dark-mode\nAI: Created openspec/changes/add-dark-mode/\n ✓ proposal.md — why we're doing this, what's changing\n ✓ specs/ — requirements and scenarios\n ✓ design.md — technical approach\n ✓ tasks.md — implementation checklist\n Ready for implementation!\n```\n\n资料来源：[README.md:1-30]()\n\n### Apply Command\n\nThe apply command transitions the workflow from specification to implementation. It reads the tasks from the change folder and executes them in sequence, marking each task as complete.\n\n```\nYou: /opsx:apply\nAI: Implementing tasks...\n ✓ 1.1 Add theme context provider\n ✓ 1.2 Create toggle component\n ✓ 2.1 Add CSS variables\n ✓ 2.2 Wire up localStorage\n All tasks complete!\n```\n\n资料来源：[README.md:1-30]()\n\n### Archive Command\n\nThe archive command finalizes a completed change by moving it to the archive directory and updating the source-of-truth specifications.\n\n```\nYou: /openspec:archive\nAI: Archived to openspec/changes/archive/2025-01-23-add-dark-mode/\n Specs updated. Ready for the next feature.\n```\n\n资料来源：[README.md:1-30]()\n\n## Command File Structure\n\n### File Format and Metadata\n\nSlash command files are stored as Markdown with optional YAML frontmatter for tool-specific metadata. The frontmatter, when supported, includes fields such as `name`, `description`, and `category` or `tags`.\n\n```yaml\n---\nname: openspec-proposal\ndescription: Create a new OpenSpec change proposal\ncategory: OpenSpec\n---\n\n...command body content...\n\n```\n\n### Marker Placement Rules\n\nThe OpenSpec system uses marker comments (`` and ``) to delineate command bodies. These markers must adhere to strict placement rules:\n\n| Rule | Description |\n|------|-------------|\n| **Outside Frontmatter** | Markers must never appear inside YAML frontmatter |\n| **Body Delimitation** | Markers wrap only the visible command body content |\n| **Recovery Behavior** | Missing or duplicated markers trigger specific recovery behaviors |\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:30-45]()\n\n### Naming Consistency\n\nTo ensure predictable behavior across tools, the following naming elements must remain aligned:\n\n| Element | Example |\n|---------|---------|\n| Visible Slash Name | `proposal`, `apply`, `archive` |\n| File Name | `proposal.md`, `apply.md`, `archive.md` |\n| Frontmatter `name`/`id` | `id: openspec-proposal` |\n\nThis alignment prevents user confusion and ensures the AI assistant can correctly invoke commands regardless of the tool being used.\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/design.md:50-70]()\n\n## Architecture\n\n### SlashCommandConfigurator\n\nThe `SlashCommandConfigurator` is the core component responsible for managing slash command files across multiple tools. It abstracts the differences between tool-specific command formats and provides a unified interface for command generation and updates.\n\n```typescript\ninterface SlashCommandConfigurator {\n getTargets(): Array<{\n path: string;\n kind: 'slash';\n id: string;\n }>;\n \n generateAll(projectPath: string, openspecDir: string): void;\n updateExisting(projectPath: string, openspecDir: string): void;\n}\n```\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/design.md:80-95]()\n\n### Design Principles\n\nThe architecture follows several key principles that guide slash command implementation across all supported tools.\n\n```mermaid\ngraph TD\n A[Centralized Template Definition] --> B[Tool-Specific Adapter]\n B --> C[Claude Code Commands]\n B --> D[Cursor Commands]\n B --> E[Amazon Q Commands]\n B --> F[Other Tool Commands]\n \n G[Init Command] --> H[generateAll]\n G --> I[Creates All Tool Directories]\n \n J[Update Command] --> K[updateExisting]\n J --> L[Refreshes Only Existing Files]\n \n style A fill:#e1f5fe\n style G fill:#fff3e0\n style J fill:#fff3e0\n```\n\n1. **Centralized Templates**: Command bodies are defined once in shared template files and applied across all tools with minimal per-tool wrappers.\n\n2. **Per-File Refresh on Update**: During `openspec update`, the system refreshes only existing slash command files on a per-file basis. It does not create missing files or add support for new tools.\n\n3. **Tool-Specific Directories**: Each AI assistant receives commands stored in its native configuration directory structure.\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:60-75]()\n\n## Command Templates\n\n### Template Content Structure\n\nEach slash command template contains several key sections that guide the AI assistant's behavior.\n\n| Section | Purpose |\n|---------|---------|\n| **Guardrails** | 1-2 clarifying questions if needed; minimal complexity rules; tool usage preferences |\n| **Step List** | Tailored workflow steps for the specific command stage |\n| **Pointers** | References to `openspec show`, `openspec list`, and troubleshooting tips |\n\n### Claude Code Naming Convention\n\nClaude Code uses namespacing within the slash command itself for better readability and natural grouping:\n\n```\n/openspec/proposal\n/openspec/apply\n/openspec/archive\n```\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/design.md:20-35]()\n\n### Other Tools Convention\n\nMost other tools use a flat naming convention with an `openspec-` prefix:\n\n```\n/openspec-proposal\n/openspec-apply\n/openspec-archive\n```\n\nGrouping is achieved through category metadata where supported (e.g., `category: OpenSpec`).\n\n## Initialization and Updates\n\n### Init Command Behavior\n\nWhen running `openspec init`, the system creates slash command directories for all supported tools:\n\n| Tool | Directory Created |\n|------|-------------------|\n| Claude Code | `.claude/commands/openspec/` |\n| Cursor | `.cursor/commands/` |\n| Amazon Q | `.amazonq/prompts/` |\n| Cline | `.clinerules/workflows/` |\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:25-30]()\n\n### Update Command Behavior\n\nThe `openspec update` command implements a conservative update strategy:\n\n1. **Detection Phase**: Identify which tools already have slash command files installed\n2. **Refresh Phase**: Update only the files that exist, refreshing both frontmatter and body content\n3. **Preservation Phase**: Do not create missing files or add support for tools not already present\n\n```mermaid\ngraph LR\n A[openspec update] --> B{Detect Existing Tools}\n B --> C[Tool A: 2 files exist]\n B --> D[Tool B: 0 files exist]\n \n C --> E[Refresh Tool A Files]\n D --> F[Skip Tool B]\n \n E --> G[Update Frontmatter + Body]\n F --> H[No Changes]\n \n style E fill:#c8e6c9\n style F fill:#ffcdd2\n```\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/design.md:100-120]()\n\n### Migration Handling\n\nWhen updating from legacy versions, the system handles backward compatibility:\n\n- **Old slash command directories** (`.claude/commands/openspec/`): The entire directory may be removed during cleanup\n- **Config files with markers**: Markers are removed; files are deleted if empty afterward\n- **Migration hints**: Users are informed about manual migration steps when needed\n\n资料来源：[openspec/changes/archive/2026-02-17-merge-init-experimental/design.md:30-50]()\n\n## Testing Strategy\n\nThe slash command system employs a comprehensive testing approach to ensure reliability across all supported tools.\n\n### Golden Snapshots\n\nGenerated files are validated against expected outputs for each tool:\n\n- Frontmatter structure and content\n- Marker placement (never inside frontmatter)\n- Body content matches centralized templates\n\n### Partial Presence Tests\n\nWhen only some files exist, the update behavior is tested:\n\n```typescript\n// If 1-2 files exist, update should only refresh those files\n// and should not create missing files\ntest('update refreshes only existing files', async () => {\n await createPartialSetup();\n await runUpdate();\n expect(existingFiles).toHaveUpdatedContent();\n expect(missingFiles).toBeUndefined();\n});\n```\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:100-115]()\n\n### Marker Placement Tests\n\nSpecific tests ensure markers never appear inside frontmatter and cover recovery behavior for missing or duplicated markers.\n\n### Logging Tests\n\nUpdate operations report per-file status, enabling verification that each tool's files are processed correctly.\n\n## Additional Commands (Opsx Workflow)\n\nBeyond the core three commands, the `/opsx` prefix provides access to an extended experimental workflow:\n\n| Command | Purpose |\n|---------|---------|\n| `/opsx:explore` | Explore ideas before committing to a change |\n| `/opsx:new` | Start a new change with a specific artifact structure |\n| `/opsx:continue` | Create artifacts one at a time (step-through mode) |\n| `/opsx:ff` | Fast-forward through completed tasks |\n| `/opsx:verify` | Verify artifact completeness and dependencies |\n| `/opsx:bulk-archive` | Archive multiple changes at once |\n| `/opsx:onboard` | Onboard new team members to the project |\n\n资料来源：[README.md:1-30]()\n\nTo enable these commands, run:\n\n```bash\nopenspec experimental\n```\n\n资料来源：[docs/opsx.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/opsx.md)\n\n## Tool-Specific Implementations\n\n### Claude Code\n\nClaude Code stores commands in nested directories with namespaced slash names:\n\n```\n.claude/commands/openspec/\n├── proposal.md\n├── apply.md\n└── archive.md\n```\n\nInvocation: `/openspec:proposal`, `/openspec:apply`, `/openspec:archive`\n\n### Cursor\n\nCursor uses flat naming with a prefix:\n\n```\n.cursor/commands/\n├── openspec-proposal.md\n├── openspec-apply.md\n└── openspec-archive.md\n```\n\nInvocation: `/openspec-proposal`, `/openspec-apply`, `/openspec-archive`\n\n### Codex\n\nCodex commands are written to the global prompts directory:\n\n```bash\n~/.codex/prompts/ # or $CODEX_HOME/prompts\n```\n\nThe system supports both local and global installation paths, with commands refreshed during `openspec update` when they already exist.\n\n资料来源：[openspec/changes/archive/2025-10-14-add-codex-slash-command-support/proposal.md:15-30]()\n\n## Configuration and Customization\n\n### Tool Registry\n\nThe `ToolRegistry` manages discovery and configuration for supported AI coding assistants, enabling the system to:\n\n- Detect which tools are installed in a project\n- Determine appropriate command storage locations\n- Handle tool-specific format variations\n\n### Context Injection\n\nSlash command templates support dynamic context injection, prepending project-specific information:\n\n```markdown\n---\nchange: add-auth\nartifact: proposal\nschema: spec-driven\noutput: openspec/changes/add-auth/proposal.md\n---\n\n## Dependencies\n- [x] (none - this is a root artifact)\n\n## Next Steps\nAfter creating this artifact, you can work on: design, specs\n\n---\n\n[original template content...]\n```\n\n资料来源：[openspec/changes/archive/2025-12-28-add-instruction-loader/design.md:1-30]()\n\n## Related Documentation\n\n- [Getting Started](docs/getting-started.md) — First steps with OpenSpec\n- [Workflows](docs/workflows.md) — Combos and patterns for using slash commands\n- [Commands Reference](docs/commands.md) — Detailed slash command documentation\n- [Supported Tools](docs/supported-tools.md) — Full list of supported AI assistants\n- [Opsx Workflow](docs/opsx.md) — Extended experimental workflow commands\n\n---\n\n\n\n## Workflows\n\n### 相关页面\n\n相关主题：[Slash Commands](#slash-commands), [Artifact Graph System](#artifact-graph)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/workflows.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/workflows.md)\n- [README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n- [src/core/templates/workflows/new-change.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/new-change.ts)\n- [openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md)\n- [openspec/changes/archive/2025-10-14-add-windsurf-workflows/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-10-14-add-windsurf-workflows/proposal.md)\n- [WORKSPACE_REIMPLEMENTATION_DIRECTION.md](https://github.com/Fission-AI/OpenSpec/blob/main/WORKSPACE_REIMPLEMENTATION_DIRECTION.md)\n- [openspec/changes/archive/2026-02-17-project-config/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-config/proposal.md)\n \n\n# Workflows\n\n## Overview\n\nWorkflows in OpenSpec define the ordered sequence of artifacts that get created during a change's lifecycle. They provide a structured approach to capturing requirements, design decisions, and implementation tasks before any code is written.\n\n**Purpose**: Workflows ensure that human and AI assistants align on what to build through a consistent, repeatable process that captures the \"why,\" \"what,\" and \"how\" of each change.\n\n**Scope**: A workflow determines which artifacts need to be created, in what order, and what dependencies exist between them.\n\n资料来源：[README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n## Core Concepts\n\n### Artifacts\n\nArtifacts are the files created during a change lifecycle. OpenSpec supports the following artifact types:\n\n| Artifact | Description | Output File |\n|----------|-------------|-------------|\n| proposal | Why and what changes | `proposal.md` |\n| specs | Requirements and scenarios | `specs/*.md` |\n| design | Technical approach | `design.md` |\n| tasks | Implementation checklist | `tasks.md` |\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md)\n\n### Workflow Stages\n\nEach workflow progresses through distinct stages:\n\n```mermaid\ngraph LR\n A[Propose] --> B[Design]\n B --> C[Specs]\n C --> D[Tasks]\n D --> E[Apply]\n E --> F[Archive]\n \n style A fill:#e1f5fe\n style E fill:#fff3e0\n style F fill:#f3e5f5\n```\n\n| Stage | Purpose | Key Question |\n|-------|---------|--------------|\n| **Proposal** | Capture the reason for the change | \"Why are we doing this?\" |\n| **Design** | Document technical approach | \"How will we build it?\" |\n| **Specs** | Define requirements and scenarios | \"What should it do?\" |\n| **Tasks** | Break down implementation | \"What are the steps?\" |\n| **Apply** | Execute implementation | \"Make it happen\" |\n| **Archive** | Finalize and merge | \"Clean up\" |\n\n资料来源：[README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n## Workflow Templates\n\nOpenSpec ships with predefined workflow templates located in `src/core/templates/workflows/`.\n\n### The New Change Workflow\n\nThe new change workflow (`new-change.ts`) scaffolds a complete change structure:\n\n```typescript\nexport const newChangeWorkflow = {\n name: \"New Change\",\n description: \"Scaffold a new OpenSpec change and validate strictly.\",\n async execute(params) {\n // 1. Validate change name (kebab-case)\n // 2. Check if change already exists\n // 3. Create change directory\n // 4. Show artifact status\n // 5. Output first artifact template\n }\n};\n```\n\n资料来源：[src/core/templates/workflows/new-change.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/new-change.ts)\n\n### Workflow Execution Steps\n\nWhen initiating a new change, the workflow performs these steps in order:\n\n1. **Validate the change name**\n - Must be kebab-case (e.g., `add-dark-mode`)\n - If invalid, prompt for a valid name\n\n2. **Check for existing changes**\n - If a change with the same name exists, suggest using `continue-change` instead\n\n3. **Create the scaffold**\n - Run `openspec init --change \"\"` with `--schema ` if a specific workflow is requested\n - Creates `openspec/changes//` with the selected schema\n\n4. **Show artifact status**\n ```bash\n openspec status --change \"\"\n ```\n This displays which artifacts need creation and which are ready (dependencies satisfied).\n\n5. **Output first artifact template**\n ```bash\n openspec instructions --change \"\"\n ```\n This outputs the template and context for creating the first artifact.\n\n6. **STOP and wait for user direction**\n\n资料来源：[src/core/templates/workflows/new-change.ts:1-60](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/new-change.ts)\n\n### Guardrails\n\nThe new change workflow includes important guardrails:\n\n- **Do NOT create any artifacts yet** — only show the instructions\n- **Do NOT advance beyond showing the first artifact template**\n- **Pass `--schema`** only if using a non-default workflow\n- Changes with invalid names (not kebab-case) trigger a prompt for correction\n- Existing changes suggest using `/continue` instead\n\n资料来源：[src/core/templates/workflows/new-change.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/new-change.ts)\n\n## Workflow Patterns\n\n### Spec-Driven Workflow\n\nThe spec-driven workflow emphasizes design-first approach:\n\n```mermaid\ngraph TD\n P[proposal] --> D[design]\n D --> S[specs]\n S --> T[tasks]\n \n P -.->|blocking| S\n P -.->|blocking| T\n D -.->|blocking| T\n```\n\n| Artifact | Generates | Dependencies |\n|----------|-----------|--------------|\n| proposal | `proposal.md` | None (root) |\n| design | `design.md` | proposal |\n| specs | `specs/*.md` | proposal, design |\n| tasks | `tasks.md` | specs |\n\n### Artifact Flow\n\n```\n┌────────────────────┐\n│ Archive & Update │\n│ Specs (source) │\n└────────────────────┘\n │\n ▼\n┌────────────────────┐\n│ 1. Draft proposal │\n└────────────────────┘\n │\n ▼\n┌────────────────────┐\n│ 2. Review proposal │\n└────────────────────┘\n │\n ▼\n┌────────────────────┐\n│ 3. Implement tasks │\n└────────────────────┘\n │\n ▼\n┌────────────────────┐\n│ 4. Archive change │\n└────────────────────┘\n │\n ▼\n┌────────────────────┐\n│ Specs updated │\n└────────────────────┘\n```\n\n资料来源：[openspec/changes/archive/2025-10-14-add-windsurf-workflows/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-10-14-add-windsurf-workflows/proposal.md)\n\n## Workflows with Slash Commands\n\nOpenSpec integrates with multiple AI coding assistants through slash command workflows. Each tool has its own command structure and file format.\n\n### Supported Tools and Commands\n\n| Tool | Slash Commands | File Location |\n|------|----------------|---------------|\n| Claude Code | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` | Built-in |\n| CodeBuddy | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` | `.codebuddy/commands/` |\n| Cursor | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.cursor/commands/` |\n| Windsurf | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.windsurf/workflows/` |\n| Kilo Code | `/openspec-proposal.md`, `/openspec-apply.md`, `/openspec-archive.md` | `.kilocode/workflows/` |\n| Cline | Workflows | `.clinerules/workflows/` |\n| GitHub Copilot | `@openspec-proposal`, `@openspec-apply`, `@openspec-archive` | `.github/prompts/` |\n| Continue | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.continue/prompts/` |\n| Antigravity | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.agent/workflows/` |\n\n资料来源：[README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n### Slash Command File Structure\n\nSlash command files follow a consistent pattern:\n\n```markdown\n---\nname: openspec-proposal\ndescription: Create an OpenSpec proposal\ncategory: OpenSpec\n---\n\n...command body from shared template...\n\n```\n\n**Template Content Structure:**\n- Guardrails: 1–2 clarifying questions\n- Minimal-complexity rules\n- Step list tailored to workflow stage\n- Pointers to `openspec show`, `openspec list`\n- Troubleshooting tips\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md)\n\n## CLI Commands for Workflows\n\nOpenSpec provides CLI commands to interact with workflows:\n\n```bash\n# List active change folders\nopenspec list\n\n# Interactive dashboard of specs and changes\nopenspec view\n\n# Display change details\nopenspec show \n\n# Check spec formatting and structure\nopenspec validate \n\n# Move completed change to archive\nopenspec archive [--yes|-y]\n\n# Show artifact status\nopenspec status --change \"\"\n\n# Get instructions for artifact creation\nopenspec instructions --change \"\"\n```\n\n资料来源：[README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n## Workflow Example\n\n### Create and Execute a Change\n\n```text\nYou: /openspec:propose add-dark-mode\nAI: Created openspec/changes/add-dark-mode/\n ✓ proposal.md — why we're doing this, what's changing\n ✓ specs/ — requirements and scenarios\n ✓ design.md — technical approach\n ✓ tasks.md — implementation checklist\n Ready for implementation!\n\nYou: /openspec:apply\nAI: Implementing tasks...\n ✓ 1.1 Add theme context provider\n ✓ 1.2 Create toggle component\n ✓ 2.1 Add CSS variables\n ✓ 2.2 Wire up localStorage\n All tasks complete!\n\nYou: /openspec:archive\nAI: Archived to openspec/changes/archive/2025-01-23-add-dark-mode/\n Specs updated. Ready for the next feature.\n```\n\n资料来源：[README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n## Project Configuration\n\nWorkflows can be customized per project through configuration:\n\n| Configuration Option | Description |\n|---------------------|-------------|\n| schema | Selected workflow/schema (e.g., \"spec-driven\") |\n| projectContext | Multi-line context (tech stack, conventions) |\n| artifactRules | Per-artifact custom rules |\n\n### Config Section Prompts\n\nWhen running `openspec init`, the setup command displays:\n\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n📋 Project Configuration (Optional)\nConfigure project defaults for OpenSpec workflows.\n```\n\nSteps:\n1. **Create config?** — Yes/No prompt (default \"Yes\")\n2. **Schema selection** — List schemas with descriptions\n3. **Project context** — Multi-line input for tech stack info\n4. **Per-artifact rules** — Optional rules for specific artifacts\n5. **Validate and write** — Save to `openspec/config.yaml`\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-config/proposal.md)\n\n## Workspace Workflow Extensions\n\nThe OpenSpec workspace feature extends workflows across multiple repositories:\n\n```mermaid\ngraph TD\n W[Workspace] --> L[Links]\n L --> P[Proposal]\n P --> R[Repo Slices]\n R --> A[Apply]\n A --> V[Verify]\n V --> C[Archive]\n```\n\n### Workspace Workflow Sequence\n\n| Step | Capability |\n|------|------------|\n| 1 | Set up the workspace |\n| 2 | See linked repos or folders |\n| 3 | Explore repos with agent |\n| 4 | Capture a proposal |\n| 5 | Check status |\n| 6 | Implement one repo slice |\n| 7 | Verify |\n| 8 | Archive |\n\n### Apply One Repo Slice\n\nThe `/apply` command for workspaces:\n\n```text\nUser: /apply integrate-docs for landing\n```\n\n**Agent behavior:**\n1. Ask OpenSpec for apply context\n2. Read proposal, design, tasks, and relevant specs\n3. Confirm the target repo checkout\n4. Edit only that repo\n5. Update workspace tasks\n6. Run relevant checks\n\n**What `/apply` means:**\n- Implement the planned slice for one repo\n- Does NOT copy planning files\n- Does NOT materialize repo-local OpenSpec state\n- Does NOT create proposal files for the first time\n\n资料来源：[WORKSPACE_REIMPLEMENTATION_DIRECTION.md](https://github.com/Fission-AI/OpenSpec/blob/main/WORKSPACE_REIMPLEMENTATION_DIRECTION.md)\n\n## Related Documentation\n\n- [Getting Started](docs/getting-started.md) — First steps with workflows\n- [Commands](docs/commands.md) — Slash commands & skills reference\n- [CLI](docs/cli.md) — Terminal command reference\n- [Supported Tools](docs/supported-tools.md) — Tool integrations & install paths\n- [Concepts](docs/concepts.md) — How it all fits together\n- [Customization](docs/customization.md) — Make workflows yours\n\n---\n\n\n\n## Artifact Graph System\n\n### 相关页面\n\n相关主题：[System Architecture](#architecture), [Workflows](#workflows), [Schemas](#schemas)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/core/artifact-graph/graph.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/graph.ts)\n- [src/core/artifact-graph/state.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/state.ts)\n- [src/core/artifact-graph/resolver.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/resolver.ts)\n- [src/core/artifact-graph/schema.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/schema.ts)\n- [src/core/artifact-graph/outputs.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/outputs.ts)\n- [src/core/artifact-graph/instruction-loader.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/instruction-loader.ts)\n \n\n# Artifact Graph System\n\n## Overview\n\nThe Artifact Graph System is the core module of OpenSpec that manages artifact dependencies, workflow state detection, and schema-driven instruction generation. It provides a declarative way to define artifact relationships through YAML schemas and enables intelligent workflow progression based on filesystem state.\n\n### Purpose\n\nThe system solves several key problems in AI-assisted development:\n\n1. **Dependency Management** - Ensures artifacts are created in the correct order based on their dependencies\n2. **State Detection** - Automatically detects which artifacts are completed, ready, or blocked based on filesystem presence\n3. **Schema Resolution** - Supports both user-defined schemas (via XDG directories) and built-in package schemas\n4. **Instruction Generation** - Enriches templates with project context, artifact-specific rules, and dependency status\n\n### High-Level Architecture\n\n```mermaid\ngraph TB\n subgraph \"Artifact Graph System\"\n YAML[(\"Schema YAML\")]\n GRAPH[(\"ArtifactGraph\")]\n STATE[(\"State Detection\")]\n INSTR[(\"Instruction Loader\")]\n CTX[(\"ChangeContext\")]\n end\n \n subgraph \"Schema Sources\"\n USER[(\"User Schemas
XDG_DATA_HOME\")]\n BUILTIN[(\"Built-in Schemas
Package\")]\n end\n \n YAML --> GRAPH\n GRAPH --> STATE\n GRAPH --> CTX\n STATE --> CTX\n CTX --> INSTR\n \n USER -->|resolveSchema| GRAPH\n BUILTIN -->|resolveSchema| GRAPH\n```\n\n## Core Concepts\n\n### Artifacts\n\nArtifacts are the fundamental units of work in OpenSpec. Each artifact has:\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `id` | string | Unique identifier within the schema |\n| `generates` | string | File pattern generated by this artifact |\n| `template` | string | Template file path (relative to schema directory) |\n| `requires` | string[] | List of artifact IDs that must complete first |\n\n### Schema Structure\n\nSchemas define the workflow for a change. They are YAML files with the following structure:\n\n```yaml\nname: spec-driven\nversion: 1\ndescription: Specification-driven development workflow\n\nartifacts:\n - id: proposal\n generates: \"proposal.md\"\n template: \"proposal.md\"\n requires: []\n\n - id: specs\n generates: \"specs/*.md\"\n template: \"spec.md\"\n requires: [proposal]\n\n - id: design\n generates: \"design.md\"\n template: \"design.md\"\n requires: [proposal]\n\n - id: tasks\n generates: \"tasks.md\"\n template: \"tasks.md\"\n requires: [specs, design]\n```\n\n## ArtifactGraph Class\n\nThe `ArtifactGraph` class is the central component that loads schemas and provides graph query operations.\n\n### Class Structure\n\n```typescript\nexport class ArtifactGraph {\n private artifacts: Map;\n private schema: SchemaYaml;\n\n private constructor(schema: SchemaYaml) {\n this.schema = schema;\n this.artifacts = new Map(schema.artifacts.map(a => [a.id, a]));\n }\n}\n```\n\n### Factory Methods\n\n| Method | Description | Source |\n|--------|-------------|--------|\n| `fromYaml(filePath)` | Load graph from a schema YAML file path | `graph.ts:18-21` |\n| `fromYamlContent(yamlContent)` | Parse graph from YAML content string | `graph.ts:27-29` |\n| `fromSchema(schema)` | Create graph from pre-validated SchemaYaml object | `graph.ts:35-37` |\n\n### Query Methods\n\n| Method | Return Type | Description |\n|--------|-------------|--------------|\n| `getArtifact(id)` | `Artifact \\| undefined` | Get a single artifact by ID |\n| `getAllArtifacts()` | `Artifact[]` | Get all artifacts in definition order |\n| `getName()` | `string` | Get the schema name |\n| `getSchema()` | `SchemaYaml` | Get the underlying schema object |\n\n## State Detection\n\nThe state detection module (`state.ts`) monitors the filesystem to determine the status of each artifact relative to a change directory.\n\n### State Types\n\n| State | Description |\n|-------|-------------|\n| `completed` | All files matching the artifact's `generates` pattern exist |\n| `ready` | All dependencies are completed, can be worked on |\n| `blocked` | Dependencies are not yet completed |\n\n### State Detection Logic\n\n```typescript\ninterface ArtifactGraphResult {\n completed: string[]; // Artifact IDs that are fully completed\n ready: string[]; // Artifact IDs ready to work on\n blocked: BlockedArtifacts; // Artifact IDs with their unmet dependencies\n buildOrder: string[]; // Topological order for creation\n}\n```\n\nThe detection process:\n\n1. For each artifact, check if files matching `generates` exist in the change directory\n2. Collect all completed artifact IDs into a `CompletedSet` (a `Set`)\n3. For each non-completed artifact, find which dependencies are unmet\n4. Artifacts with all dependencies met are marked `ready`\n\n## Topological Sorting\n\nThe system uses Kahn's algorithm for topological sorting to determine the correct build order for artifacts.\n\n### Algorithm Properties\n\n- **Cycle Detection**: Kahn's algorithm naturally fails on cyclic dependencies, providing natural cycle detection\n- **Stable Ordering**: Independent artifacts are returned in definition order\n- **Linear Time**: O(V + E) where V is artifacts and E is dependencies\n\n### Error Format\n\nWhen a cycle is detected, the error message clearly identifies the cycle path:\n\n```\nCyclic dependency detected: A → B → C → A\n```\n\n## Schema Resolution\n\nThe `resolver.ts` module handles loading schemas from multiple sources with a defined priority order.\n\n### Resolution Order\n\n```mermaid\ngraph LR\n A[(\"Schema Name\")] --> B{Global Override?}\n B -->|Yes| C[\"${XDG_DATA_HOME}/openspec/schemas/\"]\n B -->|No| D{Package Built-in?}\n D -->|Yes| E[\"/schemas/\"]\n D -->|No| F[(\"Error: Schema not found\")]\n C --> G[(\"Loaded Schema\")]\n E --> G\n```\n\n### Resolution Paths\n\n| Priority | Location | Environment Variable |\n|----------|----------|----------------------|\n| 1 (User Override) | `${XDG_DATA_HOME}/openspec/schemas/` | `XDG_DATA_HOME` |\n| 2 (Built-in) | `/schemas/` | N/A |\n| 3 (Error) | Schema not found | N/A |\n\n**Fallback Behavior**: If `XDG_DATA_HOME` is not set, the system falls back to `~/.local/share` on Unix systems.\n\n## Built-in Schemas\n\nOpenSpec ships with two built-in schemas:\n\n### spec-driven Schema\n\nThe default schema following a proposal → specs → design → tasks workflow:\n\n```yaml\nname: spec-driven\nartifacts:\n - id: proposal\n generates: \"proposal.md\"\n requires: []\n - id: specs\n generates: \"specs/*.md\"\n requires: [proposal]\n - id: design\n generates: \"design.md\"\n requires: [proposal]\n - id: tasks\n generates: \"tasks.md\"\n requires: [specs, design]\n```\n\n### tdd Schema\n\nAn alternative schema for test-driven development:\n\n```yaml\nname: tdd\nartifacts:\n - id: tests\n generates: \"tests/*.md\"\n requires: []\n - id: implementation\n generates: \"implementation.md\"\n requires: [tests]\n - id: docs\n generates: \"docs.md\"\n requires: [implementation]\n```\n\n## Instruction Loading\n\nThe `instruction-loader.ts` module enriches templates with change-specific context and project configuration.\n\n### ChangeContext Interface\n\n```typescript\ninterface ChangeContext {\n changeName: string;\n changeDir: string;\n schemaName: string;\n graph: ArtifactGraph;\n completed: CompletedSet;\n}\n```\n\n### Instruction Output Structure\n\nInstructions are formatted with XML-like sections for AI consumption:\n\n```markdown\n\n\n[Project context from config]\n\n\n\n[Artifact-specific rules from config]\n\n\n\n[Schema's template content]\n\n```\n\n### Context Injection Rules\n\n| Section | Applies To | Source |\n|---------|-----------|--------|\n| `` | All artifacts | Project config's `context` field |\n| `` | Specific artifacts only | Per-artifact rules in project config |\n| `` | All artifacts | Schema's template file |\n\n## File Structure\n\n```\nsrc/core/artifact-graph/\n├── index.ts # Public exports\n├── types.ts # Zod schemas and TypeScript types\n├── graph.ts # ArtifactGraph class\n├── state.ts # State detection logic\n├── resolver.ts # Schema resolution\n├── schema.ts # YAML parsing and validation\n├── outputs.ts # Output path resolution\n├── instruction-loader.ts # Template enrichment\n└── schemas/ # Built-in schema definitions\n ├── spec-driven/\n │ ├── schema.yaml\n │ └── templates/\n └── tdd/\n ├── schema.yaml\n └── templates/\n```\n\n## Integration Points\n\n### With Workflow Commands\n\nThe Artifact Graph System integrates with the `/opsx:continue` and `/opsx:apply` workflows:\n\n1. **Continue Workflow** - Reads instructions for the next ready artifact\n2. **Apply Workflow** - Checks completion status and provides apply-phase instructions\n\n### With Project Config\n\nProject-level configuration (`openspec/config.yaml`) can provide:\n\n- Default schema selection\n- Project context for all artifacts\n- Per-artifact rules and guidelines\n\n## Testing\n\nThe system includes comprehensive test coverage:\n\n| Test Case | Purpose |\n|-----------|---------|\n| Parse valid schema YAML | Schema loading works correctly |\n| Parse invalid schema | Missing fields throw descriptive errors |\n| Duplicate artifact IDs | Detection and error reporting |\n| Invalid `requires` reference | Identification of invalid artifact IDs |\n| Cycle detection | Error with cycle path listing |\n| Build order (linear) | Topological sort correctness |\n| Build order (diamond) | Complex dependency handling |\n| Independent artifacts | Stable ordering of unrelated nodes |\n\n## Related Documentation\n\n- [Schema Directories Design](../changes/archive/2025-12-28-restructure-schema-directories/design.md) - Schema directory structure\n- [Instruction Loader Design](../changes/archive/2025-12-28-add-instruction-loader/design.md) - Template loading and enrichment\n- [Apply-Phase Schema Design](../changes/archive/2026-01-06-make-apply-instructions-schema-aware/design.md) - Apply phase configuration\n- [Project Config Design](../changes/archive/2026-02-17-project-config/design.md) - Project-level configuration integration\n\n---\n\n\n\n## Schemas\n\n### 相关页面\n\n相关主题：[Validation System](#validation-system), [Artifact Graph System](#artifact-graph)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [schemas/spec-driven/schema.yaml](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/schema.yaml)\n- [schemas/workspace-planning/schema.yaml](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/workspace-planning/schema.yaml)\n- [src/core/schemas/index.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/schemas/index.ts)\n- [src/core/schemas/base.schema.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/schemas/base.schema.ts)\n- [src/core/schemas/change.schema.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/schemas/change.schema.ts)\n- [src/core/schemas/spec.schema.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/schemas/spec.schema.ts)\n \n\n# Schemas\n\nSchemas define the workflow structure for OpenSpec changes. They specify which artifacts should be created, their dependencies, requirements for completion, and how the apply phase operates.\n\n## Overview\n\nA schema in OpenSpec is a configuration that defines a complete workflow for planning and implementing changes. Schemas specify:\n\n- The **artifacts** to create (e.g., proposal, specs, design, tasks)\n- The **dependencies** between artifacts\n- **Requirements** that must be met before each artifact is considered complete\n- **Templates** for generating artifact content\n- **Apply phase** configuration for implementation guidance\n\nSchemas are self-contained directories containing `schema.yaml` and template files, following a structure similar to Helm charts. 资料来源：[openspec/changes/archive/2025-12-28-restructure-schema-directories/design.md]()\n\n## Schema Directory Structure\n\n```\nschemas/\n├── spec-driven/\n│ ├── schema.yaml # Schema definition\n│ └── templates/\n│ ├── proposal.md\n│ ├── design.md\n│ ├── spec.md\n│ └── tasks.md\n└── tdd/\n ├── schema.yaml\n └── templates/\n ├── spec.md\n ├── test.md\n ├── implementation.md\n └── docs.md\n```\n\nBuilt-in schemas are distributed with the package, while user overrides can be placed in XDG data directories. 资料来源：[openspec/changes/archive/2025-12-28-restructure-schema-directories/design.md]()\n\n## Schema Resolution Order\n\nOpenSpec resolves schemas using a priority-based lookup:\n\n```mermaid\ngraph TD\n A[Schema Request] --> B{CLI --schema flag?}\n B -->|Yes| C[Use CLI flag]\n B -->|No| D{.openspec.yaml in change?}\n D -->|Yes| E[Use change metadata]\n D -->|No| F{openspec/config.yaml schema?}\n F -->|Yes| G[Use project default]\n F -->|No| H{\"spec-driven\" fallback}\n```\n\n| Priority | Source | Example Path |\n|----------|--------|--------------|\n| 1 (highest) | CLI flag | `--schema tdd` |\n| 2 | Change metadata | `.openspec.yaml` |\n| 3 | Project config | `openspec/config.yaml` |\n| 4 (lowest) | Hardcoded default | `\"spec-driven\"` |\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md]()\n\n## Schema YAML Format\n\n### Core Fields\n\n```yaml\nname: spec-driven\nversion: 1\ndescription: Specification-driven development\n```\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `name` | string | Yes | Unique schema identifier (kebab-case) |\n| `version` | number | Yes | Schema version for compatibility |\n| `description` | string | Yes | Human-readable description |\n\n### Artifacts Section\n\nThe `artifacts` array defines each artifact in the workflow:\n\n```yaml\nartifacts:\n - id: proposal\n generates: proposal.md\n template: proposal.md\n requires: []\n \n - id: specs\n generates: specs/\n template: spec.md\n requires:\n - proposal\n```\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `id` | string | Yes | Unique artifact identifier |\n| `generates` | string | Yes | Output path or directory |\n| `template` | string | Yes | Template file relative to `templates/` |\n| `requires` | string[] | No | Artifact IDs that must exist first |\n| `format_requirements` | string | No | Special formatting instructions |\n\n资料来源：[schemas/spec-driven/schema.yaml]()\n\n## Built-in Schemas\n\n### spec-driven\n\nThe default schema focused on specification-driven development. It emphasizes clear requirements and scenarios before implementation.\n\n**Artifact Flow:**\n```mermaid\ngraph LR\n A[proposal] --> B[specs]\n B --> C[design]\n C --> D[tasks]\n D --> E[apply]\n```\n\n| Artifact | Generates | Requires | Purpose |\n|----------|-----------|----------|---------|\n| `proposal` | `proposal.md` | (none) | Define the change scope |\n| `specs` | `specs/*.md` | proposal | Document requirements and scenarios |\n| `design` | `design.md` | specs | Technical approach |\n| `tasks` | `tasks.md` | design, specs | Implementation checklist |\n\n### workspace-planning\n\nSchema for multi-repository planning and coordination across workspaces.\n\n资料来源：[schemas/workspace-planning/schema.yaml]()\n\n### tdd (Test-Driven Development)\n\nSchema focused on tests first, following the pattern: spec → test → implementation → docs.\n\n| Artifact | Generates | Requires |\n|----------|-----------|----------|\n| `spec` | `spec.md` | (none) |\n| `test` | `test.md` | spec |\n| `implementation` | `implementation.md` | test |\n| `docs` | `docs.md` | implementation |\n\n## Requirements Format\n\nRequirements define completion criteria for artifacts. They use a structured format with scenarios.\n\n```markdown\n## Requirements\n\n### Requirement: \n\n\n#### Scenario: \n- **WHEN** \n- **THEN** \n```\n\n**Key Formatting Rules:**\n- Requirements use `### Requirement:` with exactly 3 hashtags\n- Scenarios use `#### Scenario:` with exactly 4 hashtags\n- Use SHALL/MUST for normative requirements (avoid should/may)\n- Every requirement MUST have at least one scenario\n\n资料来源：[schemas/spec-driven/schema.yaml]()\n\n## Apply Phase Configuration\n\nThe optional `apply` block defines how implementation should proceed:\n\n```yaml\napply:\n requires:\n - specs\n - design\n - tasks\n tracks:\n - id: implementation\n label: Implementation\n instruction: |\n Proceed with implementation based on the tasks artifact.\n```\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `requires` | string[] | Artifacts that must exist before apply |\n| `tracks` | Track[] | Progress tracking categories |\n| `instruction` | string | Instructions displayed during apply |\n\n资料来源：[openspec/changes/archive/2026-01-06-make-apply-instructions-schema-aware/tasks.md]()\n\n## Schema Resolution Implementation\n\nThe `resolveSchema()` function handles schema loading with user overrides:\n\n```typescript\n// Resolution order (highest to lowest priority)\n1. ${XDG_DATA_HOME}/openspec/schemas//schema.yaml // User override\n2. /schemas//schema.yaml // Built-in\n```\n\n```typescript\nfunction getPackageSchemasDir(): string {\n const currentFile = fileURLToPath(import.meta.url);\n // Navigate from src/core/artifact-graph/ to package root\n return path.join(path.dirname(currentFile), '..', '..', '..', 'schemas');\n}\n```\n\n资料来源：[openspec/changes/archive/2025-12-28-restructure-schema-directories/design.md]()\n\n## Template Loading\n\nTemplates are loaded relative to the schema's `templates/` directory:\n\n```yaml\n# In schema.yaml\nartifacts:\n - id: proposal\n template: \"proposal.md\" # → schemas/spec-driven/templates/proposal.md\n```\n\nTemplates are simple markdown files without template engine dependencies. Context injection prepends a header section:\n\n```markdown\n---\nchange: add-auth\nartifact: proposal\nschema: spec-driven\noutput: openspec/changes/add-auth/proposal.md\n---\n\n## Dependencies\n- [x] (none - this is a root artifact)\n\n## Next Steps\nAfter creating this artifact, you can work on: design, specs\n\n---\n\n[original template content...]\n```\n\n资料来源：[openspec/changes/archive/2025-12-28-add-instruction-loader/design.md]()\n\n## Project Configuration Integration\n\nSchemas integrate with `openspec/config.yaml` for project defaults:\n\n```yaml\nschema: spec-driven # Default schema for new changes\ncontext: |\n Tech stack: TypeScript, React, Node.js\n API style: RESTful\nrules:\n design:\n - Include rollback plan\n```\n\nThe `schema` field in config sets the project default, which is used when:\n- Creating new changes without `--schema` flag\n- Running commands on changes without `.openspec.yaml` metadata\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md]()\n\n## Context Injection\n\nWhen generating instructions for artifacts, schemas support context injection via XML-style tags:\n\n```xml\n\nTech stack: TypeScript, React, Node.js, PostgreSQL\nAPI style: RESTful, documented in docs/api-conventions.md\n\n\n\n- Include rollback plan\n- Identify affected teams and notify in #platform-changes\n\n\n\n[Schema's built-in template content]\n\n```\n\n**Injection Priority:**\n- `` appears for all artifacts (from project config)\n- `` appear only for matching artifact IDs\n- `` contains the schema's base template content\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/proposal.md]()\n\n## CLI Commands\n\n### List Available Schemas\n\n```bash\nopenspec schemas list\n```\n\nDisplays all available schemas with their source (project, user, package).\n\n### Initialize New Schema\n\n```bash\nopenspec schema init \\\n --description \"My custom workflow\" \\\n --artifacts proposal,specs,design,tasks \\\n --default\n```\n\nCreates a new schema in `openspec/schemas//` with the specified configuration.\n\n### Show Schema Details\n\n```bash\nopenspec schema show \n```\n\nDisplays schema definition including artifacts, requirements, and apply configuration.\n\n---\n\n\n\n## Configuration\n\n### 相关页面\n\n相关主题：[Getting Started](#getting-started)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [openspec/config.yaml](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/config.yaml)\n- [src/core/config.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/config.ts)\n- [src/core/config-schema.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/config-schema.ts)\n- [src/core/global-config.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/global-config.ts)\n- [src/core/project-config.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/project-config.ts)\n- [src/core/profiles.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/profiles.ts)\n- [src/commands/config.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/commands/config.ts)\n \n\n# Configuration\n\nOpenSpec uses a layered configuration system that manages project-level settings, global defaults, and user preferences. This configuration architecture enables teams to share project context, define artifact-specific rules, and customize the OpenSpec workflow across different environments.\n\n## Overview\n\nThe OpenSpec configuration system serves three primary purposes:\n\n1. **Schema Selection** — Define which OpenSpec schema to use for change management\n2. **Context Injection** — Provide project background (tech stack, conventions, terminology) that gets injected into generated artifacts\n3. **Per-Artifact Rules** — Define constraints and guidelines that apply to specific artifact types\n\n```mermaid\ngraph TD\n A[User Project] --> B[openspec/config.yaml]\n A --> C[Global Config]\n A --> D[User Config]\n \n B --> E[Schema Resolution]\n C --> E\n D --> E\n \n E --> F[spec-driven]\n E --> G[minimal]\n E --> H[custom schemas]\n \n F --> I[Artifact Generation]\n G --> I\n H --> I\n \n I --> J[proposal.md]\n I --> K[specs/*.md]\n I --> L[design.md]\n I --> M[tasks.md]\n```\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-config/design.md)\n\n## Configuration Files\n\n### Project Configuration (`openspec/config.yaml`)\n\nThe project-level configuration file lives in the `openspec/` directory and is designed to be committed to version control. This ensures all team members share the same project context and rules.\n\n**Location:** `/openspec/config.yaml`\n\n**Structure:**\n\n```yaml\nschema: spec-driven\ncontext:\n project_name: My Application\n tech_stack:\n - Node.js\n - TypeScript\n - PostgreSQL\n conventions:\n - Use async/await for all asynchronous operations\n - Follow conventional commits\n terminology:\n - \"change\" refers to a feature or fix being implemented\n - \"artifact\" refers to a generated file\n\nrules:\n proposal:\n - Include spike tasks for unknowns\n specs:\n - Use SHALL/MUST for normative requirements\n - Every requirement needs at least one scenario\n```\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-config/proposal.md)\n\n### Schema Configuration\n\nEach schema defines its own structure and templates. The `spec-driven` schema, for example, includes requirements for how artifacts should be formatted:\n\n```yaml\nartifacts:\n - id: proposal\n generates: proposal.md\n requires: []\n \n - id: specs\n generates: specs/*.md\n requires:\n - proposal\n \n - id: design\n generates: design.md\n requires:\n - proposal\n - specs\n```\n\n资料来源：[schemas/spec-driven/schema.yaml](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/schema.yaml)\n\n## Configuration Architecture\n\n### Configuration Resolution Order\n\nOpenSpec resolves configuration values using a specific precedence order:\n\n```mermaid\ngraph LR\n A[CLI Flag] -->|highest| B[Change Metadata]\n B --> C[Project Config]\n C -->|lowest| D[Global Config]\n D --> E[Hardcoded Default]\n```\n\n| Priority | Source | Description |\n|----------|--------|-------------|\n| 1 | CLI Flag | Explicit `--schema` parameter |\n| 2 | Change Metadata | `.openspec.yaml` in change directory |\n| 3 | Project Config | `openspec/config.yaml` |\n| 4 | Global Config | User's global settings |\n| 5 | Default | Hardcoded fallback (`spec-driven`) |\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-config/design.md)\n\n### Module Structure\n\n```\nsrc/core/\n├── config.ts # Main configuration module\n├── config-schema.ts # Configuration schema definitions\n├── global-config.ts # Global configuration management\n├── project-config.ts # Project-level configuration handling\n└── profiles.ts # Profile management\n```\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-config/design.md)\n\n## Core Modules\n\n### Project Config Module\n\nThe `project-config.ts` module handles reading, parsing, and validating project-level configuration.\n\n**Key Responsibilities:**\n\n- Read `openspec/config.yaml` from the project root\n- Parse YAML into typed configuration objects\n- Validate schema names against available schemas\n- Provide error messages for misconfiguration\n\n**Validation Logic:**\n\n```typescript\nexport function validateProjectConfig(config: ProjectConfig): ValidationResult {\n const errors: string[] = [];\n \n if (config.schema) {\n const availableSchemas = getAvailableSchemas();\n if (!availableSchemas.includes(config.schema)) {\n errors.push(`Invalid schema: ${config.schema}`);\n }\n }\n \n return { valid: errors.length === 0, errors };\n}\n```\n\n资料来源：[src/core/project-config.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/project-config.ts)\n\n### Profile Management\n\nProfiles allow users to customize their OpenSpec workflow by selecting different command sets and behaviors.\n\n```mermaid\ngraph TD\n A[Profile Selection] --> B[Minimal Profile]\n A --> C[Artifact-Guided Profile]\n A --> D[Experimental Profile]\n \n B --> B1[Basic commands: init, list, show]\n C --> C1[opsx commands: new, continue, ff]\n D --> D1[Early access features]\n```\n\n**Available Profiles:**\n\n| Profile | Commands | Description |\n|---------|----------|-------------|\n| `minimal` | `init`, `list`, `show`, `new`, `apply`, `archive` | Basic workflow |\n| `artifact-guided` | `opsx:*` commands | New artifact-driven workflow |\n| `experimental` | All + experimental features | Early access features |\n\n资料来源：[openspec/README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n## Configuration CLI Commands\n\nThe `config` command group provides interactive management of OpenSpec configuration.\n\n### Commands\n\n| Command | Description |\n|---------|-------------|\n| `openspec config profile` | Select active workflow profile |\n| `openspec config view` | Display current configuration |\n| `openspec config validate` | Validate configuration files |\n| `openspec config init` | Initialize project configuration |\n\n### Interactive Profile Selection\n\n```bash\n$ openspec config profile\n? Select a profile:\n > minimal (default)\n artifact-guided (recommended)\n experimental\n```\n\n资料来源：[src/commands/config.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/commands/config.ts)\n\n## Context and Rules Injection\n\n### How Context Works\n\nThe project `context` section is injected into generated artifacts to provide project-specific background information:\n\n```bash\n# Get instructions for artifact with context\nopenspec instructions specs --change my-feature\n\n# Output structure:\n\n[Project context from config.yaml]\n\n\n\n[Schema's specs template]\n\n```\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-config/proposal.md)\n\n### Rule Injection by Artifact Type\n\nRules are only injected for artifacts that have them configured:\n\n```mermaid\ngraph TD\n A[Artifact Request] --> B{Has rules?}\n B -->|Yes| C[Include rules section]\n B -->|No| D[Skip rules section]\n \n C --> E[]\n C --> F[]\n C --> G[]\n \n D --> E\n D --> G\n```\n\n**Example: Rules for `proposal` artifact:**\n\n```yaml\nrules:\n proposal:\n - Include spike tasks for unknown complexities\n - Reference existing patterns before inventing new ones\n```\n\n**Example: Rules for `specs` artifact:**\n\n```yaml\nrules:\n specs:\n - Use SHALL/MUST for normative requirements\n - Every requirement MUST have at least one scenario\n - Scenarios MUST use exactly 4 hashtags (####)\n```\n\n资料来源：[schemas/spec-driven/schema.yaml](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/schema.yaml)\n\n## Schema Resolution\n\n### Resolution Function\n\nThe `resolveSchemaForChange()` function determines which schema to use:\n\n```typescript\nexport function resolveSchemaForChange(\n changeName: string,\n cliSchema?: string\n): string {\n // 1. CLI flag wins\n if (cliSchema) {\n return cliSchema;\n }\n\n // 2. Change metadata (.openspec.yaml)\n const metadata = readChangeMetadata(changeName);\n if (metadata?.schema) {\n return metadata.schema;\n }\n\n // 3. Project config (NEW)\n const projectConfig = readProjectConfig();\n if (projectConfig?.schema) {\n return projectConfig.schema;\n }\n\n // 4. Hardcoded default\n return 'spec-driven';\n}\n```\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-config/design.md)\n\n### Project-Local Schemas\n\nOpenSpec supports project-local schemas that override built-in schemas:\n\n```mermaid\ngraph TD\n A[Schema Request] --> B{Project-local exists?}\n B -->|Yes| C[Use project-local]\n B -->|No| D{User override exists?}\n D -->|Yes| E[Use user override]\n D -->|No| F[Use built-in]\n```\n\n**Schema Search Order:**\n\n1. `/openspec/schemas//`\n2. `/openspec/schemas//`\n3. `/schemas//`\n\n资料来源：[openspec/changes/archive/2026-02-17-project-local-schemas/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-local-schemas/design.md)\n\n## Global Configuration\n\nGlobal configuration lives in the user's home directory and provides defaults that apply across all projects.\n\n**Default Location:** `~/.config/openspec/config.yaml` (Linux/macOS)\n\n**Purpose:**\n\n- Default profile selection\n- Telemetry preferences\n- Editor-specific settings\n\n### Telemetry Configuration\n\nOpenSpec collects anonymous usage statistics by default:\n\n```bash\n# Opt-out via environment variable\nexport OPENSPEC_TELEMETRY=0\n# or\nexport DO_NOT_TRACK=1\n```\n\n资料来源：[openspec/README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n## Validation and Error Handling\n\n### Configuration Validation\n\nThe validation system checks for common configuration errors:\n\n```typescript\nexport function validateConfig(config: unknown): ValidationResult {\n const errors: string[] = [];\n \n // Check schema validity\n if (!config.schema || !isValidSchema(config.schema)) {\n errors.push(`Invalid schema: ${config.schema}`);\n }\n \n // Check context structure\n if (config.context && typeof config.context !== 'object') {\n errors.push('Context must be an object');\n }\n \n return { valid: errors.length === 0, errors };\n}\n```\n\n### Error Messages\n\nWhen validation fails, OpenSpec provides actionable error messages:\n\n```\nError: Invalid schema 'unknown-schema'\nAvailable schemas:\n Built-in: spec-driven, minimal, gpt-prompts\n Project-local: (none found)\n\nFix: Edit openspec/config.yaml and change 'schema: unknown-schema' to a valid schema name\n```\n\n资料来源：[src/core/project-config.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/project-config.ts)\n\n## Migration from Legacy Config\n\n### Old Configuration Files\n\nOpenSpec previously used different configuration mechanisms that are now deprecated:\n\n| Old File | New Location | Notes |\n|----------|--------------|-------|\n| `openspec/project.md` | `openspec/config.yaml.context` | Migrate manually |\n| `CLAUDE.md` | `openspec/config.yaml` | Removed |\n| `.cursorrules` | `openspec/config.yaml` | Removed |\n| `.windsurfrules` | `openspec/config.yaml` | Removed |\n\n### Migration Steps\n\n1. Run `openspec init` to detect legacy artifacts\n2. Review the migration hints provided\n3. Manually migrate `project.md` content to `config.yaml.context`\n4. Delete old configuration files when ready\n\n资料来源：[openspec/changes/archive/2026-02-17-merge-init-experimental/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-merge-init-experimental/design.md)\n\n## Best Practices\n\n### Configuration Organization\n\n1. **Commit `config.yaml`** — Keep project configuration in version control for team consistency\n2. **Use descriptive context** — Include tech stack, conventions, and terminology\n3. **Define artifact rules** — Set clear guidelines for each artifact type\n4. **Keep rules concise** — Rules should be actionable constraints, not verbose documentation\n\n### Team Collaboration\n\n```bash\n# Share configuration via git\ngit add openspec/config.yaml\ngit commit -m \"Add project config with context and rules\"\n\n# Everyone gets the same context and rules automatically\n```\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-config/proposal.md)\n\n## Summary\n\nThe OpenSpec configuration system provides a flexible, layered approach to managing project settings:\n\n- **Project-level config** (`openspec/config.yaml`) for team-shared context and rules\n- **Schema-based organization** for consistent artifact generation\n- **Per-artifact rules** for tailored guidelines\n- **Profile system** for workflow customization\n- **Validation** to catch configuration errors early\n\n---\n\n\n\n## Validation System\n\n### 相关页面\n\n相关主题：[Schemas](#schemas), [Configuration](#configuration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/core/validation/validator.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/validation/validator.ts)\n- [src/core/validation/types.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/validation/types.ts)\n- [src/core/validation/constants.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/validation/constants.ts)\n- [src/core/parsers/spec-structure.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/parsers/spec-structure.ts)\n- [src/commands/validate.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/commands/validate.ts)\n \n\n# Validation System\n\n## Overview\n\nThe OpenSpec Validation System is a multi-layered infrastructure that ensures specification files, change artifacts, and project configurations conform to defined schemas and structural requirements. The validation system serves as the quality gate for the entire OpenSpec workflow, preventing malformed specs from entering the repository and maintaining consistency across teams and projects.\n\nThe validation system operates at multiple levels: structural validation of markdown content, schema-based validation using Zod, and command-level validation for CLI operations. This layered approach ensures that validation is both comprehensive and performant, catching errors early in the development workflow.\n\nThe system is designed to be reusable across different commands and workflows, following the principle established in the implementation order that schemas and validation infrastructure should be shared between command implementations.\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n A[User/CLI Command] --> B[Validation Entry Point]\n B --> C[Command Validation]\n B --> D[Spec Structure Validation]\n B --> E[Schema Validation]\n \n C --> F[openspec validate]\n C --> G[openspec show --json --deltas-only]\n C --> H[openspec instructions]\n \n D --> I[Markdown Parser]\n D --> J[Spec Structure Parser]\n D --> K[Scenario Parser]\n \n E --> L[Zod Schemas]\n E --> M[Custom Validators]\n \n I --> N[Header Extraction]\n I --> O[Content Normalization]\n J --> P[Requirement Parsing]\n J --> Q[Delta Detection]\n K --> R[WHEN/THEN Format]\n K --> S[Scenario Validation]\n \n L --> T[ArtifactSchema]\n L --> U[SchemaYamlSchema]\n L --> V[ChangeMetadataSchema]\n```\n\n## Core Components\n\n### Validation Types (`src/core/validation/types.ts`)\n\nThe types module defines the foundational data structures used throughout the validation system. These types are constructed using Zod schemas to enable runtime validation with full type inference.\n\n| Type | Purpose | Key Fields |\n|------|---------|------------|\n| `ValidationResult` | Encapsulates validation outcome | `valid: boolean`, `errors: ValidationError[]`, `warnings: ValidationWarning[]` |\n| `ValidationError` | Represents a validation failure | `code: string`, `message: string`, `path: string`, `line?: number` |\n| `SpecRequirement` | Parsed requirement structure | `name: string`, `description: string`, `scenarios: Scenario[]` |\n| `Scenario` | Individual test scenario | `name: string`, `when: string`, `then: string[]` |\n\nThe type definitions ensure that all validation operations work with consistent data structures, reducing runtime errors and improving developer experience through IDE autocompletion.\n\n### Validation Constants (`src/core/validation/constants.ts`)\n\nConstants define the boundaries and thresholds for validation operations. These values are extracted into a dedicated module to allow easy tuning without modifying validation logic.\n\n```typescript\n// Example constant categories\nconst VALIDATION = {\n MAX_REQUIREMENT_LENGTH: 500,\n MAX_SCENARIO_COUNT: 50,\n MIN_REQUIREMENT_COUNT: 1,\n REQUIRED_HEADERS: ['## Purpose', '## Requirements'],\n} as const;\n\nconst ERROR_CODES = {\n MISSING_REQUIREMENT: 'SPEC_001',\n MISSING_SCENARIO: 'SPEC_002',\n INVALID_FORMAT: 'SPEC_003',\n CYCLIC_DEPENDENCY: 'GRAPH_001',\n INVALID_DELTA: 'DELTA_001',\n} as const;\n```\n\n### Core Validator (`src/core/validation/validator.ts`)\n\nThe validator module contains the primary validation logic that orchestrates checks across different validation layers. It provides a unified interface for validating various OpenSpec artifacts.\n\n**Key Responsibilities:**\n\n- Coordinating validation across multiple layers (structural, schema, semantic)\n- Aggregating errors and warnings from different validators\n- Providing detailed error messages with file paths and line numbers\n- Supporting both synchronous and asynchronous validation flows\n\n```typescript\n// Conceptual validation flow\nasync function validateSpec(specPath: string): Promise {\n const errors: ValidationError[] = [];\n const warnings: ValidationWarning[] = [];\n \n // Layer 1: File existence and readability\n const fileResult = await validateFileAccess(specPath);\n if (!fileResult.valid) return fileResult;\n \n // Layer 2: Structure validation\n const structure = await parseSpecStructure(specPath);\n const structureErrors = validateStructure(structure);\n errors.push(...structureErrors);\n \n // Layer 3: Content validation\n const contentErrors = validateContent(structure);\n errors.push(...contentErrors);\n \n // Layer 4: Cross-reference validation\n const xrefErrors = validateCrossReferences(structure);\n errors.push(...xrefErrors);\n \n return {\n valid: errors.length === 0,\n errors,\n warnings,\n };\n}\n```\n\n## Spec Structure Validation\n\n### Markdown Parser (`src/core/parsers/spec-structure.ts`)\n\nThe spec structure parser extracts structured data from markdown-formatted specification files. It handles the unique requirements of OpenSpec's spec format, including requirement blocks, scenario definitions, and delta operations.\n\n**Parsing Capabilities:**\n\nThe parser handles multiple content types found in OpenSpec specifications:\n\n- **Requirements**: Extracted from `### Requirement:` headers with accompanying descriptions\n- **Scenarios**: Parsed from `#### Scenario:` headers using WHEN/THEN/AND format\n- **Delta Operations**: Identifies ADDED, MODIFIED, REMOVED, and RENAMED sections\n- **Frontmatter**: Processes YAML frontmatter for metadata and schema references\n\n**Critical Parsing Rules:**\n\nPer the schema specification, scenario headers must use exactly four hashtags (`####`) followed by `Scenario:`. Using three hashtags or bullet-point formats will result in silent parsing failures.\n\n```typescript\n// Scenario detection pattern\nconst SCENARIO_PATTERN = /^#### Scenario:\\s*(.+)$/gm;\nconst WHEN_PATTERN = /^\\*?\\*?WHEN\\*?\\*?\\s+(.+)$/im;\nconst THEN_PATTERN = /^\\*?\\*?THEN\\*?\\*?\\s+(.+)$/im;\nconst AND_PATTERN = /^\\*?\\*?AND\\*?\\*?\\s+(.+)$/im;\n```\n\n### Content Normalization\n\nThe validation system normalizes input content to handle platform-specific line endings. This is particularly important because different operating systems use different line ending conventions:\n\n- Unix/Linux/macOS: LF (`\\n`)\n- Windows: CRLF (`\\r\\n`)\n- Legacy systems: CR (`\\r`)\n\nThe parser normalizes all line endings before processing to ensure consistent behavior regardless of the file's origin.\n\n## Schema Validation\n\n### Zod Integration\n\nOpenSpec uses Zod for schema validation throughout the system. Zod provides runtime type validation with compile-time type inference, eliminating the gap between TypeScript types and runtime behavior.\n\n**Schema Types:**\n\n| Schema | Purpose | Used By |\n|--------|---------|---------|\n| `ArtifactSchema` | Validates artifact definitions in schema.yaml | Artifact graph loader |\n| `SchemaYamlSchema` | Validates entire schema configuration files | Schema initialization |\n| `ChangeMetadataSchema` | Validates change folder metadata | Change creation and validation |\n| `SpecRequirementSchema` | Validates individual requirements | Spec parsing |\n\n### Schema Loading and Validation\n\nSchemas are loaded from `openspec/schemas//schema.yaml` and validated against the SchemaYamlSchema before use. This two-stage validation ensures that invalid schema definitions are caught early.\n\n```typescript\n// Schema loading flow\nasync function loadSchema(schemaName: string, projectRoot: string): Promise {\n const schemaPath = getSchemaPath(schemaName, projectRoot);\n const rawYaml = await fs.readFile(schemaPath, 'utf-8');\n const parsed = YAML.parse(rawYaml);\n \n // Validate against schema schema\n const result = SchemaYamlSchema.safeParse(parsed);\n if (!result.success) {\n throw new SchemaValidationError(result.error);\n }\n \n return result.data;\n}\n```\n\n## Command-Level Validation\n\n### CLI Validate Command (`src/commands/validate.ts`)\n\nThe `openspec validate` command provides the primary interface for manual and automated validation of OpenSpec artifacts.\n\n**Usage:**\n\n```bash\nopenspec validate [--strict]\nopenspec validate --specs [--all]\nopenspec validate --changes [--all]\n```\n\n**Flags:**\n\n| Flag | Description | Default |\n|------|-------------|---------|\n| `--strict` | Enable all validation rules including warnings as errors | `false` |\n| `--specs` | Validate all specs in the repository | `false` |\n| `--changes` | Validate all active changes | `true` |\n| `--all` | Include archived items in validation scope | `false` |\n| `--json` | Output machine-readable JSON format | `false` |\n\n**Validation Output:**\n\nWhen validation succeeds, the command outputs a summary table:\n\n```text\n✓ Change \"add-dark-mode\" validated successfully\n - proposal.md: valid\n - specs/auth/spec.md: valid (2 requirements, 5 scenarios)\n - tasks.md: valid (12 tasks)\n```\n\nWhen validation fails, the output includes detailed error information:\n\n```text\n✗ Validation failed for \"update-auth-flow\"\n - specs/auth/spec.md:12\n ERROR [SPEC_002]: Requirement \"Legacy export\" missing scenario\n HELP: Add at least one scenario using \"#### Scenario:\" header\n\n - specs/auth/spec.md:45\n ERROR [SPEC_003]: Invalid WHEN/THEN format\n HELP: Use \"**WHEN** condition\" and \"**THEN** outcome\" format\n```\n\n## Validation Workflows\n\n### Change Lifecycle Validation\n\n```mermaid\ngraph LR\n A[Create Change] --> B[Validate Proposal]\n B --> C{Valid?}\n C -->|No| D[Fix Errors]\n D --> B\n C -->|Yes| E[Implement Tasks]\n E --> F[Validate Specs]\n F --> G{Valid?}\n G -->|No| H[Update Specs]\n H --> F\n G -->|Yes| I[Archive Change]\n I --> J[Final Validation]\n J --> K[Merge to Source]\n```\n\n### Delta Detection Validation\n\nThe validation system extracts deltas from change spec files and validates their structure before applying them to the source specifications. This ensures that only properly formatted changes are merged.\n\n**Delta Types:**\n\n| Delta Type | Syntax | Description |\n|------------|--------|-------------|\n| ADDED | `## ADDED Requirements` | New requirements being introduced |\n| MODIFIED | `## MODIFIED Requirements` | Changes to existing requirements |\n| REMOVED | `## REMOVED Requirements` | Requirements being deleted |\n| RENAMED | `## RENAMED Requirements` | Requirements being renamed or restructured |\n\n**Delta Extraction Process:**\n\n1. Parse the spec file in the change's `specs/` directory\n2. Identify delta section headers using operation prefixes\n3. Validate each delta against the appropriate schema\n4. Check for conflicts between MODIFIED and REMOVED deltas\n5. Generate a validation report with all findings\n\n## Error Handling\n\n### Error Code Reference\n\n| Code | Category | Description | Resolution |\n|------|----------|-------------|------------|\n| `SPEC_001` | Structure | Missing required requirement | Add requirement with proper `### Requirement:` header |\n| `SPEC_002` | Content | Requirement missing scenario | Add `#### Scenario:` with WHEN/THEN format |\n| `SPEC_003` | Format | Invalid scenario syntax | Use exact `**WHEN**` and `**THEN**` format |\n| `SPEC_004` | Content | Empty requirement description | Provide description after requirement header |\n| `GRAPH_001` | Schema | Cyclic dependency detected | Review artifact `requires` field in schema.yaml |\n| `GRAPH_002` | Schema | Duplicate artifact ID | Ensure unique IDs in schema definition |\n| `DELTA_001` | Delta | Invalid delta operation | Use ADDED, MODIFIED, REMOVED, or RENAMED |\n| `DELTA_002` | Delta | Delta references missing spec | Ensure target spec exists in source specs/ |\n\n### Recovery Strategies\n\nThe validation system implements graceful degradation for common issues:\n\n**Silent Failures Prevention:**\n\n- Scenario parsing failures are caught and reported explicitly\n- Missing headers trigger specific error messages with fix suggestions\n- Format violations include the expected format in the error output\n\n**Partial Success Handling:**\n\nWhen a file contains multiple issues, validation continues to identify all problems rather than failing on the first error. This reduces the number of validation cycles needed to fix all issues.\n\n## Integration with Other Modules\n\n### Project Configuration\n\nThe validation system respects project-level configuration defined in `openspec/config.yaml`. Project-specific rules can be configured to add validation constraints beyond the defaults.\n\n```yaml\nvalidation:\n strict: true\n allowedDeltaTypes: [ADDED, MODIFIED, REMOVED]\n requireDesignArtifact: true\n```\n\n### Artifact Graph Integration\n\nValidation is integrated with the artifact graph system to validate artifact state transitions and dependency requirements. Before marking an artifact as complete, the validation system verifies all prerequisites are satisfied.\n\n### Change Manager Integration\n\nThe change manager uses validation to enforce naming conventions and structural requirements when creating new changes. Invalid change names or structures are rejected at creation time.\n\n## Best Practices\n\n### Writing Valid Specs\n\n1. **Use Exact Headers**: Always use `#### Scenario:` with four hashtags for scenarios\n2. **Follow WHEN/THEN Format**: Structure scenarios with clear conditions and outcomes\n3. **Include All Scenarios**: Every requirement must have at least one scenario\n4. **Use ADDED/MODIFIED/REMOVED**: Prefix delta sections with operation names\n5. **Keep Scenarios Testable**: Scenarios should describe observable behavior\n\n### Validation in CI/CD\n\nIntegrate validation into continuous integration pipelines:\n\n```yaml\n# Example CI configuration\n- name: Validate OpenSpec changes\n run: |\n npx openspec validate --changes --strict\n```\n\n### Debugging Validation Failures\n\nWhen validation fails, use the JSON output for programmatic inspection:\n\n```bash\nopenspec show add-feature --json --deltas-only\n```\n\nThis outputs the parsed deltas without full change details, helping identify parsing issues.\n\n---\n\n\n\n## Supported AI Tools\n\n### 相关页面\n\n相关主题：[Slash Commands](#slash-commands)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/supported-tools.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/supported-tools.md)\n- [src/core/available-tools.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/available-tools.ts)\n- [src/core/command-generation/adapters/index.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/command-generation/adapters/index.ts)\n- [README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n- [CHANGELOG.md](https://github.com/Fission-AI/OpenSpec/blob/main/CHANGELOG.md)\n \n\n# Supported AI Tools\n\nOpenSpec is designed to integrate seamlessly with a wide variety of AI coding assistants. The supported AI tools system enables OpenSpec to provide consistent specification workflows across different development environments and toolchains.\n\n## Overview\n\nOpenSpec supports AI tools through a multi-layered integration system that includes:\n\n- **Native Slash Commands**: Built-in commands directly recognized by the AI tool\n- **Slash Command Templates**: Tool-specific command files with frontmatter metadata\n- **AGENTS.md Compatible**: Workflow instructions that AI tools can automatically discover\n\n资料来源：[README.md:1-100]()\n\n## Architecture\n\nThe AI tools integration is built on a modular architecture with three core components:\n\n```mermaid\ngraph TD\n A[User Request] --> B[OpenSpec CLI]\n B --> C{Determine Tool}\n C --> D[Claude Code]\n C --> E[Cursor]\n C --> F[Codex]\n C --> G[Amazon Q]\n C --> H[Other Tools]\n \n D --> I[Slash Commands]\n E --> J[Cursor Commands]\n F --> K[Codex Commands]\n G --> L[Q Developer Prompts]\n H --> M[AGENTS.md]\n \n I --> N[openspec/proposal
openspec/apply
openspec/archive]\n J --> O[openspec-proposal
openspec-apply
openspec-archive]\n```\n\n资料来源：[src/core/command-generation/adapters/index.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/command-generation/adapters/index.ts)\n\n## Supported Tools List\n\nOpenSpec integrates with the following AI coding assistants:\n\n| Tool | Slash Commands | Command Directory | Category |\n|------|---------------|-------------------|----------|\n| **Claude Code** | `/openspec/proposal`, `/openspec/apply`, `/openspec/archive` | `.claude/commands/openspec/` | Native |\n| **Cursor** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.cursor/commands/` | Native |\n| **CodeBuddy Code** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` | `.codebuddy/commands/` | Native |\n| **Amazon Q Developer** | `@openspec-proposal`, `@openspec-apply`, `@openspec-archive` | `.amazonq/prompts/` | Native |\n| **Windsurf** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.windsurf/workflows/` | Native |\n| **RooCode** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.roo/commands/` | Native |\n| **Augment CLI** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.augment/commands/` | Native |\n| **Antigravity** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.agent/workflows/` | Native |\n| **Cline** | Workflows in `.clinerules/workflows/` | `.clinerules/workflows/openspec-*.md` | Native |\n| **Kilo Code** | Command palette triggers | `.kilocode/workflows/` | Native |\n| **Gemini CLI** | TOML-based commands | `.gemini/commands/openspec/` | Native |\n| **Qwen Code** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` | — | Native |\n| **CoStrict AI** | — | — | Native |\n| **Qoder CLI** | — | — | Native |\n| **Continue** | `/openspec-proposal.md`, `/openspec-apply.md`, `/openspec-archive.md` | `.continue/prompts/` | Native |\n\n资料来源：[docs/supported-tools.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/supported-tools.md)\n\n## Tool Categories\n\n### Native Slash Commands\n\nTools with native slash command support have built-in OpenSpec commands. When initializing OpenSpec for these tools, select the appropriate integration option.\n\n```mermaid\ngraph LR\n A[openspec init] --> B[Select Tool]\n B --> C[Claude Code]\n B --> D[Cursor]\n B --> E[Windsurf]\n \n C --> F[Creates: .claude/commands/openspec/]\n D --> G[Creates: .cursor/commands/]\n E --> H[Creates: .windsurf/workflows/]\n```\n\n资料来源：[README.md:150-200]()\n\n### AGENTS.md Compatible\n\nSome tools automatically read workflow instructions from `openspec/AGENTS.md`. These tools can be instructed to follow the OpenSpec workflow using natural language.\n\n| Tool | Support Level |\n|------|---------------|\n| Amp | Compatible |\n| Jules | Compatible |\n| Others | Via AGENTS.md convention |\n\n资料来源：[README.md:200-250]()\n\n## Command Structure\n\n### Slash Command Format\n\nCommands follow a consistent pattern across tools but with tool-specific adaptations:\n\n```markdown\n---\nname: openspec-proposal\ndescription: Create a new OpenSpec change proposal\ncategory: OpenSpec\n---\n\n...command body...\n\n```\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md)\n\n### Command Naming Conventions\n\n| Tool | Naming Style | Example |\n|------|-------------|---------|\n| Claude Code | Namespaced with `/` | `/openspec/proposal` |\n| Cursor | Flat with `openspec-` prefix | `/openspec-proposal` |\n| Windsurf | Flat with `openspec-` prefix | `/openspec-proposal` |\n| RooCode | Flat with `openspec-` prefix | `/openspec-proposal` |\n| Gemini CLI | TOML-based configuration | — |\n\n### Marker Placement Rules\n\nCommands must follow strict marker placement rules:\n\n1. **Frontmatter goes first** (if supported by the tool)\n2. **``** marker opens the body\n3. Command body content follows\n4. **``** marker closes the body\n\n```markdown\n---\nname: openspec-apply\ndescription: Apply OpenSpec change tasks\ncategory: OpenSpec\n---\n\nStep-by-step instructions for applying tasks...\n\n```\n\n**Critical**: Markers must never be placed inside the YAML frontmatter block.\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/design.md)\n\n## Configuration\n\n### Tool Configuration Interface\n\nThe `AIToolOption` interface defines how tools are configured:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `id` | `string` | Unique identifier for the tool |\n| `name` | `string` | Display name |\n| `skillsDir` | `string` | Path to tool's skill/command directory |\n| `commandPrefix` | `string` | Prefix for slash commands |\n| `frontmatterFormat` | `string` | Supported frontmatter type |\n\n资料来源：[src/core/available-tools.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/available-tools.ts)\n\n### Command Generation Adapters\n\nThe adapter pattern allows OpenSpec to generate tool-specific command files:\n\n```mermaid\nclassDiagram\n class ToolCommandAdapter {\n +generate(content: CommandContent): string\n +getFilePath(toolId: string): string\n +supportsFrontmatter(): boolean\n }\n \n class CommandContent {\n +id: string\n +name: string\n +description: string\n +body: string\n }\n \n class CommandGenerator {\n +generateAll(content: CommandContent, toolId: string)\n +updateExisting(content: CommandContent, toolId: string)\n }\n \n CommandGenerator --> ToolCommandAdapter\n CommandGenerator --> CommandContent\n```\n\n资料来源：[src/core/command-generation/adapters/index.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/command-generation/adapters/index.ts)\n\n## Initialization Workflow\n\nWhen running `openspec init`, the CLI performs the following steps:\n\n```mermaid\ngraph TD\n A[openspec init] --> B{Interactive or --tool flag?}\n B -->|Interactive| C[Prompt for tool selection]\n B -->|--tool| D[Use specified tool]\n \n C --> E[Select from available tools]\n D --> F[Validate tool ID]\n \n E --> G[Create tool directories]\n F --> G\n G --> H[Generate command files]\n H --> I[Apply OPENSPEC markers]\n I --> J[Confirmation message]\n```\n\n### Idempotency Rules\n\n| Operation | Behavior |\n|-----------|----------|\n| `init` | Create all command files once; subsequent runs are no-ops for existing files |\n| `update` | Refresh only existing files; do not create missing files |\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/design.md)\n\n## Adding New Tool Support\n\n### Design Pattern\n\nTo add support for a new AI tool, implement the following:\n\n1. **Create a tool adapter** in `src/core/command-generation/adapters/`\n2. **Define tool configuration** in `src/core/available-tools.ts`\n3. **Add command templates** for proposal, apply, and archive actions\n4. **Update documentation** in `docs/supported-tools.md`\n\n### Example Adapter Structure\n\n```typescript\n// src/core/command-generation/adapters/newtool-adapter.ts\nimport { ToolCommandAdapter } from './base';\n\nexport class NewToolAdapter implements ToolCommandAdapter {\n supportsFrontmatter(): boolean {\n return true;\n }\n \n getFilePath(): string {\n return '.newtool/commands/openspec';\n }\n \n generate(content: CommandContent): string {\n return this.wrapWithMarkers(content.body);\n }\n}\n```\n\n### Testing Strategy\n\n| Test Type | Purpose |\n|-----------|---------|\n| Golden snapshots | Verify generated files per tool (frontmatter + markers + body) |\n| Partial presence tests | Ensure `update` only refreshes existing files |\n| Marker placement tests | Verify markers never appear inside frontmatter |\n| Logging tests | Confirm `update` reports per-file results |\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md)\n\n## Version History\n\n### Version 1.3.0+\nAdded support for:\n- Gemini CLI with native TOML-based slash command support\n- RooCode integration with full configurator support\n- Cline workflows (moved from `.clinerules/rules/` to `.clinerules/workflows/`)\n- Continue prompt generation with MARKDOWN frontmatter and `$ARGUMENTS` placeholder\n\n资料来源：[CHANGELOG.md](https://github.com/Fission-AI/OpenSpec/blob/main/CHANGELOG.md)\n\n### Version 0.15.0+\nAdded support for:\n- Gemini CLI\n- RooCode\n- Cline (workflows)\n- Qwen Code\n- Qoder CLI\n- CoStrict AI\n\n### Version 0.14.0+\nAdded support for:\n- Qwen Code with slash command integration\n- `$ARGUMENTS` support in apply slash command\n- Qoder CLI support\n\n## Troubleshooting\n\n### Commands Not Appearing\n\nIf slash commands are not appearing:\n\n1. Verify the tool directory exists: `.claude/commands/openspec/`\n2. Check file naming matches expected pattern\n3. Run `openspec update` to refresh command files\n4. Restart the AI tool to reload commands\n\n### Marker Errors\n\nIf you see parsing errors:\n\n- Ensure `` and `` are on separate lines\n- Verify markers are not inside YAML frontmatter\n- Check for duplicate markers in the file\n\n### Tool Not Recognized\n\nFor unsupported tools:\n\n- Use `AGENTS.md` convention for workflow discovery\n- Run `openspec init` to see all available tool options\n- Check [docs/supported-tools.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/supported-tools.md) for the latest supported list\n\n## See Also\n\n- [Getting Started](docs/getting-started.md) - First steps with OpenSpec\n- [Workflows](docs/workflows.md) - Combos and patterns\n- [Commands](docs/commands.md) - Slash commands and skills reference\n- [Customization](docs/customization.md) - Making OpenSpec yours\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：Fission-AI/OpenSpec\n\n摘要：发现 22 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：/opsx:apply suggests openspec-continue-change which is not installed on core profile。\n\n## 1. 安装坑 · 来源证据：/opsx:apply suggests openspec-continue-change which is not installed on core profile\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：/opsx:apply suggests openspec-continue-change which is not installed on core profile\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_41aca88207aa4e70bba9c2ebaef629c7 | https://github.com/Fission-AI/OpenSpec/issues/963 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 配置坑 · 来源证据：Support schema extension or partial overrides to avoid full shadowing of built-in schemas\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Support schema extension or partial overrides to avoid full shadowing of built-in schemas\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_34110f57274440d4bbc5492e3b4f3bee | https://github.com/Fission-AI/OpenSpec/issues/1074 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 维护坑 · 来源证据：open:sync messed up my spec.md files\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：open:sync messed up my spec.md files\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ef1856d2856b49f5a7ed758bfc4099c8 | https://github.com/Fission-AI/OpenSpec/issues/911 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：Codex generated assets reference unsupported AskUserQuestion/TodoWrite/Task tools\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Codex generated assets reference unsupported AskUserQuestion/TodoWrite/Task tools\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_35b315a2b1a74564be1fb71d1f08359c | https://github.com/Fission-AI/OpenSpec/issues/1103 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：First steps don't work\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：First steps don't work\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_51f62d023b734ba59978cc70908c01c3 | https://github.com/Fission-AI/OpenSpec/issues/820 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 安装坑 · 来源证据：v1.1.0 - Cross-Platform Fixes, Nix Improvements\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.1.0 - Cross-Platform Fixes, Nix Improvements\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_016f567cecd44fbf96ffd635e1ec43bf | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.1.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：v1.3.1 - Path & Telemetry Fixes\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.3.1 - Path & Telemetry Fixes\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e641868122bb43938d6ff8a83b71e3d3 | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.3.1 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 8. 配置坑 · 来源证据：Incomplete artifacts marked as \"done\" after workflow interruption\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Incomplete artifacts marked as \"done\" after workflow interruption\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a0677545a17b433ca6e6561c5056ee46 | https://github.com/Fission-AI/OpenSpec/issues/1084 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 9. 配置坑 · 来源证据：OpenCode sync missing\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：OpenCode sync missing\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0076a9fb05a1443eb3e2a7c9185247e6 | https://github.com/Fission-AI/OpenSpec/issues/1007 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. 配置坑 · 来源证据：v0.22.0 - Project Configuration\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.22.0 - Project Configuration\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1a526029491b40e38c20ba075f311169 | https://github.com/Fission-AI/OpenSpec/releases/tag/v0.22.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 11. 配置坑 · 来源证据：v1.0.0 - The OPSX Release\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.0.0 - The OPSX Release\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b60a0c136c0347e9a034197f65844e1b | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.0.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 12. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1032459340 | https://github.com/Fission-AI/OpenSpec | README/documentation is current enough for a first validation pass.\n\n## 13. 运行坑 · 来源证据：v1.0.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.0.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_006cb659e21c431290fe448ddabc453c | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.0.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 14. 运行坑 · 来源证据：v1.0.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.0.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c7797487985047fba066bd58cba094ae | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.0.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 15. 维护坑 · 来源证据：Feedback: Deep verification test - PUA mode v3 active\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Feedback: Deep verification test - PUA mode v3 active\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d3d2fc07081648f796e477458600a95f | https://github.com/Fission-AI/OpenSpec/issues/1094 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 16. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1032459340 | https://github.com/Fission-AI/OpenSpec | last_activity_observed missing\n\n## 17. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1032459340 | https://github.com/Fission-AI/OpenSpec | no_demo; severity=medium\n\n## 18. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1032459340 | https://github.com/Fission-AI/OpenSpec | no_demo; severity=medium\n\n## 19. 安全/权限坑 · 来源证据：Protect OpenSpec from AI slop PRs\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Protect OpenSpec from AI slop PRs\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a941eca296774492b16583764132d1f8 | https://github.com/Fission-AI/OpenSpec/issues/1087 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 20. 安全/权限坑 · 来源证据：[Feature Request/Suggestion] Extension to package for custom schemas, associated skills, commands, hooks, and profiles\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature Request/Suggestion] Extension to package for custom schemas, associated skills, commands, hooks, and profiles\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_abcb3cf5661b4a19862619c854eb531d | https://github.com/Fission-AI/OpenSpec/issues/1081 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 21. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1032459340 | https://github.com/Fission-AI/OpenSpec | issue_or_pr_quality=unknown\n\n## 22. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1032459340 | https://github.com/Fission-AI/OpenSpec | release_recency=unknown\n\n\n",
"markdown_key": "openspec",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:1032459340",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/Fission-AI/OpenSpec"
},
{
"evidence_id": "art_0e5fb41928564ab8a00958a4bad4e970",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/Fission-AI/OpenSpec#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "OpenSpec 说明书",
"toc": [
"https://github.com/Fission-AI/OpenSpec 项目说明书",
"目录",
"Introduction to OpenSpec",
"Purpose and Scope",
"Core Features",
"Architecture Overview",
"The Change Structure",
"Workflow System",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "8498042fe8a738e8ad6facd94a5fc7f5025bf81d",
"repo_inspection_error": null,
"repo_inspection_files": [
"pnpm-lock.yaml",
"package.json",
"README.md",
"docs/customization.md",
"docs/migration-guide.md",
"docs/concepts.md",
"docs/cli.md",
"docs/opsx.md",
"docs/commands.md",
"docs/getting-started.md",
"docs/installation.md",
"docs/workflows.md",
"docs/multi-language.md",
"docs/supported-tools.md",
"src/index.ts",
"src/cli/index.ts",
"src/prompts/searchable-multi-select.ts",
"src/telemetry/index.ts",
"src/telemetry/config.ts",
"src/ui/welcome-screen.ts",
"src/ui/ascii-patterns.ts",
"src/utils/item-discovery.ts",
"src/utils/change-metadata.ts",
"src/utils/command-references.ts",
"src/utils/task-progress.ts",
"src/utils/shell-detection.ts",
"src/utils/index.ts",
"src/utils/match.ts",
"src/utils/change-utils.ts",
"src/utils/interactive.ts",
"src/utils/file-system.ts",
"src/core/view.ts",
"src/core/planning-home.ts",
"src/core/update.ts",
"src/core/config-prompts.ts",
"src/core/list.ts",
"src/core/profiles.ts",
"src/core/index.ts",
"src/core/profile-sync-drift.ts",
"src/core/config.ts"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# @fission-ai/openspec - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 @fission-ai/openspec 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `npm install -g @fission-ai/openspec@latest` 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做角色匹配试用\n- **为什么**：这个项目更像角色库，核心风险是选错角色或把角色文案当执行能力；先用 Prompt Preview 试角色匹配，再决定是否沙盒导入。\n\n### 30 秒判断\n\n- **现在怎么做**：先做角色匹配试用\n- **最小安全下一步**：先用 Prompt Preview 试角色匹配；满意后再隔离导入\n- **先别相信**：角色质量和任务匹配不能直接相信。\n- **继续会触碰**：角色选择偏差、命令执行、宿主 AI 配置\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **角色质量和任务匹配不能直接相信。**（unverified）：角色库证明有很多角色，不证明每个角色都适合你的具体任务，也不证明角色能产生高质量结果。\n- **不能把角色文案当成真实执行能力。**（unverified）：安装前只能判断角色描述和任务画像是否匹配，不能证明它能在宿主 AI 里完成任务。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`AGENTS.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n\n### 继续会触碰什么\n\n- **角色选择偏差**：用户对任务应该由哪个专家角色处理的判断。 原因：选错角色会让 AI 从错误专业视角回答，浪费时间或误导决策。\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`AGENTS.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：先用交互式试用验证任务画像和角色匹配，不要先导入整套角色库。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **保留原始角色选择记录**：如果输出偏题，可以回到任务画像阶段重新选择角色，而不是继续沿着错误角色推进。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0004` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0005` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：734\n- 重要文件覆盖：40/734\n- 证据索引条目：79\n- 角色 / Skill 条目：78\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 @fission-ai/openspec 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 @fission-ai/openspec 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 @fission-ai/openspec 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 78 个角色 / Skill / 项目文档条目。\n\n- **Changesets**（project_doc）：This directory is managed by Changesets https://github.com/changesets/changesets . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/README.md`\n- **Dev Container Setup**（project_doc）：This directory contains the VS Code dev container configuration for OpenSpec development. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.devcontainer/README.md`\n- **Agents**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`AGENTS.md`\n- **See it in action**（project_doc）：! Stars https://img.shields.io/github/stars/Fission-AI/OpenSpec?style=flat-square&label=Stars https://github.com/Fission-AI/OpenSpec/stargazers ! Downloads https://img.shields.io/npm/dm/@fission-ai/openspec?style=flat-square&label=Downloads/mo https://www.npmjs.com/package/@fission-ai/openspec ! Contributors https://img.shields.io/github/contributors/Fission-AI/OpenSpec?style=flat-square&label=Contributors https://g… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **OpenSpec Scripts**（project_doc）：Utility scripts for OpenSpec maintenance and development. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`scripts/README.md`\n- **Github Workflows**（project_doc）：Test GitHub Actions workflows locally using act https://nektosact.com/ : 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/workflows/README.md`\n- **OpenSpec Instructions**（project_doc）：This document provides instructions for AI coding assistants on how to use OpenSpec conventions for spec-driven development. Follow these rules precisely when working on OpenSpec-enabled projects. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-08-11-add-complexity-guidelines/specs/openspec-docs/README.md`\n- **opencode-command-references**（project_doc）：Transform /opsx: to /opsx- in both commands and skills for OpenCode 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2026-01-30-opencode-command-references/README.md`\n- **add-kimi-cli-skills-only-support**（project_doc）：Add Kimi CLI as a supported skills-only tool without a command adapter 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2026-04-23-add-kimi-cli-skills-only-support/README.md`\n- **Workspace Reimplementation Roadmap**（project_doc）：This change is the continuity layer for reimplementing workspace support across multiple sessions and branches. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/workspace-reimplementation-roadmap/README.md`\n- **CLI Reference**（project_doc）：The OpenSpec CLI openspec provides terminal commands for project setup, validation, status inspection, and management. These commands complement the AI slash commands like /opsx:propose documented in Commands commands.md . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/cli.md`\n- **Commands**（project_doc）：This is the reference for OpenSpec's slash commands. These commands are invoked in your AI coding assistant's chat interface e.g., Claude Code, Cursor, Windsurf . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/commands.md`\n- **Concepts**（project_doc）：This guide explains the core ideas behind OpenSpec and how they fit together. For practical usage, see Getting Started getting-started.md and Workflows workflows.md . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/concepts.md`\n- **Customization**（project_doc）：OpenSpec provides three levels of customization: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/customization.md`\n- **Getting Started**（project_doc）：This guide explains how OpenSpec works after you've installed and initialized it. For installation instructions, see the main README ../README.md quick-start . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/getting-started.md`\n- **Installation**（project_doc）：- Node.js 20.19.0 or higher — Check your version: node --version 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/installation.md`\n- **Migrating to OPSX**（project_doc）：This guide helps you transition from the legacy OpenSpec workflow to OPSX. The migration is designed to be smooth—your existing work is preserved, and the new system offers more flexibility. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/migration-guide.md`\n- **Multi-Language Guide**（project_doc）：Configure OpenSpec to generate artifacts in languages other than English. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/multi-language.md`\n- **OPSX Workflow**（project_doc）：Feedback welcome on Discord https://discord.gg/YctCnvvshC . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/opsx.md`\n- **Supported Tools**（project_doc）：OpenSpec works with many AI coding assistants. When you run openspec init , OpenSpec configures selected tools using your active profile/workflow selection and delivery mode. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/supported-tools.md`\n- **Workflows**（project_doc）：This guide covers common workflow patterns for OpenSpec and when to use each one. For basic setup, see Getting Started getting-started.md . For command reference, see Commands commands.md . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/workflows.md`\n- **Clarify Bun Node Runtime**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/clarify-bun-node-runtime.md`\n- **New Features**（project_doc）：- Kimi CLI support — OpenSpec can now initialize Kimi CLI as a supported skills-only tool using .kimi/skills/ 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/kind-rings-notice.md`\n- **New Features**（project_doc）：- Include the sync workflow in the default core profile so new installs generate /opsx:sync skills and commands by default. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/sync-default-core.md`\n- **@fission-ai/openspec**（project_doc）：- 995 https://github.com/Fission-AI/OpenSpec/pull/995 d1f3861 https://github.com/Fission-AI/OpenSpec/commit/d1f3861d9ec694cc924b042b5da01963dcf93137 Thanks @TabishB https://github.com/TabishB ! - Bug Fixes 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CHANGELOG.md`\n- **Maintainers**（project_doc）：People who maintain and guide OpenSpec. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`MAINTAINERS.md`\n- **OpenSpec**（project_doc）：Spec-driven development for AI coding assistants. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README_OLD.md`\n- **Workspace Reimplementation Direction**（project_doc）：Workspace Reimplementation Direction 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`WORKSPACE_REIMPLEMENTATION_DIRECTION.md`\n- **Workspace Reimplementation Start Here**（project_doc）：Workspace Reimplementation Start Here 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`WORKSPACE_REIMPLEMENTATION_START_HERE.md`\n- **OpenSpec Parallel Delta Remediation Plan**（project_doc）：OpenSpec Parallel Delta Remediation Plan 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec-parallel-merge-plan.md`\n- **Implementation Order and Dependencies**（project_doc）：Implementation Order and Dependencies 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/IMPLEMENTATION_ORDER.md`\n- **Add Artifact Regeneration Support**（project_doc）：Currently, there is no way to regenerate artifacts in the OPSX workflow: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-artifact-regeneration-support/proposal.md`\n- **Why**（project_doc）：Parallel changes often touch the same capabilities and cli-init / cli-update behavior, but today there is no machine-readable way to express sequencing, dependencies, or expected merge order. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-change-stacking-awareness/proposal.md`\n- **ADDED Requirements**（project_doc）：Requirement: Stack Metadata Scaffolding Change creation workflows SHALL support optional dependency metadata for new or split changes. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-change-stacking-awareness/specs/change-creation/spec.md`\n- **ADDED Requirements**（project_doc）：Requirement: Stack Metadata Model The system SHALL support optional metadata on active changes to express sequencing and decomposition relationships. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-change-stacking-awareness/specs/change-stacking-workflow/spec.md`\n- **ADDED Requirements**（project_doc）：Requirement: Stack Planning Commands The change CLI SHALL provide commands for dependency-aware sequencing of active changes. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-change-stacking-awareness/specs/cli-change/spec.md`\n- **ADDED Requirements**（project_doc）：Requirement: Stack-Aware Change Planning Conventions OpenSpec conventions SHALL define optional metadata fields for sequencing and decomposition across concurrent changes. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-change-stacking-awareness/specs/openspec-conventions/spec.md`\n- **1. Metadata Model**（project_doc）：- 1.1 Add optional stack metadata fields dependsOn , provides , requires , touches , parent to change metadata schema - 1.2 Keep metadata backward compatible for existing changes without new fields - 1.3 Add tests for valid/invalid metadata and schema evolution behavior 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-change-stacking-awareness/tasks.md`\n- **Context**（project_doc）：OpenSpec today assumes project-local installation for most generated artifacts, with Codex command prompts as the main global exception. This mixed model works, but it is implicit and not user-configurable. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-global-install-scope/design.md`\n- **Why**（project_doc）：OpenSpec installation paths are currently inconsistent: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-global-install-scope/proposal.md`\n- **MODIFIED Requirements**（project_doc）：Requirement: AIToolOption skillsDir field The AIToolOption interface SHALL include scope support metadata in addition to path metadata. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-global-install-scope/specs/ai-tool-paths/spec.md`\n- **ADDED Requirements**（project_doc）：Requirement: Install scope configuration via profile flow The config profile workflow SHALL allow users to configure install scope preference. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-global-install-scope/specs/cli-config/spec.md`\n- **ADDED Requirements**（project_doc）：Requirement: Init install scope selection The init command SHALL support install scope selection for generated artifacts. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-global-install-scope/specs/cli-init/spec.md`\n- **ADDED Requirements**（project_doc）：Requirement: Update install scope selection The update command SHALL support install scope selection for sync operations. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-global-install-scope/specs/cli-update/spec.md`\n- **MODIFIED Requirements**（project_doc）：Requirement: ToolCommandAdapter interface The system SHALL provide install-context-aware command path resolution. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-global-install-scope/specs/command-generation/spec.md`\n- **ADDED Requirements**（project_doc）：Requirement: Install scope field in global config The global config schema SHALL include install scope preference. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-global-install-scope/specs/global-config/spec.md`\n- **Purpose**（project_doc）：Define the install scope model for OpenSpec-generated skills and commands, including scope preference, effective scope resolution, and fallback/error semantics. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-global-install-scope/specs/installation-scope/spec.md`\n- **1. Global Config + Validation**（project_doc）：- 1.1 Add installScope global project to GlobalConfig with explicit global default for newly created configs - 1.2 Update config schema validation and known-key checks to include install scope - 1.3 Add schema-evolution tests ensuring missing installScope in legacy configs resolves to effective project until explicit migration - 1.4 Extend openspec config list output to show install scope and source explicit , new-d… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-global-install-scope/tasks.md`\n- **Why**（project_doc）：We need a faster, more reliable way to manually validate CLI behavior changes like profile/delivery sync, migration behavior, and tool-detection UX. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-qa-smoke-harness/proposal.md`\n- **ADDED Requirements**（project_doc）：Requirement: Makefile QA Entry Point 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-qa-smoke-harness/specs/developer-qa-workflow/spec.md`\n- **Why**（project_doc）：OpenSpec currently assumes command delivery maps directly to command adapters. That assumption does not hold for all tools. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-tool-command-surface-capabilities/proposal.md`\n- **ADDED Requirements**（project_doc）：Requirement: Command surface capability resolution The init command SHALL resolve each selected tool's command surface using explicit metadata first, then deterministic inference. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-tool-command-surface-capabilities/specs/cli-init/spec.md`\n- **ADDED Requirements**（project_doc）：Requirement: Delivery sync by command surface capability The update command SHALL synchronize artifacts using each configured tool's command surface capability. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-tool-command-surface-capabilities/specs/cli-update/spec.md`\n- **0. Stacking Coordination**（project_doc）：- 0.1 Rebase this change on latest main before implementation - 0.2 If simplify-skill-installation is merged first, preserve its profile/delivery model and apply this change as a capability-aware refinement - 0.3 If this change merges first, ensure follow-up rebases do not reintroduce a blanket \"commands = remove all skills\" rule - 0.4 If add-global-install-scope is merged, verify combined scope × delivery × command… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/add-tool-command-surface-capabilities/tasks.md`\n- **Technical Design**（project_doc）：Simplicity First - No version tracking - always update when commanded - Full replacement for OpenSpec-managed files only e.g., openspec/README.md - Marker-based updates for user-owned files e.g., CLAUDE.md - Templates bundled with package - no network required - Minimal error handling - only check prerequisites 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-01-11-add-update-command/design.md`\n- **Add Update Command**（project_doc）：Users need a way to update their local OpenSpec instructions README.md and CLAUDE.md when the OpenSpec package releases new versions with improved AI agent instructions or structural conventions. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-01-11-add-update-command/proposal.md`\n- **Update Command Specification**（project_doc）：As a developer using OpenSpec, I want to update the OpenSpec instructions in my project when new versions are released, so that I can benefit from improvements to AI agent instructions. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-01-11-add-update-command/specs/cli-update/spec.md`\n- **Implementation Tasks**（project_doc）：1. Update Command Implementation - x 1.1 Create src/core/update.ts with UpdateCommand class - x 1.2 Check if openspec directory exists use FileSystemUtils.directoryExists - x 1.3 Write readmeTemplate to openspec/README.md using FileSystemUtils.writeFile - x 1.4 Update CLAUDE.md using markers via FileSystemUtils.updateFileWithMarkers and TemplateManager.getClaudeTemplate - x 1.5 Display ASCII-safe success message: Up… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-01-11-add-update-command/tasks.md`\n- **Add List Command to OpenSpec CLI**（project_doc）：Developers need visibility into available changes and their status to understand the project's evolution and pending work. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-01-13-add-list-command/proposal.md`\n- **List Command Specification**（project_doc）：The openspec list command SHALL provide developers with a quick overview of all active changes in the project, showing their names and task completion status. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-01-13-add-list-command/specs/cli-list/spec.md`\n- **Implementation Tasks**（project_doc）：1. Core Implementation - x 1.1 Create src/core/list.ts with list logic - x 1.1.1 Implement directory scanning exclude archive/ - x 1.1.2 Implement task counting from tasks.md files - x 1.1.3 Format output as simple table - x 1.2 Add list command to CLI in src/cli/index.ts - x 1.2.1 Register openspec list command - x 1.2.2 Connect to list.ts implementation 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-01-13-add-list-command/tasks.md`\n- **Technical Design**（project_doc）：TypeScript Configuration - Strict mode : Enable all strict type checking for better AI understanding - Target : ES2022 for modern JavaScript features - Module : ES2022 for modern ESM support - Module Resolution : Node for proper package resolution - Output : dist/ directory for compiled JavaScript - Source Maps : Enable for debugging TypeScript directly - Declaration Files : Generate .d.ts files for type definitions… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-08-05-initialize-typescript-project/design.md`\n- **Initialize TypeScript Project**（project_doc）：Why The OpenSpec project needs a proper TypeScript foundation to build the minimal CLI that helps developers set up OpenSpec file structures and keep AI instructions updated. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-08-05-initialize-typescript-project/proposal.md`\n- **Tasks**（project_doc）：1. Project Configuration - x 1.1 Create package.json with project metadata, scripts, and ESM configuration - x 1.2 Configure TypeScript with tsconfig.json for ESM output - x 1.3 Add .gitignore for Node.js/TypeScript projects - x 1.4 Set Node.js engine requirement to =20.19.0 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-08-05-initialize-typescript-project/tasks.md`\n- **Technical Design for Init Command**（project_doc）：The init command follows a modular architecture with clear separation of concerns: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-08-06-add-init-command/design.md`\n- **Add Init Command for OpenSpec**（project_doc）：Projects need a simple way to adopt OpenSpec conventions. Currently, users must manually create the directory structure and understand all the conventions, which creates friction for adoption. An init command would enable instant OpenSpec setup with proper structure and guidance. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-08-06-add-init-command/proposal.md`\n- **CLI Init Specification**（project_doc）：The openspec init command SHALL create a complete OpenSpec directory structure in any project, enabling immediate adoption of OpenSpec conventions with support for multiple AI coding assistants. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-08-06-add-init-command/specs/cli-init/spec.md`\n- **Implementation Tasks for Init Command**（project_doc）：Implementation Tasks for Init Command 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-08-06-add-init-command/tasks.md`\n- **Adopt Future State Storage for OpenSpec Changes**（project_doc）：Adopt Future State Storage for OpenSpec Changes 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-08-06-adopt-future-state-storage/proposal.md`\n- **OpenSpec Conventions Specification**（project_doc）：OpenSpec conventions SHALL define how system capabilities are documented, how changes are proposed and tracked, and how specifications evolve over time. This meta-specification serves as the source of truth for OpenSpec's own conventions. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-08-06-adopt-future-state-storage/specs/openspec-conventions/spec.md`\n- **Implementation Tasks**（project_doc）：1. Update Core Documentation - x 1.1 Update openspec/README.md section on \"Creating a Change Proposal\" - x Replace patches/ with specs/ in directory structure - x Update step 3 to show storing complete future state - x Remove diff syntax instructions +/- prefixes 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-08-06-adopt-future-state-storage/tasks.md`\n- **Add Complexity Management Guidelines**（project_doc）：Add Complexity Management Guidelines 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-08-11-add-complexity-guidelines/proposal.md`\n- **Implementation Tasks**（project_doc）：1. Update OpenSpec README - x 1.1 Add \"Start Simple\" section after Core Principle - x 1.2 Add complexity triggers to \"When to Create Change Proposals\" section - x 1.3 Update AI workflow guidance to emphasize minimal implementations 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-08-11-add-complexity-guidelines/tasks.md`\n- **Why**（project_doc）：Why Need a command to archive completed changes to the archive folder with proper date prefixing, following OpenSpec conventions. Currently changes must be manually moved and renamed. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-08-13-add-archive-command/proposal.md`\n- **CLI Archive Command Specification**（project_doc）：Purpose The archive command moves completed changes from the active changes directory to the archive folder with date-based naming, following OpenSpec conventions. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-08-13-add-archive-command/specs/cli-archive/spec.md`\n- **Implementation Tasks**（project_doc）：1. Core Implementation - 1.1 Create src/core/archive.ts with ArchiveCommand class - 1.1.1 Implement change selection interactive if not provided - 1.1.2 Implement incomplete task checking from tasks.md - 1.1.3 Implement confirmation prompt for incomplete tasks - 1.1.4 Implement spec update functionality - 1.1.4.1 Detect specs in change directory - 1.1.4.2 Compare with existing main specs - 1.1.4.3 Display summary of… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-08-13-add-archive-command/tasks.md`\n- **Add Diff Command to OpenSpec CLI**（project_doc）：Developers need to easily view differences between proposed spec changes and current specs without manually comparing files. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-08-13-add-diff-command/proposal.md`\n- **CLI Diff Command Specification**（project_doc）：The openspec diff command provides developers with a visual comparison between proposed spec changes and the current deployed specs. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`openspec/changes/archive/2025-08-13-add-diff-command/specs/cli-diff/spec.md`\n\n## 证据索引\n\n- 共索引 79 条证据。\n\n- **Changesets**（documentation）：This directory is managed by Changesets https://github.com/changesets/changesets . 证据：`.changeset/README.md`\n- **Dev Container Setup**（documentation）：This directory contains the VS Code dev container configuration for OpenSpec development. 证据：`.devcontainer/README.md`\n- **See it in action**（documentation）：! Stars https://img.shields.io/github/stars/Fission-AI/OpenSpec?style=flat-square&label=Stars https://github.com/Fission-AI/OpenSpec/stargazers ! Downloads https://img.shields.io/npm/dm/@fission-ai/openspec?style=flat-square&label=Downloads/mo https://www.npmjs.com/package/@fission-ai/openspec ! Contributors https://img.shields.io/github/contributors/Fission-AI/OpenSpec?style=flat-square&label=Contributors https://github.com/Fission-AI/OpenSpec/graphs/contributors 证据：`README.md`\n- **OpenSpec Scripts**（documentation）：Utility scripts for OpenSpec maintenance and development. 证据：`scripts/README.md`\n- **Github Workflows**（documentation）：Test GitHub Actions workflows locally using act https://nektosact.com/ : 证据：`.github/workflows/README.md`\n- **OpenSpec Instructions**（documentation）：This document provides instructions for AI coding assistants on how to use OpenSpec conventions for spec-driven development. Follow these rules precisely when working on OpenSpec-enabled projects. 证据：`openspec/changes/archive/2025-08-11-add-complexity-guidelines/specs/openspec-docs/README.md`\n- **opencode-command-references**（documentation）：Transform /opsx: to /opsx- in both commands and skills for OpenCode 证据：`openspec/changes/archive/2026-01-30-opencode-command-references/README.md`\n- **add-kimi-cli-skills-only-support**（documentation）：Add Kimi CLI as a supported skills-only tool without a command adapter 证据：`openspec/changes/archive/2026-04-23-add-kimi-cli-skills-only-support/README.md`\n- **Workspace Reimplementation Roadmap**（documentation）：This change is the continuity layer for reimplementing workspace support across multiple sessions and branches. 证据：`openspec/changes/workspace-reimplementation-roadmap/README.md`\n- **Package**（package_manifest）：{ \"name\": \"@fission-ai/openspec\", \"version\": \"1.3.1\", \"description\": \"AI-native system for spec-driven development\", \"keywords\": \"openspec\", \"specs\", \"cli\", \"ai\", \"development\" , \"homepage\": \"https://github.com/Fission-AI/OpenSpec\", \"repository\": { \"type\": \"git\", \"url\": \"https://github.com/Fission-AI/OpenSpec\" }, \"license\": \"MIT\", \"author\": \"OpenSpec Contributors\", \"type\": \"module\", \"publishConfig\": { \"access\": \"public\" }, \"exports\": { \".\": { \"types\": \"./dist/index.d.ts\", \"default\": \"./dist/index.js\" } }, \"bin\": { \"openspec\": \"./bin/openspec.js\" }, \"files\": \"dist\", \"bin\", \"schemas\", \"scripts/postinstall.js\", \"!dist/ / .test.js\", \"!dist/ / tests \", \"!dist/ / .map\" , \"scripts\": { \"lint\": \"esl… 证据：`package.json`\n- **License**（source_file）：Copyright c 2024 OpenSpec Contributors 证据：`LICENSE`\n- **CLI Reference**（documentation）：The OpenSpec CLI openspec provides terminal commands for project setup, validation, status inspection, and management. These commands complement the AI slash commands like /opsx:propose documented in Commands commands.md . 证据：`docs/cli.md`\n- **Commands**（documentation）：This is the reference for OpenSpec's slash commands. These commands are invoked in your AI coding assistant's chat interface e.g., Claude Code, Cursor, Windsurf . 证据：`docs/commands.md`\n- **Concepts**（documentation）：This guide explains the core ideas behind OpenSpec and how they fit together. For practical usage, see Getting Started getting-started.md and Workflows workflows.md . 证据：`docs/concepts.md`\n- **Customization**（documentation）：OpenSpec provides three levels of customization: 证据：`docs/customization.md`\n- **Getting Started**（documentation）：This guide explains how OpenSpec works after you've installed and initialized it. For installation instructions, see the main README ../README.md quick-start . 证据：`docs/getting-started.md`\n- **Installation**（documentation）：- Node.js 20.19.0 or higher — Check your version: node --version 证据：`docs/installation.md`\n- **Migrating to OPSX**（documentation）：This guide helps you transition from the legacy OpenSpec workflow to OPSX. The migration is designed to be smooth—your existing work is preserved, and the new system offers more flexibility. 证据：`docs/migration-guide.md`\n- **Multi-Language Guide**（documentation）：Configure OpenSpec to generate artifacts in languages other than English. 证据：`docs/multi-language.md`\n- **OPSX Workflow**（documentation）：Feedback welcome on Discord https://discord.gg/YctCnvvshC . 证据：`docs/opsx.md`\n- **Supported Tools**（documentation）：OpenSpec works with many AI coding assistants. When you run openspec init , OpenSpec configures selected tools using your active profile/workflow selection and delivery mode. 证据：`docs/supported-tools.md`\n- **Workflows**（documentation）：This guide covers common workflow patterns for OpenSpec and when to use each one. For basic setup, see Getting Started getting-started.md . For command reference, see Commands commands.md . 证据：`docs/workflows.md`\n- **Clarify Bun Node Runtime**（documentation）：--- --- 证据：`.changeset/clarify-bun-node-runtime.md`\n- **New Features**（documentation）：- Kimi CLI support — OpenSpec can now initialize Kimi CLI as a supported skills-only tool using .kimi/skills/ 证据：`.changeset/kind-rings-notice.md`\n- **New Features**（documentation）：- Include the sync workflow in the default core profile so new installs generate /opsx:sync skills and commands by default. 证据：`.changeset/sync-default-core.md`\n- **@fission-ai/openspec**（documentation）：- 995 https://github.com/Fission-AI/OpenSpec/pull/995 d1f3861 https://github.com/Fission-AI/OpenSpec/commit/d1f3861d9ec694cc924b042b5da01963dcf93137 Thanks @TabishB https://github.com/TabishB ! - Bug Fixes 证据：`CHANGELOG.md`\n- **Maintainers**（documentation）：People who maintain and guide OpenSpec. 证据：`MAINTAINERS.md`\n- **OpenSpec**（documentation）：Spec-driven development for AI coding assistants. 证据：`README_OLD.md`\n- **Workspace Reimplementation Direction**（documentation）：Workspace Reimplementation Direction 证据：`WORKSPACE_REIMPLEMENTATION_DIRECTION.md`\n- **Workspace Reimplementation Start Here**（documentation）：Workspace Reimplementation Start Here 证据：`WORKSPACE_REIMPLEMENTATION_START_HERE.md`\n- **OpenSpec Parallel Delta Remediation Plan**（documentation）：OpenSpec Parallel Delta Remediation Plan 证据：`openspec-parallel-merge-plan.md`\n- **Implementation Order and Dependencies**（documentation）：Implementation Order and Dependencies 证据：`openspec/changes/IMPLEMENTATION_ORDER.md`\n- **Add Artifact Regeneration Support**（documentation）：Currently, there is no way to regenerate artifacts in the OPSX workflow: 证据：`openspec/changes/add-artifact-regeneration-support/proposal.md`\n- **Why**（documentation）：Parallel changes often touch the same capabilities and cli-init / cli-update behavior, but today there is no machine-readable way to express sequencing, dependencies, or expected merge order. 证据：`openspec/changes/add-change-stacking-awareness/proposal.md`\n- **ADDED Requirements**（documentation）：Requirement: Stack Metadata Scaffolding Change creation workflows SHALL support optional dependency metadata for new or split changes. 证据：`openspec/changes/add-change-stacking-awareness/specs/change-creation/spec.md`\n- **ADDED Requirements**（documentation）：Requirement: Stack Metadata Model The system SHALL support optional metadata on active changes to express sequencing and decomposition relationships. 证据：`openspec/changes/add-change-stacking-awareness/specs/change-stacking-workflow/spec.md`\n- **ADDED Requirements**（documentation）：Requirement: Stack Planning Commands The change CLI SHALL provide commands for dependency-aware sequencing of active changes. 证据：`openspec/changes/add-change-stacking-awareness/specs/cli-change/spec.md`\n- **ADDED Requirements**（documentation）：Requirement: Stack-Aware Change Planning Conventions OpenSpec conventions SHALL define optional metadata fields for sequencing and decomposition across concurrent changes. 证据：`openspec/changes/add-change-stacking-awareness/specs/openspec-conventions/spec.md`\n- **1. Metadata Model**（documentation）：- 1.1 Add optional stack metadata fields dependsOn , provides , requires , touches , parent to change metadata schema - 1.2 Keep metadata backward compatible for existing changes without new fields - 1.3 Add tests for valid/invalid metadata and schema evolution behavior 证据：`openspec/changes/add-change-stacking-awareness/tasks.md`\n- **Context**（documentation）：OpenSpec today assumes project-local installation for most generated artifacts, with Codex command prompts as the main global exception. This mixed model works, but it is implicit and not user-configurable. 证据：`openspec/changes/add-global-install-scope/design.md`\n- **Why**（documentation）：OpenSpec installation paths are currently inconsistent: 证据：`openspec/changes/add-global-install-scope/proposal.md`\n- **MODIFIED Requirements**（documentation）：Requirement: AIToolOption skillsDir field The AIToolOption interface SHALL include scope support metadata in addition to path metadata. 证据：`openspec/changes/add-global-install-scope/specs/ai-tool-paths/spec.md`\n- **ADDED Requirements**（documentation）：Requirement: Install scope configuration via profile flow The config profile workflow SHALL allow users to configure install scope preference. 证据：`openspec/changes/add-global-install-scope/specs/cli-config/spec.md`\n- **ADDED Requirements**（documentation）：Requirement: Init install scope selection The init command SHALL support install scope selection for generated artifacts. 证据：`openspec/changes/add-global-install-scope/specs/cli-init/spec.md`\n- **ADDED Requirements**（documentation）：Requirement: Update install scope selection The update command SHALL support install scope selection for sync operations. 证据：`openspec/changes/add-global-install-scope/specs/cli-update/spec.md`\n- **MODIFIED Requirements**（documentation）：Requirement: ToolCommandAdapter interface The system SHALL provide install-context-aware command path resolution. 证据：`openspec/changes/add-global-install-scope/specs/command-generation/spec.md`\n- **ADDED Requirements**（documentation）：Requirement: Install scope field in global config The global config schema SHALL include install scope preference. 证据：`openspec/changes/add-global-install-scope/specs/global-config/spec.md`\n- **Purpose**（documentation）：Define the install scope model for OpenSpec-generated skills and commands, including scope preference, effective scope resolution, and fallback/error semantics. 证据：`openspec/changes/add-global-install-scope/specs/installation-scope/spec.md`\n- **1. Global Config + Validation**（documentation）：- 1.1 Add installScope global project to GlobalConfig with explicit global default for newly created configs - 1.2 Update config schema validation and known-key checks to include install scope - 1.3 Add schema-evolution tests ensuring missing installScope in legacy configs resolves to effective project until explicit migration - 1.4 Extend openspec config list output to show install scope and source explicit , new-default , legacy-default 证据：`openspec/changes/add-global-install-scope/tasks.md`\n- **Why**（documentation）：We need a faster, more reliable way to manually validate CLI behavior changes like profile/delivery sync, migration behavior, and tool-detection UX. 证据：`openspec/changes/add-qa-smoke-harness/proposal.md`\n- **ADDED Requirements**（documentation）：Requirement: Makefile QA Entry Point 证据：`openspec/changes/add-qa-smoke-harness/specs/developer-qa-workflow/spec.md`\n- **Why**（documentation）：OpenSpec currently assumes command delivery maps directly to command adapters. That assumption does not hold for all tools. 证据：`openspec/changes/add-tool-command-surface-capabilities/proposal.md`\n- **ADDED Requirements**（documentation）：Requirement: Command surface capability resolution The init command SHALL resolve each selected tool's command surface using explicit metadata first, then deterministic inference. 证据：`openspec/changes/add-tool-command-surface-capabilities/specs/cli-init/spec.md`\n- **ADDED Requirements**（documentation）：Requirement: Delivery sync by command surface capability The update command SHALL synchronize artifacts using each configured tool's command surface capability. 证据：`openspec/changes/add-tool-command-surface-capabilities/specs/cli-update/spec.md`\n- **0. Stacking Coordination**（documentation）：- 0.1 Rebase this change on latest main before implementation - 0.2 If simplify-skill-installation is merged first, preserve its profile/delivery model and apply this change as a capability-aware refinement - 0.3 If this change merges first, ensure follow-up rebases do not reintroduce a blanket \"commands = remove all skills\" rule - 0.4 If add-global-install-scope is merged, verify combined scope × delivery × command-surface behavior remains deterministic 证据：`openspec/changes/add-tool-command-surface-capabilities/tasks.md`\n- **Technical Design**（documentation）：Simplicity First - No version tracking - always update when commanded - Full replacement for OpenSpec-managed files only e.g., openspec/README.md - Marker-based updates for user-owned files e.g., CLAUDE.md - Templates bundled with package - no network required - Minimal error handling - only check prerequisites 证据：`openspec/changes/archive/2025-01-11-add-update-command/design.md`\n- **Add Update Command**（documentation）：Users need a way to update their local OpenSpec instructions README.md and CLAUDE.md when the OpenSpec package releases new versions with improved AI agent instructions or structural conventions. 证据：`openspec/changes/archive/2025-01-11-add-update-command/proposal.md`\n- **Update Command Specification**（documentation）：As a developer using OpenSpec, I want to update the OpenSpec instructions in my project when new versions are released, so that I can benefit from improvements to AI agent instructions. 证据：`openspec/changes/archive/2025-01-11-add-update-command/specs/cli-update/spec.md`\n- **Implementation Tasks**（documentation）：1. Update Command Implementation - x 1.1 Create src/core/update.ts with UpdateCommand class - x 1.2 Check if openspec directory exists use FileSystemUtils.directoryExists - x 1.3 Write readmeTemplate to openspec/README.md using FileSystemUtils.writeFile - x 1.4 Update CLAUDE.md using markers via FileSystemUtils.updateFileWithMarkers and TemplateManager.getClaudeTemplate - x 1.5 Display ASCII-safe success message: Updated OpenSpec instructions 证据：`openspec/changes/archive/2025-01-11-add-update-command/tasks.md`\n- **Add List Command to OpenSpec CLI**（documentation）：Developers need visibility into available changes and their status to understand the project's evolution and pending work. 证据：`openspec/changes/archive/2025-01-13-add-list-command/proposal.md`\n- 其余 19 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`.changeset/README.md`, `.devcontainer/README.md`, `AGENTS.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`.changeset/README.md`, `.devcontainer/README.md`, `AGENTS.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **Introduction to OpenSpec**：importance `high`\n - source_paths: README.md, docs/concepts.md\n- **Getting Started**：importance `high`\n - source_paths: docs/getting-started.md, docs/installation.md, package.json, src/core/init.ts\n- **System Architecture**：importance `high`\n - source_paths: src/index.ts, src/cli/index.ts, src/core/index.ts, src/core/artifact-graph/index.ts, src/core/artifact-graph/types.ts\n- **Slash Commands**：importance `high`\n - source_paths: docs/commands.md, docs/opsx.md, src/core/templates/index.ts, src/core/templates/workflows/apply-change.ts, src/core/templates/workflows/archive-change.ts\n- **Workflows**：importance `high`\n - source_paths: docs/workflows.md, src/core/templates/types.ts, src/core/templates/workflows/propose.ts, src/core/templates/workflows/new-change.ts, src/core/templates/workflows/continue-change.ts\n- **Artifact Graph System**：importance `medium`\n - source_paths: src/core/artifact-graph/graph.ts, src/core/artifact-graph/state.ts, src/core/artifact-graph/resolver.ts, src/core/artifact-graph/schema.ts, src/core/artifact-graph/outputs.ts\n- **Schemas**：importance `high`\n - source_paths: schemas/spec-driven/schema.yaml, schemas/workspace-planning/schema.yaml, src/core/schemas/index.ts, src/core/schemas/base.schema.ts, src/core/schemas/change.schema.ts\n- **Configuration**：importance `high`\n - source_paths: openspec/config.yaml, src/core/config.ts, src/core/config-schema.ts, src/core/global-config.ts, src/core/project-config.ts\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `8498042fe8a738e8ad6facd94a5fc7f5025bf81d`\n- inspected_files: `pnpm-lock.yaml`, `package.json`, `README.md`, `docs/customization.md`, `docs/migration-guide.md`, `docs/concepts.md`, `docs/cli.md`, `docs/opsx.md`, `docs/commands.md`, `docs/getting-started.md`, `docs/installation.md`, `docs/workflows.md`, `docs/multi-language.md`, `docs/supported-tools.md`, `src/index.ts`, `src/cli/index.ts`, `src/prompts/searchable-multi-select.ts`, `src/telemetry/index.ts`, `src/telemetry/config.ts`, `src/ui/welcome-screen.ts`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：/opsx:apply suggests openspec-continue-change which is not installed on core profile\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：/opsx:apply suggests openspec-continue-change which is not installed on core profile\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_41aca88207aa4e70bba9c2ebaef629c7 | https://github.com/Fission-AI/OpenSpec/issues/963 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：Support schema extension or partial overrides to avoid full shadowing of built-in schemas\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Support schema extension or partial overrides to avoid full shadowing of built-in schemas\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_34110f57274440d4bbc5492e3b4f3bee | https://github.com/Fission-AI/OpenSpec/issues/1074 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：open:sync messed up my spec.md files\n\n- Trigger: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：open:sync messed up my spec.md files\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_ef1856d2856b49f5a7ed758bfc4099c8 | https://github.com/Fission-AI/OpenSpec/issues/911 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：Codex generated assets reference unsupported AskUserQuestion/TodoWrite/Task tools\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Codex generated assets reference unsupported AskUserQuestion/TodoWrite/Task tools\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_35b315a2b1a74564be1fb71d1f08359c | https://github.com/Fission-AI/OpenSpec/issues/1103 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：First steps don't work\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：First steps don't work\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_51f62d023b734ba59978cc70908c01c3 | https://github.com/Fission-AI/OpenSpec/issues/820 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：v1.1.0 - Cross-Platform Fixes, Nix Improvements\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.1.0 - Cross-Platform Fixes, Nix Improvements\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_016f567cecd44fbf96ffd635e1ec43bf | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.1.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：v1.3.1 - Path & Telemetry Fixes\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.3.1 - Path & Telemetry Fixes\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_e641868122bb43938d6ff8a83b71e3d3 | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.3.1 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：Incomplete artifacts marked as \"done\" after workflow interruption\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Incomplete artifacts marked as \"done\" after workflow interruption\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_a0677545a17b433ca6e6561c5056ee46 | https://github.com/Fission-AI/OpenSpec/issues/1084 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：OpenCode sync missing\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：OpenCode sync missing\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_0076a9fb05a1443eb3e2a7c9185247e6 | https://github.com/Fission-AI/OpenSpec/issues/1007 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 来源证据：v0.22.0 - Project Configuration\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.22.0 - Project Configuration\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_1a526029491b40e38c20ba075f311169 | https://github.com/Fission-AI/OpenSpec/releases/tag/v0.22.0 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：Fission-AI/OpenSpec\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：/opsx:apply suggests openspec-continue-change which is not installed on core profile（high）：可能阻塞安装或首次运行。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Support schema extension or partial overrides to avoid full shadowing of built-in schemas（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：open:sync messed up my spec.md files（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Codex generated assets reference unsupported AskUserQuestion/TodoWrite/Task tools（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：First steps don't work（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/Fission-AI/OpenSpec 项目说明书\n\n生成时间：2026-05-18 02:52:58 UTC\n\n## 目录\n\n- [Introduction to OpenSpec](#introduction)\n- [Getting Started](#getting-started)\n- [System Architecture](#architecture)\n- [Slash Commands](#slash-commands)\n- [Workflows](#workflows)\n- [Artifact Graph System](#artifact-graph)\n- [Schemas](#schemas)\n- [Configuration](#configuration)\n- [Validation System](#validation-system)\n- [Supported AI Tools](#supported-tools)\n\n\n\n## Introduction to OpenSpec\n\n### 相关页面\n\n相关主题：[Getting Started](#getting-started), [System Architecture](#architecture)\n\n\nRelevant Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n- [CHANGELOG.md](https://github.com/Fission-AI/OpenSpec/blob/main/CHANGELOG.md)\n- [docs/getting-started.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/getting-started.md)\n- [docs/concepts.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/concepts.md)\n- [docs/workflows.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/workflows.md)\n- [docs/commands.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/commands.md)\n- [docs/supported-tools.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/supported-tools.md)\n \n\n# Introduction to OpenSpec\n\nOpenSpec is a lightweight specification framework designed to bring structure and alignment to AI-assisted software development. It establishes a shared understanding between human developers and AI coding assistants before any code is written, reducing unpredictability and improving project organization.\n\n## Purpose and Scope\n\nAI coding assistants are powerful but often unpredictable when project requirements exist only in chat history. OpenSpec adds a lightweight spec layer that ensures human and AI align on specifications before code gets written.\n\nThe framework operates under a core philosophy:\n\n```text\n→ fluid not rigid\n→ iterative not waterfall\n→ easy not complex\n→ built for brownfield not just greenfield\n→ scalable from personal projects to enterprises\n```\n\n**资料来源：** [README.md:1-20]()\n\n## Core Features\n\nOpenSpec provides several key capabilities:\n\n| Feature | Description |\n|---------|-------------|\n| **Agree Before Build** | Human and AI align on specs before code gets written |\n| **Stay Organized** | Each change gets its own folder with proposal, specs, design, and tasks |\n| **Work Fluidly** | Update any artifact anytime, no rigid phase gates |\n| **Tool Integration** | Works with 25+ AI assistants via slash commands |\n\n**资料来源：** [README.md:21-30]()\n\n## Architecture Overview\n\nOpenSpec uses an artifact-guided workflow where changes are organized into structured folders. The system tracks dependencies between artifacts and automatically manages state transitions.\n\n```mermaid\ngraph TD\n A[User Request] --> B[Proposal]\n B --> C[Specs]\n C --> D[Design]\n D --> E[Tasks]\n E --> F[Implementation]\n F --> G[Archive]\n G --> C\n \n H[Config.yaml] --> A\n H --> B\n H --> C\n \n style A fill:#e1f5fe\n style G fill:#c8e6c9\n```\n\n**资料来源：** [CHANGELOG.md:1-30]()\n\n## The Change Structure\n\nEvery change in OpenSpec follows a consistent folder structure:\n\n```\nopenspec/\n├── specs/ # Source-of-truth specifications\n│ └── /\n│ └── spec.md\n├── changes/\n│ ├── / # Active change folder\n│ │ ├── proposal.md # Why and what changes\n│ │ ├── tasks.md # Implementation checklist\n│ │ ├── design.md # Technical decisions (optional)\n│ │ └── specs/\n│ │ └── /\n│ │ └── spec.md # Delta showing additions/modifications\n│ └── archive/ # Completed changes\n│ └── YYYY-MM-DD-/\n└── config.yaml # Project configuration\n```\n\n**资料来源：** [README.md:200-230]()\n\n## Workflow System\n\nOpenSpec supports multiple workflow approaches:\n\n### Standard Workflow\n\nThe traditional linear approach:\n\n1. **Propose** - Create a change proposal that captures spec updates\n2. **Review** - Review the proposal with AI assistant until agreement\n3. **Implement** - Implement tasks that reference agreed specs\n4. **Archive** - Archive the change to merge approved updates back into source specs\n\n### Experimental Workflow\n\nThe new artifact-guided workflow using slash commands:\n\n| Command | Purpose |\n|---------|---------|\n| `/opsx:propose` | Start a new change |\n| `/opsx:new` | Start a new change (alternative) |\n| `/opsx:continue` | Create one artifact at a time (step-through) |\n| `/opsx:ff` | Fast-forward to completion |\n| `/opsx:verify` | Verify artifact integrity |\n| `/opsx:bulk-archive` | Archive multiple changes |\n| `/opsx:onboard` | Initialize OpenSpec in a project |\n\n**资料来源：** [README.md:150-170]()\n\n## Instruction System\n\nOpenSpec dynamically assembles instructions from three layers:\n\n```mermaid\ngraph LR\n A[Context] --> D[Enriched Instruction]\n B[Rules] --> D\n C[Template] --> D\n \n A1[project.yaml] --> A\n B1[Artifact-specific] --> B\n C1[Schema template] --> C\n```\n\n### Context Layer\nProject background from `config.yaml` including tech stack and conventions. Applied to **all artifacts**.\n\n### Rules Layer\nArtifact-specific constraints (e.g., \"propose spike tasks for unknowns\"). Applied only to **matching artifacts**.\n\n### Template Layer\nThe actual structure for the output file, sourced from schemas.\n\n**资料来源：** [CHANGELOG.md:40-70]()\n\n## Supported AI Tools\n\nOpenSpec integrates with 25+ AI coding assistants through slash commands or natural language:\n\n### Native Slash Commands\n\n| Tool | Commands | Configuration Path |\n|------|----------|-------------------|\n| **Claude Code** | `/opsx:propose`, `/opsx:apply`, `/opsx:archive` | Built-in |\n| **Amazon Q Developer** | `@openspec-proposal`, `@openspec-apply`, `@openspec-archive` | `.amazonq/prompts/` |\n| **CodeBuddy Code** | `/opsx:propose`, `/opsx:apply`, `/opsx:archive` | `.codebuddy/commands/` |\n| **Cursor** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.cursor/commands/` |\n| **Roo Code** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.roo/commands/` |\n\n### Workflow-Based Tools\n\n| Tool | Workflow Location |\n|------|-------------------|\n| **Cline** | `.clinerules/workflows/` |\n| **Windsurf** | `.windsurf/workflows/` |\n| **Kilo Code** | `.kilocode/workflows/` |\n\n**资料来源：** [README.md:80-120]()\n\n## Installation and Setup\n\n### Prerequisites\n\n- **Node.js >= 20.19.0** - Check with `node --version`\n\n### Installation Methods\n\n**Option A: npm (Global)**\n\n```bash\nnpm install -g @fission-ai/openspec@latest\n```\n\n**Option B: nix (NixOS)**\n\n```bash\nnix run github:Fission-AI/OpenSpec -- init\n```\n\nOr install to profile:\n\n```bash\nnix profile install github:Fission-AI/OpenSpec\n```\n\n**资料来源：** [README.md:50-80]()\n\n### Quick Start\n\n```bash\n# Navigate to project\ncd your-project\n\n# Initialize OpenSpec\nopenspec init\n\n# Start a new change\n/opsx:propose \n\n# Or use CLI directly\nopenspec new \n```\n\n**资料来源：** [README.md:40-55]()\n\n## Command Reference\n\n| Command | Description |\n|---------|-------------|\n| `openspec list` | View active change folders |\n| `openspec view` | Interactive dashboard of specs and changes |\n| `openspec show ` | Display change details |\n| `openspec validate ` | Check spec formatting and structure |\n| `openspec archive [--yes]` | Archive completed change |\n| `openspec config profile` | Select workflow profile |\n\n**资料来源：** [README.md:180-200]()\n\n## Telemetry\n\nOpenSpec collects anonymous usage statistics to understand usage patterns:\n\n- **Collected:** Command names and version only\n- **NOT collected:** Arguments, paths, content, or PII\n- **Auto-disabled:** In CI environments\n\n**Opt-out:**\n\n```bash\nexport OPENSPEC_TELEMETRY=0\n# or\nexport DO_NOT_TRACK=1\n```\n\n**资料来源：** [README.md:220-240]()\n\n## Contributing to OpenSpec\n\n```bash\n# Install dependencies\npnpm install\n\n# Build\npnpm run build\n\n# Test\npnpm test\n\n# Develop CLI locally\npnpm run dev\npnpm run dev:cli\n```\n\n**Commit convention:**\n\n```text\ntype(scope): subject\n```\n\n**资料来源：** [README.md:250-260]()\n\n## License\n\nOpenSpec is released under the **MIT License**.\n\n---\n\n\n\n## Getting Started\n\n### 相关页面\n\n相关主题：[Introduction to OpenSpec](#introduction), [Slash Commands](#slash-commands)\n\n\nRelevant Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n- [docs/getting-started.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/getting-started.md)\n- [docs/workflows.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/workflows.md)\n- [docs/cli.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/cli.md)\n- [docs/commands.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/commands.md)\n- [docs/installation.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/installation.md)\n- [openspec/changes/archive/2025-12-28-add-instruction-loader/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-12-28-add-instruction-loader/design.md)\n \n\n# Getting Started\n\n## Overview\n\nOpenSpec is a lightweight specification framework designed to help development teams align on requirements before writing code. It provides a structured approach to capturing proposals, specifications, designs, and implementation tasks in organized change folders that integrate seamlessly with AI coding assistants.\n\nThe \"Getting Started\" documentation serves as the entry point for new users, covering prerequisites, installation methods, project initialization, and the fundamental workflows that define how OpenSpec operates. This guide ensures users can quickly set up OpenSpec in their development environment and begin using its artifact-guided workflow for managing changes systematically.\n\n## Prerequisites\n\n### System Requirements\n\nOpenSpec has specific version requirements that must be met before installation:\n\n| Requirement | Minimum Version | Notes |\n|------------|-----------------|-------|\n| Node.js | 20.19.0 or higher | Check with `node --version` |\n| Package Managers | npm, pnpm, yarn, bun, or nix | Alternative installation options available |\n\n资料来源：[README.md:1]()\n\nTo verify your Node.js installation, run:\n\n```bash\nnode --version\n```\n\nIf the version is below 20.19.0, you must upgrade Node.js before proceeding with OpenSpec installation.\n\n## Installation\n\nOpenSpec can be installed through multiple methods depending on your development environment and preferences.\n\n### Method 1: npm (Global Installation)\n\nThe standard installation method uses npm to install OpenSpec globally:\n\n```bash\nnpm install -g @fission-ai/openspec@latest\n```\n\nAfter installation, verify the installation by checking the version:\n\n```bash\nopenspec --version\n```\n\n资料来源：[README.md:1]()\n\n### Method 2: Nix Package Manager\n\nFor NixOS or Nix package manager users, OpenSpec can be run directly without explicit installation:\n\n```bash\nnix run github:Fission-AI/OpenSpec -- init\n```\n\nAlternatively, install to your user profile:\n\n```bash\nnix profile install github:Fission-AI/OpenSpec\n```\n\nOr add to your Nix configuration for persistent access.\n\n### Method 3: Development Installation\n\nFor contributors or those who want to work with the source code:\n\n```bash\n# Clone the repository\ngit clone https://github.com/Fission-AI/OpenSpec.git\ncd OpenSpec\n\n# Install dependencies\npnpm install\n\n# Build the project\npnpm run build\n\n# Run tests\npnpm test\n\n# Develop CLI locally\npnpm run dev\n```\n\n资料来源：[README.md:1]()\n\n## Project Initialization\n\nOnce OpenSpec is installed, navigate to your project directory and initialize the OpenSpec structure:\n\n```bash\ncd your-project\nopenspec init\n```\n\nThe initialization process creates the necessary directory structure for OpenSpec artifacts:\n\n```text\nopenspec/\n├── config.yaml # Project configuration and context\n├── specs/ # Schema definitions and templates\n└── changes/ # Individual change proposals\n```\n\n### What `openspec init` Creates\n\n| Artifact | Purpose |\n|----------|---------|\n| `config.yaml` | Project context, tech stack, conventions |\n| `openspec/schemas/` | Schema definitions (spec-driven, etc.) |\n| `openspec/changes/` | Directory for change proposals |\n\n### Legacy Cleanup\n\nWhen running `openspec init` in an existing project that previously used OpenSpec, the initialization process detects and handles legacy artifacts:\n\n- Old slash command directories (`.claude/commands/openspec/`)\n- Config files with OpenSpec markers (`CLAUDE.md`, `.cursorrules`, `.windsurfrules`)\n- Legacy `openspec/AGENTS.md` files\n\nUsers are prompted for confirmation before removing these legacy artifacts.\n\n资料来源：[README.md:1]()\n资料来源：[openspec/changes/archive/2026-02-17-merge-init-experimental/design.md:1]()\n\n## Core Workflow: Artifact-Guided Approach\n\nOpenSpec uses an experimental artifact-guided workflow centered on creating structured changes. The workflow revolves around four key artifacts that capture different aspects of a change:\n\n```mermaid\ngraph TD\n A[Propose Change] --> B[Create Proposal]\n B --> C[Write Specs]\n C --> D[Design Solution]\n D --> E[Define Tasks]\n E --> F[Implement]\n F --> G[Verify]\n G --> H[Archive]\n \n I[Iterate on Any Artifact] -.-> A\n I -.-> B\n I -.-> C\n I -.-> D\n I -.-> E\n```\n\n### The Four Core Artifacts\n\n| Artifact | Purpose | Generated By |\n|----------|---------|--------------|\n| **Proposal** | Why the change is needed, what's changing | `/opsx:propose` |\n| **Specs** | Requirements and acceptance scenarios | Sequential creation |\n| **Design** | Technical approach and architecture | Sequential creation |\n| **Tasks** | Implementation checklist | Sequential creation |\n\nEach change folder under `openspec/changes//` contains these artifacts organized in a predictable structure.\n\n资料来源：[README.md:1]()\n\n## Supported AI Coding Assistants\n\nOpenSpec integrates with over 25 AI coding assistants through slash commands. The supported tools include:\n\n| Tool Category | Examples |\n|--------------|----------|\n| Claude Code | `/openspec/proposal`, `/openspec/apply`, `/openspec/archive` |\n| Cursor | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |\n| CodeBuddy | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |\n| Codex | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |\n| RooCode | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |\n| Kilo Code | `.kilocode/workflows/` with `/openspec-proposal.md` |\n| Windsurf | `.windsurf/workflows/` with `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |\n| Continue | `.continue/` with custom configuration |\n| Cline | `CLAUDE.md` compatible |\n| Other | Works with natural language requests |\n\nTo check if your tool is supported, view the [full list of supported tools](docs/supported-tools.md).\n\n资料来源：[README.md:1]()\n资料来源 [docs/supported-tools.md]()\n\n## Essential Commands\n\n### Quick Command Reference\n\n| Command | Description |\n|---------|-------------|\n| `openspec list` | View active change folders |\n| `openspec view` | Interactive dashboard of specs and changes |\n| `openspec show ` | Display change details |\n| `openspec update` | Refresh slash command files |\n| `openspec config profile` | Switch between standard and experimental workflows |\n| `openspec archive ` | Archive a completed change |\n\n资料来源：[README.md:1]()\n资料来源 [docs/cli.md]()\n\n## The Experimental Workflow\n\nOpenSpec offers an experimental artifact-guided workflow that provides a more flexible, iterative approach to managing changes.\n\n### Enabling Experimental Features\n\n```bash\nopenspec experimental\n```\n\n### Experimental Slash Commands\n\n| Command | Purpose |\n|---------|---------|\n| `/opsx:propose` | Start a new change |\n| `/opsx:new` | Create a new change folder |\n| `/opsx:continue` | Create the next artifact in sequence |\n| `/opsx:ff` | Fast-forward through completed tasks |\n| `/opsx:verify` | Verify implementation against specs |\n| `/opsx:bulk-archive` | Archive multiple completed changes |\n| `/opsx:onboard` | Set up OpenSpec in a new project |\n| `/opsx:explore` | Think through ideas before committing |\n\n资料来源 [docs/opsx.md]()\n\n### Workflow Comparison\n\n| Aspect | Standard Workflow | Experimental Workflow |\n|--------|------------------|----------------------|\n| Artifact creation | Manual/guided | Sequential with dependencies |\n| State tracking | File-based | Dynamic artifact graph |\n| Flexibility | Phase-locked | Action-based |\n| Iteration | Limited | Full iteration support |\n\n## Telemetry\n\nOpenSpec collects anonymous usage statistics to understand usage patterns. Only command names and version numbers are collected—no arguments, paths, content, or personally identifiable information.\n\n**To opt out:**\n\n```bash\nexport OPENSPEC_TELEMETRY=0\n```\n\nOr set the `DO_NOT_TRACK` environment variable:\n\n```bash\nexport DO_NOT_TRACK=1\n```\n\nTelemetry is automatically disabled in CI environments.\n\n资料来源：[README.md:1]()\n\n## Next Steps\n\nAfter completing the initial setup:\n\n1. **Review Documentation**\n - [Workflows](docs/workflows.md) - Combos and patterns\n - [Commands](docs/commands.md) - Slash commands & skills\n - [Concepts](docs/concepts.md) - How OpenSpec fits together\n\n2. **Try the Workflow**\n - Create your first proposal using `/opsx:propose`\n - Work through the artifact sequence\n - Archive and review the result\n\n3. **Configure Your Tool**\n - Set up slash commands for your preferred AI assistant\n - Run `openspec update` to refresh command files\n\n4. **Explore Advanced Features**\n - Multi-language support: [docs/multi-language.md](docs/multi-language.md)\n - Customization options: [docs/customization.md](docs/customization.md)\n - Community schemas: Browse the catalog in customization docs\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| Node.js version too low | Upgrade to 20.19.0 or higher |\n| Command not found | Verify installation with `openspec --version` |\n| Legacy artifacts remain | Run `openspec init` with `--force` flag |\n| Tool not responding | Check supported tools list and use natural language |\n\n### Getting Help\n\n- Join the [OpenSpec Discord](https://discord.gg/YctCnvvshC) for questions\n- Follow [@0xTab on X](https://x.com/0xTab) for updates\n- Review archived changes in `openspec/changes/archive/` for examples\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Introduction to OpenSpec](#introduction), [Artifact Graph System](#artifact-graph), [Workflows](#workflows)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [openspec/changes/archive/2026-02-17-project-config/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-config/design.md)\n- [openspec/changes/archive/2025-12-28-add-instruction-loader/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-12-28-add-instruction-loader/design.md)\n- [openspec/changes/archive/2026-02-17-project-local-schemas/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-local-schemas/design.md)\n- [schemas/spec-driven/schema.yaml](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/schema.yaml)\n- [openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md)\n- [openspec/changes/archive/2025-08-06-add-init-command/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-08-06-add-init-command/design.md)\n \n\n# System Architecture\n\nOpenSpec is a lightweight specification framework designed to add a spec layer between human-AI alignment and code implementation. The system architecture enables teams to agree on what to build before any code is written, maintaining organization through structured change folders and dynamic instruction generation.\n\n## Architecture Overview\n\nOpenSpec follows a modular architecture with clear separation between CLI interface, core business logic, and artifact management. The framework is designed to be tool-agnostic, supporting 25+ AI assistants through slash commands and natural language processing.\n\n```mermaid\ngraph TD\n subgraph \"CLI Layer\"\n CLI[CLI Entry Point]\n Commands[Slash Commands]\n end\n \n subgraph \"Core Layer\"\n Config[Project Config]\n Schemas[Schema System]\n Artifacts[Artifact Graph]\n Instructions[Instruction Loader]\n end\n \n subgraph \"Change Management\"\n Changes[Change Folders]\n Proposals[Proposals]\n Specs[Specs]\n Designs[Designs]\n Tasks[Tasks]\n end\n \n CLI --> Commands\n Commands --> Artifacts\n Artifacts --> Instructions\n Instructions --> Config\n Instructions --> Schemas\n Artifacts --> Changes\n Changes --> Proposals\n Changes --> Specs\n Changes --> Designs\n Changes --> Tasks\n```\n\n## Core Components\n\n### CLI Interface\n\nThe CLI serves as the entry point for all OpenSpec operations. It handles initialization, change management, and command execution across supported tools.\n\n| Command | Purpose |\n|---------|---------|\n| `openspec init` | Initialize OpenSpec in a project directory |\n| `openspec update` | Refresh generated instruction files |\n| `openspec list` | View active change folders |\n| `openspec show ` | Display change details |\n| `openspec archive ` | Archive completed changes |\n\n资料来源：[openspec/changes/archive/2025-08-06-add-init-command/design.md:1-50]()\n\n### Schema System\n\nSchemas define the workflow structure and artifact templates for OpenSpec changes. The system supports three schema sources:\n\n| Source | Path | Priority |\n|--------|------|----------|\n| Project | `openspec/schemas//` | Highest |\n| User | `~/.local/share/openspec/schemas//` | Middle |\n| Package | Built-in `@fission-ai/openspec` | Lowest |\n\n资料来源：[openspec/changes/archive/2026-02-17-project-local-schemas/design.md:1-30]()\n\n**Schema Resolution Order:**\n1. CLI `--schema` flag (explicit override)\n2. `.openspec.yaml` in change directory (change-specific binding)\n3. `openspec/config.yaml` schema field (project default)\n4. `\"spec-driven\"` (hardcoded fallback)\n\nThe default `spec-driven` schema includes artifacts: proposal, specs, design, and tasks.\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md:1-50]()\n\n## Artifact Graph System\n\nThe artifact graph tracks dependencies between different artifacts and manages their creation state. This system replaces the old phase-locked workflow with a flexible action-based model.\n\n### Artifact Types\n\n| Artifact | Generates | Dependencies |\n|----------|-----------|--------------|\n| proposal | proposal.md | None |\n| specs | specs/*.md | proposal |\n| design | design.md | proposal |\n| tasks | tasks.md | specs, design |\n\n### Instruction Loading\n\nInstructions are dynamically assembled from three layers:\n\n```mermaid\ngraph LR\n A[Context] --> D[Enriched Instruction]\n B[Rules] --> D\n C[Template] --> D\n \n subgraph \"Instruction Components\"\n A\n B\n C\n end\n```\n\n资料来源：[openspec/changes/archive/2025-12-28-add-instruction-loader/design.md:1-30]()\n\n**Instruction Structure:**\n\n```xml\n\n[Project context from config.yaml]\n\n\n\n- Rule 1 for specific artifact\n- Rule 2 for specific artifact\n\n\n\n[Schema's specs template]\n\n```\n\nRules only appear for the **specific artifact** they're configured for. Artifacts without rules (e.g., design, tasks) don't get a `` section.\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md:50-100]()\n\n## Project Configuration\n\nProject configuration is stored in `openspec/config.yaml` and provides shared context and rules across the entire project.\n\n### Configuration Structure\n\n```yaml\ncontext: |\n Tech stack: TypeScript, React\n Key conventions: ...\n\nschema: spec-driven\n\nrules:\n proposal:\n - Include rollback plan\n specs:\n - Use Given/When/Then format for scenarios\n```\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md:100-150]()\n\n### Design Decisions\n\n1. **Config file location**: `openspec/config.yaml` in project root\n - Mirrors structure used by other tools (e.g., `.github/`)\n - Keeps OpenSpec-related files under one directory\n\n2. **XML tags vs Markdown sections**: Use XML-style tags `` and ``\n - Clear delimiters that don't conflict with Markdown\n - Agents can easily parse structure\n\n3. **Rules validation**: Warn on unknown artifact IDs, don't error\n - Future-proof for new artifact types\n - Non-breaking change for existing configs\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md:150-200]()\n\n## Command Workflow\n\n### Modern Workflow (opsx)\n\nThe new artifact-guided workflow provides flexible action-based interactions:\n\n| Command | What it does |\n|---------|--------------|\n| `/opsx:propose` | Start a new change with proposal |\n| `/opsx:continue` | Create one artifact at a time |\n| `/opsx:ff` | Fast-forward to next ready artifact |\n| `/opsx:verify` | Verify specs and update tasks |\n| `/opsx:bulk-archive` | Archive multiple changes |\n| `/opsx:onboard` | Initialize project for OpenSpec |\n\n资料来源：[README.md:1-50]()\n\n### Legacy Commands\n\nThe legacy slash commands have been removed:\n\n- `/openspec:proposal` - **Removed**\n- `/openspec:apply` - **Removed**\n- `/openspec:archive` - **Removed**\n\nTool-specific instruction files (`CLAUDE.md`, `.cursorrules`, `AGENTS.md`, `project.md`) are no longer generated.\n\n资料来源：[CHANGELOG.md:1-30]()\n\n## Change Lifecycle\n\n```mermaid\ngraph TD\n A[Create Change] --> B[Write Proposal]\n B --> C[Create Specs]\n C --> D[Write Design]\n D --> E[Implement Tasks]\n E --> F[Archive Change]\n \n G[Explore Ideas] -.-> A\n \n style A fill:#e1f5fe\n style F fill:#fff3e0\n```\n\n### Change Directory Structure\n\n```\nopenspec/\n├── config.yaml # Project configuration\n├── schemas/ # Project-local schemas\n│ └── /\n│ └── templates/\n└── changes/\n ├── /\n │ ├── proposal.md\n │ ├── specs/\n │ │ └── *.md\n │ ├── design.md\n │ ├── tasks.md\n │ └── .openspec.yaml\n └── archive/\n └── -/\n```\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:1-30]()\n\n## Data Flow Architecture\n\n### Instruction Generation Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant CLI\n participant Config\n participant Schema\n participant Loader\n participant Output\n \n User->>CLI: openspec instructions \n CLI->>Config: readProjectConfig()\n Config-->>CLI: context + rules\n CLI->>Schema: resolveSchemaForChange()\n Schema-->>CLI: schema name\n CLI->>Loader: loadInstructions(change, artifact)\n Loader->>Schema: getTemplate(artifact)\n Schema-->>Loader: baseInstructions\n Loader->>Config: getRulesForArtifact(artifact)\n Config-->>Loader: artifactRules\n Loader->>Output: enrichInstruction(context, rules, template)\n Output-->>User: Enriched instruction with XML sections\n```\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md:200-250]()\n\n### Schema Loading Priority\n\nWhen loading schemas, the system checks multiple locations in order:\n\n```mermaid\ngraph TD\n A[Schema Request] --> B{Project schemas dir?}\n B -->|Yes| C[Return project-local schema]\n B -->|No| D{User schemas dir?}\n D -->|Yes| E[Return user schema]\n D -->|No| F[Return package schema]\n \n C --> G[Schema found]\n E --> G\n F --> G\n```\n\n资料来源：[openspec/changes/archive/2026-02-17-project-local-schemas/design.md:50-80]()\n\n## Extensibility Points\n\n### Slash Command Configuration\n\nSlash commands are managed through a `SlashCommandConfigurator` that handles multiple files per tool:\n\n- `getTargets()`: Expose targets with path and kind\n- `generateAll(projectPath, openspecDir)`: For init\n- `updateExisting(projectPath, openspecDir)`: For update\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:50-80]()\n\n### Template System\n\nTemplates are brief, actionable, and sourced from `openspec/README.md`. Each command body includes:\n\n- Guardrails: Ask 1-2 clarifying questions if needed\n- Step list tailored to workflow stage\n- Pointers to troubleshooting tips\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:30-50]()\n\n## Security Considerations\n\nThe implementation includes several security measures:\n\n| Concern | Mitigation |\n|---------|------------|\n| Path Traversal | Sanitize all user-provided paths |\n| File Permissions | Check write permissions before operations |\n| Existing Files | Never overwrite without explicit `--force` flag |\n| Template Injection | Sanitize user inputs in templates |\n\n资料来源：[openspec/changes/archive/2025-08-06-add-init-command/design.md:50-70]()\n\n## Performance and Caching\n\nProject config is read multiple times during a single command execution:\n\n1. **Schema resolution** - To know which schema to use\n2. **Instruction loading** - To inject context and rules\n\nRules are validated lazily during instruction loading (not at config load time) because:\n- Schema isn't known at config load time (circular dependency)\n- Warnings shown when user actually uses the feature (better UX)\n- Validation warnings cached per session to avoid spam\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md:250-280]()\n\n## Technology Stack\n\n| Component | Technology |\n|-----------|------------|\n| Runtime | Node.js 20.19.0+ |\n| Package Manager | npm, pnpm, yarn, bun, nix |\n| License | MIT |\n| Package | `@fission-ai/openspec` |\n\n资料来源：[README.md:50-80]()\n\n---\n\n\n\n## Slash Commands\n\n### 相关页面\n\n相关主题：[Workflows](#workflows), [Getting Started](#getting-started), [Supported AI Tools](#supported-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/commands.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/commands.md)\n- [docs/opsx.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/opsx.md)\n- [README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n- [openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md)\n- [openspec/changes/archive/2025-09-29-add-slash-command-support/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/design.md)\n- [openspec/changes/archive/2025-10-14-add-codex-slash-command-support/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-10-14-add-codex-slash-command-support/proposal.md)\n \n\n# Slash Commands\n\nSlash Commands provide a convenient shorthand mechanism for invoking OpenSpec workflows directly from AI coding assistants. Instead of typing verbose natural language instructions, users can trigger specific OpenSpec actions through a single slash command invocation, streamlining the specification-driven development workflow.\n\n## Overview\n\nOpenSpec integrates with over 20 AI coding assistants through native slash command support. These commands serve as shortcuts that invoke predefined workflow templates, allowing AI assistants to execute OpenSpec operations without requiring manual CLI invocation.\n\nThe slash command system is built on two fundamental principles:\n\n1. **Centralized Templates**: Command bodies are defined once and reused across all supported tools, ensuring consistency while allowing minimal per-tool adaptations.\n2. **Per-Tool Organization**: Each AI assistant receives its commands in the format and location that tool natively recognizes.\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:1-20]()\n\n## Supported Tools and Command Formats\n\nDifferent AI coding assistants use varying conventions for slash command naming and organization. The following table summarizes the supported tools and their respective command formats.\n\n| Tool | Commands | Storage Location |\n|------|----------|------------------|\n| **Claude Code** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` | `.claude/commands/openspec/` |\n| **Cursor** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.cursor/commands/` |\n| **Amazon Q Developer** | `@openspec-proposal`, `@openspec-apply`, `@openspec-archive` | `.amazonq/prompts/` |\n| **CodeBuddy Code** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` | `.codebuddy/commands/` |\n| **Antigravity** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.agent/workflows/` |\n| **Auggie** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.augment/commands/` |\n| **Roo Code** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.roo/commands/` |\n| **Windsurf** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.windsurf/workflows/` |\n| **Cline** | Workflows with `openspec-*` prefix | `.clinerules/workflows/` |\n\n资料来源：[README.md:1-80]()\n\n## Core Commands\n\nOpenSpec defines three primary slash commands that cover the essential workflow stages.\n\n### Proposal Command\n\nThe proposal command initiates a new change specification. When invoked, the AI assistant creates a dedicated change folder with the necessary artifact structure.\n\n```\nYou: /openspec:propose add-dark-mode\nAI: Created openspec/changes/add-dark-mode/\n ✓ proposal.md — why we're doing this, what's changing\n ✓ specs/ — requirements and scenarios\n ✓ design.md — technical approach\n ✓ tasks.md — implementation checklist\n Ready for implementation!\n```\n\n资料来源：[README.md:1-30]()\n\n### Apply Command\n\nThe apply command transitions the workflow from specification to implementation. It reads the tasks from the change folder and executes them in sequence, marking each task as complete.\n\n```\nYou: /opsx:apply\nAI: Implementing tasks...\n ✓ 1.1 Add theme context provider\n ✓ 1.2 Create toggle component\n ✓ 2.1 Add CSS variables\n ✓ 2.2 Wire up localStorage\n All tasks complete!\n```\n\n资料来源：[README.md:1-30]()\n\n### Archive Command\n\nThe archive command finalizes a completed change by moving it to the archive directory and updating the source-of-truth specifications.\n\n```\nYou: /openspec:archive\nAI: Archived to openspec/changes/archive/2025-01-23-add-dark-mode/\n Specs updated. Ready for the next feature.\n```\n\n资料来源：[README.md:1-30]()\n\n## Command File Structure\n\n### File Format and Metadata\n\nSlash command files are stored as Markdown with optional YAML frontmatter for tool-specific metadata. The frontmatter, when supported, includes fields such as `name`, `description`, and `category` or `tags`.\n\n```yaml\n---\nname: openspec-proposal\ndescription: Create a new OpenSpec change proposal\ncategory: OpenSpec\n---\n\n...command body content...\n\n```\n\n### Marker Placement Rules\n\nThe OpenSpec system uses marker comments (`` and ``) to delineate command bodies. These markers must adhere to strict placement rules:\n\n| Rule | Description |\n|------|-------------|\n| **Outside Frontmatter** | Markers must never appear inside YAML frontmatter |\n| **Body Delimitation** | Markers wrap only the visible command body content |\n| **Recovery Behavior** | Missing or duplicated markers trigger specific recovery behaviors |\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:30-45]()\n\n### Naming Consistency\n\nTo ensure predictable behavior across tools, the following naming elements must remain aligned:\n\n| Element | Example |\n|---------|---------|\n| Visible Slash Name | `proposal`, `apply`, `archive` |\n| File Name | `proposal.md`, `apply.md`, `archive.md` |\n| Frontmatter `name`/`id` | `id: openspec-proposal` |\n\nThis alignment prevents user confusion and ensures the AI assistant can correctly invoke commands regardless of the tool being used.\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/design.md:50-70]()\n\n## Architecture\n\n### SlashCommandConfigurator\n\nThe `SlashCommandConfigurator` is the core component responsible for managing slash command files across multiple tools. It abstracts the differences between tool-specific command formats and provides a unified interface for command generation and updates.\n\n```typescript\ninterface SlashCommandConfigurator {\n getTargets(): Array<{\n path: string;\n kind: 'slash';\n id: string;\n }>;\n \n generateAll(projectPath: string, openspecDir: string): void;\n updateExisting(projectPath: string, openspecDir: string): void;\n}\n```\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/design.md:80-95]()\n\n### Design Principles\n\nThe architecture follows several key principles that guide slash command implementation across all supported tools.\n\n```mermaid\ngraph TD\n A[Centralized Template Definition] --> B[Tool-Specific Adapter]\n B --> C[Claude Code Commands]\n B --> D[Cursor Commands]\n B --> E[Amazon Q Commands]\n B --> F[Other Tool Commands]\n \n G[Init Command] --> H[generateAll]\n G --> I[Creates All Tool Directories]\n \n J[Update Command] --> K[updateExisting]\n J --> L[Refreshes Only Existing Files]\n \n style A fill:#e1f5fe\n style G fill:#fff3e0\n style J fill:#fff3e0\n```\n\n1. **Centralized Templates**: Command bodies are defined once in shared template files and applied across all tools with minimal per-tool wrappers.\n\n2. **Per-File Refresh on Update**: During `openspec update`, the system refreshes only existing slash command files on a per-file basis. It does not create missing files or add support for new tools.\n\n3. **Tool-Specific Directories**: Each AI assistant receives commands stored in its native configuration directory structure.\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:60-75]()\n\n## Command Templates\n\n### Template Content Structure\n\nEach slash command template contains several key sections that guide the AI assistant's behavior.\n\n| Section | Purpose |\n|---------|---------|\n| **Guardrails** | 1-2 clarifying questions if needed; minimal complexity rules; tool usage preferences |\n| **Step List** | Tailored workflow steps for the specific command stage |\n| **Pointers** | References to `openspec show`, `openspec list`, and troubleshooting tips |\n\n### Claude Code Naming Convention\n\nClaude Code uses namespacing within the slash command itself for better readability and natural grouping:\n\n```\n/openspec/proposal\n/openspec/apply\n/openspec/archive\n```\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/design.md:20-35]()\n\n### Other Tools Convention\n\nMost other tools use a flat naming convention with an `openspec-` prefix:\n\n```\n/openspec-proposal\n/openspec-apply\n/openspec-archive\n```\n\nGrouping is achieved through category metadata where supported (e.g., `category: OpenSpec`).\n\n## Initialization and Updates\n\n### Init Command Behavior\n\nWhen running `openspec init`, the system creates slash command directories for all supported tools:\n\n| Tool | Directory Created |\n|------|-------------------|\n| Claude Code | `.claude/commands/openspec/` |\n| Cursor | `.cursor/commands/` |\n| Amazon Q | `.amazonq/prompts/` |\n| Cline | `.clinerules/workflows/` |\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:25-30]()\n\n### Update Command Behavior\n\nThe `openspec update` command implements a conservative update strategy:\n\n1. **Detection Phase**: Identify which tools already have slash command files installed\n2. **Refresh Phase**: Update only the files that exist, refreshing both frontmatter and body content\n3. **Preservation Phase**: Do not create missing files or add support for tools not already present\n\n```mermaid\ngraph LR\n A[openspec update] --> B{Detect Existing Tools}\n B --> C[Tool A: 2 files exist]\n B --> D[Tool B: 0 files exist]\n \n C --> E[Refresh Tool A Files]\n D --> F[Skip Tool B]\n \n E --> G[Update Frontmatter + Body]\n F --> H[No Changes]\n \n style E fill:#c8e6c9\n style F fill:#ffcdd2\n```\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/design.md:100-120]()\n\n### Migration Handling\n\nWhen updating from legacy versions, the system handles backward compatibility:\n\n- **Old slash command directories** (`.claude/commands/openspec/`): The entire directory may be removed during cleanup\n- **Config files with markers**: Markers are removed; files are deleted if empty afterward\n- **Migration hints**: Users are informed about manual migration steps when needed\n\n资料来源：[openspec/changes/archive/2026-02-17-merge-init-experimental/design.md:30-50]()\n\n## Testing Strategy\n\nThe slash command system employs a comprehensive testing approach to ensure reliability across all supported tools.\n\n### Golden Snapshots\n\nGenerated files are validated against expected outputs for each tool:\n\n- Frontmatter structure and content\n- Marker placement (never inside frontmatter)\n- Body content matches centralized templates\n\n### Partial Presence Tests\n\nWhen only some files exist, the update behavior is tested:\n\n```typescript\n// If 1-2 files exist, update should only refresh those files\n// and should not create missing files\ntest('update refreshes only existing files', async () => {\n await createPartialSetup();\n await runUpdate();\n expect(existingFiles).toHaveUpdatedContent();\n expect(missingFiles).toBeUndefined();\n});\n```\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:100-115]()\n\n### Marker Placement Tests\n\nSpecific tests ensure markers never appear inside frontmatter and cover recovery behavior for missing or duplicated markers.\n\n### Logging Tests\n\nUpdate operations report per-file status, enabling verification that each tool's files are processed correctly.\n\n## Additional Commands (Opsx Workflow)\n\nBeyond the core three commands, the `/opsx` prefix provides access to an extended experimental workflow:\n\n| Command | Purpose |\n|---------|---------|\n| `/opsx:explore` | Explore ideas before committing to a change |\n| `/opsx:new` | Start a new change with a specific artifact structure |\n| `/opsx:continue` | Create artifacts one at a time (step-through mode) |\n| `/opsx:ff` | Fast-forward through completed tasks |\n| `/opsx:verify` | Verify artifact completeness and dependencies |\n| `/opsx:bulk-archive` | Archive multiple changes at once |\n| `/opsx:onboard` | Onboard new team members to the project |\n\n资料来源：[README.md:1-30]()\n\nTo enable these commands, run:\n\n```bash\nopenspec experimental\n```\n\n资料来源：[docs/opsx.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/opsx.md)\n\n## Tool-Specific Implementations\n\n### Claude Code\n\nClaude Code stores commands in nested directories with namespaced slash names:\n\n```\n.claude/commands/openspec/\n├── proposal.md\n├── apply.md\n└── archive.md\n```\n\nInvocation: `/openspec:proposal`, `/openspec:apply`, `/openspec:archive`\n\n### Cursor\n\nCursor uses flat naming with a prefix:\n\n```\n.cursor/commands/\n├── openspec-proposal.md\n├── openspec-apply.md\n└── openspec-archive.md\n```\n\nInvocation: `/openspec-proposal`, `/openspec-apply`, `/openspec-archive`\n\n### Codex\n\nCodex commands are written to the global prompts directory:\n\n```bash\n~/.codex/prompts/ # or $CODEX_HOME/prompts\n```\n\nThe system supports both local and global installation paths, with commands refreshed during `openspec update` when they already exist.\n\n资料来源：[openspec/changes/archive/2025-10-14-add-codex-slash-command-support/proposal.md:15-30]()\n\n## Configuration and Customization\n\n### Tool Registry\n\nThe `ToolRegistry` manages discovery and configuration for supported AI coding assistants, enabling the system to:\n\n- Detect which tools are installed in a project\n- Determine appropriate command storage locations\n- Handle tool-specific format variations\n\n### Context Injection\n\nSlash command templates support dynamic context injection, prepending project-specific information:\n\n```markdown\n---\nchange: add-auth\nartifact: proposal\nschema: spec-driven\noutput: openspec/changes/add-auth/proposal.md\n---\n\n## Dependencies\n- [x] (none - this is a root artifact)\n\n## Next Steps\nAfter creating this artifact, you can work on: design, specs\n\n---\n\n[original template content...]\n```\n\n资料来源：[openspec/changes/archive/2025-12-28-add-instruction-loader/design.md:1-30]()\n\n## Related Documentation\n\n- [Getting Started](docs/getting-started.md) — First steps with OpenSpec\n- [Workflows](docs/workflows.md) — Combos and patterns for using slash commands\n- [Commands Reference](docs/commands.md) — Detailed slash command documentation\n- [Supported Tools](docs/supported-tools.md) — Full list of supported AI assistants\n- [Opsx Workflow](docs/opsx.md) — Extended experimental workflow commands\n\n---\n\n\n\n## Workflows\n\n### 相关页面\n\n相关主题：[Slash Commands](#slash-commands), [Artifact Graph System](#artifact-graph)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/workflows.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/workflows.md)\n- [README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n- [src/core/templates/workflows/new-change.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/new-change.ts)\n- [openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md)\n- [openspec/changes/archive/2025-10-14-add-windsurf-workflows/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-10-14-add-windsurf-workflows/proposal.md)\n- [WORKSPACE_REIMPLEMENTATION_DIRECTION.md](https://github.com/Fission-AI/OpenSpec/blob/main/WORKSPACE_REIMPLEMENTATION_DIRECTION.md)\n- [openspec/changes/archive/2026-02-17-project-config/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-config/proposal.md)\n \n\n# Workflows\n\n## Overview\n\nWorkflows in OpenSpec define the ordered sequence of artifacts that get created during a change's lifecycle. They provide a structured approach to capturing requirements, design decisions, and implementation tasks before any code is written.\n\n**Purpose**: Workflows ensure that human and AI assistants align on what to build through a consistent, repeatable process that captures the \"why,\" \"what,\" and \"how\" of each change.\n\n**Scope**: A workflow determines which artifacts need to be created, in what order, and what dependencies exist between them.\n\n资料来源：[README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n## Core Concepts\n\n### Artifacts\n\nArtifacts are the files created during a change lifecycle. OpenSpec supports the following artifact types:\n\n| Artifact | Description | Output File |\n|----------|-------------|-------------|\n| proposal | Why and what changes | `proposal.md` |\n| specs | Requirements and scenarios | `specs/*.md` |\n| design | Technical approach | `design.md` |\n| tasks | Implementation checklist | `tasks.md` |\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md)\n\n### Workflow Stages\n\nEach workflow progresses through distinct stages:\n\n```mermaid\ngraph LR\n A[Propose] --> B[Design]\n B --> C[Specs]\n C --> D[Tasks]\n D --> E[Apply]\n E --> F[Archive]\n \n style A fill:#e1f5fe\n style E fill:#fff3e0\n style F fill:#f3e5f5\n```\n\n| Stage | Purpose | Key Question |\n|-------|---------|--------------|\n| **Proposal** | Capture the reason for the change | \"Why are we doing this?\" |\n| **Design** | Document technical approach | \"How will we build it?\" |\n| **Specs** | Define requirements and scenarios | \"What should it do?\" |\n| **Tasks** | Break down implementation | \"What are the steps?\" |\n| **Apply** | Execute implementation | \"Make it happen\" |\n| **Archive** | Finalize and merge | \"Clean up\" |\n\n资料来源：[README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n## Workflow Templates\n\nOpenSpec ships with predefined workflow templates located in `src/core/templates/workflows/`.\n\n### The New Change Workflow\n\nThe new change workflow (`new-change.ts`) scaffolds a complete change structure:\n\n```typescript\nexport const newChangeWorkflow = {\n name: \"New Change\",\n description: \"Scaffold a new OpenSpec change and validate strictly.\",\n async execute(params) {\n // 1. Validate change name (kebab-case)\n // 2. Check if change already exists\n // 3. Create change directory\n // 4. Show artifact status\n // 5. Output first artifact template\n }\n};\n```\n\n资料来源：[src/core/templates/workflows/new-change.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/new-change.ts)\n\n### Workflow Execution Steps\n\nWhen initiating a new change, the workflow performs these steps in order:\n\n1. **Validate the change name**\n - Must be kebab-case (e.g., `add-dark-mode`)\n - If invalid, prompt for a valid name\n\n2. **Check for existing changes**\n - If a change with the same name exists, suggest using `continue-change` instead\n\n3. **Create the scaffold**\n - Run `openspec init --change \"\"` with `--schema ` if a specific workflow is requested\n - Creates `openspec/changes//` with the selected schema\n\n4. **Show artifact status**\n ```bash\n openspec status --change \"\"\n ```\n This displays which artifacts need creation and which are ready (dependencies satisfied).\n\n5. **Output first artifact template**\n ```bash\n openspec instructions --change \"\"\n ```\n This outputs the template and context for creating the first artifact.\n\n6. **STOP and wait for user direction**\n\n资料来源：[src/core/templates/workflows/new-change.ts:1-60](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/new-change.ts)\n\n### Guardrails\n\nThe new change workflow includes important guardrails:\n\n- **Do NOT create any artifacts yet** — only show the instructions\n- **Do NOT advance beyond showing the first artifact template**\n- **Pass `--schema`** only if using a non-default workflow\n- Changes with invalid names (not kebab-case) trigger a prompt for correction\n- Existing changes suggest using `/continue` instead\n\n资料来源：[src/core/templates/workflows/new-change.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/new-change.ts)\n\n## Workflow Patterns\n\n### Spec-Driven Workflow\n\nThe spec-driven workflow emphasizes design-first approach:\n\n```mermaid\ngraph TD\n P[proposal] --> D[design]\n D --> S[specs]\n S --> T[tasks]\n \n P -.->|blocking| S\n P -.->|blocking| T\n D -.->|blocking| T\n```\n\n| Artifact | Generates | Dependencies |\n|----------|-----------|--------------|\n| proposal | `proposal.md` | None (root) |\n| design | `design.md` | proposal |\n| specs | `specs/*.md` | proposal, design |\n| tasks | `tasks.md` | specs |\n\n### Artifact Flow\n\n```\n┌────────────────────┐\n│ Archive & Update │\n│ Specs (source) │\n└────────────────────┘\n │\n ▼\n┌────────────────────┐\n│ 1. Draft proposal │\n└────────────────────┘\n │\n ▼\n┌────────────────────┐\n│ 2. Review proposal │\n└────────────────────┘\n │\n ▼\n┌────────────────────┐\n│ 3. Implement tasks │\n└────────────────────┘\n │\n ▼\n┌────────────────────┐\n│ 4. Archive change │\n└────────────────────┘\n │\n ▼\n┌────────────────────┐\n│ Specs updated │\n└────────────────────┘\n```\n\n资料来源：[openspec/changes/archive/2025-10-14-add-windsurf-workflows/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-10-14-add-windsurf-workflows/proposal.md)\n\n## Workflows with Slash Commands\n\nOpenSpec integrates with multiple AI coding assistants through slash command workflows. Each tool has its own command structure and file format.\n\n### Supported Tools and Commands\n\n| Tool | Slash Commands | File Location |\n|------|----------------|---------------|\n| Claude Code | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` | Built-in |\n| CodeBuddy | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` | `.codebuddy/commands/` |\n| Cursor | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.cursor/commands/` |\n| Windsurf | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.windsurf/workflows/` |\n| Kilo Code | `/openspec-proposal.md`, `/openspec-apply.md`, `/openspec-archive.md` | `.kilocode/workflows/` |\n| Cline | Workflows | `.clinerules/workflows/` |\n| GitHub Copilot | `@openspec-proposal`, `@openspec-apply`, `@openspec-archive` | `.github/prompts/` |\n| Continue | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.continue/prompts/` |\n| Antigravity | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.agent/workflows/` |\n\n资料来源：[README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n### Slash Command File Structure\n\nSlash command files follow a consistent pattern:\n\n```markdown\n---\nname: openspec-proposal\ndescription: Create an OpenSpec proposal\ncategory: OpenSpec\n---\n\n...command body from shared template...\n\n```\n\n**Template Content Structure:**\n- Guardrails: 1–2 clarifying questions\n- Minimal-complexity rules\n- Step list tailored to workflow stage\n- Pointers to `openspec show`, `openspec list`\n- Troubleshooting tips\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md)\n\n## CLI Commands for Workflows\n\nOpenSpec provides CLI commands to interact with workflows:\n\n```bash\n# List active change folders\nopenspec list\n\n# Interactive dashboard of specs and changes\nopenspec view\n\n# Display change details\nopenspec show \n\n# Check spec formatting and structure\nopenspec validate \n\n# Move completed change to archive\nopenspec archive [--yes|-y]\n\n# Show artifact status\nopenspec status --change \"\"\n\n# Get instructions for artifact creation\nopenspec instructions --change \"\"\n```\n\n资料来源：[README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n## Workflow Example\n\n### Create and Execute a Change\n\n```text\nYou: /openspec:propose add-dark-mode\nAI: Created openspec/changes/add-dark-mode/\n ✓ proposal.md — why we're doing this, what's changing\n ✓ specs/ — requirements and scenarios\n ✓ design.md — technical approach\n ✓ tasks.md — implementation checklist\n Ready for implementation!\n\nYou: /openspec:apply\nAI: Implementing tasks...\n ✓ 1.1 Add theme context provider\n ✓ 1.2 Create toggle component\n ✓ 2.1 Add CSS variables\n ✓ 2.2 Wire up localStorage\n All tasks complete!\n\nYou: /openspec:archive\nAI: Archived to openspec/changes/archive/2025-01-23-add-dark-mode/\n Specs updated. Ready for the next feature.\n```\n\n资料来源：[README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n## Project Configuration\n\nWorkflows can be customized per project through configuration:\n\n| Configuration Option | Description |\n|---------------------|-------------|\n| schema | Selected workflow/schema (e.g., \"spec-driven\") |\n| projectContext | Multi-line context (tech stack, conventions) |\n| artifactRules | Per-artifact custom rules |\n\n### Config Section Prompts\n\nWhen running `openspec init`, the setup command displays:\n\n```\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n📋 Project Configuration (Optional)\nConfigure project defaults for OpenSpec workflows.\n```\n\nSteps:\n1. **Create config?** — Yes/No prompt (default \"Yes\")\n2. **Schema selection** — List schemas with descriptions\n3. **Project context** — Multi-line input for tech stack info\n4. **Per-artifact rules** — Optional rules for specific artifacts\n5. **Validate and write** — Save to `openspec/config.yaml`\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-config/proposal.md)\n\n## Workspace Workflow Extensions\n\nThe OpenSpec workspace feature extends workflows across multiple repositories:\n\n```mermaid\ngraph TD\n W[Workspace] --> L[Links]\n L --> P[Proposal]\n P --> R[Repo Slices]\n R --> A[Apply]\n A --> V[Verify]\n V --> C[Archive]\n```\n\n### Workspace Workflow Sequence\n\n| Step | Capability |\n|------|------------|\n| 1 | Set up the workspace |\n| 2 | See linked repos or folders |\n| 3 | Explore repos with agent |\n| 4 | Capture a proposal |\n| 5 | Check status |\n| 6 | Implement one repo slice |\n| 7 | Verify |\n| 8 | Archive |\n\n### Apply One Repo Slice\n\nThe `/apply` command for workspaces:\n\n```text\nUser: /apply integrate-docs for landing\n```\n\n**Agent behavior:**\n1. Ask OpenSpec for apply context\n2. Read proposal, design, tasks, and relevant specs\n3. Confirm the target repo checkout\n4. Edit only that repo\n5. Update workspace tasks\n6. Run relevant checks\n\n**What `/apply` means:**\n- Implement the planned slice for one repo\n- Does NOT copy planning files\n- Does NOT materialize repo-local OpenSpec state\n- Does NOT create proposal files for the first time\n\n资料来源：[WORKSPACE_REIMPLEMENTATION_DIRECTION.md](https://github.com/Fission-AI/OpenSpec/blob/main/WORKSPACE_REIMPLEMENTATION_DIRECTION.md)\n\n## Related Documentation\n\n- [Getting Started](docs/getting-started.md) — First steps with workflows\n- [Commands](docs/commands.md) — Slash commands & skills reference\n- [CLI](docs/cli.md) — Terminal command reference\n- [Supported Tools](docs/supported-tools.md) — Tool integrations & install paths\n- [Concepts](docs/concepts.md) — How it all fits together\n- [Customization](docs/customization.md) — Make workflows yours\n\n---\n\n\n\n## Artifact Graph System\n\n### 相关页面\n\n相关主题：[System Architecture](#architecture), [Workflows](#workflows), [Schemas](#schemas)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/core/artifact-graph/graph.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/graph.ts)\n- [src/core/artifact-graph/state.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/state.ts)\n- [src/core/artifact-graph/resolver.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/resolver.ts)\n- [src/core/artifact-graph/schema.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/schema.ts)\n- [src/core/artifact-graph/outputs.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/outputs.ts)\n- [src/core/artifact-graph/instruction-loader.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/instruction-loader.ts)\n \n\n# Artifact Graph System\n\n## Overview\n\nThe Artifact Graph System is the core module of OpenSpec that manages artifact dependencies, workflow state detection, and schema-driven instruction generation. It provides a declarative way to define artifact relationships through YAML schemas and enables intelligent workflow progression based on filesystem state.\n\n### Purpose\n\nThe system solves several key problems in AI-assisted development:\n\n1. **Dependency Management** - Ensures artifacts are created in the correct order based on their dependencies\n2. **State Detection** - Automatically detects which artifacts are completed, ready, or blocked based on filesystem presence\n3. **Schema Resolution** - Supports both user-defined schemas (via XDG directories) and built-in package schemas\n4. **Instruction Generation** - Enriches templates with project context, artifact-specific rules, and dependency status\n\n### High-Level Architecture\n\n```mermaid\ngraph TB\n subgraph \"Artifact Graph System\"\n YAML[(\"Schema YAML\")]\n GRAPH[(\"ArtifactGraph\")]\n STATE[(\"State Detection\")]\n INSTR[(\"Instruction Loader\")]\n CTX[(\"ChangeContext\")]\n end\n \n subgraph \"Schema Sources\"\n USER[(\"User Schemas
XDG_DATA_HOME\")]\n BUILTIN[(\"Built-in Schemas
Package\")]\n end\n \n YAML --> GRAPH\n GRAPH --> STATE\n GRAPH --> CTX\n STATE --> CTX\n CTX --> INSTR\n \n USER -->|resolveSchema| GRAPH\n BUILTIN -->|resolveSchema| GRAPH\n```\n\n## Core Concepts\n\n### Artifacts\n\nArtifacts are the fundamental units of work in OpenSpec. Each artifact has:\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `id` | string | Unique identifier within the schema |\n| `generates` | string | File pattern generated by this artifact |\n| `template` | string | Template file path (relative to schema directory) |\n| `requires` | string[] | List of artifact IDs that must complete first |\n\n### Schema Structure\n\nSchemas define the workflow for a change. They are YAML files with the following structure:\n\n```yaml\nname: spec-driven\nversion: 1\ndescription: Specification-driven development workflow\n\nartifacts:\n - id: proposal\n generates: \"proposal.md\"\n template: \"proposal.md\"\n requires: []\n\n - id: specs\n generates: \"specs/*.md\"\n template: \"spec.md\"\n requires: [proposal]\n\n - id: design\n generates: \"design.md\"\n template: \"design.md\"\n requires: [proposal]\n\n - id: tasks\n generates: \"tasks.md\"\n template: \"tasks.md\"\n requires: [specs, design]\n```\n\n## ArtifactGraph Class\n\nThe `ArtifactGraph` class is the central component that loads schemas and provides graph query operations.\n\n### Class Structure\n\n```typescript\nexport class ArtifactGraph {\n private artifacts: Map;\n private schema: SchemaYaml;\n\n private constructor(schema: SchemaYaml) {\n this.schema = schema;\n this.artifacts = new Map(schema.artifacts.map(a => [a.id, a]));\n }\n}\n```\n\n### Factory Methods\n\n| Method | Description | Source |\n|--------|-------------|--------|\n| `fromYaml(filePath)` | Load graph from a schema YAML file path | `graph.ts:18-21` |\n| `fromYamlContent(yamlContent)` | Parse graph from YAML content string | `graph.ts:27-29` |\n| `fromSchema(schema)` | Create graph from pre-validated SchemaYaml object | `graph.ts:35-37` |\n\n### Query Methods\n\n| Method | Return Type | Description |\n|--------|-------------|--------------|\n| `getArtifact(id)` | `Artifact \\| undefined` | Get a single artifact by ID |\n| `getAllArtifacts()` | `Artifact[]` | Get all artifacts in definition order |\n| `getName()` | `string` | Get the schema name |\n| `getSchema()` | `SchemaYaml` | Get the underlying schema object |\n\n## State Detection\n\nThe state detection module (`state.ts`) monitors the filesystem to determine the status of each artifact relative to a change directory.\n\n### State Types\n\n| State | Description |\n|-------|-------------|\n| `completed` | All files matching the artifact's `generates` pattern exist |\n| `ready` | All dependencies are completed, can be worked on |\n| `blocked` | Dependencies are not yet completed |\n\n### State Detection Logic\n\n```typescript\ninterface ArtifactGraphResult {\n completed: string[]; // Artifact IDs that are fully completed\n ready: string[]; // Artifact IDs ready to work on\n blocked: BlockedArtifacts; // Artifact IDs with their unmet dependencies\n buildOrder: string[]; // Topological order for creation\n}\n```\n\nThe detection process:\n\n1. For each artifact, check if files matching `generates` exist in the change directory\n2. Collect all completed artifact IDs into a `CompletedSet` (a `Set`)\n3. For each non-completed artifact, find which dependencies are unmet\n4. Artifacts with all dependencies met are marked `ready`\n\n## Topological Sorting\n\nThe system uses Kahn's algorithm for topological sorting to determine the correct build order for artifacts.\n\n### Algorithm Properties\n\n- **Cycle Detection**: Kahn's algorithm naturally fails on cyclic dependencies, providing natural cycle detection\n- **Stable Ordering**: Independent artifacts are returned in definition order\n- **Linear Time**: O(V + E) where V is artifacts and E is dependencies\n\n### Error Format\n\nWhen a cycle is detected, the error message clearly identifies the cycle path:\n\n```\nCyclic dependency detected: A → B → C → A\n```\n\n## Schema Resolution\n\nThe `resolver.ts` module handles loading schemas from multiple sources with a defined priority order.\n\n### Resolution Order\n\n```mermaid\ngraph LR\n A[(\"Schema Name\")] --> B{Global Override?}\n B -->|Yes| C[\"${XDG_DATA_HOME}/openspec/schemas/\"]\n B -->|No| D{Package Built-in?}\n D -->|Yes| E[\"/schemas/\"]\n D -->|No| F[(\"Error: Schema not found\")]\n C --> G[(\"Loaded Schema\")]\n E --> G\n```\n\n### Resolution Paths\n\n| Priority | Location | Environment Variable |\n|----------|----------|----------------------|\n| 1 (User Override) | `${XDG_DATA_HOME}/openspec/schemas/` | `XDG_DATA_HOME` |\n| 2 (Built-in) | `/schemas/` | N/A |\n| 3 (Error) | Schema not found | N/A |\n\n**Fallback Behavior**: If `XDG_DATA_HOME` is not set, the system falls back to `~/.local/share` on Unix systems.\n\n## Built-in Schemas\n\nOpenSpec ships with two built-in schemas:\n\n### spec-driven Schema\n\nThe default schema following a proposal → specs → design → tasks workflow:\n\n```yaml\nname: spec-driven\nartifacts:\n - id: proposal\n generates: \"proposal.md\"\n requires: []\n - id: specs\n generates: \"specs/*.md\"\n requires: [proposal]\n - id: design\n generates: \"design.md\"\n requires: [proposal]\n - id: tasks\n generates: \"tasks.md\"\n requires: [specs, design]\n```\n\n### tdd Schema\n\nAn alternative schema for test-driven development:\n\n```yaml\nname: tdd\nartifacts:\n - id: tests\n generates: \"tests/*.md\"\n requires: []\n - id: implementation\n generates: \"implementation.md\"\n requires: [tests]\n - id: docs\n generates: \"docs.md\"\n requires: [implementation]\n```\n\n## Instruction Loading\n\nThe `instruction-loader.ts` module enriches templates with change-specific context and project configuration.\n\n### ChangeContext Interface\n\n```typescript\ninterface ChangeContext {\n changeName: string;\n changeDir: string;\n schemaName: string;\n graph: ArtifactGraph;\n completed: CompletedSet;\n}\n```\n\n### Instruction Output Structure\n\nInstructions are formatted with XML-like sections for AI consumption:\n\n```markdown\n\n\n[Project context from config]\n\n\n\n[Artifact-specific rules from config]\n\n\n\n[Schema's template content]\n\n```\n\n### Context Injection Rules\n\n| Section | Applies To | Source |\n|---------|-----------|--------|\n| `` | All artifacts | Project config's `context` field |\n| `` | Specific artifacts only | Per-artifact rules in project config |\n| `` | All artifacts | Schema's template file |\n\n## File Structure\n\n```\nsrc/core/artifact-graph/\n├── index.ts # Public exports\n├── types.ts # Zod schemas and TypeScript types\n├── graph.ts # ArtifactGraph class\n├── state.ts # State detection logic\n├── resolver.ts # Schema resolution\n├── schema.ts # YAML parsing and validation\n├── outputs.ts # Output path resolution\n├── instruction-loader.ts # Template enrichment\n└── schemas/ # Built-in schema definitions\n ├── spec-driven/\n │ ├── schema.yaml\n │ └── templates/\n └── tdd/\n ├── schema.yaml\n └── templates/\n```\n\n## Integration Points\n\n### With Workflow Commands\n\nThe Artifact Graph System integrates with the `/opsx:continue` and `/opsx:apply` workflows:\n\n1. **Continue Workflow** - Reads instructions for the next ready artifact\n2. **Apply Workflow** - Checks completion status and provides apply-phase instructions\n\n### With Project Config\n\nProject-level configuration (`openspec/config.yaml`) can provide:\n\n- Default schema selection\n- Project context for all artifacts\n- Per-artifact rules and guidelines\n\n## Testing\n\nThe system includes comprehensive test coverage:\n\n| Test Case | Purpose |\n|-----------|---------|\n| Parse valid schema YAML | Schema loading works correctly |\n| Parse invalid schema | Missing fields throw descriptive errors |\n| Duplicate artifact IDs | Detection and error reporting |\n| Invalid `requires` reference | Identification of invalid artifact IDs |\n| Cycle detection | Error with cycle path listing |\n| Build order (linear) | Topological sort correctness |\n| Build order (diamond) | Complex dependency handling |\n| Independent artifacts | Stable ordering of unrelated nodes |\n\n## Related Documentation\n\n- [Schema Directories Design](../changes/archive/2025-12-28-restructure-schema-directories/design.md) - Schema directory structure\n- [Instruction Loader Design](../changes/archive/2025-12-28-add-instruction-loader/design.md) - Template loading and enrichment\n- [Apply-Phase Schema Design](../changes/archive/2026-01-06-make-apply-instructions-schema-aware/design.md) - Apply phase configuration\n- [Project Config Design](../changes/archive/2026-02-17-project-config/design.md) - Project-level configuration integration\n\n---\n\n\n\n## Schemas\n\n### 相关页面\n\n相关主题：[Validation System](#validation-system), [Artifact Graph System](#artifact-graph)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [schemas/spec-driven/schema.yaml](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/schema.yaml)\n- [schemas/workspace-planning/schema.yaml](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/workspace-planning/schema.yaml)\n- [src/core/schemas/index.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/schemas/index.ts)\n- [src/core/schemas/base.schema.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/schemas/base.schema.ts)\n- [src/core/schemas/change.schema.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/schemas/change.schema.ts)\n- [src/core/schemas/spec.schema.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/schemas/spec.schema.ts)\n \n\n# Schemas\n\nSchemas define the workflow structure for OpenSpec changes. They specify which artifacts should be created, their dependencies, requirements for completion, and how the apply phase operates.\n\n## Overview\n\nA schema in OpenSpec is a configuration that defines a complete workflow for planning and implementing changes. Schemas specify:\n\n- The **artifacts** to create (e.g., proposal, specs, design, tasks)\n- The **dependencies** between artifacts\n- **Requirements** that must be met before each artifact is considered complete\n- **Templates** for generating artifact content\n- **Apply phase** configuration for implementation guidance\n\nSchemas are self-contained directories containing `schema.yaml` and template files, following a structure similar to Helm charts. 资料来源：[openspec/changes/archive/2025-12-28-restructure-schema-directories/design.md]()\n\n## Schema Directory Structure\n\n```\nschemas/\n├── spec-driven/\n│ ├── schema.yaml # Schema definition\n│ └── templates/\n│ ├── proposal.md\n│ ├── design.md\n│ ├── spec.md\n│ └── tasks.md\n└── tdd/\n ├── schema.yaml\n └── templates/\n ├── spec.md\n ├── test.md\n ├── implementation.md\n └── docs.md\n```\n\nBuilt-in schemas are distributed with the package, while user overrides can be placed in XDG data directories. 资料来源：[openspec/changes/archive/2025-12-28-restructure-schema-directories/design.md]()\n\n## Schema Resolution Order\n\nOpenSpec resolves schemas using a priority-based lookup:\n\n```mermaid\ngraph TD\n A[Schema Request] --> B{CLI --schema flag?}\n B -->|Yes| C[Use CLI flag]\n B -->|No| D{.openspec.yaml in change?}\n D -->|Yes| E[Use change metadata]\n D -->|No| F{openspec/config.yaml schema?}\n F -->|Yes| G[Use project default]\n F -->|No| H{\"spec-driven\" fallback}\n```\n\n| Priority | Source | Example Path |\n|----------|--------|--------------|\n| 1 (highest) | CLI flag | `--schema tdd` |\n| 2 | Change metadata | `.openspec.yaml` |\n| 3 | Project config | `openspec/config.yaml` |\n| 4 (lowest) | Hardcoded default | `\"spec-driven\"` |\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md]()\n\n## Schema YAML Format\n\n### Core Fields\n\n```yaml\nname: spec-driven\nversion: 1\ndescription: Specification-driven development\n```\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `name` | string | Yes | Unique schema identifier (kebab-case) |\n| `version` | number | Yes | Schema version for compatibility |\n| `description` | string | Yes | Human-readable description |\n\n### Artifacts Section\n\nThe `artifacts` array defines each artifact in the workflow:\n\n```yaml\nartifacts:\n - id: proposal\n generates: proposal.md\n template: proposal.md\n requires: []\n \n - id: specs\n generates: specs/\n template: spec.md\n requires:\n - proposal\n```\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `id` | string | Yes | Unique artifact identifier |\n| `generates` | string | Yes | Output path or directory |\n| `template` | string | Yes | Template file relative to `templates/` |\n| `requires` | string[] | No | Artifact IDs that must exist first |\n| `format_requirements` | string | No | Special formatting instructions |\n\n资料来源：[schemas/spec-driven/schema.yaml]()\n\n## Built-in Schemas\n\n### spec-driven\n\nThe default schema focused on specification-driven development. It emphasizes clear requirements and scenarios before implementation.\n\n**Artifact Flow:**\n```mermaid\ngraph LR\n A[proposal] --> B[specs]\n B --> C[design]\n C --> D[tasks]\n D --> E[apply]\n```\n\n| Artifact | Generates | Requires | Purpose |\n|----------|-----------|----------|---------|\n| `proposal` | `proposal.md` | (none) | Define the change scope |\n| `specs` | `specs/*.md` | proposal | Document requirements and scenarios |\n| `design` | `design.md` | specs | Technical approach |\n| `tasks` | `tasks.md` | design, specs | Implementation checklist |\n\n### workspace-planning\n\nSchema for multi-repository planning and coordination across workspaces.\n\n资料来源：[schemas/workspace-planning/schema.yaml]()\n\n### tdd (Test-Driven Development)\n\nSchema focused on tests first, following the pattern: spec → test → implementation → docs.\n\n| Artifact | Generates | Requires |\n|----------|-----------|----------|\n| `spec` | `spec.md` | (none) |\n| `test` | `test.md` | spec |\n| `implementation` | `implementation.md` | test |\n| `docs` | `docs.md` | implementation |\n\n## Requirements Format\n\nRequirements define completion criteria for artifacts. They use a structured format with scenarios.\n\n```markdown\n## Requirements\n\n### Requirement: \n\n\n#### Scenario: \n- **WHEN** \n- **THEN** \n```\n\n**Key Formatting Rules:**\n- Requirements use `### Requirement:` with exactly 3 hashtags\n- Scenarios use `#### Scenario:` with exactly 4 hashtags\n- Use SHALL/MUST for normative requirements (avoid should/may)\n- Every requirement MUST have at least one scenario\n\n资料来源：[schemas/spec-driven/schema.yaml]()\n\n## Apply Phase Configuration\n\nThe optional `apply` block defines how implementation should proceed:\n\n```yaml\napply:\n requires:\n - specs\n - design\n - tasks\n tracks:\n - id: implementation\n label: Implementation\n instruction: |\n Proceed with implementation based on the tasks artifact.\n```\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `requires` | string[] | Artifacts that must exist before apply |\n| `tracks` | Track[] | Progress tracking categories |\n| `instruction` | string | Instructions displayed during apply |\n\n资料来源：[openspec/changes/archive/2026-01-06-make-apply-instructions-schema-aware/tasks.md]()\n\n## Schema Resolution Implementation\n\nThe `resolveSchema()` function handles schema loading with user overrides:\n\n```typescript\n// Resolution order (highest to lowest priority)\n1. ${XDG_DATA_HOME}/openspec/schemas//schema.yaml // User override\n2. /schemas//schema.yaml // Built-in\n```\n\n```typescript\nfunction getPackageSchemasDir(): string {\n const currentFile = fileURLToPath(import.meta.url);\n // Navigate from src/core/artifact-graph/ to package root\n return path.join(path.dirname(currentFile), '..', '..', '..', 'schemas');\n}\n```\n\n资料来源：[openspec/changes/archive/2025-12-28-restructure-schema-directories/design.md]()\n\n## Template Loading\n\nTemplates are loaded relative to the schema's `templates/` directory:\n\n```yaml\n# In schema.yaml\nartifacts:\n - id: proposal\n template: \"proposal.md\" # → schemas/spec-driven/templates/proposal.md\n```\n\nTemplates are simple markdown files without template engine dependencies. Context injection prepends a header section:\n\n```markdown\n---\nchange: add-auth\nartifact: proposal\nschema: spec-driven\noutput: openspec/changes/add-auth/proposal.md\n---\n\n## Dependencies\n- [x] (none - this is a root artifact)\n\n## Next Steps\nAfter creating this artifact, you can work on: design, specs\n\n---\n\n[original template content...]\n```\n\n资料来源：[openspec/changes/archive/2025-12-28-add-instruction-loader/design.md]()\n\n## Project Configuration Integration\n\nSchemas integrate with `openspec/config.yaml` for project defaults:\n\n```yaml\nschema: spec-driven # Default schema for new changes\ncontext: |\n Tech stack: TypeScript, React, Node.js\n API style: RESTful\nrules:\n design:\n - Include rollback plan\n```\n\nThe `schema` field in config sets the project default, which is used when:\n- Creating new changes without `--schema` flag\n- Running commands on changes without `.openspec.yaml` metadata\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md]()\n\n## Context Injection\n\nWhen generating instructions for artifacts, schemas support context injection via XML-style tags:\n\n```xml\n\nTech stack: TypeScript, React, Node.js, PostgreSQL\nAPI style: RESTful, documented in docs/api-conventions.md\n\n\n\n- Include rollback plan\n- Identify affected teams and notify in #platform-changes\n\n\n\n[Schema's built-in template content]\n\n```\n\n**Injection Priority:**\n- `` appears for all artifacts (from project config)\n- `` appear only for matching artifact IDs\n- `` contains the schema's base template content\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/proposal.md]()\n\n## CLI Commands\n\n### List Available Schemas\n\n```bash\nopenspec schemas list\n```\n\nDisplays all available schemas with their source (project, user, package).\n\n### Initialize New Schema\n\n```bash\nopenspec schema init \\\n --description \"My custom workflow\" \\\n --artifacts proposal,specs,design,tasks \\\n --default\n```\n\nCreates a new schema in `openspec/schemas//` with the specified configuration.\n\n### Show Schema Details\n\n```bash\nopenspec schema show \n```\n\nDisplays schema definition including artifacts, requirements, and apply configuration.\n\n---\n\n\n\n## Configuration\n\n### 相关页面\n\n相关主题：[Getting Started](#getting-started)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [openspec/config.yaml](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/config.yaml)\n- [src/core/config.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/config.ts)\n- [src/core/config-schema.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/config-schema.ts)\n- [src/core/global-config.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/global-config.ts)\n- [src/core/project-config.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/project-config.ts)\n- [src/core/profiles.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/profiles.ts)\n- [src/commands/config.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/commands/config.ts)\n \n\n# Configuration\n\nOpenSpec uses a layered configuration system that manages project-level settings, global defaults, and user preferences. This configuration architecture enables teams to share project context, define artifact-specific rules, and customize the OpenSpec workflow across different environments.\n\n## Overview\n\nThe OpenSpec configuration system serves three primary purposes:\n\n1. **Schema Selection** — Define which OpenSpec schema to use for change management\n2. **Context Injection** — Provide project background (tech stack, conventions, terminology) that gets injected into generated artifacts\n3. **Per-Artifact Rules** — Define constraints and guidelines that apply to specific artifact types\n\n```mermaid\ngraph TD\n A[User Project] --> B[openspec/config.yaml]\n A --> C[Global Config]\n A --> D[User Config]\n \n B --> E[Schema Resolution]\n C --> E\n D --> E\n \n E --> F[spec-driven]\n E --> G[minimal]\n E --> H[custom schemas]\n \n F --> I[Artifact Generation]\n G --> I\n H --> I\n \n I --> J[proposal.md]\n I --> K[specs/*.md]\n I --> L[design.md]\n I --> M[tasks.md]\n```\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-config/design.md)\n\n## Configuration Files\n\n### Project Configuration (`openspec/config.yaml`)\n\nThe project-level configuration file lives in the `openspec/` directory and is designed to be committed to version control. This ensures all team members share the same project context and rules.\n\n**Location:** `/openspec/config.yaml`\n\n**Structure:**\n\n```yaml\nschema: spec-driven\ncontext:\n project_name: My Application\n tech_stack:\n - Node.js\n - TypeScript\n - PostgreSQL\n conventions:\n - Use async/await for all asynchronous operations\n - Follow conventional commits\n terminology:\n - \"change\" refers to a feature or fix being implemented\n - \"artifact\" refers to a generated file\n\nrules:\n proposal:\n - Include spike tasks for unknowns\n specs:\n - Use SHALL/MUST for normative requirements\n - Every requirement needs at least one scenario\n```\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-config/proposal.md)\n\n### Schema Configuration\n\nEach schema defines its own structure and templates. The `spec-driven` schema, for example, includes requirements for how artifacts should be formatted:\n\n```yaml\nartifacts:\n - id: proposal\n generates: proposal.md\n requires: []\n \n - id: specs\n generates: specs/*.md\n requires:\n - proposal\n \n - id: design\n generates: design.md\n requires:\n - proposal\n - specs\n```\n\n资料来源：[schemas/spec-driven/schema.yaml](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/schema.yaml)\n\n## Configuration Architecture\n\n### Configuration Resolution Order\n\nOpenSpec resolves configuration values using a specific precedence order:\n\n```mermaid\ngraph LR\n A[CLI Flag] -->|highest| B[Change Metadata]\n B --> C[Project Config]\n C -->|lowest| D[Global Config]\n D --> E[Hardcoded Default]\n```\n\n| Priority | Source | Description |\n|----------|--------|-------------|\n| 1 | CLI Flag | Explicit `--schema` parameter |\n| 2 | Change Metadata | `.openspec.yaml` in change directory |\n| 3 | Project Config | `openspec/config.yaml` |\n| 4 | Global Config | User's global settings |\n| 5 | Default | Hardcoded fallback (`spec-driven`) |\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-config/design.md)\n\n### Module Structure\n\n```\nsrc/core/\n├── config.ts # Main configuration module\n├── config-schema.ts # Configuration schema definitions\n├── global-config.ts # Global configuration management\n├── project-config.ts # Project-level configuration handling\n└── profiles.ts # Profile management\n```\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-config/design.md)\n\n## Core Modules\n\n### Project Config Module\n\nThe `project-config.ts` module handles reading, parsing, and validating project-level configuration.\n\n**Key Responsibilities:**\n\n- Read `openspec/config.yaml` from the project root\n- Parse YAML into typed configuration objects\n- Validate schema names against available schemas\n- Provide error messages for misconfiguration\n\n**Validation Logic:**\n\n```typescript\nexport function validateProjectConfig(config: ProjectConfig): ValidationResult {\n const errors: string[] = [];\n \n if (config.schema) {\n const availableSchemas = getAvailableSchemas();\n if (!availableSchemas.includes(config.schema)) {\n errors.push(`Invalid schema: ${config.schema}`);\n }\n }\n \n return { valid: errors.length === 0, errors };\n}\n```\n\n资料来源：[src/core/project-config.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/project-config.ts)\n\n### Profile Management\n\nProfiles allow users to customize their OpenSpec workflow by selecting different command sets and behaviors.\n\n```mermaid\ngraph TD\n A[Profile Selection] --> B[Minimal Profile]\n A --> C[Artifact-Guided Profile]\n A --> D[Experimental Profile]\n \n B --> B1[Basic commands: init, list, show]\n C --> C1[opsx commands: new, continue, ff]\n D --> D1[Early access features]\n```\n\n**Available Profiles:**\n\n| Profile | Commands | Description |\n|---------|----------|-------------|\n| `minimal` | `init`, `list`, `show`, `new`, `apply`, `archive` | Basic workflow |\n| `artifact-guided` | `opsx:*` commands | New artifact-driven workflow |\n| `experimental` | All + experimental features | Early access features |\n\n资料来源：[openspec/README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n## Configuration CLI Commands\n\nThe `config` command group provides interactive management of OpenSpec configuration.\n\n### Commands\n\n| Command | Description |\n|---------|-------------|\n| `openspec config profile` | Select active workflow profile |\n| `openspec config view` | Display current configuration |\n| `openspec config validate` | Validate configuration files |\n| `openspec config init` | Initialize project configuration |\n\n### Interactive Profile Selection\n\n```bash\n$ openspec config profile\n? Select a profile:\n > minimal (default)\n artifact-guided (recommended)\n experimental\n```\n\n资料来源：[src/commands/config.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/commands/config.ts)\n\n## Context and Rules Injection\n\n### How Context Works\n\nThe project `context` section is injected into generated artifacts to provide project-specific background information:\n\n```bash\n# Get instructions for artifact with context\nopenspec instructions specs --change my-feature\n\n# Output structure:\n\n[Project context from config.yaml]\n\n\n\n[Schema's specs template]\n\n```\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-config/proposal.md)\n\n### Rule Injection by Artifact Type\n\nRules are only injected for artifacts that have them configured:\n\n```mermaid\ngraph TD\n A[Artifact Request] --> B{Has rules?}\n B -->|Yes| C[Include rules section]\n B -->|No| D[Skip rules section]\n \n C --> E[]\n C --> F[]\n C --> G[]\n \n D --> E\n D --> G\n```\n\n**Example: Rules for `proposal` artifact:**\n\n```yaml\nrules:\n proposal:\n - Include spike tasks for unknown complexities\n - Reference existing patterns before inventing new ones\n```\n\n**Example: Rules for `specs` artifact:**\n\n```yaml\nrules:\n specs:\n - Use SHALL/MUST for normative requirements\n - Every requirement MUST have at least one scenario\n - Scenarios MUST use exactly 4 hashtags (####)\n```\n\n资料来源：[schemas/spec-driven/schema.yaml](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/schema.yaml)\n\n## Schema Resolution\n\n### Resolution Function\n\nThe `resolveSchemaForChange()` function determines which schema to use:\n\n```typescript\nexport function resolveSchemaForChange(\n changeName: string,\n cliSchema?: string\n): string {\n // 1. CLI flag wins\n if (cliSchema) {\n return cliSchema;\n }\n\n // 2. Change metadata (.openspec.yaml)\n const metadata = readChangeMetadata(changeName);\n if (metadata?.schema) {\n return metadata.schema;\n }\n\n // 3. Project config (NEW)\n const projectConfig = readProjectConfig();\n if (projectConfig?.schema) {\n return projectConfig.schema;\n }\n\n // 4. Hardcoded default\n return 'spec-driven';\n}\n```\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-config/design.md)\n\n### Project-Local Schemas\n\nOpenSpec supports project-local schemas that override built-in schemas:\n\n```mermaid\ngraph TD\n A[Schema Request] --> B{Project-local exists?}\n B -->|Yes| C[Use project-local]\n B -->|No| D{User override exists?}\n D -->|Yes| E[Use user override]\n D -->|No| F[Use built-in]\n```\n\n**Schema Search Order:**\n\n1. `/openspec/schemas//`\n2. `/openspec/schemas//`\n3. `/schemas//`\n\n资料来源：[openspec/changes/archive/2026-02-17-project-local-schemas/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-local-schemas/design.md)\n\n## Global Configuration\n\nGlobal configuration lives in the user's home directory and provides defaults that apply across all projects.\n\n**Default Location:** `~/.config/openspec/config.yaml` (Linux/macOS)\n\n**Purpose:**\n\n- Default profile selection\n- Telemetry preferences\n- Editor-specific settings\n\n### Telemetry Configuration\n\nOpenSpec collects anonymous usage statistics by default:\n\n```bash\n# Opt-out via environment variable\nexport OPENSPEC_TELEMETRY=0\n# or\nexport DO_NOT_TRACK=1\n```\n\n资料来源：[openspec/README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n\n## Validation and Error Handling\n\n### Configuration Validation\n\nThe validation system checks for common configuration errors:\n\n```typescript\nexport function validateConfig(config: unknown): ValidationResult {\n const errors: string[] = [];\n \n // Check schema validity\n if (!config.schema || !isValidSchema(config.schema)) {\n errors.push(`Invalid schema: ${config.schema}`);\n }\n \n // Check context structure\n if (config.context && typeof config.context !== 'object') {\n errors.push('Context must be an object');\n }\n \n return { valid: errors.length === 0, errors };\n}\n```\n\n### Error Messages\n\nWhen validation fails, OpenSpec provides actionable error messages:\n\n```\nError: Invalid schema 'unknown-schema'\nAvailable schemas:\n Built-in: spec-driven, minimal, gpt-prompts\n Project-local: (none found)\n\nFix: Edit openspec/config.yaml and change 'schema: unknown-schema' to a valid schema name\n```\n\n资料来源：[src/core/project-config.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/project-config.ts)\n\n## Migration from Legacy Config\n\n### Old Configuration Files\n\nOpenSpec previously used different configuration mechanisms that are now deprecated:\n\n| Old File | New Location | Notes |\n|----------|--------------|-------|\n| `openspec/project.md` | `openspec/config.yaml.context` | Migrate manually |\n| `CLAUDE.md` | `openspec/config.yaml` | Removed |\n| `.cursorrules` | `openspec/config.yaml` | Removed |\n| `.windsurfrules` | `openspec/config.yaml` | Removed |\n\n### Migration Steps\n\n1. Run `openspec init` to detect legacy artifacts\n2. Review the migration hints provided\n3. Manually migrate `project.md` content to `config.yaml.context`\n4. Delete old configuration files when ready\n\n资料来源：[openspec/changes/archive/2026-02-17-merge-init-experimental/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-merge-init-experimental/design.md)\n\n## Best Practices\n\n### Configuration Organization\n\n1. **Commit `config.yaml`** — Keep project configuration in version control for team consistency\n2. **Use descriptive context** — Include tech stack, conventions, and terminology\n3. **Define artifact rules** — Set clear guidelines for each artifact type\n4. **Keep rules concise** — Rules should be actionable constraints, not verbose documentation\n\n### Team Collaboration\n\n```bash\n# Share configuration via git\ngit add openspec/config.yaml\ngit commit -m \"Add project config with context and rules\"\n\n# Everyone gets the same context and rules automatically\n```\n\n资料来源：[openspec/changes/archive/2026-02-17-project-config/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-config/proposal.md)\n\n## Summary\n\nThe OpenSpec configuration system provides a flexible, layered approach to managing project settings:\n\n- **Project-level config** (`openspec/config.yaml`) for team-shared context and rules\n- **Schema-based organization** for consistent artifact generation\n- **Per-artifact rules** for tailored guidelines\n- **Profile system** for workflow customization\n- **Validation** to catch configuration errors early\n\n---\n\n\n\n## Validation System\n\n### 相关页面\n\n相关主题：[Schemas](#schemas), [Configuration](#configuration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/core/validation/validator.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/validation/validator.ts)\n- [src/core/validation/types.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/validation/types.ts)\n- [src/core/validation/constants.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/validation/constants.ts)\n- [src/core/parsers/spec-structure.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/parsers/spec-structure.ts)\n- [src/commands/validate.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/commands/validate.ts)\n \n\n# Validation System\n\n## Overview\n\nThe OpenSpec Validation System is a multi-layered infrastructure that ensures specification files, change artifacts, and project configurations conform to defined schemas and structural requirements. The validation system serves as the quality gate for the entire OpenSpec workflow, preventing malformed specs from entering the repository and maintaining consistency across teams and projects.\n\nThe validation system operates at multiple levels: structural validation of markdown content, schema-based validation using Zod, and command-level validation for CLI operations. This layered approach ensures that validation is both comprehensive and performant, catching errors early in the development workflow.\n\nThe system is designed to be reusable across different commands and workflows, following the principle established in the implementation order that schemas and validation infrastructure should be shared between command implementations.\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n A[User/CLI Command] --> B[Validation Entry Point]\n B --> C[Command Validation]\n B --> D[Spec Structure Validation]\n B --> E[Schema Validation]\n \n C --> F[openspec validate]\n C --> G[openspec show --json --deltas-only]\n C --> H[openspec instructions]\n \n D --> I[Markdown Parser]\n D --> J[Spec Structure Parser]\n D --> K[Scenario Parser]\n \n E --> L[Zod Schemas]\n E --> M[Custom Validators]\n \n I --> N[Header Extraction]\n I --> O[Content Normalization]\n J --> P[Requirement Parsing]\n J --> Q[Delta Detection]\n K --> R[WHEN/THEN Format]\n K --> S[Scenario Validation]\n \n L --> T[ArtifactSchema]\n L --> U[SchemaYamlSchema]\n L --> V[ChangeMetadataSchema]\n```\n\n## Core Components\n\n### Validation Types (`src/core/validation/types.ts`)\n\nThe types module defines the foundational data structures used throughout the validation system. These types are constructed using Zod schemas to enable runtime validation with full type inference.\n\n| Type | Purpose | Key Fields |\n|------|---------|------------|\n| `ValidationResult` | Encapsulates validation outcome | `valid: boolean`, `errors: ValidationError[]`, `warnings: ValidationWarning[]` |\n| `ValidationError` | Represents a validation failure | `code: string`, `message: string`, `path: string`, `line?: number` |\n| `SpecRequirement` | Parsed requirement structure | `name: string`, `description: string`, `scenarios: Scenario[]` |\n| `Scenario` | Individual test scenario | `name: string`, `when: string`, `then: string[]` |\n\nThe type definitions ensure that all validation operations work with consistent data structures, reducing runtime errors and improving developer experience through IDE autocompletion.\n\n### Validation Constants (`src/core/validation/constants.ts`)\n\nConstants define the boundaries and thresholds for validation operations. These values are extracted into a dedicated module to allow easy tuning without modifying validation logic.\n\n```typescript\n// Example constant categories\nconst VALIDATION = {\n MAX_REQUIREMENT_LENGTH: 500,\n MAX_SCENARIO_COUNT: 50,\n MIN_REQUIREMENT_COUNT: 1,\n REQUIRED_HEADERS: ['## Purpose', '## Requirements'],\n} as const;\n\nconst ERROR_CODES = {\n MISSING_REQUIREMENT: 'SPEC_001',\n MISSING_SCENARIO: 'SPEC_002',\n INVALID_FORMAT: 'SPEC_003',\n CYCLIC_DEPENDENCY: 'GRAPH_001',\n INVALID_DELTA: 'DELTA_001',\n} as const;\n```\n\n### Core Validator (`src/core/validation/validator.ts`)\n\nThe validator module contains the primary validation logic that orchestrates checks across different validation layers. It provides a unified interface for validating various OpenSpec artifacts.\n\n**Key Responsibilities:**\n\n- Coordinating validation across multiple layers (structural, schema, semantic)\n- Aggregating errors and warnings from different validators\n- Providing detailed error messages with file paths and line numbers\n- Supporting both synchronous and asynchronous validation flows\n\n```typescript\n// Conceptual validation flow\nasync function validateSpec(specPath: string): Promise {\n const errors: ValidationError[] = [];\n const warnings: ValidationWarning[] = [];\n \n // Layer 1: File existence and readability\n const fileResult = await validateFileAccess(specPath);\n if (!fileResult.valid) return fileResult;\n \n // Layer 2: Structure validation\n const structure = await parseSpecStructure(specPath);\n const structureErrors = validateStructure(structure);\n errors.push(...structureErrors);\n \n // Layer 3: Content validation\n const contentErrors = validateContent(structure);\n errors.push(...contentErrors);\n \n // Layer 4: Cross-reference validation\n const xrefErrors = validateCrossReferences(structure);\n errors.push(...xrefErrors);\n \n return {\n valid: errors.length === 0,\n errors,\n warnings,\n };\n}\n```\n\n## Spec Structure Validation\n\n### Markdown Parser (`src/core/parsers/spec-structure.ts`)\n\nThe spec structure parser extracts structured data from markdown-formatted specification files. It handles the unique requirements of OpenSpec's spec format, including requirement blocks, scenario definitions, and delta operations.\n\n**Parsing Capabilities:**\n\nThe parser handles multiple content types found in OpenSpec specifications:\n\n- **Requirements**: Extracted from `### Requirement:` headers with accompanying descriptions\n- **Scenarios**: Parsed from `#### Scenario:` headers using WHEN/THEN/AND format\n- **Delta Operations**: Identifies ADDED, MODIFIED, REMOVED, and RENAMED sections\n- **Frontmatter**: Processes YAML frontmatter for metadata and schema references\n\n**Critical Parsing Rules:**\n\nPer the schema specification, scenario headers must use exactly four hashtags (`####`) followed by `Scenario:`. Using three hashtags or bullet-point formats will result in silent parsing failures.\n\n```typescript\n// Scenario detection pattern\nconst SCENARIO_PATTERN = /^#### Scenario:\\s*(.+)$/gm;\nconst WHEN_PATTERN = /^\\*?\\*?WHEN\\*?\\*?\\s+(.+)$/im;\nconst THEN_PATTERN = /^\\*?\\*?THEN\\*?\\*?\\s+(.+)$/im;\nconst AND_PATTERN = /^\\*?\\*?AND\\*?\\*?\\s+(.+)$/im;\n```\n\n### Content Normalization\n\nThe validation system normalizes input content to handle platform-specific line endings. This is particularly important because different operating systems use different line ending conventions:\n\n- Unix/Linux/macOS: LF (`\\n`)\n- Windows: CRLF (`\\r\\n`)\n- Legacy systems: CR (`\\r`)\n\nThe parser normalizes all line endings before processing to ensure consistent behavior regardless of the file's origin.\n\n## Schema Validation\n\n### Zod Integration\n\nOpenSpec uses Zod for schema validation throughout the system. Zod provides runtime type validation with compile-time type inference, eliminating the gap between TypeScript types and runtime behavior.\n\n**Schema Types:**\n\n| Schema | Purpose | Used By |\n|--------|---------|---------|\n| `ArtifactSchema` | Validates artifact definitions in schema.yaml | Artifact graph loader |\n| `SchemaYamlSchema` | Validates entire schema configuration files | Schema initialization |\n| `ChangeMetadataSchema` | Validates change folder metadata | Change creation and validation |\n| `SpecRequirementSchema` | Validates individual requirements | Spec parsing |\n\n### Schema Loading and Validation\n\nSchemas are loaded from `openspec/schemas//schema.yaml` and validated against the SchemaYamlSchema before use. This two-stage validation ensures that invalid schema definitions are caught early.\n\n```typescript\n// Schema loading flow\nasync function loadSchema(schemaName: string, projectRoot: string): Promise {\n const schemaPath = getSchemaPath(schemaName, projectRoot);\n const rawYaml = await fs.readFile(schemaPath, 'utf-8');\n const parsed = YAML.parse(rawYaml);\n \n // Validate against schema schema\n const result = SchemaYamlSchema.safeParse(parsed);\n if (!result.success) {\n throw new SchemaValidationError(result.error);\n }\n \n return result.data;\n}\n```\n\n## Command-Level Validation\n\n### CLI Validate Command (`src/commands/validate.ts`)\n\nThe `openspec validate` command provides the primary interface for manual and automated validation of OpenSpec artifacts.\n\n**Usage:**\n\n```bash\nopenspec validate [--strict]\nopenspec validate --specs [--all]\nopenspec validate --changes [--all]\n```\n\n**Flags:**\n\n| Flag | Description | Default |\n|------|-------------|---------|\n| `--strict` | Enable all validation rules including warnings as errors | `false` |\n| `--specs` | Validate all specs in the repository | `false` |\n| `--changes` | Validate all active changes | `true` |\n| `--all` | Include archived items in validation scope | `false` |\n| `--json` | Output machine-readable JSON format | `false` |\n\n**Validation Output:**\n\nWhen validation succeeds, the command outputs a summary table:\n\n```text\n✓ Change \"add-dark-mode\" validated successfully\n - proposal.md: valid\n - specs/auth/spec.md: valid (2 requirements, 5 scenarios)\n - tasks.md: valid (12 tasks)\n```\n\nWhen validation fails, the output includes detailed error information:\n\n```text\n✗ Validation failed for \"update-auth-flow\"\n - specs/auth/spec.md:12\n ERROR [SPEC_002]: Requirement \"Legacy export\" missing scenario\n HELP: Add at least one scenario using \"#### Scenario:\" header\n\n - specs/auth/spec.md:45\n ERROR [SPEC_003]: Invalid WHEN/THEN format\n HELP: Use \"**WHEN** condition\" and \"**THEN** outcome\" format\n```\n\n## Validation Workflows\n\n### Change Lifecycle Validation\n\n```mermaid\ngraph LR\n A[Create Change] --> B[Validate Proposal]\n B --> C{Valid?}\n C -->|No| D[Fix Errors]\n D --> B\n C -->|Yes| E[Implement Tasks]\n E --> F[Validate Specs]\n F --> G{Valid?}\n G -->|No| H[Update Specs]\n H --> F\n G -->|Yes| I[Archive Change]\n I --> J[Final Validation]\n J --> K[Merge to Source]\n```\n\n### Delta Detection Validation\n\nThe validation system extracts deltas from change spec files and validates their structure before applying them to the source specifications. This ensures that only properly formatted changes are merged.\n\n**Delta Types:**\n\n| Delta Type | Syntax | Description |\n|------------|--------|-------------|\n| ADDED | `## ADDED Requirements` | New requirements being introduced |\n| MODIFIED | `## MODIFIED Requirements` | Changes to existing requirements |\n| REMOVED | `## REMOVED Requirements` | Requirements being deleted |\n| RENAMED | `## RENAMED Requirements` | Requirements being renamed or restructured |\n\n**Delta Extraction Process:**\n\n1. Parse the spec file in the change's `specs/` directory\n2. Identify delta section headers using operation prefixes\n3. Validate each delta against the appropriate schema\n4. Check for conflicts between MODIFIED and REMOVED deltas\n5. Generate a validation report with all findings\n\n## Error Handling\n\n### Error Code Reference\n\n| Code | Category | Description | Resolution |\n|------|----------|-------------|------------|\n| `SPEC_001` | Structure | Missing required requirement | Add requirement with proper `### Requirement:` header |\n| `SPEC_002` | Content | Requirement missing scenario | Add `#### Scenario:` with WHEN/THEN format |\n| `SPEC_003` | Format | Invalid scenario syntax | Use exact `**WHEN**` and `**THEN**` format |\n| `SPEC_004` | Content | Empty requirement description | Provide description after requirement header |\n| `GRAPH_001` | Schema | Cyclic dependency detected | Review artifact `requires` field in schema.yaml |\n| `GRAPH_002` | Schema | Duplicate artifact ID | Ensure unique IDs in schema definition |\n| `DELTA_001` | Delta | Invalid delta operation | Use ADDED, MODIFIED, REMOVED, or RENAMED |\n| `DELTA_002` | Delta | Delta references missing spec | Ensure target spec exists in source specs/ |\n\n### Recovery Strategies\n\nThe validation system implements graceful degradation for common issues:\n\n**Silent Failures Prevention:**\n\n- Scenario parsing failures are caught and reported explicitly\n- Missing headers trigger specific error messages with fix suggestions\n- Format violations include the expected format in the error output\n\n**Partial Success Handling:**\n\nWhen a file contains multiple issues, validation continues to identify all problems rather than failing on the first error. This reduces the number of validation cycles needed to fix all issues.\n\n## Integration with Other Modules\n\n### Project Configuration\n\nThe validation system respects project-level configuration defined in `openspec/config.yaml`. Project-specific rules can be configured to add validation constraints beyond the defaults.\n\n```yaml\nvalidation:\n strict: true\n allowedDeltaTypes: [ADDED, MODIFIED, REMOVED]\n requireDesignArtifact: true\n```\n\n### Artifact Graph Integration\n\nValidation is integrated with the artifact graph system to validate artifact state transitions and dependency requirements. Before marking an artifact as complete, the validation system verifies all prerequisites are satisfied.\n\n### Change Manager Integration\n\nThe change manager uses validation to enforce naming conventions and structural requirements when creating new changes. Invalid change names or structures are rejected at creation time.\n\n## Best Practices\n\n### Writing Valid Specs\n\n1. **Use Exact Headers**: Always use `#### Scenario:` with four hashtags for scenarios\n2. **Follow WHEN/THEN Format**: Structure scenarios with clear conditions and outcomes\n3. **Include All Scenarios**: Every requirement must have at least one scenario\n4. **Use ADDED/MODIFIED/REMOVED**: Prefix delta sections with operation names\n5. **Keep Scenarios Testable**: Scenarios should describe observable behavior\n\n### Validation in CI/CD\n\nIntegrate validation into continuous integration pipelines:\n\n```yaml\n# Example CI configuration\n- name: Validate OpenSpec changes\n run: |\n npx openspec validate --changes --strict\n```\n\n### Debugging Validation Failures\n\nWhen validation fails, use the JSON output for programmatic inspection:\n\n```bash\nopenspec show add-feature --json --deltas-only\n```\n\nThis outputs the parsed deltas without full change details, helping identify parsing issues.\n\n---\n\n\n\n## Supported AI Tools\n\n### 相关页面\n\n相关主题：[Slash Commands](#slash-commands)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/supported-tools.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/supported-tools.md)\n- [src/core/available-tools.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/available-tools.ts)\n- [src/core/command-generation/adapters/index.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/command-generation/adapters/index.ts)\n- [README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md)\n- [CHANGELOG.md](https://github.com/Fission-AI/OpenSpec/blob/main/CHANGELOG.md)\n \n\n# Supported AI Tools\n\nOpenSpec is designed to integrate seamlessly with a wide variety of AI coding assistants. The supported AI tools system enables OpenSpec to provide consistent specification workflows across different development environments and toolchains.\n\n## Overview\n\nOpenSpec supports AI tools through a multi-layered integration system that includes:\n\n- **Native Slash Commands**: Built-in commands directly recognized by the AI tool\n- **Slash Command Templates**: Tool-specific command files with frontmatter metadata\n- **AGENTS.md Compatible**: Workflow instructions that AI tools can automatically discover\n\n资料来源：[README.md:1-100]()\n\n## Architecture\n\nThe AI tools integration is built on a modular architecture with three core components:\n\n```mermaid\ngraph TD\n A[User Request] --> B[OpenSpec CLI]\n B --> C{Determine Tool}\n C --> D[Claude Code]\n C --> E[Cursor]\n C --> F[Codex]\n C --> G[Amazon Q]\n C --> H[Other Tools]\n \n D --> I[Slash Commands]\n E --> J[Cursor Commands]\n F --> K[Codex Commands]\n G --> L[Q Developer Prompts]\n H --> M[AGENTS.md]\n \n I --> N[openspec/proposal
openspec/apply
openspec/archive]\n J --> O[openspec-proposal
openspec-apply
openspec-archive]\n```\n\n资料来源：[src/core/command-generation/adapters/index.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/command-generation/adapters/index.ts)\n\n## Supported Tools List\n\nOpenSpec integrates with the following AI coding assistants:\n\n| Tool | Slash Commands | Command Directory | Category |\n|------|---------------|-------------------|----------|\n| **Claude Code** | `/openspec/proposal`, `/openspec/apply`, `/openspec/archive` | `.claude/commands/openspec/` | Native |\n| **Cursor** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.cursor/commands/` | Native |\n| **CodeBuddy Code** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` | `.codebuddy/commands/` | Native |\n| **Amazon Q Developer** | `@openspec-proposal`, `@openspec-apply`, `@openspec-archive` | `.amazonq/prompts/` | Native |\n| **Windsurf** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.windsurf/workflows/` | Native |\n| **RooCode** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.roo/commands/` | Native |\n| **Augment CLI** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.augment/commands/` | Native |\n| **Antigravity** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.agent/workflows/` | Native |\n| **Cline** | Workflows in `.clinerules/workflows/` | `.clinerules/workflows/openspec-*.md` | Native |\n| **Kilo Code** | Command palette triggers | `.kilocode/workflows/` | Native |\n| **Gemini CLI** | TOML-based commands | `.gemini/commands/openspec/` | Native |\n| **Qwen Code** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` | — | Native |\n| **CoStrict AI** | — | — | Native |\n| **Qoder CLI** | — | — | Native |\n| **Continue** | `/openspec-proposal.md`, `/openspec-apply.md`, `/openspec-archive.md` | `.continue/prompts/` | Native |\n\n资料来源：[docs/supported-tools.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/supported-tools.md)\n\n## Tool Categories\n\n### Native Slash Commands\n\nTools with native slash command support have built-in OpenSpec commands. When initializing OpenSpec for these tools, select the appropriate integration option.\n\n```mermaid\ngraph LR\n A[openspec init] --> B[Select Tool]\n B --> C[Claude Code]\n B --> D[Cursor]\n B --> E[Windsurf]\n \n C --> F[Creates: .claude/commands/openspec/]\n D --> G[Creates: .cursor/commands/]\n E --> H[Creates: .windsurf/workflows/]\n```\n\n资料来源：[README.md:150-200]()\n\n### AGENTS.md Compatible\n\nSome tools automatically read workflow instructions from `openspec/AGENTS.md`. These tools can be instructed to follow the OpenSpec workflow using natural language.\n\n| Tool | Support Level |\n|------|---------------|\n| Amp | Compatible |\n| Jules | Compatible |\n| Others | Via AGENTS.md convention |\n\n资料来源：[README.md:200-250]()\n\n## Command Structure\n\n### Slash Command Format\n\nCommands follow a consistent pattern across tools but with tool-specific adaptations:\n\n```markdown\n---\nname: openspec-proposal\ndescription: Create a new OpenSpec change proposal\ncategory: OpenSpec\n---\n\n...command body...\n\n```\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md)\n\n### Command Naming Conventions\n\n| Tool | Naming Style | Example |\n|------|-------------|---------|\n| Claude Code | Namespaced with `/` | `/openspec/proposal` |\n| Cursor | Flat with `openspec-` prefix | `/openspec-proposal` |\n| Windsurf | Flat with `openspec-` prefix | `/openspec-proposal` |\n| RooCode | Flat with `openspec-` prefix | `/openspec-proposal` |\n| Gemini CLI | TOML-based configuration | — |\n\n### Marker Placement Rules\n\nCommands must follow strict marker placement rules:\n\n1. **Frontmatter goes first** (if supported by the tool)\n2. **``** marker opens the body\n3. Command body content follows\n4. **``** marker closes the body\n\n```markdown\n---\nname: openspec-apply\ndescription: Apply OpenSpec change tasks\ncategory: OpenSpec\n---\n\nStep-by-step instructions for applying tasks...\n\n```\n\n**Critical**: Markers must never be placed inside the YAML frontmatter block.\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/design.md)\n\n## Configuration\n\n### Tool Configuration Interface\n\nThe `AIToolOption` interface defines how tools are configured:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `id` | `string` | Unique identifier for the tool |\n| `name` | `string` | Display name |\n| `skillsDir` | `string` | Path to tool's skill/command directory |\n| `commandPrefix` | `string` | Prefix for slash commands |\n| `frontmatterFormat` | `string` | Supported frontmatter type |\n\n资料来源：[src/core/available-tools.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/available-tools.ts)\n\n### Command Generation Adapters\n\nThe adapter pattern allows OpenSpec to generate tool-specific command files:\n\n```mermaid\nclassDiagram\n class ToolCommandAdapter {\n +generate(content: CommandContent): string\n +getFilePath(toolId: string): string\n +supportsFrontmatter(): boolean\n }\n \n class CommandContent {\n +id: string\n +name: string\n +description: string\n +body: string\n }\n \n class CommandGenerator {\n +generateAll(content: CommandContent, toolId: string)\n +updateExisting(content: CommandContent, toolId: string)\n }\n \n CommandGenerator --> ToolCommandAdapter\n CommandGenerator --> CommandContent\n```\n\n资料来源：[src/core/command-generation/adapters/index.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/command-generation/adapters/index.ts)\n\n## Initialization Workflow\n\nWhen running `openspec init`, the CLI performs the following steps:\n\n```mermaid\ngraph TD\n A[openspec init] --> B{Interactive or --tool flag?}\n B -->|Interactive| C[Prompt for tool selection]\n B -->|--tool| D[Use specified tool]\n \n C --> E[Select from available tools]\n D --> F[Validate tool ID]\n \n E --> G[Create tool directories]\n F --> G\n G --> H[Generate command files]\n H --> I[Apply OPENSPEC markers]\n I --> J[Confirmation message]\n```\n\n### Idempotency Rules\n\n| Operation | Behavior |\n|-----------|----------|\n| `init` | Create all command files once; subsequent runs are no-ops for existing files |\n| `update` | Refresh only existing files; do not create missing files |\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/design.md)\n\n## Adding New Tool Support\n\n### Design Pattern\n\nTo add support for a new AI tool, implement the following:\n\n1. **Create a tool adapter** in `src/core/command-generation/adapters/`\n2. **Define tool configuration** in `src/core/available-tools.ts`\n3. **Add command templates** for proposal, apply, and archive actions\n4. **Update documentation** in `docs/supported-tools.md`\n\n### Example Adapter Structure\n\n```typescript\n// src/core/command-generation/adapters/newtool-adapter.ts\nimport { ToolCommandAdapter } from './base';\n\nexport class NewToolAdapter implements ToolCommandAdapter {\n supportsFrontmatter(): boolean {\n return true;\n }\n \n getFilePath(): string {\n return '.newtool/commands/openspec';\n }\n \n generate(content: CommandContent): string {\n return this.wrapWithMarkers(content.body);\n }\n}\n```\n\n### Testing Strategy\n\n| Test Type | Purpose |\n|-----------|---------|\n| Golden snapshots | Verify generated files per tool (frontmatter + markers + body) |\n| Partial presence tests | Ensure `update` only refreshes existing files |\n| Marker placement tests | Verify markers never appear inside frontmatter |\n| Logging tests | Confirm `update` reports per-file results |\n\n资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md)\n\n## Version History\n\n### Version 1.3.0+\nAdded support for:\n- Gemini CLI with native TOML-based slash command support\n- RooCode integration with full configurator support\n- Cline workflows (moved from `.clinerules/rules/` to `.clinerules/workflows/`)\n- Continue prompt generation with MARKDOWN frontmatter and `$ARGUMENTS` placeholder\n\n资料来源：[CHANGELOG.md](https://github.com/Fission-AI/OpenSpec/blob/main/CHANGELOG.md)\n\n### Version 0.15.0+\nAdded support for:\n- Gemini CLI\n- RooCode\n- Cline (workflows)\n- Qwen Code\n- Qoder CLI\n- CoStrict AI\n\n### Version 0.14.0+\nAdded support for:\n- Qwen Code with slash command integration\n- `$ARGUMENTS` support in apply slash command\n- Qoder CLI support\n\n## Troubleshooting\n\n### Commands Not Appearing\n\nIf slash commands are not appearing:\n\n1. Verify the tool directory exists: `.claude/commands/openspec/`\n2. Check file naming matches expected pattern\n3. Run `openspec update` to refresh command files\n4. Restart the AI tool to reload commands\n\n### Marker Errors\n\nIf you see parsing errors:\n\n- Ensure `` and `` are on separate lines\n- Verify markers are not inside YAML frontmatter\n- Check for duplicate markers in the file\n\n### Tool Not Recognized\n\nFor unsupported tools:\n\n- Use `AGENTS.md` convention for workflow discovery\n- Run `openspec init` to see all available tool options\n- Check [docs/supported-tools.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/supported-tools.md) for the latest supported list\n\n## See Also\n\n- [Getting Started](docs/getting-started.md) - First steps with OpenSpec\n- [Workflows](docs/workflows.md) - Combos and patterns\n- [Commands](docs/commands.md) - Slash commands and skills reference\n- [Customization](docs/customization.md) - Making OpenSpec yours\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：Fission-AI/OpenSpec\n\n摘要：发现 22 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：/opsx:apply suggests openspec-continue-change which is not installed on core profile。\n\n## 1. 安装坑 · 来源证据：/opsx:apply suggests openspec-continue-change which is not installed on core profile\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：/opsx:apply suggests openspec-continue-change which is not installed on core profile\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_41aca88207aa4e70bba9c2ebaef629c7 | https://github.com/Fission-AI/OpenSpec/issues/963 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 配置坑 · 来源证据：Support schema extension or partial overrides to avoid full shadowing of built-in schemas\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Support schema extension or partial overrides to avoid full shadowing of built-in schemas\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_34110f57274440d4bbc5492e3b4f3bee | https://github.com/Fission-AI/OpenSpec/issues/1074 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 维护坑 · 来源证据：open:sync messed up my spec.md files\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：open:sync messed up my spec.md files\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ef1856d2856b49f5a7ed758bfc4099c8 | https://github.com/Fission-AI/OpenSpec/issues/911 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：Codex generated assets reference unsupported AskUserQuestion/TodoWrite/Task tools\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Codex generated assets reference unsupported AskUserQuestion/TodoWrite/Task tools\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_35b315a2b1a74564be1fb71d1f08359c | https://github.com/Fission-AI/OpenSpec/issues/1103 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：First steps don't work\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：First steps don't work\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_51f62d023b734ba59978cc70908c01c3 | https://github.com/Fission-AI/OpenSpec/issues/820 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 安装坑 · 来源证据：v1.1.0 - Cross-Platform Fixes, Nix Improvements\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.1.0 - Cross-Platform Fixes, Nix Improvements\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_016f567cecd44fbf96ffd635e1ec43bf | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.1.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：v1.3.1 - Path & Telemetry Fixes\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.3.1 - Path & Telemetry Fixes\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e641868122bb43938d6ff8a83b71e3d3 | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.3.1 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 8. 配置坑 · 来源证据：Incomplete artifacts marked as \"done\" after workflow interruption\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Incomplete artifacts marked as \"done\" after workflow interruption\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a0677545a17b433ca6e6561c5056ee46 | https://github.com/Fission-AI/OpenSpec/issues/1084 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 9. 配置坑 · 来源证据：OpenCode sync missing\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：OpenCode sync missing\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0076a9fb05a1443eb3e2a7c9185247e6 | https://github.com/Fission-AI/OpenSpec/issues/1007 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. 配置坑 · 来源证据：v0.22.0 - Project Configuration\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.22.0 - Project Configuration\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1a526029491b40e38c20ba075f311169 | https://github.com/Fission-AI/OpenSpec/releases/tag/v0.22.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 11. 配置坑 · 来源证据：v1.0.0 - The OPSX Release\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.0.0 - The OPSX Release\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b60a0c136c0347e9a034197f65844e1b | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.0.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 12. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1032459340 | https://github.com/Fission-AI/OpenSpec | README/documentation is current enough for a first validation pass.\n\n## 13. 运行坑 · 来源证据：v1.0.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.0.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_006cb659e21c431290fe448ddabc453c | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.0.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 14. 运行坑 · 来源证据：v1.0.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.0.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c7797487985047fba066bd58cba094ae | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.0.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 15. 维护坑 · 来源证据：Feedback: Deep verification test - PUA mode v3 active\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Feedback: Deep verification test - PUA mode v3 active\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d3d2fc07081648f796e477458600a95f | https://github.com/Fission-AI/OpenSpec/issues/1094 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 16. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1032459340 | https://github.com/Fission-AI/OpenSpec | last_activity_observed missing\n\n## 17. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1032459340 | https://github.com/Fission-AI/OpenSpec | no_demo; severity=medium\n\n## 18. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1032459340 | https://github.com/Fission-AI/OpenSpec | no_demo; severity=medium\n\n## 19. 安全/权限坑 · 来源证据：Protect OpenSpec from AI slop PRs\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Protect OpenSpec from AI slop PRs\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a941eca296774492b16583764132d1f8 | https://github.com/Fission-AI/OpenSpec/issues/1087 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 20. 安全/权限坑 · 来源证据：[Feature Request/Suggestion] Extension to package for custom schemas, associated skills, commands, hooks, and profiles\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature Request/Suggestion] Extension to package for custom schemas, associated skills, commands, hooks, and profiles\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_abcb3cf5661b4a19862619c854eb531d | https://github.com/Fission-AI/OpenSpec/issues/1081 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 21. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1032459340 | https://github.com/Fission-AI/OpenSpec | issue_or_pr_quality=unknown\n\n## 22. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1032459340 | https://github.com/Fission-AI/OpenSpec | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：Fission-AI/OpenSpec\n\n摘要：发现 22 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：/opsx:apply suggests openspec-continue-change which is not installed on core profile。\n\n## 1. 安装坑 · 来源证据：/opsx:apply suggests openspec-continue-change which is not installed on core profile\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：/opsx:apply suggests openspec-continue-change which is not installed on core profile\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_41aca88207aa4e70bba9c2ebaef629c7 | https://github.com/Fission-AI/OpenSpec/issues/963 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 配置坑 · 来源证据：Support schema extension or partial overrides to avoid full shadowing of built-in schemas\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Support schema extension or partial overrides to avoid full shadowing of built-in schemas\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_34110f57274440d4bbc5492e3b4f3bee | https://github.com/Fission-AI/OpenSpec/issues/1074 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 维护坑 · 来源证据：open:sync messed up my spec.md files\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：open:sync messed up my spec.md files\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ef1856d2856b49f5a7ed758bfc4099c8 | https://github.com/Fission-AI/OpenSpec/issues/911 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：Codex generated assets reference unsupported AskUserQuestion/TodoWrite/Task tools\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Codex generated assets reference unsupported AskUserQuestion/TodoWrite/Task tools\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_35b315a2b1a74564be1fb71d1f08359c | https://github.com/Fission-AI/OpenSpec/issues/1103 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：First steps don't work\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：First steps don't work\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_51f62d023b734ba59978cc70908c01c3 | https://github.com/Fission-AI/OpenSpec/issues/820 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 安装坑 · 来源证据：v1.1.0 - Cross-Platform Fixes, Nix Improvements\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.1.0 - Cross-Platform Fixes, Nix Improvements\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_016f567cecd44fbf96ffd635e1ec43bf | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.1.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：v1.3.1 - Path & Telemetry Fixes\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.3.1 - Path & Telemetry Fixes\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e641868122bb43938d6ff8a83b71e3d3 | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.3.1 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 8. 配置坑 · 来源证据：Incomplete artifacts marked as \"done\" after workflow interruption\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Incomplete artifacts marked as \"done\" after workflow interruption\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a0677545a17b433ca6e6561c5056ee46 | https://github.com/Fission-AI/OpenSpec/issues/1084 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 9. 配置坑 · 来源证据：OpenCode sync missing\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：OpenCode sync missing\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0076a9fb05a1443eb3e2a7c9185247e6 | https://github.com/Fission-AI/OpenSpec/issues/1007 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. 配置坑 · 来源证据：v0.22.0 - Project Configuration\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.22.0 - Project Configuration\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1a526029491b40e38c20ba075f311169 | https://github.com/Fission-AI/OpenSpec/releases/tag/v0.22.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 11. 配置坑 · 来源证据：v1.0.0 - The OPSX Release\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.0.0 - The OPSX Release\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b60a0c136c0347e9a034197f65844e1b | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.0.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 12. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1032459340 | https://github.com/Fission-AI/OpenSpec | README/documentation is current enough for a first validation pass.\n\n## 13. 运行坑 · 来源证据：v1.0.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.0.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_006cb659e21c431290fe448ddabc453c | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.0.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 14. 运行坑 · 来源证据：v1.0.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.0.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c7797487985047fba066bd58cba094ae | https://github.com/Fission-AI/OpenSpec/releases/tag/v1.0.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 15. 维护坑 · 来源证据：Feedback: Deep verification test - PUA mode v3 active\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Feedback: Deep verification test - PUA mode v3 active\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d3d2fc07081648f796e477458600a95f | https://github.com/Fission-AI/OpenSpec/issues/1094 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 16. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1032459340 | https://github.com/Fission-AI/OpenSpec | last_activity_observed missing\n\n## 17. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1032459340 | https://github.com/Fission-AI/OpenSpec | no_demo; severity=medium\n\n## 18. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1032459340 | https://github.com/Fission-AI/OpenSpec | no_demo; severity=medium\n\n## 19. 安全/权限坑 · 来源证据：Protect OpenSpec from AI slop PRs\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Protect OpenSpec from AI slop PRs\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a941eca296774492b16583764132d1f8 | https://github.com/Fission-AI/OpenSpec/issues/1087 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 20. 安全/权限坑 · 来源证据：[Feature Request/Suggestion] Extension to package for custom schemas, associated skills, commands, hooks, and profiles\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature Request/Suggestion] Extension to package for custom schemas, associated skills, commands, hooks, and profiles\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_abcb3cf5661b4a19862619c854eb531d | https://github.com/Fission-AI/OpenSpec/issues/1081 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 21. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1032459340 | https://github.com/Fission-AI/OpenSpec | issue_or_pr_quality=unknown\n\n## 22. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1032459340 | https://github.com/Fission-AI/OpenSpec | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# OpenSpec - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for Fission-AI/OpenSpec.\n\nProject:\n- Name: OpenSpec\n- Repository: https://github.com/Fission-AI/OpenSpec\n- Summary: Spec-driven development (SDD) for AI coding assistants.\n- Host target: local_cli\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: Spec-driven development (SDD) for AI coding assistants.\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Spec-driven development (SDD) for AI coding assistants.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. introduction: Introduction to OpenSpec. Produce one small intermediate artifact and wait for confirmation.\n2. getting-started: Getting Started. Produce one small intermediate artifact and wait for confirmation.\n3. architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n4. slash-commands: Slash Commands. Produce one small intermediate artifact and wait for confirmation.\n5. workflows: Workflows. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/Fission-AI/OpenSpec\n- https://github.com/Fission-AI/OpenSpec#readme\n- README.md\n- docs/concepts.md\n- docs/getting-started.md\n- docs/installation.md\n- package.json\n- src/core/init.ts\n- src/index.ts\n- src/cli/index.ts\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：Fission-AI/OpenSpec\n\n## 官方安装入口\n\n### Node.js / npm · 官方安装入口\n\n```bash\nnpm install -g @fission-ai/openspec@latest\n```\n\n来源：https://github.com/Fission-AI/OpenSpec#readme\n\n## 来源\n\n- repo: https://github.com/Fission-AI/OpenSpec\n- docs: https://github.com/Fission-AI/OpenSpec#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_bf038cb8d2444b7e9b33261fa07cd526"
}