@bonesofspring/ai-rules 0.2.21 → 0.2.23

package/presets/mavis/next/commands/spec-start.md

@@ -0,0 +1,24 @@
+# Spec start — generate / bootstrap product specs
+
+Routes intent **`spec-gen`** (or bootstrap) → **task-analyst** in **author mode** → human gate (`after:task-analyst`) → stop, or continue to feature-developer if the user asked to implement after.
+
+## What to do
+
+1. Extract description from arguments after the spec-start procedure in `.mavis/commands/spec-start.md` (domain, page/feature ids, sources).
+2. Generate a **slug** (kebab-case, ≤48 chars), e.g. `spec-<domain>-<id>`.
+3. Ensure `.mavis/team/tasks/<slug>/` exists (Write artifacts; not Shell mkdir).
+4. Write `.mavis/team/active-task.json` → `{ "slug": "<slug>" }`.
+5. Write minimal `pipeline.json`: task-analyst → (optional stop) → feature-developer only if user asked implement-after. **No separate spec-author agent.**
+6. Invoke **task-analyst** with: author mode; load **`product-specs`** + **`product-specs-authoring`** + skill **`spec-authoring`**; Bootstrap if `docs/specs/` absent, else Generate. Optional: if arguments/AC ask research-before-spec, also load skill **`spec-discovery`** (not default).
+7. Wait for analyst. **Do not** invoke feature-developer until human gate passes.
+
+## Human gate
+
+- Show created/updated spec paths and INDEX diff.
+- Ask user to approve drafts (`status: draft` → promote) or send edits.
+- Continue: continue `<slug>` using `.mavis/commands/task-continue.md` only after approval when implementation follows; otherwise stop after docs.
+
+## Notes
+
+- Greenfield invent of INDEX is allowed **only** via this command, explicit ask, or AC bootstrap language.
+- mcp-ts: analyst-only author/sync (no tech-writer).

package/presets/mavis/next/commands/task-continue.md

@@ -0,0 +1,50 @@
+# Task continue — after human gate or pause
+
+Resume the pipeline from `pipeline.json`.
+
+## Arguments
+
+`<slug>` — task identifier.
+
+## Preconditions
+
+1. Read `.mavis/team/tasks/<slug>/pipeline.json` and `status.json`.
+2. Continue if:
+   - `awaitingHumanGate: true` or `state: awaiting_approval`, **or**
+   - `state: changes_requested` (after review), **or**
+   - the task was interrupted and must resume from `pipelineIndex`.
+
+## Algorithm
+
+1. Write `.mavis/team/active-task.json` → `{ "slug": "<slug>" }`.
+2. **Human gate resume** (`awaitingHumanGate` / `awaiting_approval`):
+   1. **Do not** manually increment `pipelineIndex` or invent `currentAgent` first.
+   2. Close the gate + activate the next attempt via the **installed** hook (single authority for ledger + status):
+
+```bash
+printf '%s\n' '{"status":"completed","action":"end_human_gate","activateNext":true}' | bash .mavis/hooks/chain-team-phases.sh
+```
+
+   3. Re-read `status.json` (and the hook `followup_message`).
+   4. Invoke the subagent named in `status.currentAgent` / followup — do **not** advance the pipeline a second time.
+3. **Review `changes_requested`** (not a human gate): if `currentAgent` is **`mockup-reviewer`**, this is the FAIL-only mockup gate — do **not** retry `feature-developer`. Read `mockup-review.md` and resume via the human-gate path (`end_human_gate` / `activateNext`). Otherwise: set `currentAgent` to `feature-developer` (same index / find developer in steps), `state: in_progress`, then invoke developer. Do **not** call `end_human_gate` unless `activeHumanGateEventId` is set.
+4. **`blocked` + `currentAgent: mockup-reviewer`** (`BLOCKED_MCP`): skip-forward via the same `end_human_gate`/`activateNext` path (explicit «proceed without MCP»). Do not invent DS claims.
+5. **Other resume**: restore `pipelineIndex` / `currentAgent` from status and invoke that agent.
+6. After the invoked agent completes, `chain-team-phases.sh` on `subagentStop` continues the chain when `autoChain: true`.
+
+## Artifacts for handoff
+
+| Agent | Read |
+|-------|------|
+| feature-developer | brief.md (incl. **Related specs**), decomposition.md, ux-design.md (if present), mockup-review.md (if present), validation-report.md (if retry), review.md (if retry), architecture.md; if `docs/specs/INDEX.md` exists → load **`product-specs`** |
+| build-verifier | git diff, decomposition.md |
+| code-reviewer | brief.md, validation-report.md, git diff |
+| mockup-reviewer | mockup-review.md |
+| qa-tester | brief.md, decomposition.md, scope from pipeline step |
+
+## Product specs (docs/specs)
+
+When the next agent is **feature-developer** (or other implementer): if `docs/specs/INDEX.md` exists or brief lists approved specs, instruct them to load **`product-specs`** and honor **Related specs** / approved generated specs as behavior SoT. Soft-fail on miss; never invent product behavior.
+
+If analyst ran **author mode**, confirm human approved drafts before developer. Pass spec paths + INDEX diff in the handoff. No-op if INDEX is absent and no approved specs.
+

package/presets/mavis/next/commands/task.md

@@ -0,0 +1,50 @@
+# Task — unified entry point (router + pipeline)
+
+Main command for task intake. Parent agent = orchestrator (`agent-team-orchestrator.md`). Intake for work requests without the task procedure in `.mavis/commands/task.md` — `agent-team-intake.md`.
+
+## Arguments
+
+Everything after the task procedure in `.mavis/commands/task.md` is the task description in natural language.
+
+Examples:
+
+- `/task Добавить фильтр по дате в Order History` (Add date filter to Order History) <!-- i18n-keep: E4 -->
+- `/task Order History падает при пустом списке — пофикси` (Order History crashes on empty list — fix it) <!-- i18n-keep: E4 -->
+- `/task CI упал на type-check в PR` (CI failed on type-check in PR) <!-- i18n-keep: E4 -->
+- `/task Миграция HTTP-клиента на fetch` (Migrate HTTP client to fetch) <!-- i18n-keep: E4 -->
+- `/task Проверь a11y формы логина` (Check login form a11y) <!-- i18n-keep: E4 -->
+- `/task Покрой unit-тестами mapper payments` (Cover payments mapper with unit tests) <!-- i18n-keep: E4 -->
+- `/task Напиши changelog для релиза фильтров` (Write changelog for filters release) <!-- i18n-keep: E4 -->
+- `/task Сделай ревью моих изменений в store/orders` (Review my changes in store/orders) <!-- i18n-keep: E4 -->
+- `/task Напиши e2e для сценария оплаты` (Write e2e for payment scenario) <!-- i18n-keep: E4 -->
+- `/task Ревью макета https://figma.com/design/...` (Review a Figma mockup) <!-- i18n-keep: E4 -->
+- `/task Разработай UX для Order History` (Design UX flows without Figma) <!-- i18n-keep: E4 -->
+
+## Procedure
+
+1. **Slug** — kebab-case from the description (≤48 characters). Create `.mavis/team/tasks/<slug>/` via **Write** (e.g. placeholder `pipeline.json` or empty marker) — runtime/hook owns `status.json` — **not** via Shell `mkdir` (sandbox → `Operation not permitted`).
+2. **Router** — invoke subagent **task-router** with the task description and slug path.
+3. **Plan** — show the user the table from `pipeline.json`: intent, steps, skipped, humanGates.
+4. **Intent retro** — if `intent === "retro"`, run the technical-retro procedure in `.mavis/commands/technical-retro.md` and **stop**.
+5. **Start** — after router:
+   - confirm `pipeline.json` and `active-task.json`;
+   - **do not** write lifecycle fields in `status.json` / `metrics.json` yourself — orchestration runtime/hook owns them (see **agent-artifact-contracts**). If `status.json` is missing, only minimal bootstrap is allowed (`slug`, `intent`, `pipelineIndex: 0`, `currentAgent: steps[0]`, `state: in_progress`) — **do not** increment `pipelineIndex` manually;
+   - invoke subagent for `pipeline.steps[0].agent` (slug, artifact paths, scope).
+6. **After each agent** — wait for hook handoff / reconciliation terminal receipt → `status.state`; do not start the next step until `status.json` reflects handoff (or until there is a `followup_message` from the hook).
+7. **Human gate** — if after the current step there is a gate in `humanGates` (`after:<agent>`), after the agent finishes **stop** and ask for continue `<slug>` using `.mavis/commands/task-continue.md`.
+
+## Do not
+
+- Invoke developer before router and (if in pipeline) analyst/architect.
+- Hardcode role order — only `pipeline.json`.
+- Skip human gate without explicit continue.
+
+## If slug is taken
+
+- `awaitingHumanGate` / `state: awaiting_approval` → offer artifact review or continue `<slug>` using `.mavis/commands/task-continue.md`.
+- `in_progress` → ask: continue or new slug.
+
+
+## Metrics
+
+Runtime/hook owns `metrics.json` and `status.json` attempt ledgers. Before the first invocation ensure `task_started` and one `activeAttempts[attemptId]` + `attempt_started` exist (router/runtime bootstrap — parent must not invent parallel indices). On the task-continue procedure in `.mavis/commands/task-continue.md`, run the installed chain hook `end_human_gate` action (or wrapper) so `human_gate_ended` lands before the next attempt. Do not calculate durations in agents.

package/presets/mavis/next/commands/technical-retro.md

@@ -0,0 +1,80 @@
+# Technical retrospective
+
+The agent acts as a **neutral facilitator of a technical retrospective**, not as a code reviewer or people evaluator. Use skill **`technical-retro`** as the primary scenario.
+
+## When to use
+
+- User asks: "retro", "technical retro", "sprint/iteration review", "action items after release" — also common RU phrasing: «ретро» (retro), «техническое ретро» (technical retro), «разбор спринта/итерации» (sprint/iteration review) <!-- i18n-keep: E4 -->.
+- After completing the agent-team pipeline.
+- Context available: period, topic (release, incident), task slug, notes.
+
+## Inputs (gather; do not invent)
+
+Request when missing:
+
+- **Period and focus**.
+- **Task slug** (if retro is about agent-team work).
+- **Participants/roles** (if relevant).
+- **Constraints**: time, format (async vs sync).
+
+### Agent-team artifacts (if slug present)
+
+Read from the repository:
+
+- `.mavis/team/tasks/<slug>/pipeline.json`
+- `.mavis/team/tasks/<slug>/brief.md`
+- `.mavis/team/tasks/<slug>/decomposition.md`
+- `.mavis/team/tasks/<slug>/status.json`
+- Git diff / `git status` for changed files
+
+Do not attribute facts not present in artifacts, diff, or the user's message.
+
+## Facilitation principles
+
+- **Safety**: process and system, not "blame".
+- **Specificity**: from abstractions to observable events.
+- **Balance**: positives and growth areas.
+- **Action items**: owner and deadline for each.
+- **Do not mix with code review** — separate blocks if both were requested.
+
+## Default session structure
+
+1. **Goal and scope**.
+2. **Fact gathering**: went well / blocked / surprises.
+3. **Theme grouping** (3–7).
+4. **Root causes** for 1–2 painful themes.
+5. **Experiments** (1–3 process changes).
+6. **Action items**: what / owner / by when / success criteria.
+
+## "Agent work" block (required when slug present)
+
+If retro is tied to an agent-team pipeline:
+
+| Question | What to capture |
+|--------|-----------------|
+| Router | Intent error, extra/missing pipeline steps |
+| Analyst | Assumption errors, missed AC, extra/missing tasks |
+| Decomposition | Incomplete layer coverage, wrong order, blocked dependencies |
+| Developer | Scope creep, missed rules, lint/type gaps |
+| Reviewer | Missed defects, false positives, checklist quality |
+| QA | AC test coverage, flakiness, e2e plan gaps |
+
+**Action items** in this block — improve **prompts, subagents, and rules** (not only code).
+
+## Response format
+
+- Header: period, focus, slug (if any), assumptions.
+- Agenda by stage.
+- **"Agent work"** block (if applicable).
+- Themes — bullets; disputed points — **questions for the team**.
+- **Action items** at the end.
+
+## Constraints
+
+- Do not attribute quotes or facts without input.
+- No HR recommendations.
+- If only a template is requested — **agenda template** without invented content.
+
+### Metrics evidence
+
+When `metrics.json` exists, run the local aggregation script and report the cohort, sample size, incomplete artifacts, attribution confidence, active attempt duration, and human-gate wait separately. Do not treat gate wait or malformed ledgers as agent duration.

package/presets/mavis/next/hooks/README.md

@@ -0,0 +1,22 @@
+# Mavis hooks
+
+No documented MiniMax project hook API is assumed.
+
+## Shipped
+
+`chain-team-phases.sh` — manual/semi-auto runner. After a producer receipt:
+
+```bash
+printf '%s\n' '{"status":"completed","attemptId":"<runtime-attempt-id>"}' \
+  | bash .mavis/hooks/chain-team-phases.sh
+```
+
+`<runtime-attempt-id>` comes from `.mavis/team/tasks/<slug>/status.json`.
+Do not invent it. Agents never write lifecycle fields in `status.json` or
+`metrics.json`.
+
+## Omitted
+
+- `hooks.json` — no native registration schema
+- `guard-shell-command.sh` — not wired; do not describe it as enforcement
+- `hooks/examples/**` — no confirmed Mavis event API