@bonesofspring/ai-rules 0.2.0 → 0.2.2

package/presets/claude/next/rules/ui-and-accessibility/react-a11y-coding.md

@@ -1,37 +0,0 @@
----
-paths:
-  - app/src/ui/**/*.tsx
-  - app/src/ui/**/*.ts
----
-
-# A11y при разработке UI
-
-Reviewer (`accessibility-reviewer`) проверяет diff; эти правила — **при написании** кода.
-
-## Семантика и ARIA
-
-- Предпочитать **нативные элементы** (`button`, `a`, `label`, `input`) вместо `div` с `onClick`.
-- **`role` / `aria-*`** — только когда нативного аналога нет; не дублировать то, что даёт семантика.
-- Заголовки — иераархия `h1`–`h6` без пропусков уровней ради стилей.
-
-## Формы
-
-- Каждый input связан с **`label`** (`htmlFor` / `id` или обёртка).
-- Сообщения об ошибках — **`aria-describedby`**, `aria-invalid` при validation errors.
-- Кнопки submit vs button — явный `type`.
-
-## Клавиатура и focus
-
-- Все интерактивные элементы **достижимы с Tab** и активируются Enter/Space где ожидается.
-- **Modals/drawers** — focus trap, возврат focus на trigger при закрытии, Esc закрывает (если по UX).
-- Не удалять видимый **focus outline** без замены на доступный custom focus style.
-
-## Контент
-
-- Изображения — **`alt`** (пустой `alt` только для декора).
-- Иконки-кнопки — **`aria-label`** или visually hidden text.
-- Динамические обновления — `aria-live` для критичных status/error (умеренно).
-
-## Проверка
-
-- При сомнении — devtools a11y tree или `accessibility-reviewer` в pipeline для UI-heavy фич.

package/presets/claude/next/rules/ui-and-accessibility/react-ui.md

@@ -1,90 +0,0 @@
----
-paths:
-  - app/src/ui/**/*.tsx
-  - app/src/ui/**/*.ts
----
-
-# Общие правила компонентов
-
-- Использовать **функциональные компоненты** с хуками, без классов.
-- Компонент должен:
-  - быть максимально «тонким» по бизнес‑логике;
-  - делегировать состояние в store/хуки, если оно нужно в нескольких местах;
-  - опираться на **общие UI‑примитивы дизайна проекта** (пакеты или локальная библиотека компонентов), если они есть.
-- Перед новым кастомным контролом — поискать готовый или близкий компонент в репозитории / пакетах UI проекта и переиспользовать или расширить его.
-- Для повторяемой логики создавать `useSomething`‑хуки рядом или в `src/ui/hooks/**`.
-- При обращении к store, API, общим хелперам и утилитам компоненты и хуки должны использовать только их **public API** (например, `@/store`, `@/store/slices/Foo`, `@/lib/utils`), а не импортировать внутренние файлы реализации других модулей.
-
-# Структура файлов
-
-Для страницы/крупного блока:
-
-- `FeatureBlock.tsx` — JSX и композиция.
-- `styles.ts` или соседний модуль стилей — по конвенции репозитория (CSS Modules, CSS-in-JS, и т.д.).
-- `index.ts` — реэкспорт (если нужно наружу).
-
-## Дочерние компоненты (`./components`)
-
-- Локальные подкомпоненты, используемые только этим блоком, выносятся в **`./components/<ComponentName>/`** относительно папки родительского компонента (не оставлять крупные куски JSX и «внутренние» компоненты в том же файле, что и родитель).
-- У каждого такого подкомпонента — **своя** папка с тем же именем, что и публичное имя компонента:
-  - `ComponentName.tsx` — разметка и композиция;
-  - `styles.ts` — только стили этого подкомпонента (см. `ui-and-accessibility/component-styles.md`: не тянуть `styles` соседних компонентов);
-  - при необходимости — `ComponentName.data.ts`, `ComponentName.utils.ts`, `ComponentName.hooks.ts` по тем же правилам префикса, что и у родителя;
-  - опционально `index.ts` с реэкспортом.
-- Родитель импортирует подкомпонент из `./components/...`, а не держит его реализацию inline.
-
-Для переиспользуемого компонента:
-
-- Папка с именем компонента:
-  - `ComponentName.tsx`
-  - файлы стилей по принятой схеме;
-  - опционально: `types.ts`, `ComponentName.hooks.ts` (см. ниже про префикс).
-
-## Вспомогательные модули рядом с компонентом (именование)
-
-**Префикс имени файла = публичное имя компонента** (как у `ComponentName.tsx` в этой папке), в **PascalCase**. Не вводить отдельные «говорящие» имена файлов по смыслу содержимого (`analysisPreparationIconMap.ts`, `buildAnalysisIdToNameMap.ts` и т.п.) — так теряется связь с компонентом и плодятся одноразовые названия.
-
-**Суффикс по роли:**
-
-| Суффикс | Назначение | Примеры содержимого |
-|--------|------------|---------------------|
-| `ComponentName.data.ts` | Статические данные и конфигурация для UI | мапы `id → иконка/лейбл`, константы списков, таблицы соответствий для отображения |
-| `ComponentName.utils.ts` | Чистые функции без React | форматирование, предобработка пропсов/данных для рендера, `build…`/`map…`‑хелперы |
-| `ComponentName.hooks.ts` | Хуки, используемые только этим блоком | локальные `use…` (если не вынесены в `src/ui/hooks/**`) |
-
-- Несколько констант/мапов или несколько функций — **по-прежнему один** `.data.ts` и один `.utils.ts`, не дробить по «темам» отдельными файлами без веской причины (размер, разные зоны ответственности на уровне подкомпонентов).
-- Если логика принадлежит **подкомпоненту** в подпапке (`components/Child/Child.tsx`), те же правила применяются к **`Child.data.ts`**, **`Child.utils.ts`** относительно этого подкомпонента.
-- Тесты для утилит и данных — рядом в `__tests__/` или с суффиксом `.test.ts`, согласно `testing/tests-unit.md`, с тем же префиксом (`RequestForAnalysisRecommendations.utils.test.ts` и т.д.).
-
-# Стили и дизайн‑токены
-
-- **Корневой** styled-элемент компонента в соседнем `styles` — **`Root`** (`<s.Root>`). Подробнее: `ui-and-accessibility/component-styles.md`.
-- Порядок объявлений в CSS / `styled` — как требует Stylelint: см. `ui-and-accessibility/css-property-order.md`.
-- Для визуала использовать **тот стек стилей и токенов, который уже в проекте** (переменные, тема, общие классы, дизайн‑пакет).
-- Избегать:
-  - inline‑стилей, кроме простых случаев;
-  - дублирования оформления, уже закрытого общими примитивами;
-  - «магических» литералов (`#xxxxxx`, произвольные `17px` / `23px`), если в проекте есть токены или масштаб.
-- Если подходящего токена нет — локальный примитив **в одном месте** с последующим выравниванием под систему дизайна при возможности.
-
-# Пропсы и типизация
-
-- **Не передавать пропы в компоненты через spread** (`<Foo {...x} />`). Только явные атрибуты; подробности — `ui-and-accessibility/no-props-spread.md` (в `app/src/ui` это дополнительно ловит ESLint).
-- Описывать пропсы через `type Props = { ... }` или `interface Props { ... }`.
-- Не использовать `any`; при необходимости — обобщения (`<T>`), `unknown`, type guards.
-- Для доменных сущностей использовать типы из `@/types` (и enum из `@/types/enums`), а не описывать их заново (`architecture/public-imports.md`).
-
-# Логика и side effects
-
-- Side effects и асинхронщина — по возможности в store (thunk’и, middleware) или в отдельные хуки.
-- Компоненты не должны:
-  - напрямую знать детали API (URL, структура DTO);
-  - заниматься маппингом «сырых» DTO — только доменные типы;
-  - содержать нетривиальные вычисления и преобразования данных (булевы флаги, сложная склейка строк, агрегаты и т.п.). Данные для отображения должны быть подготовлены на этапах маппинга/подготовки (API → доменная модель → store).
-
-# Тестирование UI
-
-- Для нетривиальных компонентов добавлять тесты:
-  - **Testing Library** для React, как принято в проекте;
-  - проверять поведение и бизнес‑правила, а не конкретные CSS‑классы.
-- В тестах ориентироваться на текст, роли и aria‑атрибуты.

package/presets/claude/next/skills/ci-investigation/SKILL.md

@@ -1,36 +0,0 @@
----
-name: ci-investigation
-description: Investigates failing CI checks on PRs and branches — lint, type-check, unit, e2e — with local reproduction and minimal fixes. Use when CI is red or for ci-fix pipeline tasks.
----
-
-# CI Investigation
-
-## Workflow
-
-1. Identify the **first failing check** (lint, type-check, unit, e2e, build).
-2. Capture error output — ignore cascading failures until root cause is found.
-3. Reproduce locally with the same commands CI uses from `app/`:
-   - `lint:js`, `lint:css`, `type-check`
-   - targeted unit test file or suite
-   - affected Playwright spec if e2e failed
-4. Inspect git diff for changed files related to the failure.
-5. Apply **minimal fix** — no unrelated refactors.
-
-## Artifact
-
-Write `ci-report.md` under the task slug folder:
-
-- Failed check name and link/log excerpt
-- Root cause classification
-- Fix applied (or handoff to feature-developer)
-- Validation commands and results
-
-## Handoff Rules
-
-- Config-only or one-line fixes → fix in place, re-run check.
-- Missing tests or architecture work → document and route to `feature-developer` or `qa-tester`.
-- Flaky e2e → prefer `playwright-test-healer` after ci-investigator identifies the spec.
-
-## Validation
-
-Always re-run the failing command locally before marking complete. If environment blocks execution, state the exact command and blocker.

package/presets/claude/next/skills/code-review/SKILL.md

@@ -1,26 +0,0 @@
----
-name: code-review
-description: Reviews pull requests, merge requests, git diffs, and branch changes using the preset's architecture, import, UI, API, and testing standards. Use when the user asks for review or when code-reviewer runs in an agent pipeline.
----
-
-# Code Review
-
-## Inputs
-
-Use the local repository as the source of truth: `git status`, `git diff`, task artifacts under `.claude/team/tasks/<slug>/` when present, and opened files. Do not invent hosting metadata such as labels, CI status, or reviewers.
-
-## Review Order
-
-1. Understand the intent and affected layers.
-2. Check correctness and regressions first.
-3. Verify architecture boundaries: UI does not know DTO/transport, store does not depend on UI, API services do not pull UI/store.
-4. Check public imports through `@/types` and `@/api`, plus barrel updates for new public symbols.
-5. Review UI consistency, styling conventions, and prop shape.
-6. Check tests: unit for mapper/domain logic, behavior tests for HTTP client changes, e2e plan/spec updates for user flows.
-7. Report validation gaps: lint, stylelint, type-check, or relevant tests not run.
-
-## Output
-
-Lead with findings ordered by severity. Each finding should include the file, the problem, impact, and a concrete fix direction. If there are no findings, say so and call out remaining test or validation risk.
-
-For agent team tasks, write `.claude/team/tasks/<slug>/review.md` and set `status.json` to `completed` or `changes_requested`.

package/presets/claude/next/skills/debug-investigation/SKILL.md

@@ -1,28 +0,0 @@
----
-name: debug-investigation
-description: Investigates bugs, failing tests, crashes, and incorrect behavior with runtime evidence before applying minimal fixes. Use for bugfix tasks, debugger agent runs, regressions, and flaky test diagnosis.
----
-
-# Debug Investigation
-
-## Process
-
-1. Reproduce the issue or collect the closest available evidence: error output, failing test, browser snapshot, logs, or user steps.
-2. Define expected vs actual behavior in one sentence.
-3. Trace the failing path through the smallest relevant slice of the codebase.
-4. Identify the root cause before editing. Avoid broad refactors during bugfixes.
-5. Apply the smallest fix that preserves existing architecture and public contracts.
-6. Add or update a regression test when the behavior is user-facing or likely to recur.
-7. Run the narrow failing check first, then relevant lint/type/test validation.
-
-## Artifacts
-
-For agent team tasks, write `.claude/team/tasks/<slug>/debug-report.md` with:
-
-- Reproduction steps or evidence source.
-- Root cause.
-- Fix scope.
-- Regression coverage.
-- Remaining risk.
-
-Update `status.json` when complete.

package/presets/claude/next/skills/feature-delivery/SKILL.md

@@ -1,15 +0,0 @@
----
-name: feature-delivery
-description: Delivers Next.js frontend features end-to-end across domain types, API services, store, UI, mocks, tests, and validation. Use when implementing or extending a feature, especially through /task or feature-developer.
----
-
-# Feature Delivery
-
-1. Read task brief, acceptance criteria, and decomposition if present.
-2. Read **`rules/architecture/feature-delivery-workflow.md`** and **`rules/architecture/reference-features.md`** — follow layer order and mirror closest reference feature.
-3. Add or update focused tests for changed behavior.
-4. Validation from `app/`: see **`rules/tooling-and-review/post-change-lint.md`** (pipeline: scoped lint OK if next step is `build-verifier`).
-
-## Handoff
-
-Summarize by layer, validation results, and known gaps. Agent team: update `.claude/team/tasks/<slug>/status.json`.

package/presets/claude/next/skills/playwright-e2e/SKILL.md

@@ -1,31 +0,0 @@
----
-name: playwright-e2e
-description: Plans, generates, and heals Playwright e2e tests using this preset's app/__tests__/e2e layout, *.cases.md plans, page objects, and shared helpers. Use for e2e planning, test generation, or fixing failing browser tests.
----
-
-# Playwright E2E
-
-## Project Layout
-
-- Test root: `app/__tests__/e2e`.
-- Test plans: `*.cases.md` files under the matching feature folder.
-- Executable specs: `*.spec.ts` files in the same folder.
-- Seed/setup reference: `app/__tests__/e2e/seed.spec.ts`.
-
-Do not introduce top-level `specs/` or `tests/` folders for real coverage unless the user explicitly asks for a sandbox.
-
-## Planner
-
-Create or update the relevant `*.cases.md` file. Each scenario should include title, preconditions, steps, and expected result. Cover happy path, important edge cases, validation, and error states.
-
-## Generator
-
-Generate specs from `*.cases.md` into the same folder. Reuse existing page objects and `_shared/` helpers. Keep test names aligned with scenario names.
-
-## Healer
-
-Fix selectors, waits, setup, or page-object details without weakening business assertions. Use the matching `*.cases.md` file as the behavior contract.
-
-## Validation
-
-Run the affected spec when feasible. If the environment blocks execution, report the command that should be run and the blocker.

package/presets/claude/next/skills/technical-retro/SKILL.md

@@ -1,40 +0,0 @@
----
-name: technical-retro
-description: Facilitates technical retrospectives for tasks, sprints, incidents, releases, and agent-team pipelines. Use when the user asks for retro, postmortem, process review, or action items after delivery.
----
-
-# Technical Retro
-
-## Inputs
-
-Ask for missing period, focus, task slug, participants, or format constraints. If a slug is provided, read `.claude/team/tasks/<slug>/` artifacts and local git status/diff. Do not invent facts not present in artifacts or the user's message.
-
-## Facilitation Principles
-
-- Focus on process and system behavior, not blame.
-- Separate facts, interpretations, and proposed actions.
-- Balance what worked with what slowed delivery.
-- Keep action items concrete, owned, and measurable.
-
-## Default Structure
-
-1. Goal and scope.
-2. Timeline or factual observations.
-3. What worked.
-4. What hurt quality, speed, or confidence.
-5. Root causes for the top one or two issues.
-6. Experiments and action items.
-
-## Agent Team Block
-
-For `/task` pipelines, include router, analyst, developer, **build-verifier**, reviewer, QA/e2e, hooks, and rules.
-
-## Preset feedback loop
-
-If the same issue appeared in 2+ tasks, add section **Preset updates**:
-
-- Proposed change to `.claude/rules/`, `.claude/agents/`, or `.claude/skills/`
-- One concrete diff or file path to update
-- Whether it belongs in session-start rules vs `paths:` vs skill
-
-Do not apply preset changes without user approval.

package/presets/claude/next/skills/unit-testing/SKILL.md

@@ -1,32 +0,0 @@
----
-name: unit-testing
-description: Plans, generates, and heals unit tests for mappers, thunks, HTTP client behavior, and React components using colocated *.spec.ts files and tests-unit rules. Use for unit test planning, generation, or fixing failing unit tests.
----
-
-# Unit Testing
-
-## Project Layout
-
-- Specs colocated with source: `*.spec.ts` / `*.spec.tsx` next to the module under test.
-- Legacy `*.test.ts` / `*.test.tsx` — do not rename without a separate task.
-- Runner: Jest or Vitest as configured in the target repo; components use `@testing-library/react`.
-
-Follow **`rules/testing/tests-unit.md`**.
-
-## Planner
-
-Write or update `.claude/team/tasks/<slug>/unit-test-plan.md`.
-
-Each scenario needs a Russian `it()` title (capital letter after each sentence). Cover mappers, thunks, client behavior branches, and component interactions per AC.
-
-## Generator
-
-Implement specs from `unit-test-plan.md`. Reuse project test-store, HTTP mocks, and existing test utilities. Do not change production code.
-
-## Healer
-
-Fix mocks, async timing, selectors, and setup — preserve business assertions. Use `unit-test-plan.md` and `brief.md` as the behavior contract.
-
-## Validation
-
-Run affected unit tests from `app/` when feasible. Report command, pass/fail, and remaining gaps vs plan.

package/presets/claude/next/team/README.md

@@ -1,46 +0,0 @@
-# Agent team artifacts
-
-Каталог артефактов пайплайна «команда агентов» Claude Code.
-
-## Layout
-
-```
-.claude/team/
-  active-task.json
-  tasks/
-    <slug>/
-      pipeline.json
-      status.json
-      brief.md
-      decomposition.md
-      debug-report.md
-      validation-report.md
-      architecture.md
-      migration-plan.md
-      ci-report.md
-      a11y-review.md
-      perf-report.md
-      security-review.md
-      api-contract-review.md
-      unit-test-plan.md
-      documentation.md
-      review.md
-```
-
-## pipeline.json schema
-
-Same as Cursor preset — see `agents/task-router.md` for examples with `build-verifier`, `skipIf`, and `parallel` steps.
-
-## status.json
-
-Use **`phase: executing`** in pipeline mode. Optional fields: `parallelCompleted`, `retryAfterFix`, `validation_failed` state.
-
-## Workflow entry
-
-```bash
-/task <описание>
-/task-continue <slug>
-/technical-retro <slug>
-```
-
-Legacy: `/feature-start`, `/feature-continue`.

package/presets/claude/next/team/tasks/.gitkeep

@@ -1 +0,0 @@
-# Keep the task artifact directory in the published preset.

package/presets/cursor/next/AGENTS.md

@@ -1,43 +0,0 @@
-# Next.js stack — Cursor agent team
-
-Краткая точка входа для Cursor. Подробные правила — `.cursor/rules/*.mdc`; сценарии — `.cursor/skills/**`.
-
-See `.cursor/rules/README.md` for the full catalog and loading strategy.
-
-## Quick start
-
-| Задача | Куда смотреть |
-|--------|----------------|
-| Любая новая work-задача | `/task` → `commands/task.md` + `agent-team-orchestrator.mdc` (+ `agent-team-intake.mdc` on-demand) |
-| Новая фича end-to-end | skill `feature-delivery` + `feature-delivery-workflow.mdc` |
-| Стек и слои | `next-app-core.mdc` |
-| Эталонные фичи | `reference-features.mdc` (заполнить пути в репо) |
-| После правок кода | `post-change-lint.mdc` |
-| Code review MR | skill `code-review` + `code-review-mr.mdc` |
-| Валидация перед review | agent `build-verifier` |
-| Техническое ретро | `/technical-retro` + skill `technical-retro` |
-
-## Когда использовать `/task`
-
-- Реализация, багфикс, миграция, тесты, ревью MR, CI-fix — **предпочтительно через `/task`**.
-- Простой one-liner без архитектурного риска — можно без pipeline, если пользователь явно просит.
-- Вопросы «как работает X» — ответ без `/task`.
-
-## Intent → pipeline (кратко)
-
-| intent | Типичный pipeline |
-|--------|-------------------|
-| `feature` | analyst → developer (+ unit) → build-verifier → reviewer → e2e/QA |
-| `bugfix` | debugger → developer (skip if fixed) → build-verifier → reviewer |
-| `ci-fix` | ci-investigator → developer (skip if resolved) → build-verifier |
-| `migration` | analyst → migration-specialist → developer → build-verifier → reviewer → QA |
-
-Полная таблица — `agents/README.md`, router — `agents/task-router.md`.
-
-## Install
-
-```bash
-npx @bonesofspring/ai-rules init cursor --preset next
-```
-
-Копирует rules, commands, agents, hooks, skills, team, `hooks.json`, `BUGBOT.md`, `AGENTS.md`.

package/presets/cursor/next/BUGBOT.md

@@ -1,14 +0,0 @@
-# Cursor Bugbot Review Guidelines
-
-Follow the **`code-review` skill** and **`code-review-mr.mdc`** for the full checklist.
-
-## Priorities
-
-1. Correctness regressions and runtime bugs.
-2. Architecture boundary violations (`architecture-boundaries.mdc`).
-3. Missing unit tests for mapper/domain/store logic; e2e updates for user flows.
-4. Type safety, `@/types` / `@/api` imports, barrel exports.
-
-## Review style
-
-Lead with concrete findings: file, impact, fix direction. Skip style-only nits unless they violate lint rules or project conventions.

package/presets/cursor/next/agents/README.md

@@ -1,158 +0,0 @@
-# `.cursor/agents` (preset next)
-
-Ролевые subagents для командного пайплайна Cursor.
-
-## Planning and routing
-
-| Agent | Файл | Production-код |
-|-------|------|----------------|
-| Router | `task-router.md` | no |
-| Аналитик | `task-analyst.md` | no |
-| Архитектор | `solution-architect.md` | no |
-| Migration planner | `migration-specialist.md` | no |
-| API contract reviewer | `api-contract-reviewer.md` | no |
-
-## Implementation and CI
-
-| Agent | Файл | Production-код |
-|-------|------|----------------|
-| Debugger | `debugger.md` | minimal fix only |
-| CI investigator | `ci-investigator.md` | minimal CI fix only |
-| Build verifier | `build-verifier.md` | no |
-| Разработчик | `feature-developer.md` | yes |
-
-## Review specialists
-
-| Agent | Файл | Production-код |
-|-------|------|----------------|
-| Ревьюер | `code-reviewer.md` | no |
-| A11y reviewer | `accessibility-reviewer.md` | no |
-| Security reviewer | `security-reviewer.md` | no |
-| Performance auditor | `performance-auditor.md` | no |
-
-## Testing
-
-| Agent | Файл | Production-код |
-|-------|------|----------------|
-| QA | `qa-tester.md` | tests only |
-| Unit planner | `unit-test-planner.md` | no |
-| Unit generator | `unit-test-generator.md` | tests only |
-| Unit healer | `unit-test-healer.md` | tests only |
-| Playwright planner | `playwright-test-planner.md` | e2e plans only |
-| Playwright generator | `playwright-test-generator.md` | e2e tests only |
-| Playwright healer | `playwright-test-healer.md` | e2e fixes only |
-
-## Documentation
-
-| Agent | Файл | Production-код |
-|-------|------|----------------|
-| Tech writer | `tech-writer.md` | docs only |
-
-Копируется в `.cursor/agents/` при `ai-rules init cursor --preset next`.
-
-## Оркестрация
-
-| Command | Назначение |
-|---------|------------|
-| `/task <desc>` | Router → dynamic pipeline → первый agent |
-| `/task-continue <slug>` | После human gate |
-| `/feature-start`, `/feature-continue` | Legacy (совместимость) |
-
-Правило: `agent-team-orchestrator.mdc`. План: `pipeline.json` в `.cursor/team/tasks/<slug>/`.
-
-## Intent → pipeline (кратко)
-
-| intent | Типичный pipeline |
-|--------|-------------------|
-| `feature` | analyst → developer (+ unit) → build-verifier → reviewer → e2e/QA |
-| `bugfix` | debugger → developer (skipIf fixed) → build-verifier → reviewer |
-| `ci-fix` | ci-investigator → developer (skipIf resolved) → build-verifier |
-| `migration` | analyst → migration-specialist → developer → reviewer → QA |
-| `perf-audit` | performance-auditor |
-| `a11y` | analyst → developer → a11y-reviewer → code-reviewer |
-| `unit-only` | unit-planner → unit-generator (или healer) |
-| `e2e-only` | playwright planner → generator (или healer) |
-| `docs-only` | analyst → tech-writer |
-
-Опциональные шаги (router добавляет по контексту): `api-contract-reviewer`, `accessibility-reviewer`, `security-reviewer`, `performance-auditor`, `tech-writer`.
-
-## pipeline.json reference
-
-### Step fields
-
-| Field | Required | Description |
-|-------|----------|-------------|
-| `agent` | yes | Subagent name (kebab-case) or array for `parallel: true` |
-| `label` | yes | Short human-readable step name |
-| `scope` | no | e.g. `unit-in-dev`, `e2e-only`, `regression`, `full` |
-| `skipIf` | no | `debugger.fixed` \| `ci-investigator.resolved` |
-| `parallel` | no | When `true` and `agent` is array — invoke all in one turn |
-
-### Minimal template
-
-```json
-{
-  "slug": "<slug>",
-  "intent": "feature",
-  "summary": "One-line task summary",
-  "steps": [
-    { "agent": "task-analyst", "label": "Clarify and decompose" },
-    { "agent": "feature-developer", "label": "Implement + unit tests", "scope": "unit-in-dev" },
-    { "agent": "build-verifier", "label": "Lint, type-check, unit smoke" },
-    { "agent": "code-reviewer", "label": "Code review" }
-  ],
-  "humanGates": ["after:task-analyst"],
-  "autoChain": true,
-  "skipped": []
-}
-```
-
-### Example: parallel reviewers
-
-```json
-{
-  "intent": "feature",
-  "steps": [
-    { "agent": "task-analyst", "label": "Clarify" },
-    { "agent": "feature-developer", "label": "Implement", "scope": "unit-in-dev" },
-    { "agent": "build-verifier", "label": "Validation gate" },
-    {
-      "agent": ["accessibility-reviewer", "security-reviewer"],
-      "parallel": true,
-      "label": "A11y and security"
-    },
-    { "agent": "code-reviewer", "label": "Review" }
-  ],
-  "humanGates": ["after:task-analyst"]
-}
-```
-
-### Example: bugfix skipIf
-
-```json
-{
-  "intent": "bugfix",
-  "steps": [
-    { "agent": "debugger", "label": "Root cause" },
-    { "agent": "feature-developer", "label": "Fix if needed", "skipIf": "debugger.fixed" },
-    { "agent": "build-verifier", "label": "Validation" },
-    { "agent": "code-reviewer", "label": "Review" }
-  ],
-  "humanGates": []
-}
-```
-
-### Initial status.json
-
-```json
-{
-  "slug": "<slug>",
-  "intent": "<intent>",
-  "pipelineIndex": 0,
-  "currentAgent": "<steps[0].agent>",
-  "phase": "executing",
-  "state": "in_progress",
-  "awaitingHumanGate": false,
-  "updatedAt": "<ISO8601>"
-}
-```