@bonesofspring/ai-rules 0.2.24 → 0.2.26

package/presets/opencode/php-hexagonal/ai-local/conventions.md

@@ -0,0 +1,21 @@
+# Living conventions
+
+Consumer-owned store for post-init gotchas, patterns, and decisions. **Not** always-on. Fill after `ai-rules init`. Root `AGENTS.md` only points here.
+
+## Gotchas
+
+<!-- e.g. fragile flows, “never do X in this repo” -->
+
+-
+
+## Patterns
+
+<!-- local patterns beyond reference-features table -->
+
+-
+
+## Decisions
+
+<!-- short pointers to ADRs / product choices that affect code -->
+
+-

package/presets/opencode/php-hexagonal/commands/README.md

@@ -0,0 +1,52 @@
+# `.opencode/commands` (preset php-hexagonal)
+
+Slash commands are copied to `.opencode/commands/` on `ai-rules init opencode --preset php-hexagonal`. OpenCode loads `/<filename>` natively.
+
+## Agent commands
+
+| Command | Purpose |
+|---------|---------|
+| **`/task <description>`** | **Main entry point:** router → pipeline.json → required roles in order |
+| `/task-continue <slug>` | After human gate or pause |
+| `/technical-retro [slug]` | Retro; with slug — “Agent work” section |
+
+## `/task` examples
+
+```
+/task Добавить CancelOrder use case (domain → ports → HTTP) (Add CancelOrder use case) <!-- i18n-keep: E4 -->
+→ analyst → developer → build-verifier → reviewer → QA (integration)
+
+/task HTTP controller tests CreateOrder падает на пустом body (CreateOrder HTTP controller tests fail on empty body) <!-- i18n-keep: E4 -->
+→ debugger → developer → reviewer → QA (regression)
+
+/task CI упал на composer test / vendor/bin/phpunit / static analysis в PR #142 (CI failed on composer test / phpunit / static analysis in PR #142) <!-- i18n-keep: E4 -->
+→ ci-investigator → developer → reviewer
+
+/task Миграция на PHP 21 / обновление PHP framework edge (Migrate to PHP 21 / update PHP framework edge) <!-- i18n-keep: E4 -->
+→ analyst → migration-specialist → developer → reviewer → QA
+
+/task Проверь OpenAPI drift для /orders (Check OpenAPI drift for /orders) <!-- i18n-keep: E4 -->
+→ api-contract-reviewer (or analyst → …)
+
+/task Покрой unit-тестами CancelOrder use case (Cover CancelOrder use case with unit tests) <!-- i18n-keep: E4 -->
+→ unit-planner → unit-generator
+
+/task Напиши README для нового adapter persistence (Write README for new persistence adapter) <!-- i18n-keep: E4 -->
+→ analyst → tech-writer
+
+/task Сделай ревью изменений в adapters/inbound/http (Review changes in adapters/inbound/http) <!-- i18n-keep: E4 -->
+→ reviewer only
+
+/task Repository contract для OrderRepository (Repository contract for OrderRepository) <!-- i18n-keep: E4 -->
+→ integration-test-planner → generator → healer (or QA e2e-only = integration)
+```
+
+## Related files
+
+- Subagents: `../agents/` (**22** roles, including `task-router.md`, `codebase-analyzer.md`, and `integration-test-{planner,generator,healer}`; no `accessibility-reviewer` / Playwright / XCUITest)
+- Orchestrator: `../rules/agent-team-orchestrator.md`
+- Skills: `../skills/` (`feature-delivery`, `code-review`, `debug-investigation`, `ci-investigation`, `unit-testing`, `integration-testing`, `technical-retro`)
+- Artifacts: `.ai.local/team/README.md` (`pipeline.json`, `status.json`)
+- Hooks: `../hooks/chain-team-phases.sh` only (semi-auto runner; no `hooks.json`)
+
+Create and edit commands via `/commands` in Cursor or directly in this preset folder.

package/presets/opencode/php-hexagonal/commands/spec-start.md

@@ -0,0 +1,32 @@
+---
+description: Bootstrap or generate docs/specs (INDEX + page/feature) via task-analyst author mode. Optional docs-only path with human gate.
+---
+
+## Invocation arguments
+
+$ARGUMENTS
+
+# 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 `/spec-start` (domain, page/feature ids, sources).
+2. Generate a **slug** (kebab-case, ≤48 chars), e.g. `spec-<domain>-<id>`.
+3. Ensure `.ai.local/team/tasks/<slug>/` exists (Write artifacts; not Shell mkdir).
+4. Write `.ai.local/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: `/task-continue <slug>` 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/opencode/php-hexagonal/commands/task-continue.md

@@ -0,0 +1,56 @@
+---
+description: Continue an agent-team task after a human gate, pause, or review changes request using pipeline.json and status.json.
+---
+
+## Invocation arguments
+
+$ARGUMENTS
+
+# Task continue — after human gate or pause
+
+Resume the pipeline from `pipeline.json`.
+
+## Arguments
+
+`<slug>` — task identifier.
+
+## Preconditions
+
+1. Read `.ai.local/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`.
+
+## Procedure
+
+1. Write `.ai.local/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 .opencode/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): 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. **Other resume**: restore `pipelineIndex` / `currentAgent` from status and invoke that agent.
+5. 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, 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 |
+| 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/opencode/php-hexagonal/commands/task.md

@@ -0,0 +1,55 @@
+---
+description: Route a natural-language task through the agent-team pipeline: task-router, pipeline.json, and the first planned specialist.
+---
+
+## Invocation arguments
+
+$ARGUMENTS
+
+# Task — unified entry point (router + pipeline)
+
+Main command for task intake. Parent agent = orchestrator (`agent-team-orchestrator.md`). Intake for work requests without `/task` — `agent-team-intake.md`.
+
+## Arguments
+
+Everything after `/task` is the task description in natural language.
+
+Examples:
+
+- `/task Добавить use case отмены заказа` (Add cancel-order use case) <!-- i18n-keep: E4 -->
+- `/task Handler падает при пустом body — пофикси` (Handler crashes on empty body — fix it) <!-- i18n-keep: E4 -->
+- `/task CI упал на composer test / composer test в PR` (CI failed on composer test in PR) <!-- i18n-keep: E4 -->
+- `/task Миграция на новый PHP / обновление Composer модуля` (Migrate to new PHP / update Composer module) <!-- i18n-keep: E4 -->
+- `/task Покрой unit-тестами OrderService` (Cover OrderService with unit tests) <!-- i18n-keep: E4 -->
+- `/task Напиши changelog для релиза фильтров` (Write changelog for filters release) <!-- i18n-keep: E4 -->
+- `/task Сделай ревью моих изменений в application/` (Review my changes in application/) <!-- i18n-keep: E4 -->
+- `/task Напиши integration tests для persistence adapter` (Write integration tests for persistence adapter) <!-- i18n-keep: E4 -->
+
+## Procedure
+
+1. **Slug** — kebab-case from the description (≤48 characters). Create `.ai.local/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 `/technical-retro` 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 `/task-continue <slug>`.
+
+## 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 `/task-continue <slug>`.
+- `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 `/task-continue`, 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/opencode/php-hexagonal/commands/technical-retro.md

@@ -0,0 +1,88 @@
+---
+description: Facilitate a technical retrospective for a period, incident, release, or completed agent-team task slug.
+---
+
+## Invocation arguments
+
+$ARGUMENTS
+
+# 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:
+
+- `.ai.local/team/tasks/<slug>/pipeline.json`
+- `.ai.local/team/tasks/<slug>/brief.md`
+- `.ai.local/team/tasks/<slug>/decomposition.md`
+- `.ai.local/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/opencode/php-hexagonal/hooks/README.md

@@ -0,0 +1,22 @@
+# OpenCode hooks
+
+No Cursor `hooks.json` and no TypeScript plugin in v1.
+
+## Shipped
+
+`chain-team-phases.sh` — manual/semi-auto runner. After a producer receipt:
+
+```bash
+printf '%s\n' '{"status":"completed","attemptId":"<runtime-attempt-id>"}' \
+  | bash .opencode/hooks/chain-team-phases.sh
+```
+
+`<runtime-attempt-id>` comes from `.ai.local/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 in this preset
+- `guard-shell-command.sh` — not wired; do not describe it as enforcement
+- `hooks/examples/**` — plugin port is a follow-up