archive
Use at ship time to merge the spec into the living documentation, delete the staging spec and plan, and ask how to finish.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 1.6k
- Forks
- 491
01 前言 Front Matter
- name
- archive
- description
- Use at ship time to merge the spec into the living documentation, delete the staging spec and plan, and ask how to finish.
03 SKILL.md 正文
Living documentation
Always in sync with code. Current ground truth only — atemporal, no history, no plans.
README.md— for users: what it is, who for, how to usedocs/tech-spec.md— for developers/agents: current system state (core backbone, ≤300 lines)docs/specs/<topic>.md— modular subsystem/protocol details; referenced by pathdocs/ROADMAP.md— direction (≥3 milestones or long-term)CHANGELOG.md— version history (shipmaintains)docs/decisions/— architectural rationale (context / choice / ruled-out), append-only
Living doc North Star
Standard: Zero history, maximum truth density, instant scannability.
- The Razor: Past rationale belongs in
docs/decisions/orCHANGELOG.md;docs/tech-spec.mdholds exclusively active ground truth.
- Atemporal: Describes exclusively current ground truth. No version/milestone headers, changelog deltas, or supersession notes. Mutate in-place.
- Modular (Progressive disclosure): Bulky subsystem specs (>15 lines, schemas, complex state machines) live in
docs/specs/<topic>.md, referenced by a one-line declaration intech-spec.md. - Structured & concise: Atomic declarations (≤25 words per sentence). Multi-attribute contracts use structured bulleted lists or tables; no dense text blocks.
tech-spec format
Declarations only.
purpose: <what problem this solves — one sentence>
user: <who uses this>
use-case: <key scenarios, one line each>
architecture: <structural shape — one line, or see docs/architecture.md>
stack: <language, runtime, frameworks, key deps>
entry: <where execution starts>
contract: <public APIs / interfaces that must not break — stability set; full surface by doc-coverage>
flow: <name>: <trigger> → <steps> → <output>
(complex — branching/async/multi-actor: one-line summary here, diagram in docs/specs/<flow>.md)
invariant: <what must always hold>
constraint: <limits, warnings from code>
convention: <naming, file structure, test patterns, lint/format/typecheck tools, error-handling, security baseline>
milestone: <current milestone> (see docs/ROADMAP.md)
Archive
If topology=multi-module (triage announcement or coordinator spec/plan declaration), read ../references/multi-module.md. Merge each module's artifacts in its own repository first. Then merge shared contracts and integration facts in the coordinator, record the revision set, and archive it last. Keep module-local facts in module repos.
<gate> Before proceeding: (1) verify tdd/subagents have completed all tasks listed in the plan; (2) user has approved shipping/archiving this change (ship disposition or an explicit archive go-ahead). </gate>
-
Merge staging spec into living doc:
- Integrate in-place into existing declarations; overwrite modified contracts rather than appending new sections.
- Subsystem details >15 lines go to
docs/specs/<topic>.md. - Maintain concise, structured formatting (lists/tables, no text walls).
-
Roadmap (if spec contains
## Roadmap): update roadmap independently; do not duplicate into tech-spec. -
Decisions (if spec or working notes contain a knowledge artifact — protocol spec, RE findings, architectural rationale): save to
docs/decisions/YYYY-MM-DD-<topic>.mdascontext / choice / ruled-out.
<gate> Before deleting staging spec/plan, verify Living Doc North Star: (1) Atemporal (zero history/dates/supersessions)? (2) Truth-dense (binding facts only)? (3) Modular (subsystems >15 lines in docs/specs/)? (4) User approved merged living-doc. </gate>
- Delete
docs/staging/specs/YYYY-MM-DD-<topic>.md— content absorbed; Git has the history. - Delete
docs/staging/plans/YYYY-MM-DD-<topic>.md— plans don't belong onmain.
04 同仓库更多 Skills
worktable-review-with-annotations
Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.
worktable-find-and-synthesize-context
Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.
worktable-create-or-update-docs
Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.
worktable-create-or-manage-records
Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.
worktable-create-or-manage-interactive-html
Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.
worktable-collaborate-threads
Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.