chore: harden SDD governance workflow
This commit is contained in:
@@ -0,0 +1,244 @@
|
||||
name: wealth-ledger-sdd
|
||||
version: 1
|
||||
description: WealthLedger SDD workflow - proposal → specs → design → tasks
|
||||
artifacts:
|
||||
- id: proposal
|
||||
generates: proposal.md
|
||||
description: Owner-approved intent without implementation details
|
||||
template: proposal.md
|
||||
instruction: |
|
||||
Создай Proposal, который формулирует намерение и объясняет, ПОЧЕМУ
|
||||
изменение нужно. Его должен понимать и утверждать владелец продукта или
|
||||
процесса без знания структуры кода.
|
||||
|
||||
Sections:
|
||||
Разделы:
|
||||
- **Why**: проблема или возможность и причина заняться ею сейчас.
|
||||
- **What Changes**: намерение, ожидаемый результат и явные non-goals.
|
||||
- **Capabilities**: какие поведенческие specs появятся или изменятся:
|
||||
- **New Capabilities**: List capabilities being introduced. Each becomes a new `specs/<capability-path>/spec.md`. Use kebab-case for path segments you introduce (e.g., `user-auth` or `identity/user-auth`) and follow the project's existing spec organization.
|
||||
- **Modified Capabilities**: List existing capabilities whose REQUIREMENTS are changing. Only include if spec-level behavior changes (not just implementation details). Each needs a delta spec file. Use the exact existing path under `openspec/specs/`. Leave empty if no requirement changes.
|
||||
- **Impact**: затронутые пользователи, процессы или части системы только
|
||||
на уровне scope.
|
||||
|
||||
IMPORTANT: The Capabilities section is critical. It creates the contract between
|
||||
proposal and specs phases. Research existing specs before filling this in.
|
||||
Each capability listed here will need a corresponding spec file.
|
||||
|
||||
Every change must either declare at least one capability (new or
|
||||
modified) or explicitly opt out of specs: `openspec validate` rejects a
|
||||
change with zero deltas unless the change's `.openspec.yaml` sets
|
||||
`skip_specs: true`. Use `skip_specs: true` only when no spec-level
|
||||
behavior changes (pure refactor, tooling, docs) - specs describe
|
||||
behavior, so if behavior does not change, no spec should change either.
|
||||
Do not invent a requirement just to satisfy validation.
|
||||
|
||||
MUST NOT включать технологии, библиотеки, API signatures, имена файлов,
|
||||
зависимости, классы или пошаговую реализацию. Эти решения появляются
|
||||
только после Delta Specs в Design.
|
||||
|
||||
This is the foundation - specs, design, and tasks all build on this.
|
||||
requires: []
|
||||
|
||||
- id: specs
|
||||
generates: "specs/**/*.md"
|
||||
description: Observable behavior and invariants changed by the proposal
|
||||
template: spec.md
|
||||
instruction: |
|
||||
Создай Delta Specs, определяющие, ЧТО наблюдаемо изменяется в системе.
|
||||
|
||||
Spec является behavior contract, а не планом изменения кода.
|
||||
|
||||
Good spec content:
|
||||
- Observable behavior users or downstream systems rely on
|
||||
- Inputs, outputs, and error conditions
|
||||
- External constraints (security, privacy, reliability, compatibility)
|
||||
- Scenarios that can be tested or explicitly validated
|
||||
|
||||
Не включай в specs:
|
||||
- Internal class/function names
|
||||
- Library or framework choices
|
||||
- Step-by-step implementation details
|
||||
- Detailed execution plans (those belong in design.md or tasks.md)
|
||||
|
||||
Quick test: if the implementation can change without changing externally
|
||||
visible behavior, it likely does not belong in the spec.
|
||||
|
||||
Create one spec file per capability listed in the proposal's Capabilities section.
|
||||
`<capability-path>` is the spec directory relative to `specs/` (for example,
|
||||
`user-auth` or `identity/user-auth`). Preserve the full path:
|
||||
- New capabilities: use the exact path from the proposal at `specs/<capability-path>/spec.md`. Any path segment newly introduced in the proposal must be kebab-case. Follow the project's existing organization; do not add a new domain level when the project uses a flat layout.
|
||||
- Modified capabilities: use the exact existing path from `openspec/specs/<capability-path>/` when creating the delta at `specs/<capability-path>/spec.md`. Do not move or rename the capability.
|
||||
|
||||
There must be at least one spec file unless the change's `.openspec.yaml`
|
||||
sets `skip_specs: true` (no spec-level behavior change) - `openspec validate`
|
||||
rejects a zero-delta change without that marker. If the proposal lists no
|
||||
capabilities and `skip_specs` is not set, revisit the proposal first.
|
||||
|
||||
Delta operations (use ## headers):
|
||||
- **ADDED Requirements**: New capabilities
|
||||
- **MODIFIED Requirements**: Changed behavior - MUST include full updated content
|
||||
- **REMOVED Requirements**: Deprecated features - MUST include **Reason** and **Migration**
|
||||
- **RENAMED Requirements**: Name changes only - use FROM:/TO: format
|
||||
|
||||
Format requirements:
|
||||
- Each requirement: `### Requirement: <name>` followed by description
|
||||
- Use SHALL/MUST for normative requirements (avoid should/may)
|
||||
- Each scenario: `#### Scenario: <name>` with WHEN/THEN format
|
||||
- **CRITICAL**: Scenarios MUST use exactly 4 hashtags (`####`). Using 3 hashtags or bullets will fail silently.
|
||||
- Every requirement MUST have at least one scenario.
|
||||
|
||||
New capabilities only: start the delta spec with a `## Purpose` section -
|
||||
one or two sentences (50+ characters, or `openspec validate --strict`
|
||||
reports it as too brief) describing what the capability is for. Archive
|
||||
copies it into the main spec it creates; without it the new main spec is
|
||||
left with a `TBD ... Update Purpose after archive` placeholder to fill in
|
||||
by hand. Do NOT add `## Purpose` to a delta for an existing capability -
|
||||
that spec already has one and the delta's is ignored. To change an
|
||||
existing capability's Purpose - including a leftover `TBD` placeholder -
|
||||
edit `<planningHome.root>/openspec/specs/<capability-path>/spec.md`
|
||||
directly. `planningHome.root` comes from the `openspec instructions ...
|
||||
--json` response. Always use it rather than a repo-relative path: it
|
||||
resolves to the store whenever the change lives in one - whether that
|
||||
came from `--store`, a project `store:` pointer, or a global default
|
||||
store - and to the current repository otherwise. Do not try to work out
|
||||
which case applies; the field already has.
|
||||
|
||||
MODIFIED requirements workflow:
|
||||
1. Locate the existing requirement in `<planningHome.root>/openspec/specs/<capability-path>/spec.md` (the same store-aware root as above)
|
||||
2. Copy the ENTIRE requirement block (from `### Requirement:` through all scenarios)
|
||||
3. Paste under `## MODIFIED Requirements` and edit to reflect new behavior
|
||||
4. Ensure header text matches exactly (whitespace-insensitive)
|
||||
|
||||
Common pitfall: Using MODIFIED with partial content loses detail at archive time.
|
||||
If adding new concerns without changing existing behavior, use ADDED instead.
|
||||
|
||||
Example (a new capability, so it opens with `## Purpose`):
|
||||
```
|
||||
## Purpose
|
||||
|
||||
Lets users take their data out of the product in a portable format.
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: User can export data
|
||||
The system SHALL allow users to export their data in CSV format.
|
||||
|
||||
#### Scenario: Successful export
|
||||
- **WHEN** user clicks "Export" button
|
||||
- **THEN** system downloads a CSV file with all user data
|
||||
|
||||
## REMOVED Requirements
|
||||
|
||||
### Requirement: Legacy export
|
||||
**Reason**: Replaced by new export system
|
||||
**Migration**: Use new export endpoint at /api/v2/export
|
||||
```
|
||||
|
||||
Specs должны быть проверяемыми, но scenario не означает автоматический
|
||||
unit test: уровень проверки выбирается по риску поведения.
|
||||
requires:
|
||||
- proposal
|
||||
|
||||
- id: design
|
||||
generates: design.md
|
||||
description: Architectural implementation approach and delivery decisions
|
||||
template: design.md
|
||||
instruction: |
|
||||
Создай Design, объясняющий, КАК архитектурно выполнить утверждённые
|
||||
Delta Specs. Не превращай его в построчную инструкцию или список правок.
|
||||
|
||||
Обязательные разделы:
|
||||
- **Context**: только текущее состояние и ограничения подхода.
|
||||
- **Goals / Non-Goals**: технические границы, не пересказ Proposal.
|
||||
- **Decisions**: крупные решения, rationale и рассмотренные alternatives.
|
||||
- **Delivery Map**: ровно frontend, backend, specs и docs; для каждой
|
||||
области `affected` с ожидаемым архитектурным результатом либо `N/A` с
|
||||
конкретной причиной. `specs` всегда affected. Здесь же зафиксируй
|
||||
Contract Gate Decision для `runtime-openapi`: `required`, только когда
|
||||
change затрагивает обе стороны API contract, либо `N/A` с причиной.
|
||||
- **Risks / Trade-offs**: риск и mitigation.
|
||||
- **Migration Plan**: порядок поставки и rollback, если применимо.
|
||||
|
||||
Добавь **Solution Assessment**, если изменение вводит или существенно
|
||||
заменяет auth, security, storage, external integration, observability,
|
||||
caching, concurrency или общую infrastructure/tooling либо содержит
|
||||
другое дорогостоящее необратимое решение. Сравни зрелые готовые решения
|
||||
по fit, maturity, security, operating cost, constraints и migration cost.
|
||||
Custom implementation допустима только после фиксации несовместимости
|
||||
подходящих alternatives и принятых рисков. Не создавай отдельный artifact.
|
||||
|
||||
**Open Questions** допустим только для неизвестного, которое не меняет
|
||||
Specs, выбранный подход или Tasks. Иначе остановись и запроси решение
|
||||
владельца до сохранения Design.
|
||||
|
||||
Open questions are for genuinely deferrable unknowns, not decisions you
|
||||
skipped. If a question would change the specs, the chosen approach, or
|
||||
the task breakdown, resolve it now - ask the user instead of guessing.
|
||||
|
||||
Design формируется только после явного owner approval Delta Specs.
|
||||
requires:
|
||||
- specs
|
||||
|
||||
- id: tasks
|
||||
generates: tasks.md
|
||||
description: Implementation checklist with trackable tasks
|
||||
template: tasks.md
|
||||
instruction: |
|
||||
Создай implementation checklist, достаточный для выполнения Design и
|
||||
Delta Specs. Это конкретное DO, а не ещё один архитектурный документ.
|
||||
|
||||
Before writing tasks, check design.md for Open Questions. If any of them
|
||||
would change what gets built, resolve them with the user first - do not
|
||||
bake an unstated assumption into the task list.
|
||||
|
||||
**IMPORTANT: Follow the template below exactly.** The apply phase parses
|
||||
checkbox format to track progress. Tasks not using `- [ ]` won't be tracked.
|
||||
|
||||
Правила:
|
||||
- Группируй задачи под numbered `##` headings и располагай по dependencies.
|
||||
- Каждая задача MUST иметь формат `- [ ] X.Y ...` и быть выполнимой за
|
||||
одну рабочую сессию.
|
||||
- Для каждой `affected` области Delivery Map должна существовать задача
|
||||
реализации и её canonical local gate; пустые commits запрещены.
|
||||
- Каждая задача MUST указывать planned verification action: команду,
|
||||
проверку наблюдаемого поведения или delivered artifact.
|
||||
- Автоматические тесты обязательны для security/privacy, денежных
|
||||
расчётов, data integrity/migration, concurrency, public contracts,
|
||||
critical journeys и подтверждённых regressions.
|
||||
- Не требуй отдельный unit test только из-за изменения файла. DTO без
|
||||
логики, declarative structures, thin adapters, прямолинейная
|
||||
orchestration, hygiene scripts и third-party behavior проверяются
|
||||
существующим integration/contract gate, если нет собственного
|
||||
branching, transformation, invariant или regression.
|
||||
- Перед custom implementation в обязательных областях включи действие по
|
||||
утверждённому Solution Assessment из Design.
|
||||
- MUST NOT записывать ещё не наблюдённые результаты как выполненные,
|
||||
предполагаемые commit identifiers, archive path или post-archive
|
||||
Completion Evidence. Такое evidence создаётся только после факта.
|
||||
|
||||
Example:
|
||||
```
|
||||
## 1. Setup
|
||||
|
||||
- [ ] 1.1 Create new module structure and verify expected files are present
|
||||
- [ ] 1.2 Add dependencies to package.json and verify package installation succeeds
|
||||
|
||||
## 2. Core Implementation
|
||||
|
||||
- [ ] 2.1 Implement data export function and verify the export test passes
|
||||
- [ ] 2.2 Add CSV formatting utilities and verify unit tests cover quoting and delimiters
|
||||
```
|
||||
|
||||
Reference specs for what needs to be built, design for how to build it.
|
||||
requires:
|
||||
- design
|
||||
|
||||
apply:
|
||||
requires: [ tasks ]
|
||||
tracks: tasks.md
|
||||
instruction: |
|
||||
Сначала проверь exact OpenSpec version contract. Работай только с change в
|
||||
canonical store `wealth-ledger-specs` и не создавай parallel planning root.
|
||||
Read context files, work through pending tasks, mark complete as you go.
|
||||
Pause if you hit blockers or need clarification.
|
||||
Reference in New Issue
Block a user