Модель Workflow

Строгая цепочка фаз

constitution -> spec -> [inspect, опционально] -> plan -> tasks -> implement -> archive

verify при этом остаётся опциональным аудитом по требованию: всегда доступен, но по умолчанию пропускается.

Две лёгкие полосы ускоряют закрытие фич без раздувания артефактов:

• One-shot propose (/spk-propose): идея → spec.md + tasks.md за один проход (plan опционален), сразу к implement. Откатывается на /spk-spec при неоднозначности или мультифичевости.
• Express-полоса: крошечные/низкорисковые правки пропускают plan.md (и data-model.md). /spk-tasks выводит задачи напрямую из spec.md; плановые решения уходят в tasks.md → ## Implementation Context. Lifecycle позволяет фиче с spec.md + tasks.md дойти до implement и archive без отдельного плана.
• Цикл converge (/spk-converge / speckeep converge <slug>): после implement дешёво перепроверяет task/proof/surface/AC покрытие и сообщает разрывы. Агент добавляет follow-up задачи и повторяет до converged (жёсткая остановка после 2 раундов). Легче verify — файла отчёта нет.

speckeep guard . — машинный вариант гейта: exit 0 только когда каждая активная фича готова к архивации. Фичи из воркспейсов OpenSpec/Spec Kit переносятся командой speckeep import openspec|speckit ..

Для новых проектов (Greenfield) работа начинается с расширенной фазы Constitution (с флагом --foundation), которая фиксирует как правила процесса, так и технологический фундамент проекта.

SpecKeep предполагает branch-based delivery: каждая активная фича должна разрабатываться в своей git-ветке, а общим источником истины служат feature spec и feature artifact set, а не общий mutable memory-файл. Соглашение по умолчанию для веток — feature/<slug>.

Роли фаз

constitution

Определяет неоспоримые правила проекта.

Для проектов с нуля (Greenfield) конституция расширяется секциями Tech Stack и Core Architecture, заменяя собой отдельное проектирование «нулевой» фичи. Это создает единый, неархивируемый источник истины для всего проекта.

Обязательные секции:

• Purpose
• Core Principles
• Constraints
• Tech Stack
• Core Architecture
• Language Policy
• Development Workflow
• Governance
• Last Updated

После обновления конституции агент проверяет, не конфликтуют ли активные спеки с изменёнными правилами, и помечает их как NEEDS RE-INSPECT, не модифицируя сами спеки.

spec

Описывает одну фичу как конкретную спецификацию. Acceptance criteria должны использовать канонические маркеры Given / When / Then, даже если остальной текст документа на русском.

Для agent-facing /spk-spec SpecKeep должен поддерживать optional аргументы:

• --name <название фичи>
• --slug <slug фичи>
• --branch <имя ветки>

Семантика аргументов:

• --name задает каноническое имя фичи для текущего spec-запроса
• --slug переопределяет slug спецификации
• --branch переопределяет только рабочую ветку и не меняет slug спецификации

/spk-spec должен поддерживать два режима ввода:

• inline mode: имя и описание фичи передаются в одном сообщении
• staged mode: пользователь сначала передает /spk-spec --name ..., а описание фичи присылает следующим сообщением

Когда /spk-spec запускается от prompt-файла, SpecKeep должен предпочитать метаданные в начале файла, например:

name: Add dark mode
slug: add-dark-mode

Правила приоритета для slug:

1. --slug
2. slug:
3. slug, выведенный из --name
4. slug, выведенный из name:
5. safe fallback из filename или краткого user request только если он достаточно конкретен

Правила приоритета для имени фичи:

1. --name
2. name:
3. краткое имя, безопасно выведенное из user request

Если /spk-spec вызван с --name, но подробного описания фичи еще недостаточно для корректной спецификации, SpecKeep не должен терять контекст запроса: он должен запросить недостающее описание или интерпретировать следующее сообщение пользователя как продолжение того же spec-запроса.

По умолчанию feature-ветка должна быть feature/<slug>. Если пользователь явно передает --branch <name>, SpecKeep должен использовать это имя ветки вместо default, не меняя при этом slug спецификации.

Сама спецификация при этом должна оставаться branch-agnostic: рабочая ветка относится к execution context, а не к содержимому spec.md.

Если запрос неоднозначен, смешивает несколько фич или пытается вывести одну spec из нескольких изменений конституции, SpecKeep должен остановиться и запросить одно конкретное изменение до создания ветки и spec.

inspect

Проверяет качество и согласованность одной фичи. Фаза может находить отсутствующие сценарии, слабые acceptance criteria, конфликт с конституцией, drift между spec и plan или отсутствие покрытия задачами.

inspect перед plan опционален. Планирование может продолжаться без inspect report, если спецификация ясная и низкорисковая. Если inspect report присутствует, для продолжения он должен иметь валидный неблокирующий статус (pass или concerns).

--delta: режим инкрементальной перепроверки. После spec --amend перепроверяет только изменённые секции вместо полной проверки. Сохраняет валидные findings из предыдущего отчёта. Откатывается к полной проверке если изменения слишком обширны (>50% переписано).

Полный inspection report должен использовать стабильную структуру:

• # Inspect Report: <slug>
• ## Scope
• ## Verdict
• ## Errors
• ## Warnings
• ## Questions
• ## Suggestions
• ## Traceability
• ## Next Step

Verdict должен быть одним из значений:

• pass
• concerns
• blocked

Рекомендуемая семантика:

• pass: блокирующих проблем нет; остаются только незначительные предупреждения или их нет совсем
• concerns: workflow можно продолжать, но warnings или открытые вопросы желательно закрыть в ближайшее время
• blocked: следующая фаза иначе продолжила бы работу с отсутствующей или противоречивой информацией

Если inspection report сохраняется на диск, SpecKeep должен использовать канонический путь:

• specs/active/<slug>/inspect.md

Используйте .speckeep/templates/inspect-report.md как канонический шаблон, если отчет записывается в файл. Сохраненные inspect и verify reports должны начинаться с machine-readable metadata block с полями report_type, slug, status, docs_language и generated_at.

Стабильные идентификаторы критериев вроде AC-001 делают traceability легче и проще для валидации.

SpecKeep должен предпочитать cheap helper findings как первый слой доказательств для inspect:

• check-inspect-ready и inspect-spec должны сначала фиксировать структурные findings, прежде чем агент начнет расширять scope
• helper findings могут нести категории вроде structure, traceability, ambiguity, consistency и readiness
• inspect-агент должен сохранять эти findings в отчете и добавлять reasoning только там, где cheap checks не могут доказать утверждение напрямую
• helper findings нельзя молча игнорировать только потому, что общая narrative выглядит приемлемо

Для дешевой проверки spec <-> plan consistency SpecKeep должен предпочитать такую область анализа:

• всегда читать: CONSTITUTION.md, spec.md
• читать по необходимости: plan.md, tasks.md
• читать глубже только если этого требует конкретный вывод: data-model.md, contracts/, research.md
• implementation code по умолчанию не читать

Цель этой проверки — поймать явный drift, а не запускать полный архитектурный review. Полезные типы проверок:

• alignment между constitution и spec
• goal alignment
• необоснованное расширение scope
• отражение acceptance-critical behavior на уровне плана
• alignment между plan и tasks, если tasks.md уже существует
• сравнение planned implementation surfaces с Surface Map и Touches: в tasks.md, когда и plan, и tasks уже существуют
• соответствие конституции
• оправданность более богатых plan artifacts вроде data-model.md и contracts/

plan

Создает технические артефакты для одного feature package:

• plan.md
• data-model.md
• contracts/
• research.md (optional) — используется для выявления и разрешения технических неопределенностей, архитектурных компромиссов или интеграционных ограничений перед финализацией плана реализации.

tasks

Преобразует plan artifacts в исполнимые задачи. tasks.md лежит рядом с остальными feature artifacts внутри specs/active/<slug>/.

SpecKeep использует Ленивую декомпозицию для экономии контекста:

• Фаза tasks: Создает высокоуровневую карту (5-10 задач), привязанную к функциональным границам. Микро-задачи (на 1-5 строк кода) на этом этапе не приветствуются.
• Фаза implement: Агент может выполнять In-place Декомпозицию, добавляя вложенные подзадачи (напр., T1.1.1) только для текущей активной задачи.

Задачи должны быть сгруппированы по фазам и использовать phase-scoped task IDs вроде T1.1, T1.2 и T2.1.

Покрытие критериев приемки должно ссылаться на эти task IDs напрямую:

AC-001 -> T1.1, T2.1

--repair <task-id-list>: режим точечного исправления. Исправляет конкретные задачи, выявленные verify или review (напр. --repair T2.3,T3.1), не переписывая весь task list. Если repair выявляет проблему в плане — предлагает /spk-plan --update.

implement

Выполняет незавершенные задачи и обновляет tasks.md.

Правила In-place Декомпозиции:

• Подзадачи НЕ ДОЛЖНЫ добавлять новые файлы в список Touches: родительской задачи.
• Подзадачи НЕ ДОЛЖНЫ менять привязку AC-* родительской задачи.
• Если декомпозиция выявляет ошибку на уровне плана, агент ОБЯЗАН остановиться и запросить обновление плана.

Поведение по умолчанию должно оставаться полным: без явных scope-флагов SpecKeep проходит по всем незавершенным задачам в порядке task list.

Выборочное выполнение допустимо, когда пользователь явно сужает scope:

• --phase <номер> для одной implementation-фазы
• --tasks <список-task-id> для конкретных задач вроде T1.1,T2.1

--continue: режим возобновления. Начинает с первой незавершённой задачи, считая все ранее отмеченные задачи корректно выполненными. Batch-читает только surfaces из оставшихся незавершённых задач. Полезен после прерывания сессии (таймаут, context overflow).

--phase и --tasks не должны использоваться вместе в одном запуске.

Если выборочное выполнение перескакивает через незавершенную более раннюю работу, SpecKeep должен предупредить о риске порядка, не расширяя scope молча.

Во время реализации SpecKeep должен выдавать короткие runtime progress updates каждый раз, когда начинает или завершает фазу внутри текущего execution scope.

Для каждой завершенной задачи ([x]) в tasks.md записывается строка Proof: непосредственно под отмеченной задачей. Доказательства живут только в tasks.md — trace-маркеров в исходном коде нет.

Формат записи: Proof: <kind> <path> [<anchor>], где kind — одно из code|test|docs|chore, path — путь относительно корня репозитория, anchor — owning-функция/тест/тип (опционален, но рекомендуется).

Proof: code src/handlers/export.go ExportHandler
Proof: test src/tests/export_test.go TestExportFlow
Proof: docs docs/export.md

Задача [x] без хотя бы одной записи Proof: не считается выполненной — speckeep check и speckeep archive блокируют её. Proof: обязан указывать на существующий файл (отсутствующий файл — это жесткая ошибка); anchor должен по возможности резолвиться к owning-символу (отсутствующий anchor — предупреждение).

Такие phase-status сообщения должны следовать настроенному в проекте языку общения с агентом, а не автоматически сваливаться в английский.

verify

verify — это опциональный аудит по требованию: всегда доступен, но по умолчанию пропускается. Он запускается как audit + отчет на уровне AC (вторая оценка), когда нужно независимо подтвердить готовность фичи, а не как обязательный шаг цепочки.

Проверка использует данные прослеживаемости, собранные с помощью ./.speckeep/scripts/trace.* <slug>, который читает записи Proof: из tasks.md, чтобы подтвердить соответствие реализации заявленным задачам и критериям приемки. Сканирование исходного кода на аннотации не выполняется.

Поведение настраивается конфигом workflow.verify: optional|required (по умолчанию optional).

Полный verification report должен использовать стабильную структуру:

• # Verify Report: <slug>
• ## Scope
• ## Verdict
• ## Checks
• ## Errors
• ## Warnings
• ## Questions
• ## Not Verified
• ## Next Step

Рекомендуемые детали отчета:

• ## Scope должен фиксировать реальный verification mode, например default или deep
• ## Scope должен перечислять конкретные surfaces, которые реально проверялись
• ## Verdict должен включать archive_readiness
• ## Verdict должен включать однострочное summary, объясняющее, почему verdict обоснован
• ## Checks должен включать task_state
• ## Checks должен включать acceptance_evidence для тех AC-*, которые действительно подтверждены
• ## Checks должен включать implementation_alignment, привязанный к конкретной проверенной surface
• ## Not Verified должен перечислять material claims или surfaces, которые сознательно не проверялись

Verdict должен быть одним из значений:

• pass
• concerns
• blocked

Рекомендуемая семантика:

• pass: блокирующих проблем нет; остаются только незначительные предупреждения или их нет совсем
• concerns: по workflow можно двигаться дальше, но warnings или открытые вопросы желательно закрыть в ближайшее время
• blocked: архивирование или заявление о завершенности иначе опирались бы на противоречивое состояние реализации или незавершенную обязательную работу

Если evidence частичны, но явного противоречия не найдено, предпочитайте concerns, а не pass.

--persist: записать отчёт в specs/active/<slug>/verify.md в дополнение к выводу в чат. Без этого флага отчёт остаётся только в чате.

Используйте .speckeep/templates/verify-report.md как канонический шаблон, если отчет записывается в файл.

Сохраненные verify reports должны начинаться с того же machine-readable metadata block, что и inspect reports: report_type, slug, status, docs_language и generated_at.

Если доступен .speckeep/scripts/check-verify-ready.sh <slug>, SpecKeep должен предпочитать его как дешевую readiness-проверку перед более глубокой verification.

Используйте .speckeep/scripts/verify-task-state.sh <slug> как самый дешевый helper первого прохода, когда нужно только подтвердить состояние задач.

Примечание: сгенерированные обёртки .speckeep/scripts/* вычисляют корень проекта из расположения скрипта и передают его через --root, поэтому их можно запускать из любого текущего каталога.

archive

Копирует завершенный, вытесненный, отклоненный, abandoned или deferred feature package в specs/archived/<slug>/<YYYY-MM-DD>/.

Архивация — это CLI-only шаг. Она разрешена, когда фича детерминированно доказана (все задачи [x] имеют записи Proof:) ИЛИ после verify: pass. Наличие verify.md со статусом ≠ pass блокирует архив. При невыполнении предусловий скрипт возвращает понятную ошибку и проверяет наличие открытых задач. Статус по умолчанию — completed; для остальных статусов (superseded, abandoned, rejected, deferred) требуется явный --reason.

--compact архивирует «лёгко»: хранит только summary.md плюс git-указатель snapshot.sha (branch + commit + список файлов) вместо копий всех артефактов — полная история и так живёт в git. Восстановление (--restore) пересоздаёт файлы через git show. Компактный архив требует закоммиченные артефакты и git-репозиторий.

Зачем нужна такая цепочка

Эта модель делает инструмент строгим, но не бюрократичным:

• сначала фиксируются архитектурные и процессные законы
• затем пользовательское намерение превращается в spec
• потом появляется технический plan
• только после этого строятся tasks
• implementation идет по tasks, а не по широкой импровизации
• опциональный verify по требованию закрывает разрыв между implementation и archive, когда нужна независимая проверка
• завершенные feature packages уходят в archive, не раздувая активное рабочее пространство