## Context

Workspace уже использует canonical OpenSpec graph и явные approval gates, но
существующие entrypoints ориентированы на отдельные OpenSpec-операции и могут
вести одну agent-задачу через несколько инженерных ролей. Нужен локальный слой
инструкций, который задаёт границу одной роли на сессию, не изменяя lifecycle
OpenSpec и не создавая второй источник требований.

## Goals / Non-Goals

**Goals:**

- Дать пользователю один устойчивый вход для начала или продолжения
  session-oriented SDD change.
- Выделить пять ролей в самостоятельные, краткие и независимо применимые
  agent skills.
- Передавать между задачами только навигационный state и immutable phase record;
  requirements, decisions и approvals остаются в canonical authority и
  conversation Change Owner.
- Сохранить retry flow Implementation ↔ Validation и возврат к planning при
  SPEC_ISSUE.

**Non-Goals:**

- Не менять OpenSpec schema, lifecycle, approvals, archive rules или repository
  quality gates.
- Не вводить executable workflow engine, новый CLI, фоновую orchestration либо
  автоматическое создание новых agent-сессий.
- Не заменять существующие generic OpenSpec skills и не переносить их content.

## Decisions

### Локальный набор из шести skills

В `.agents/skills` размещаются `sdd-session`, `sdd-discovery`,
`sdd-specification`, `sdd-implementation`, `sdd-validation` и
`sdd-finalization`. Каждый содержит только роль-specific procedure, входы,
выходы и границы полномочий. Их descriptions остаются discriminating, поэтому
skill можно выбрать по прямому запросу роли или по запросу начать/продолжить
session-oriented SDD, не захватывая обычную OpenSpec-работу.

`sdd-session` — тонкий router. Он восстанавливает state, выбирает ровно одну
разрешённую роль и передаёт выполнение соответствующему phase contract. Phase
skills проверяют, что запрошенная роль совпадает с текущим состоянием, поэтому
прямой вызов не может обойти переход workflow.

### Общий protocol и non-authority session state

Общие инварианты state, phase records, transition table и bootstrap prompt
живут в одном shared protocol рядом с локальными skills. Это единственное место
для их формы; phase skills ссылаются на него, а не копируют protocol.

Для каждого change создаётся local non-authority session directory под
`.agents/sdd/changes/<change>`. В нём mutable state pointer хранит только change
identity, текущую/следующую роль, ссылку на current record и iteration counters.
Каждая завершённая роль добавляет новый immutable phase record; предыдущие
records не переписываются. Record содержит краткий outcome, changed areas,
checks, findings или blockers и один next outcome. Он не содержит нормативных
требований, design/tasks либо approval markers.

Это состояние не является versioned planning artifact и не требуется для
доказательства approval: при его отсутствии или расхождении с OpenSpec skill
останавливается и запрашивает недостающий owner decision либо recovery
direction. После Specification requirements читаются из approved OpenSpec
artifacts; старые phase records читаются только для расследования.

### Границы ролей и переходы

Каждая роль завершает session только после записи собственного phase record,
обновления state pointer и выдачи короткого bootstrap prompt для новой задачи.
Discovery направляет к Specification только при достаточной определённости.
Specification остаётся адаптером к canonical OpenSpec: она создаёт лишь текущий
разрешённый artifact и останавливается для approval. Implementation выполняет
утверждённые Tasks, а при gap возвращает процесс к нужной planning boundary.
Validation — read-only относительно implementation/specification, выдаёт PASS,
FAIL или SPEC_ISSUE. Finalization допускается только после PASS и возвращает
blocker к ответственной роли вместо исправления.

### Явная граница между задачами

Skills не пытаются очистить контекст текущей agent-сессии технически. Вместо
этого они завершают работу после одной роли и выводят bootstrap prompt для новой
изолированной задачи. Bootstrap содержит identity change и вход `sdd-session`,
но не сериализует историю или содержание specification.

## Delivery Map

| Area | Status | Architectural outcome or N/A reason |
| --- | --- | --- |
| frontend | `N/A` | Не меняются пользовательское поведение, frontend agent routing, API snapshot или canonical frontend gate. |
| backend | `N/A` | Не меняются backend behavior, данные, API contract, backend agent routing или canonical backend gate. |
| specs | `affected` | Новый capability фиксирует наблюдаемые границы session-oriented SDD workflow в canonical OpenSpec store. |
| docs | `N/A` | Пользователь запросил local agent skills; durable engineering policy и as-built product documentation не меняются и не должны дублировать новый planning capability. |

### Contract Gate Decision

| Gate | Status | Reason |
| --- | --- | --- |
| runtime-openapi | `N/A` | Не меняются ни frontend-, ни backend-сторона публичного API contract. |

## Solution Assessment

| Option | Fit and maturity | Security / operating cost | Constraints / migration cost | Decision |
| --- | --- | --- | --- | --- |
| Local Markdown skills with one shared protocol | Соответствует пользовательскому пути `.agents/skills`, существующему skill format и требуемой роли instructions | Не добавляет runtime, credentials, data path или service | Требует вручную начать новую задачу по bootstrap prompt | Выбрано |
| Existing generic `.opencode/skills` | Зрелые entrypoints для individual OpenSpec operations | Не создаёт новых costs | Их fluid workflow не даёт одной роли на сессию и не хранит required session transitions | Не выбрано |
| Custom workflow CLI or orchestration service | Мог бы автоматизировать state transitions | Добавляет shared tooling, maintenance и риск ошибочных side effects | Противоречит first-iteration scope без подтверждённой повторяемой потребности | Отложено |

## Risks / Trade-offs

- Локальный state может устареть или отсутствовать. Router сверяет его с
  canonical change и не выводит approval из файла; при конфликте требуется
  recovery direction от Change Owner.
- Человеку нужно открыть новую задачу после bootstrap prompt. Это осознанная
  цена за изоляцию context и независимую Validation.
- Шесть skills увеличивают discovery surface. Короткие descriptions и единый
  `sdd-session` entrypoint ограничивают этот cognitive load.

## Migration Plan

1. Добавить shared session protocol и шесть local skills с исходными
   phase contracts.
2. Проверить каждый skill на корректный frontmatter, ссылки на protocol и
   отсутствие duplicated planning authority.
3. Использовать router на новом change; дальнейшую автоматизацию рассматривать
   только после повторяемого наблюдаемого затруднения.

### Rollback Contract

| Field | Decision |
| --- | --- |
| Status | `N/A` |
| Reason | Изменение добавляет обратимые локальные instructions и non-authority session records, не меняя auth, данные, migration или public contract. |
| Trigger | N/A |
| Actions | N/A |
| Data safety | N/A — workflow не создаёт и не изменяет пользовательские или runtime data. |
| Verification | N/A |