docs(specs): archive session workflow changes
This commit is contained in:
@@ -0,0 +1,137 @@
|
||||
## 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 |
|
||||
Reference in New Issue
Block a user