Planning and Blueprinting System

规划与蓝图体系

A minimal, enforceable system for doing planning, blueprinting, and specification inside a codebase using two core concepts: plans (proposals) and specs (contracts).

这是一个轻量、可强制执行的体系，可用于在代码库中开展规划、蓝图设计和规范制定工作，核心围绕两个概念展开：plans（提案） 和 specs（契约）。

When to Apply

适用场景

Use this skill when:

Creating a proposal or blueprint for new work
Documenting accepted specifications
Doing architectural planning
Tracking decision and implementation status
Promoting a plan to a formal specification

在以下场景中使用本工具：

为新工作创建提案或蓝图
记录已通过的规范
开展架构规划
跟踪决策和落地进度
将提案升级为正式规范

Core Concepts

核心概念

Plan — A proposal, blueprint, or work-in-progress design. Plans are iterative, may contain open questions, and are not authoritative contracts.

Spec — An accepted contract and source of truth. Specs define reference behavior that reviewers and tests enforce. They must remain accurate over time.

Plan — 提案、蓝图或正在迭代的设计稿。Plan 是迭代式的，可能包含待解决的问题，不属于具有权威性的契约。

Spec — 已通过的契约和唯一可信源。Spec 定义了评审人员和测试环节要强制执行的参考行为，必须长期保持准确性。

Folder Structure

文件夹结构

Create this structure in the repository when needed:

docs/
├── README.md              # Overview and rules
├── plan/
│   ├── README.md          # Plan guidelines
│   └── template.plan.md   # Plan template
└── spec/
    ├── README.md          # Spec guidelines
    └── template.spec.md   # Spec template

需要时在代码仓库中创建如下结构：

docs/
├── README.md              # Overview and rules
├── plan/
│   ├── README.md          # Plan guidelines
│   └── template.plan.md   # Plan template
└── spec/
    ├── README.md          # Spec guidelines
    └── template.spec.md   # Spec template

Promotion Flow

晋升流程

plan (Draft) → plan (In Review) → plan (Accepted) → spec

When a plan reaches Accepted status, promote it into

docs/spec/

as a formal specification.

plan (Draft) → plan (In Review) → plan (Accepted) → spec

当 Plan 状态变为 Accepted（已通过） 时，将其升级为正式规范并存放在

docs/spec/

目录下。

Two-Axis Status Tracking for Specs

Spec 双维度状态跟踪

Specs must track two independent dimensions:

Spec 必须跟踪两个独立的维度：

Decision Status (contract lifecycle)

决策状态（契约生命周期）

Status	Meaning
Draft	Under development, not yet accepted
Accepted	Approved as the authoritative contract
Deprecated	No longer recommended, superseded or obsolete
Superseded	Replaced by a newer spec

状态	含义
Draft（草稿）	仍在编写中，尚未通过评审
Accepted（已通过）	已被批准为权威契约
Deprecated（已弃用）	不再推荐使用，已被取代或过时
Superseded（已替换）	已被更新的 spec 替代

Implementation Status (delivery lifecycle)

落地状态（交付生命周期）

Status	Meaning
Not Implemented	Work has not started
In Progress	Active development
Partial	Some parts implemented
Implemented	Fully complete
Blocked	Cannot proceed due to dependencies

状态	含义
Not Implemented（未落地）	尚未启动开发工作
In Progress（开发中）	正在积极开发
Partial（部分落地）	部分功能已实现
Implemented（已落地）	全部开发完成
Blocked（阻塞）	因依赖问题无法推进

Rules

规则

Plans are not contracts. They may be messy, incomplete, or exploratory.
Specs are contracts. They must remain accurate and are the authoritative reference for implementation and testing.
Specs may describe future behavior only when Decision Status = Accepted. This allows specs to document planned work before implementation begins.
Status fields are authoritative. Update them as work progresses.
Architecture uses Constructive tooling. Designs should leverage constructive-skills and interoperable Constructive patterns where applicable.

Plan 不属于契约。 可以是粗糙、不完整或探索性的。
Spec 属于契约。 必须保持准确性，是落地和测试环节的权威参考。
仅当决策状态为 Accepted 时，Spec 可描述未来行为 这支持在开发启动前，就用 Spec 记录规划中的工作内容。
状态字段是权威依据。 随着工作推进及时更新状态。
架构使用 Constructive 工具。 适用场景下，设计应利用 constructive-skills 和可互通的 Constructive 模式。

Plan Template

Plan 模板

markdown

undefined

markdown

undefined

[Plan Title]

Field	Value
Status	Draft / In Review / Accepted / Rejected
Owner	@username
Created	YYYY-MM-DD
Related	#issue, #pr

Field	Value
Status	Draft / In Review / Accepted / Rejected
Owner	@username
Created	YYYY-MM-DD
Related	#issue, #pr

Problem Statement

What problem does this solve? Why does it matter?

Goals

What this plan aims to achieve.

Non-Goals

What is explicitly out of scope.

Proposal

High-level approach to solving the problem.

Detailed Design

Technical blueprint: architecture, data flow, component interactions.

Milestones

Milestone	Description	Target
M1	...	...

Milestone	Description	Target
M1	...	...

Rollout Plan

How this will be deployed/released. Phasing, feature flags, migration steps.

Risks and Mitigations

Risk	Likelihood	Impact	Mitigation
...	...	...	...

Risk	Likelihood	Impact	Mitigation
...	...	...	...

Alternatives Considered

Other approaches evaluated and why they were not chosen.

Open Questions

Question 1
Question 2

undefined

Question 1
Question 2

undefined

Spec Template

Spec 模板

markdown

undefined

markdown

undefined

[Spec Title]

Field	Value
Decision Status	Draft / Accepted / Deprecated / Superseded
Implementation Status	Not Implemented / In Progress / Partial / Implemented / Blocked
Last Updated	YYYY-MM-DD
Plan	[link to plan]
Issues	#issue
PRs	#pr

Field	Value
Decision Status	Draft / Accepted / Deprecated / Superseded
Implementation Status	Not Implemented / In Progress / Partial / Implemented / Blocked
Last Updated	YYYY-MM-DD
Plan	[link to plan]
Issues	#issue
PRs	#pr

Summary

Brief description of what this spec defines.

Definitions

Key terms and their meanings within this spec.

Requirements

Functional

What the system must do.

Non-Functional

Performance, security, reliability, and other quality attributes.

Behavior

Expected system behavior under normal and edge conditions.

Interfaces

API

Endpoints, methods, request/response formats.

Data Model

Schemas, entities, relationships.

Edge Cases

How the system handles boundary conditions and error states.

Observability

Logging, metrics, alerts, and debugging support.

Test Plan

How compliance with this spec is verified.

Implementation Notes

Links to PRs, technical decisions made during implementation.

Changelog

Date	Change	Author
YYYY-MM-DD	Initial spec	@username

undefined

Date	Change	Author
YYYY-MM-DD	Initial spec	@username

undefined

docs/README.md Template

docs/README.md 模板

markdown

undefined

markdown

undefined

Documentation System

This directory contains the in-repo planning and specification system.

Concepts

Plan — A proposal, blueprint, or work-in-progress design. Plans live in

docs/plan/

.

Spec — An accepted contract and source of truth. Specs live in

docs/spec/

.

Plan — A proposal, blueprint, or work-in-progress design. Plans live in

docs/plan/

.

Spec — An accepted contract and source of truth. Specs live in

docs/spec/

.

Promotion Flow

plan (Draft) → plan (In Review) → plan (Accepted) → spec

Rules

Plans are not contracts. They may be messy or exploratory.
Specs are contracts. They must remain accurate.
Specs may describe future behavior only when Decision Status = Accepted.
Status fields are authoritative. Update them as work progresses.

undefined

Plans are not contracts. They may be messy or exploratory.
Specs are contracts. They must remain accurate.
Specs may describe future behavior only when Decision Status = Accepted.
Status fields are authoritative. Update them as work progresses.

undefined

docs/plan/README.md Template

docs/plan/README.md 模板

markdown

undefined

markdown

undefined

Plans

Plans are blueprints and proposals. They are allowed to be messy and iterative, may contain open questions, and are not authoritative contracts.

When a plan is accepted, it is promoted into

docs/spec/

.

Plans are blueprints and proposals. They are allowed to be messy and iterative, may contain open questions, and are not authoritative contracts.

When a plan is accepted, it is promoted into

docs/spec/

.

Creating a Plan

Copy
```
template.plan.md
```
to a new file
Fill in the sections
Set Status to Draft
Submit for review when ready

undefined

Copy
```
template.plan.md
```
to a new file
Fill in the sections
Set Status to Draft
Submit for review when ready

undefined

docs/spec/README.md Template

docs/spec/README.md 模板

markdown

undefined

markdown

undefined

Specifications

Specs are accepted contracts and reference behavior. They are the source of truth for implementation and tests. Specs must remain accurate over time.

Specs may describe not-yet-implemented behavior only when explicitly marked with Decision Status = Accepted.

Specs are accepted contracts and reference behavior. They are the source of truth for implementation and tests. Specs must remain accurate over time.

Specs may describe not-yet-implemented behavior only when explicitly marked with Decision Status = Accepted.

Status Tracking

Specs track two independent dimensions:

Decision Status: Draft, Accepted, Deprecated, Superseded

Implementation Status: Not Implemented, In Progress, Partial, Implemented, Blocked

undefined

Specs track two independent dimensions:

Decision Status: Draft, Accepted, Deprecated, Superseded

Implementation Status: Not Implemented, In Progress, Partial, Implemented, Blocked

undefined

Best Practices

最佳实践

Keep plans focused: One plan per feature or change
Update status promptly: Status fields should reflect current reality
Link related artifacts: Connect plans to issues, PRs, and specs
Prune deprecated specs: Mark old specs as Deprecated or Superseded
Dense content: Be succinct yet descriptive, avoid verbose cruft

保持 Plan 聚焦 每个 Plan 仅对应一个功能或变更
及时更新状态 状态字段应反映当前真实情况
关联相关产物 将 Plan 关联到 issue、PR 和 Spec
清理已弃用的 Spec 将旧 Spec 标记为 Deprecated 或 Superseded
内容紧凑 简洁且信息全面，避免冗余内容

planning-blueprinting

Original

Translation

Planning and Blueprinting System

规划与蓝图体系

When to Apply

适用场景

Core Concepts

核心概念

Folder Structure

文件夹结构

Promotion Flow

晋升流程

Two-Axis Status Tracking for Specs

Spec 双维度状态跟踪

Decision Status (contract lifecycle)

决策状态（契约生命周期）

Implementation Status (delivery lifecycle)

落地状态（交付生命周期）

Rules

规则

Plan Template

Plan 模板

[Plan Title]

[Plan Title]

Problem Statement

Problem Statement

Goals

Goals

Non-Goals

Non-Goals

Proposal

Proposal

Detailed Design

Detailed Design

Milestones

Milestones

Rollout Plan

Rollout Plan

Risks and Mitigations

Risks and Mitigations

Alternatives Considered

Alternatives Considered

Open Questions

Open Questions

Spec Template

Spec 模板

[Spec Title]

[Spec Title]

Summary

Summary

Definitions

Definitions

Requirements

Requirements

Functional

Functional

Non-Functional

Non-Functional

Behavior

Behavior

Interfaces

Interfaces

API

API

Data Model

Data Model

Edge Cases

Edge Cases

Observability

Observability

Test Plan

Test Plan

Implementation Notes

Implementation Notes

Changelog

Changelog

docs/README.md Template

docs/README.md 模板

Documentation System