210 lines
14 KiB
YAML
210 lines
14 KiB
YAML
name: wealth-ledger-sdd
|
||
version: 3
|
||
description: WealthLedger SDD workflow - proposal → specs → design → tasks → apply
|
||
artifacts:
|
||
- id: proposal
|
||
generates: proposal.md
|
||
description: Owner-approved intent without implementation details
|
||
template: proposal.md
|
||
instruction: |
|
||
Critical Rules:
|
||
- Создай только Proposal: причина, намерение, scope, ожидаемый результат и
|
||
явные non-goals языком Change Owner.
|
||
- Сначала исследуй canonical main specs; для audit-derived change также
|
||
прочитай remediation registry.
|
||
- Capabilities перечисляет каждую новую или изменяемую behavior spec точным
|
||
path. Если spec-level behavior не меняется, не выдумывай Requirement:
|
||
оставь capabilities пустыми и установи `skip_specs: true`.
|
||
- Оставь технологии, зависимости, архитектуру, API, database/code/file
|
||
structure для Design, а implementation steps и verification — для Tasks.
|
||
- После записи запусти
|
||
`bash specs/scripts/verify-openspec-planning.sh <change>`. Исправляй
|
||
artifact только при `artifact-validation`; при `invocation` исправь вызов,
|
||
при `environment` — prerequisite. Structural success не является approval.
|
||
|
||
Required Shape:
|
||
- **Why**: проблема или возможность и причина заняться ею сейчас.
|
||
- **What Changes**: намерение, ожидаемый результат и non-goals.
|
||
- **Capabilities**:
|
||
- **New Capabilities**: exact `specs/<capability-path>/spec.md`; новые path
|
||
segments используют kebab-case и существующую organization.
|
||
- **Modified Capabilities**: exact existing path под `openspec/specs/`
|
||
только при изменении Requirements.
|
||
- **Impact**: затронутые пользователи, процессы или части системы на уровне
|
||
scope, без implementation topology.
|
||
|
||
Один Proposal формирует contract для downstream artifacts. Покажи его
|
||
Change Owner и остановись до explicit approval.
|
||
requires: []
|
||
|
||
- id: specs
|
||
generates: "specs/**/*.md"
|
||
description: Observable behavior and invariants changed by the proposal
|
||
template: spec.md
|
||
instruction: |
|
||
Critical Rules:
|
||
- Создай behavior contract только для capabilities утверждённого Proposal:
|
||
observable inputs, outputs, errors и security/privacy/reliability/
|
||
compatibility constraints.
|
||
- Не добавляй intent вне Proposal, code/database/file structure, technology
|
||
choices, delivery steps или test procedure. Scenario задаёт WHEN/THEN
|
||
behavior; способ проверки выбирается позже.
|
||
- Создай один `specs/<capability-path>/spec.md` на каждый Proposal path.
|
||
New path следует Proposal; modified path точно совпадает с существующим
|
||
path под `<planningHome.root>/openspec/specs/` и не переименовывается.
|
||
- Используй только применимые `## ADDED Requirements`,
|
||
`## MODIFIED Requirements`, `## REMOVED Requirements` и
|
||
`## RENAMED Requirements`; не оставляй пустые operation sections.
|
||
- Каждый `### Requirement:` содержит SHALL/MUST и хотя бы один
|
||
`#### Scenario:` с `- **WHEN**` и `- **THEN**`.
|
||
- После explicit Proposal approval и записи запусти planning verifier.
|
||
Исправляй artifact только при `artifact-validation`; `invocation` и
|
||
`environment` не разрешают менять Delta Specs.
|
||
|
||
Delta Operations:
|
||
- `ADDED`: новый Requirement.
|
||
- `MODIFIED`: скопируй из main spec полный existing Requirement block со
|
||
всеми Scenarios, затем измени behavior; heading совпадает точно.
|
||
- `REMOVED`: добавь **Reason** и **Migration**.
|
||
- `RENAMED`: только heading rename в формате `FROM:` / `TO:`.
|
||
|
||
New Capability:
|
||
Добавь `## Purpose` из 1–2 предложений (не менее 50 characters). Archive
|
||
переносит его в новую main spec; без него появляется ручной `TBD`. Для
|
||
existing capability `Purpose` в delta не добавляй. Existing Purpose меняй
|
||
прямо в main spec под `planningHome.root` отдельным явно разрешённым
|
||
изменением. `planningHome.root` уже разрешает store-backed или local root;
|
||
не вычисляй path самостоятельно.
|
||
|
||
`skip_specs: true` допустим только при отсутствии Proposal capabilities и
|
||
delta files. Specs должны быть проверяемыми, но Scenario не означает
|
||
обязательный unit test: уровень проверки определяется риском.
|
||
|
||
Покажи Delta Specs Change Owner и остановись до explicit approval. Если
|
||
обнаружилось изменение intent, вернись к Proposal и инвалидируй downstream
|
||
approvals.
|
||
requires:
|
||
- proposal
|
||
|
||
- id: design
|
||
generates: design.md
|
||
description: Architectural implementation approach and delivery decisions
|
||
template: design.md
|
||
instruction: |
|
||
Critical Rules:
|
||
- Создай архитектурный способ выполнить утверждённые Delta Specs крупными
|
||
решениями, rationale, alternatives, risks и migration order.
|
||
- Не добавляй observable behavior вне Specs, не пересказывай upstream
|
||
artifacts и не пиши file-by-file checklist, verification commands,
|
||
будущие results, commits или Completion Evidence.
|
||
- Разреши до сохранения любой вопрос, который меняет Specs, approach или
|
||
Tasks. `Open Questions` оставляет только genuinely deferrable unknowns.
|
||
- После explicit Delta Specs approval и записи запусти planning verifier.
|
||
Исправляй Design только при `artifact-validation`; `invocation` и
|
||
`environment` требуют исправить вызов или prerequisite.
|
||
|
||
Required Shape:
|
||
- **Context**: current state и constraints подхода.
|
||
- **Goals / Non-Goals**: технические границы.
|
||
- **Decisions**: ключевые решения, rationale и alternatives.
|
||
- **Delivery Map**: ровно `frontend`, `backend`, `specs`, `docs`; каждая
|
||
area имеет `affected` outcome или конкретный `N/A` reason. `specs` всегда
|
||
`affected`.
|
||
- **Contract Gate Decision**: `runtime-openapi` = `required`, только когда
|
||
меняются обе стороны API contract; иначе конкретный `N/A`.
|
||
- **Risks / Trade-offs** и **Migration Plan**.
|
||
- В Migration Plan — `### Rollback Contract`: `required` с Trigger,
|
||
Actions, Data safety, Verification для auth/security, data integrity/
|
||
migration, public contract или другого труднообратимого решения; иначе
|
||
`N/A` с конкретным Reason.
|
||
|
||
Solution Assessment:
|
||
Включи section внутри Design, если change вводит или существенно заменяет
|
||
auth, security, storage, external integration, observability, caching,
|
||
concurrency, shared infrastructure/tooling либо другое дорогостоящее
|
||
необратимое решение. Сравни mature options по fit, maturity, security,
|
||
operating cost, constraints и migration cost. Custom implementation
|
||
допустима только после конкретной несовместимости alternatives. Не создавай
|
||
отдельный assessment artifact.
|
||
|
||
Покажи Design Change Owner и остановись до explicit approval. Если approach
|
||
несовместим с intent или behavior, вернись к самому раннему затронутому
|
||
artifact и инвалидируй downstream approvals.
|
||
requires:
|
||
- specs
|
||
|
||
- id: tasks
|
||
generates: tasks.md
|
||
description: Implementation checklist with trackable tasks
|
||
template: tasks.md
|
||
instruction: |
|
||
Critical Rules:
|
||
- Создай dependency-ordered implementation checklist только после explicit
|
||
Design approval. Формат каждого item:
|
||
`- [ ] X.Y [frontend|backend|specs|docs|workspace] action`.
|
||
- Каждый checkbox имеет ровно одну indented `- **Covers:**` и одну
|
||
`- **Verification:**` line, одного owner и помещается в одну рабочую
|
||
сессию.
|
||
- `Covers` содержит exact
|
||
`` `capability-path` — `Requirement heading` `` pairs либо
|
||
`` `N/A` — reason ``. Каждый Delta Requirement покрыт хотя бы одной task;
|
||
parallel requirement IDs не вводятся.
|
||
- `N/A` reason объясняет отсутствие самостоятельного observable behavior,
|
||
техническую необходимость и связь с утверждённым Design или delivery.
|
||
Не оставляй template placeholder. Смысл проверяется owner review, а не
|
||
text heuristic.
|
||
- Owner repository обязан быть `affected` в Delivery Map. Cross-repository
|
||
implementation разделяй. `workspace` владеет только orchestration или
|
||
verification и всегда использует содержательный `N/A`.
|
||
- Для каждой affected area добавь owned implementation и canonical gate.
|
||
Не создавай empty commit. Planned Verification задаёт command,
|
||
observable check или delivered artifact, но не будущий result.
|
||
- Новое behavior возвращает change в Specs; новое architecture — в Design;
|
||
multi-owner или vague task исправляется в Tasks. Не добавляй commits,
|
||
archive path или post-archive Completion Evidence.
|
||
- После записи запусти planning verifier. Исправляй Tasks только при
|
||
`artifact-validation`; `invocation` и `environment` не разрешают менять
|
||
checklist.
|
||
|
||
Testing:
|
||
Автоматические tests обязательны для security/privacy, денежных расчётов,
|
||
data integrity/migration, concurrency, public contracts, critical journeys
|
||
и подтверждённых regressions. DTO без логики, declarative structure, thin
|
||
adapter, прямолинейная orchestration, hygiene script и third-party behavior
|
||
используют существующий integration/contract gate, если нет собственного
|
||
branching, transformation, invariant или regression. Перед custom work в
|
||
mandatory assessment area включи утверждённый Solution Assessment action.
|
||
|
||
Group tasks под numbered `##` headings. Покажи Tasks Change Owner и
|
||
остановись до explicit approval. Если checklist требует новое behavior или
|
||
architecture, вернись к Specs или Design и инвалидируй Tasks approval.
|
||
requires:
|
||
- design
|
||
|
||
apply:
|
||
requires: [ tasks ]
|
||
tracks: tasks.md
|
||
instruction: |
|
||
Critical Rules:
|
||
- Apply допустим только после explicit approvals Proposal, Delta Specs,
|
||
Design и Tasks. Проверь exact OpenSpec version, canonical store
|
||
`wealth-ledger-specs` и planning verifier до implementation.
|
||
- Прочитай каждый path из `contextFiles`, возвращённых native OpenSpec apply
|
||
instructions, затем applicable repository-local `AGENTS.md` affected areas.
|
||
Не вычисляй planning paths и не создавай второй context map.
|
||
- Выполняй pending tasks по dependencies. Запускай planned Verification и
|
||
отмечай checkbox только после observed success.
|
||
- Feedback routing: intent/scope → Proposal; observable behavior → Delta
|
||
Specs; architecture/rollback → Design; decomposition/ownership/coverage →
|
||
Tasks. Останови downstream work, сообщи evidence и инвалидируй approvals от
|
||
самого раннего затронутого artifact.
|
||
- Механическая правка ограничена Markdown heading, typo без изменения
|
||
нормативного смысла или table alignment. Requirement wording, Scenario,
|
||
architecture и planned Verification являются semantic changes и требуют
|
||
соответствующего reapproval.
|
||
- `artifact-validation` разрешает исправить указанную planning form;
|
||
`invocation` требует исправить вызов; `environment` — prerequisite.
|
||
Последние два класса не разрешают менять planning artifact.
|
||
- Structural validation не заменяет semantic verification и independent
|
||
read-only review.
|