138 lines
9.7 KiB
Markdown
138 lines
9.7 KiB
Markdown
## 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 |
|