sspec 2.4.0__tar.gz → 2.4.2__tar.gz

{sspec-2.4.0/src/sspec/templates → sspec-2.4.2/.agents}/skills/sspec-design/SKILL.md

@@ -133,7 +133,9 @@ After confirmation → proceed to `sspec-plan`.
 
 ### Revision mechanism
 
-After this gate, spec.md and design.md baselines become **immutable**. Any subsequent scope or design change MUST go through the revision protocol:
+During Design: user-requested changes → edit spec.md/design.md directly, no revision.
+
+Once the change enters Plan (tasks.md created), spec.md/design.md become **immutable**. Any subsequent scope or design change MUST go through the revision protocol:
 1. Create `revisions/NNN-description.md` recording what changed and why
 2. Update tasks.md to reflect new work
 3. The original spec.md/design.md are NOT modified

{sspec-2.4.0 → sspec-2.4.2}/.agents/skills/sspec-implement/SKILL.md

@@ -32,7 +32,7 @@ Execute the approved plan. Work through tasks.md systematically.
 
 **Do not guess on blockers.** One `@align` < one rework cycle.
 
-### Post-Gate Design Changes
+### Design Changes During Implementation
 
 Apply this test first:
 > Can the original spec/design still accurately predict the post-change code?

{sspec-2.4.0 → sspec-2.4.2}/.gitignore

@@ -53,3 +53,4 @@ uv.lock
 # OS
 .DS_Store
 Thumbs.db
+.pi-input.md

{sspec-2.4.0 → sspec-2.4.2}/.sspec/.meta.json

@@ -1,15 +1,15 @@
 {
   "meta_schema": "2.1",
   "sspec_schema": "6.0",
-  "sspec_version": "2.2.2.dev0+g827c13fab.d20260504",
+  "sspec_version": "2.4.2.dev1+g0235b5044.d20260531",
   "created_at": "2026-02-07T18:42:39.297150",
-  "updated_at": "2026-05-04T17:57:06.107447",
+  "updated_at": "2026-05-31T19:44:23.445396",
   "file_hashes": {
     "skills/write-patch": "850929827559ba69",
     "skills/write-spec-doc": "13bb5686b0ff98e4",
     "skills/sspec-mdtoc": "b9fdfc4a23d816e0",
-    "skills/sspec-design": "5568dff1e82ab5f3",
-    "skills/sspec-implement": "04a20c5c851841a3",
+    "skills/sspec-design": "d94bf8ad6f16a810",
+    "skills/sspec-implement": "5e6bf57d5af39f82",
     "skills/sspec-plan": "2f0d39c5ace5b83d",
     "skills/sspec-review": "243e10ca983c6fbe",
     "skills/sspec-align": "0b1138822f677707",

{sspec-2.4.0 → sspec-2.4.2}/.sspec/spec-docs/interaction-records.md

@@ -23,7 +23,7 @@ replacement: ""
 
 sspec 通过两类持久记录承载人与 Agent 的互动：
 
-- `request`：开发者提交的任务入口
+- `request`：开发者意图记录（任务/现象/想法）
 - `ask`：Agent 在缺少 `question`-like 工具时使用的 fallback 对齐记录
 
 这两类记录都必须能被归档，并在归档后保持跨文件引用有效。
@@ -59,15 +59,35 @@ graph TD
 ```yaml
 created: 2026-03-07T00:00:00
 status: OPEN
+kind: directive
 attach-change: null
 tldr: ''
 ```
 
 补充规则：
 - `name` 可选；缺失时从文件名提取
+- `kind` 控制模板结构，可选值为 `directive | observe | idea`，默认 `directive`
 - `status` 读取时走 `normalize_status()`，兼容历史别名
 - `tldr` 为空时，会从正文中提取首条有效摘要
 
+### Request Kinds
+
+`kind` frontmatter 字段控制创建时选择哪个模板。不同 kind 仅影响模板结构和注释规则，不改变运行行为。
+
+| kind | 模板 | 定位 | @AGENT |
+|------|------|------|--------|
+| `directive` | `requests.md` | 人向 Agent 指派任务，期望立即行动 | 有 |
+| `observe` | `observe.md` | 记录观察到的现象/问题，方便以后讨论/triage | 无 |
+| `idea` | `idea.md` | 想法备忘，可能演化或捡起 | 无 |
+
+CLI：
+
+```bash
+sspec request new <name>                    # 默认 directive
+sspec request new <name> --kind observe     # 现象记录
+sspec request new <name> --kind idea        # 想法备忘
+```
+
 ### Linking to Change
 
 `link_request_to_change()` 负责双向绑定：
@@ -179,7 +199,7 @@ why: Ask user for design confirmation
 
 ## Testing Requirements
 
-- request：名称提取、frontmatter 解析、link、archive、引用改写
+- request：名称提取、frontmatter 解析（含 `kind`）、link、archive、引用改写
 - ask：YAML 模板、预填答案、legacy `.py` 兼容、转 `.md`、archive
 - 跨模块：request/change/ask archive 后引用路径保持可追踪
 

{sspec-2.4.0 → sspec-2.4.2}/AGENTS.md

@@ -152,9 +152,9 @@ When uncertain, align — never proceed with unclarified assumptions.
 | Input | Action |
 |-------|--------|
 | Directive (`@resume`, `@memory`, etc.) | Execute → §4 |
-| Request under `.sspec/requests` | Assess scale → §2 |
+| Request under `.sspec/requests` | Check `kind` → §1.1 |
 | Resume existing change | `read(memory)` → infer phase from State → load phase SKILL → continue |
-| Create request | `sspec request new` |
+| Create request | `sspec request new [--kind directive|observe|idea]` |
 | Create spec doc | `sspec doc new` |
 | Micro (≤3 files, ≤30min, obvious) | Do directly |
 | Mini (user opts out of formal change) | Clarify+Design thinking → `sspec tmp new` → §2.0 |
@@ -179,6 +179,19 @@ When uncertain, align — never proceed with unclarified assumptions.
 - Time uncertain → `sspec tool now`
 - Template HTML comments with BCP 14 keywords (MUST, SHOULD, MAY per RFC 2119) are persistent constraints — never delete them.
 
+### 1.1 Request Dispatch
+
+When agent encounters a request under `.sspec/requests/`, check `kind` frontmatter:
+
+| kind | Agent behavior |
+|------|---------------|
+| `directive` | Assess scale → §2 Change Lifecycle (this is a task for the agent) |
+| `observe` | Read, note context, but do NOT create a change. The request is a phenomenon record for later human triage. |
+| `idea` | Read, may refer to it as context, but do NOT create a change unless explicitly asked. The request is a memo. |
+| (missing) | Treat as `directive` (backward compatible). |
+
+A request of any kind MAY be linked to a change later via `sspec request link`.
+
 ## 2. Change Lifecycle
 
 Each phase has a SKILL. MUST read it before starting.
@@ -192,7 +205,7 @@ Review   (sspec-review)     DONE | fix→Implement | amend→revision | follow-u
 ```
 
 `■` = hard stop, **MUST stop & align**. `→` = output summary, COULD keep going. Failed gate → return, update, realign.
-Post-Design gate: spec.md/design.md baselines immutable. Changes → `revisions/NNN-*.md`.
+Once Plan begins: spec.md/design.md locked. Changes → `revisions/NNN-*.md`.
 memory.md: maintained throughout, not a phase. → `sspec howto write-memory`
 
 → `sspec howto handle-review-scope-change`
@@ -243,6 +256,7 @@ Decisions → natural home: design → spec.md, direction → memory.md Knowledg
 | Command | Use |
 |---------|-----|
 | `sspec change new <name> [--from REQ] [--root] [--scaffold design]` | Create change |
+| `sspec request new <name> [--kind directive|observe|idea]` | Create request |
 | `sspec change scaffold <type> <change>` | Add file: tasks, design, revision |
 | `sspec change find/status <name>` | Inspect change |
 | `sspec doc new "<name>"` | Create spec-doc |

sspec-2.4.2/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: sspec
+Version: 2.4.2
+Summary: Lightweight AI collaboration spec for solo/small projects
+Author-email: frostime <frostime@foxmail.com>
+License: AGPL-V3
+License-File: LICENSE
+Keywords: agent,ai,collaboration,llm,spec
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: pathspec>=0.12.0
+Requires-Dist: prompt-toolkit>=3.0.48
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: questionary>=2.1.1
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# sspec
+
+[简体中文](README_zh-CN.md)
+
+> Spec-driven development for AI coding. Developer controls the agent. State lives in files, not chat.
+
+---
+
+## The Idea
+
+AI coding agents are powerful but unpredictable. They forget decisions across sessions, they run ahead without alignment, and the thread becomes the only record of what was decided and why.
+
+sspec inverts this: **the repository is the source of truth, not the chat**. The agent reads files to understand context. The agent writes files to commit to decisions. At key points, the agent stops and waits for the developer to review — before code is written, not after.
+
+Three principles:
+
+- **Predictability**: You must be able to predict the outcome before implementation begins. No unclarified assumptions survive.
+- **Durable state**: Project context, specs, tasks, and session memory live in repository files. Agents resume from files, not from reconstructing chat history.
+- **Hard gates**: Design and implementation each end with a mandatory review point. The agent stops. You decide.
+
+## Is sspec for you?
+
+**Yes** if you:
+- review design before code is written
+- want specs and tasks tracked in files, not buried in chat
+- work on projects where continuity across sessions matters
+
+**Probably not** if you:
+- prefer free-form conversation with the agent, no structure
+- do not plan to review the agent's design or code
+- work on one-shot scripts where a single chat session suffices
+
+## How it works
+
+### Request — intent record
+
+A request captures what you want, something you observed, or an idea to keep. Three kinds:
+
+| kind | when to use | agent behavior |
+|------|-------------|----------------|
+| `directive` | You have a clear task for the agent | Agent assesses scale, creates a change, starts working |
+| `observe` | You noticed something off — a UX glitch, weird code, a smell | Agent reads and notes it. Does **not** create a change. For later human triage. |
+| `idea` | A thought worth keeping, maybe for later | Agent may refer to it as context. Does **not** act unless asked. |
+
+```bash
+sspec request new add-password-reset                # directive (default)
+sspec request new strange-logout-bug --kind observe
+sspec request new async-refactor --kind idea
+```
+
+### Change — atomic unit of work
+
+A change is a cohesive, reviewable piece of work. It lives in `.sspec/changes/<name>/` and contains:
+
+| File | Purpose |
+|------|---------|
+| `spec.md` | Problem, approach, scope, and success criteria — **the contract** |
+| `tasks.md` | File-level execution checklist with progress |
+| `memory.md` | Current state, key decisions, milestones — **continuity across sessions** |
+| `design.md` | (optional) Technical design for interfaces, data models, architecture |
+| `revisions/` | (optional) Amendments after the design gate |
+
+### Lifecycle with gates
+
+```
+Clarify  →  Design  →  Plan  →  Implement  →  Review
+              ■                   ■
+```
+
+`■` = hard stop. The agent **must** wait for your review before proceeding.
+
+- **Design gate**: Review `spec.md` (+ `design.md`). The solution contract is now fixed. Changes after this go into `revisions/`.
+- **Implementation gate**: Review the code. Fix issues, amend scope, or approve as done.
+
+### Memory — continuity file
+
+`memory.md` is how the agent resumes. Next session, the agent reads `memory.md` first — it knows exactly where the work stands, what files matter, and why past decisions were made. No reconstructing from chat history.
+
+### Spec-docs — long-lived knowledge
+
+Architecture decisions, design patterns, platform constraints — things that outlive any single change. Live in `.sspec/spec-docs/`, referenced by the agent across all changes.
+
+## Folder layout
+
+```
+project/
+├── AGENTS.md              ← the protocol (agent reads this first)
+├── .agents/skills/        ← synced from .sspec/skills/
+└── .sspec/
+    ├── project.md         ← your stack, conventions, key paths
+    ├── requests/          ← intent records (directive / observe / idea)
+    ├── changes/           ← active and archived changes
+    │   └── <name>/
+    │       ├── spec.md
+    │       ├── tasks.md
+    │       └── memory.md
+    ├── spec-docs/         ← architecture and design knowledge
+    ├── skills/            ← agent-facing skill definitions
+    ├── asks/              ← structured Q&A records
+    ├── howto/             ← operational guides
+    └── tmp/               ← scratch space
+```
+
+## Quick Start
+
+### 1. Install and initialize
+
+```bash
+pip install sspec
+cd your-project
+sspec project init
+```
+
+Then fill `.sspec/project.md` with your stack, key paths, and conventions.
+
+### 2. Start work — two paths
+
+**Path A: Describe your need to the agent.** Tell the agent what you want. A capable agent reads `AGENTS.md` and follows the sspec protocol — it clarifies, creates a change, writes the spec, and stops at the design gate for your review.
+
+**Path B: Write a request file.** If you have clear ideas, create a request:
+
+```bash
+sspec request new add-dark-mode --kind directive
+```
+
+Fill in background, problem, direction, and success criteria. The agent picks it up from there.
+
+### 3. Review at gates
+
+The agent stops at two points:
+- **Design gate**: read `spec.md`, confirm the approach, then tell the agent to proceed.
+- **Implementation gate**: review the code, request fixes, or approve.
+
+### 4. Archive when done
+
+```bash
+sspec change archive --with-request <name>
+```
+
+## Common commands
+
+```bash
+# Requests
+sspec request new <name> [--kind directive|observe|idea]
+sspec request list
+
+# Changes
+sspec change new <name> [--from <request>] [--root]
+sspec change status <name>
+sspec change list
+sspec change archive <name> --with-request
+
+# Project
+sspec project status
+sspec project update --dry-run
+
+# Docs
+sspec doc new "Architecture Overview"
+
+# Tools
+sspec tool now
+sspec tool mdtoc README.md
+```
+
+Run `sspec --help` for the full command list.
+
+## License
+
+AGPL-3.0

sspec-2.4.2/README.md

@@ -0,0 +1,169 @@
+# sspec
+
+[简体中文](README_zh-CN.md)
+
+> Spec-driven development for AI coding. Developer controls the agent. State lives in files, not chat.
+
+---
+
+## The Idea
+
+AI coding agents are powerful but unpredictable. They forget decisions across sessions, they run ahead without alignment, and the thread becomes the only record of what was decided and why.
+
+sspec inverts this: **the repository is the source of truth, not the chat**. The agent reads files to understand context. The agent writes files to commit to decisions. At key points, the agent stops and waits for the developer to review — before code is written, not after.
+
+Three principles:
+
+- **Predictability**: You must be able to predict the outcome before implementation begins. No unclarified assumptions survive.
+- **Durable state**: Project context, specs, tasks, and session memory live in repository files. Agents resume from files, not from reconstructing chat history.
+- **Hard gates**: Design and implementation each end with a mandatory review point. The agent stops. You decide.
+
+## Is sspec for you?
+
+**Yes** if you:
+- review design before code is written
+- want specs and tasks tracked in files, not buried in chat
+- work on projects where continuity across sessions matters
+
+**Probably not** if you:
+- prefer free-form conversation with the agent, no structure
+- do not plan to review the agent's design or code
+- work on one-shot scripts where a single chat session suffices
+
+## How it works
+
+### Request — intent record
+
+A request captures what you want, something you observed, or an idea to keep. Three kinds:
+
+| kind | when to use | agent behavior |
+|------|-------------|----------------|
+| `directive` | You have a clear task for the agent | Agent assesses scale, creates a change, starts working |
+| `observe` | You noticed something off — a UX glitch, weird code, a smell | Agent reads and notes it. Does **not** create a change. For later human triage. |
+| `idea` | A thought worth keeping, maybe for later | Agent may refer to it as context. Does **not** act unless asked. |
+
+```bash
+sspec request new add-password-reset                # directive (default)
+sspec request new strange-logout-bug --kind observe
+sspec request new async-refactor --kind idea
+```
+
+### Change — atomic unit of work
+
+A change is a cohesive, reviewable piece of work. It lives in `.sspec/changes/<name>/` and contains:
+
+| File | Purpose |
+|------|---------|
+| `spec.md` | Problem, approach, scope, and success criteria — **the contract** |
+| `tasks.md` | File-level execution checklist with progress |
+| `memory.md` | Current state, key decisions, milestones — **continuity across sessions** |
+| `design.md` | (optional) Technical design for interfaces, data models, architecture |
+| `revisions/` | (optional) Amendments after the design gate |
+
+### Lifecycle with gates
+
+```
+Clarify  →  Design  →  Plan  →  Implement  →  Review
+              ■                   ■
+```
+
+`■` = hard stop. The agent **must** wait for your review before proceeding.
+
+- **Design gate**: Review `spec.md` (+ `design.md`). The solution contract is now fixed. Changes after this go into `revisions/`.
+- **Implementation gate**: Review the code. Fix issues, amend scope, or approve as done.
+
+### Memory — continuity file
+
+`memory.md` is how the agent resumes. Next session, the agent reads `memory.md` first — it knows exactly where the work stands, what files matter, and why past decisions were made. No reconstructing from chat history.
+
+### Spec-docs — long-lived knowledge
+
+Architecture decisions, design patterns, platform constraints — things that outlive any single change. Live in `.sspec/spec-docs/`, referenced by the agent across all changes.
+
+## Folder layout
+
+```
+project/
+├── AGENTS.md              ← the protocol (agent reads this first)
+├── .agents/skills/        ← synced from .sspec/skills/
+└── .sspec/
+    ├── project.md         ← your stack, conventions, key paths
+    ├── requests/          ← intent records (directive / observe / idea)
+    ├── changes/           ← active and archived changes
+    │   └── <name>/
+    │       ├── spec.md
+    │       ├── tasks.md
+    │       └── memory.md
+    ├── spec-docs/         ← architecture and design knowledge
+    ├── skills/            ← agent-facing skill definitions
+    ├── asks/              ← structured Q&A records
+    ├── howto/             ← operational guides
+    └── tmp/               ← scratch space
+```
+
+## Quick Start
+
+### 1. Install and initialize
+
+```bash
+pip install sspec
+cd your-project
+sspec project init
+```
+
+Then fill `.sspec/project.md` with your stack, key paths, and conventions.
+
+### 2. Start work — two paths
+
+**Path A: Describe your need to the agent.** Tell the agent what you want. A capable agent reads `AGENTS.md` and follows the sspec protocol — it clarifies, creates a change, writes the spec, and stops at the design gate for your review.
+
+**Path B: Write a request file.** If you have clear ideas, create a request:
+
+```bash
+sspec request new add-dark-mode --kind directive
+```
+
+Fill in background, problem, direction, and success criteria. The agent picks it up from there.
+
+### 3. Review at gates
+
+The agent stops at two points:
+- **Design gate**: read `spec.md`, confirm the approach, then tell the agent to proceed.
+- **Implementation gate**: review the code, request fixes, or approve.
+
+### 4. Archive when done
+
+```bash
+sspec change archive --with-request <name>
+```
+
+## Common commands
+
+```bash
+# Requests
+sspec request new <name> [--kind directive|observe|idea]
+sspec request list
+
+# Changes
+sspec change new <name> [--from <request>] [--root]
+sspec change status <name>
+sspec change list
+sspec change archive <name> --with-request
+
+# Project
+sspec project status
+sspec project update --dry-run
+
+# Docs
+sspec doc new "Architecture Overview"
+
+# Tools
+sspec tool now
+sspec tool mdtoc README.md
+```
+
+Run `sspec --help` for the full command list.
+
+## License
+
+AGPL-3.0

sspec-2.4.2/README_zh-CN.md

@@ -0,0 +1,169 @@
+# sspec
+
+[English](README.md)
+
+> AI 编码的规格驱动开发。开发者控制 Agent，状态存文件而非聊天。
+
+---
+
+## 核心理念
+
+AI 编码 Agent 很强大，但不可预测。跨会话时决策丢失，未经确认就往前冲，聊天记录成为唯一的事实来源。
+
+sspec 反转了这一点：**仓库是真相来源，而不是聊天记录**。Agent 从文件读取上下文，向文件写入决策承诺。在关键节点，Agent 停下来等你审查——在代码被写出来之前，而不是之后。
+
+三个原则：
+
+- **可预测性**：你必须能在动手前预测结果。不允许未经澄清的假设存续。
+- **状态持久**：项目上下文、规格、任务和会话内存都存于仓库文件。Agent 从中恢复，不需要从聊天历史重建。
+- **硬性审查门**：设计和实现各自以强制性审查点结束。Agent 停下来。你来决策。
+
+## sspec 适合你吗？
+
+**适合**，如果你：
+- 在写代码之前先审查设计
+- 希望规格和任务跟踪在文件里，而不是埋没在聊天中
+- 工作在跨会话连续性很重要的项目上
+
+**不太适合**，如果你：
+- 偏好和 Agent 自由形式的对话，不需要结构
+- 不打算审查 Agent 的设计或代码
+- 工作在一次性的脚本上，单次聊天就足够
+
+## 工作原理
+
+### Request — 意图记录
+
+request 记录你想要什么、你观察到了什么、或者一个值得留存的想法。分三种：
+
+| kind | 使用场景 | Agent 行为 |
+|------|----------|-----------|
+| `directive` | 给 Agent 的明确任务 | Agent 评估规模，创建 change，开始工作 |
+| `observe` | 你注意到哪里不太对劲——UX 问题、奇怪代码、异味 | Agent 读取并记录。**不**创建 change。留给后续人工 triage。 |
+| `idea` | 值得留存的想法，未必现在做 | Agent 可作为上下文引用。除非明确要求，**不**主动行动。 |
+
+```bash
+sspec request new add-password-reset                # directive（默认）
+sspec request new strange-logout-bug --kind observe
+sspec request new async-refactor --kind idea
+```
+
+### Change — 原子工作单元
+
+change 是一次内聚、可审查的工作。存放在 `.sspec/changes/<name>/`，包含：
+
+| 文件 | 用途 |
+|------|------|
+| `spec.md` | 问题、方案、范围和成功标准——**这是合约** |
+| `tasks.md` | 文件级执行清单与进度 |
+| `memory.md` | 当前状态、关键决策、里程碑——**跨会话的连续性** |
+| `design.md` | （可选）接口、数据模型、架构等技术设计 |
+| `revisions/` | （可选）design gate 之后的修订 |
+
+### 带门的生命周期
+
+```
+澄清  →  设计  →  规划  →  实现  →  审查
+          ■              ■
+```
+
+`■` = 硬性停止。Agent **必须**等你审查后才能继续。
+
+- **设计门**：审查 `spec.md`（+ `design.md`）。方案合约就此固定。此后的变更记录在 `revisions/` 里。
+- **实现门**：审查代码。修复问题、调整范围，或批准完成。
+
+### Memory — 连续性文件
+
+`memory.md` 是 Agent 恢复工作的入口。下一会话中，Agent 先读 `memory.md`——它知道工作进展到哪、哪些文件关键、为什么做了那些决策。不需要从聊天历史重建。
+
+### Spec-docs — 长期知识
+
+架构决策、设计模式、平台约束——那些超越单次 change 的知识。存于 `.sspec/spec-docs/`，Agent 在任意 change 中均可引用。
+
+## 目录结构
+
+```
+project/
+├── AGENTS.md              ← 协议（Agent 首先读这个）
+├── .agents/skills/        ← 从 .sspec/skills/ 同步
+└── .sspec/
+    ├── project.md         ← 技术栈、约定、关键路径
+    ├── requests/          ← 意图记录（directive / observe / idea）
+    ├── changes/           ← 活跃与已归档变更
+    │   └── <name>/
+    │       ├── spec.md
+    │       ├── tasks.md
+    │       └── memory.md
+    ├── spec-docs/         ← 架构与设计知识
+    ├── skills/            ← Agent 技能定义
+    ├── asks/              ← 结构化问答记录
+    ├── howto/             ← 操作指南
+    └── tmp/               ← 临时草稿
+```
+
+## 快速开始
+
+### 1. 安装并初始化
+
+```bash
+pip install sspec
+cd your-project
+sspec project init
+```
+
+然后补全 `.sspec/project.md`，写清技术栈、关键路径和编码约定。
+
+### 2. 启动工作——两种方式
+
+**方式 A：直接告诉 Agent 你的需求。** 把需求描述清楚。有能力的 Agent 会读取 `AGENTS.md` 并遵循 sspec 协议——先澄清，创建 change，写 spec，然后在设计门停下来等你审查。
+
+**方式 B：手写 request 文件。** 如果你想法清晰，自己创建一个 request：
+
+```bash
+sspec request new add-dark-mode --kind directive
+```
+
+填好背景、问题、方向和成功标准。Agent 会从这里接手。
+
+### 3. 在门节点审查
+
+Agent 会在两个节点停下：
+- **设计门**：读 `spec.md`，确认方案方向，然后告诉 Agent 继续。
+- **实现门**：审查代码，要求修复或批准完成。
+
+### 4. 完成后归档
+
+```bash
+sspec change archive --with-request <name>
+```
+
+## 常用命令
+
+```bash
+# Request
+sspec request new <name> [--kind directive|observe|idea]
+sspec request list
+
+# Change
+sspec change new <name> [--from <request>] [--root]
+sspec change status <name>
+sspec change list
+sspec change archive <name> --with-request
+
+# 项目
+sspec project status
+sspec project update --dry-run
+
+# 文档
+sspec doc new "Architecture Overview"
+
+# 工具
+sspec tool now
+sspec tool mdtoc README.md
+```
+
+完整命令列表请运行 `sspec --help`。
+
+## License
+
+AGPL-3.0