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//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. `` 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//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//` when creating the delta at `specs//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: ` followed by description - Use SHALL/MUST for normative requirements (avoid should/may) - Each scenario: `#### Scenario: ` 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 `/openspec/specs//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 `/openspec/specs//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.