specs/openspec/changes/archive/2026-08-27-add-session-oriented-sdd-skills/design.md

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