index.md

Docs Index

• Status: active
• Source of truth: README.md, AGENTS.md, docs/structure.md, llms.txt
• Verified with: npm run build, npm run test:unit, npm run validate:docs
• Last verified: 2026-03-25

Purpose

This file is the shortest stable map for humans and AI agents reading Spec2Flow.

Spec2Flow是一个“自动驾驶”级别的软件工程控制台（Autonomous Engineering Control Plane）。它不仅仅是一个任务管理工具，而是一个能够观察 Agent 思考、编码、测试和自我修复过程的“数字指挥部”

Use it to answer two questions quickly:

1. which document should I read first for this task?
2. which file is the source of truth for this topic?

Read First

1. llms.txt
2. AGENTS.md
3. docs/index.md
4. README.md

Repository intake rule for AI agents:

• Read llms.txt first on every new task.
• Read AGENTS.md next for repository boundaries.
• Use this index third to choose the smallest relevant source-of-truth set before reading deeper docs or code.

Docs governance quick path:

• active docs layout and source-of-truth rules: docs/structure.md
• plan placement and archive rules: docs/plans/index.md

By Question

What is Spec2Flow?

• README.md

What are the repository rules and architecture boundaries?

• AGENTS.md
• docs/architecture.md
• docs/agent-orchestration-platform-design.md
• docs/adr/index.md

How should Copilot behave in this repository?

• .github/copilot-instructions.md
• docs/copilot.md
• docs/Harness_engineering.md

Which document applies to the file I am editing?

• docs instructions
• TypeScript CLI instructions
• schema instructions

Where do active docs rules and archived plan rules live?

• active docs governance: docs/structure.md
• archived plan and plan-placement rules: docs/plans/index.md

How does the runtime work?

• docs/architecture.md
• docs/agent-orchestration-platform-design.md
• docs/runtime-config-reference.md
• packages/cli/src/runtime/
• packages/cli/src/planning/
• packages/cli/src/adapters/

How should Spec2Flow evolve into an agent orchestration platform?

• docs/agent-orchestration-platform-design.md
• docs/cross-project-agent-orchestration-evolution.md
• docs/project-workspace-autonomous-delivery-design.md
• docs/ui/operator-console.md
• docs/architecture.md
• docs/synapse-integration-automation-design.md

How do I adopt or run the workflow?

• docs/ops-startup-guide.md — start API server, web UI, worker, and run DB migration
• docs/usage-guide.md
• docs/runtime-config-reference.md
• docs/playbooks/index.md
• docs/collaboration.md
• docs/examples/synapse-network/README.md

How should local artifact storage and the MinIO upgrade path work?

• docs/object-store-local-first-design.md
• docs/playbooks/automated-execution.md
• docs/usage-guide.md

How should one project, one workspace, and one autonomous delivery run fit together?

• docs/project-workspace-autonomous-delivery-design.md
• docs/agent-orchestration-platform-design.md
• docs/usage-guide.md

How should the web control plane product UI be designed?

• docs/ui/index.md
• docs/ui/operator-console.md
• docs/ui/visual-language.md
• docs/ui/interaction-concepts.md
• docs/plans/web-control-plane-frontend-implementation.md
• docs/project-workspace-autonomous-delivery-design.md

Where do the UI mockups, screenshots, and generated prototypes live?

• docs/ui/index.md
• docs/ui/reference/README.md

Where did the older plans go?

• docs/plans/index.md
• docs/plans/historical/index.md

What should an agent do in each workflow stage?

• docs/playbooks/index.md
• docs/playbooks/requirements-analysis.md
• docs/playbooks/code-implementation.md
• docs/playbooks/test-design.md
• docs/playbooks/automated-execution.md
• docs/playbooks/defect-feedback.md
• docs/playbooks/collaboration.md

What are the enforceable contracts?

• schemas/
• schemas/task-graph.schema.json
• schemas/execution-state.schema.json
• schemas/model-adapter-capability.schema.json
• schemas/model-adapter-runtime.schema.json

Source Of Truth Map

Product overview

• primary: README.md

Architecture and boundaries

• primary: AGENTS.md
• supporting: docs/architecture.md

Platform evolution design

• primary: docs/agent-orchestration-platform-design.md
• supporting: docs/architecture.md

Project workspace autonomous delivery

• primary: docs/project-workspace-autonomous-delivery-design.md
• supporting: docs/agent-orchestration-platform-design.md

Web control plane product UI

• primary: docs/ui/operator-console.md
• supporting: docs/ui/visual-language.md

Copilot operating policy

• primary: .github/copilot-instructions.md
• supporting: docs/copilot.md

AI-facing repository optimization

• primary: docs/Harness_engineering.md

Stable architecture decisions

• primary: docs/adr/index.md
• supporting: docs/architecture.md

Repository layout

• primary: docs/structure.md
• supporting: docs/plans/index.md

Workflow adoption and commands

• primary: docs/usage-guide.md
• supporting: docs/runtime-config-reference.md

Artifact storage and retrieval

• primary: docs/object-store-local-first-design.md
• supporting: docs/playbooks/automated-execution.md

Stage-scoped execution guidance

• primary: docs/playbooks/index.md
• supporting: docs/Harness_engineering.md

Runtime contracts

• primary: schemas/
• supporting: packages/cli/src/types/

Execution behavior

• primary: packages/cli/src/runtime/
• supporting: docs/examples/synapse-network/generated/

Stable Validation Paths

• npm run build
• npm run typecheck
• npm run test:unit
• npm run validate:docs
• npm run validate:synapse-example
• npm run generate:synapse-task-graph
• npm run generate:synapse-execution-state
• npm run preflight:copilot-cli

What Not To Treat As Source Of Truth

• .spec2flow/
• spec2flow/outputs/

These paths contain runtime evidence and local execution artifacts. They are useful for debugging and examples, but they do not define the repository contract.