@bonesofspring/ai-rules 0.2.10 → 0.2.12

package/presets/claude/php-laravel/skills/technical-retro/SKILL.md

@@ -0,0 +1,54 @@
+---
+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** (composer test / vendor/bin/phpunit), reviewer, QA/integration tests, hooks, and rules.
+
+## Wrong-turn taxonomy (optional)
+
+When artifacts or the user mention agent mistakes, tag incidents:
+
+| Kind | Signal |
+|------|--------|
+| `correction` | User pushback («no», «don't», «actually») |
+| `retry` | Same tool/approach 2+ times before success |
+| `waste` | Many searches before the right file |
+| `reversal` | Edit then revert / delete |
+| `dead-end` | Env/tool failure (missing binary, wrong path) |
+
+Severity: **high** (explicit correction / large waste) · **med** · **low**. Confidence 0–100 — be honest; low-confidence items are optional.
+
+## Preset feedback loop
+
+If the same issue appeared in **2+** tasks (or **3+** for packaging a new rule/skill — Rule of Three), add section **Preset updates**:
+
+- Proposed change to `.claude/rules/`, `.claude/agents/`, `.claude/skills/`, or **`.claude/team/conventions.md`** (prefer conventions for project gotchas)
+- One concrete snippet or file path
+- Whether it belongs in session-start vs `paths:` vs skill vs conventions (see `PRESET-CONTRIBUTION` → Building blocks)
+
+Do not apply preset or conventions changes without user approval.

package/presets/claude/php-laravel/skills/unit-testing/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: unit-testing
+description: Plans, generates, and heals PHPUnit/Pest unit tests for Laravel Actions, Services, and pure helpers using *Test.php and tests-unit rules. Use for unit-test planning, generation, or healing.
+---
+
+# Unit testing (Laravel)
+
+1. Prefer PHPUnit (or Pest if already in repo/CI) under `tests/Unit/**` (`*Test.php`).
+2. Fake Eloquent collaborators / repos when justified; use `Bus::fake` / `Event::fake` for side effects — no real HTTP kernel or DB unless the harness already boots lightly.
+3. Follow `testing/unit.md`; heal with `unit-test-healer` when red.
+
+## Agents
+
+`unit-test-planner` → `unit-test-generator` → `unit-test-healer`.

package/presets/claude/php-laravel/skills/write-adr/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: write-adr
+description: Author an Architecture Decision Record (ADR) with Context, Decision, Consequences, and Links. Use when capturing a durable technical choice for the team.
+---
+
+# Write ADR
+
+On-demand skill for durable architecture decisions. Stack-agnostic sections — fill with project-specific paths and links.
+
+## When to use
+
+- Choosing between non-trivial alternatives (storage, layering, library, API shape).
+- Recording a decision that future agents/humans should not silently reverse.
+- User asks for an ADR, decision log, or “why did we pick X”.
+
+## Template
+
+Create (or append) a short markdown ADR in the repo’s agreed location (e.g. `docs/adr/`, `.cursor/team/`, wiki). Suggested filename: `NNNN-short-title.md`.
+
+```markdown
+# ADR NNNN: <Title>
+
+## Context
+What problem / constraint / force requires a decision?
+
+## Decision
+What we chose (one clear option). Include rejected alternatives briefly if useful.
+
+## Consequences
+Positive and negative outcomes; follow-up work; what becomes harder.
+
+## Links
+Related PRs, issues, rules, prior ADRs, diagrams.
+```
+
+## Guidelines
+
+- Prefer one decision per ADR.
+- Keep Context factual; Decision imperative and short.
+- Link living gotchas to `team/conventions.md` when the decision becomes a recurring local pattern.
+- Do not put ADR bodies only in root `AGENTS.md` (overwrite on init).

package/presets/claude/php-laravel/team/README.md

@@ -0,0 +1,17 @@
+# Agent team artifacts (preset php-laravel)
+
+Каталог артефактов пайплайна «команда агентов» для Laravel backend.
+
+| Fixture | Pipeline sketch |
+|---------|-----------------|
+| `feature-full.json` | full delivery + integration-test-* + build-verifier |
+| `feature-light.json` | developer → build-verifier (`php artisan test` / configured static analysis) |
+| `bugfix-standard.json` | debugger → fix → build-verifier |
+
+## Local metrics ledger
+
+`metrics.json` is an append-only schema-v1 event ledger for one task run. It contains only allowlisted IDs, task dimensions, timestamps, outcomes, and attribution confidence—never prompts, secrets, file paths, or contents. The router writes `task_started` / `attempt_started`; the hook records host-clock completion and human-gate edges under a per-task lock with temp-and-rename.
+
+`status.json.activeAttempts` is a transient timing bridge keyed by `attemptId`; `lastCompletedAttempt` is diagnostic. For parallel stops, the hook must use a stable payload identity or the sole active attempt. Otherwise an explicit `.metrics-receipts.json` receipt is fallback data marked `source: agent`, `attributionConfidence: fallback`; it must never guess from `currentAgent`.
+
+Aggregate with `node packages/ai-rules/scripts/aggregate-agent-task-metrics.mjs --team-root .claude/team`. It reports role/agent count, completed count, total/average duration, distinct completed run IDs, separate human-gate wait, and incomplete artifacts.

package/presets/claude/php-laravel/team/conventions.md

@@ -0,0 +1,21 @@
+# Living conventions (team)
+
+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/claude/php-laravel/team/fixtures/bugfix-standard.json

@@ -0,0 +1,12 @@
+{
+  "profile": "standard",
+  "summary": "Laravel bugfix",
+  "steps": [
+    { "agent": "debugger", "label": "Investigate with runtime evidence" },
+    { "agent": "feature-developer", "label": "Apply minimal fix" },
+    {
+      "agent": "build-verifier",
+      "label": "php artisan test / composer test / static analysis"
+    }
+  ]
+}

package/presets/claude/php-laravel/team/fixtures/feature-full.json

@@ -0,0 +1,15 @@
+{
+  "profile": "full",
+  "summary": "Laravel full feature delivery",
+  "steps": [
+    { "agent": "task-analyst", "label": "Decompose" },
+    { "agent": "solution-architect", "label": "Design", "model": "strong" },
+    { "agent": "feature-developer", "label": "Implement" },
+    { "agent": "unit-test-planner", "label": "Plan unit tests" },
+    { "agent": "unit-test-generator", "label": "Generate unit tests" },
+    { "agent": "integration-test-planner", "label": "Plan Feature/integration tests" },
+    { "agent": "integration-test-generator", "label": "Generate Feature tests" },
+    { "agent": "build-verifier", "label": "php artisan test / composer test / static analysis", "model": "cheap" },
+    { "agent": "code-reviewer", "label": "Review" }
+  ]
+}

package/presets/claude/php-laravel/team/fixtures/feature-light.json

@@ -0,0 +1,8 @@
+{
+  "profile": "light",
+  "summary": "Laravel light feature delivery",
+  "steps": [
+    { "agent": "feature-developer", "label": "Implement Laravel feature slice" },
+    { "agent": "build-verifier", "label": "php artisan test / composer test / static analysis", "model": "cheap" }
+  ]
+}

package/presets/cursor/go/agents/build-verifier.md

@@ -29,7 +29,7 @@ Hard gates: twin-map (stacks include **go**), token-budget (alwaysApply/session-
 
 Document PASS/FAIL in `validation-report.md`.
 
-1. **Root AGENTS template:** each installable preset (`cursor|claude` × `next|ios-swift|go|java`) must ship `REPO_AGENTS.md` when validating preset packaging → **FAIL** if missing.
+1. **Root AGENTS template:** each installable preset (`cursor|claude` × `next|ios-swift|go|java|mcp-ts|php-hexagonal`) must ship `REPO_AGENTS.md` when validating preset packaging → **FAIL** if missing.
 2. **Hooks cookbook:** default `hooks.json` must **not** reference `hooks/examples/` → **FAIL** if it does.
-3. **No react-performance on ios/go/java:** skill directory / required handoff must be absent under ios-swift, go, and java → **FAIL** (leakage). Prefer `check:preset-leakage`.
+3. **No react-performance on ios/go/java:** skill directory / required handoff must be absent under ios-swift, go, java, mcp-ts, php-hexagonal, and php-laravel → **FAIL** (leakage). Prefer `check:preset-leakage`.
 4. **Rule eval (WARN):** `scripts/check-rule-eval.mjs` / `yarn check:rule-eval` should exist for maintainers; smoke optional. Hard fail only when the opt-in eval job runs — not part of default `check:preset-structure`.

package/presets/cursor/go/agents/task-router.md

@@ -67,3 +67,7 @@ Write `.cursor/team/tasks/<slug>/pipeline.json` and initial `status.json` via th
 ## Handoff
 
 Intent + steps table + skipped + gates → invoke `steps[0].agent` (unless retro).
+
+## Metrics initialization
+
+Alongside `pipeline.json` and `status.json`, create `metrics.json` with `schemaVersion: 1`, immutable task dimensions, `task_started`, and a generated `runId`. Before the parent invokes each agent, append `attempt_started` and set `status.activeAttempts[attemptId]` with agent, step index, attempt number, and host-clock `startedAt`. For parallel work create one entry per agent; do not use `currentAgent` to identify their completion.

package/presets/cursor/go/commands/task-continue.md

@@ -22,22 +22,19 @@ description: Continue an agent-team task after a human gate, pause, or review ch
 ## Алгоритм
 
 1. Запиши `.cursor/team/active-task.json` → `{ "slug": "<slug>" }`.
-2. Сбрось gate: `awaitingHumanGate: false`.
-3. Определи **следующий шаг**:
-   - После approval analyst/architect: `pipelineIndex + 1` → следующий agent в `steps`.
-   - После `changes_requested`: снова **feature-developer** (тот же index или найди developer в steps).
-4. Обнови `status.json`:
-   ```json
-   {
-     "pipelineIndex": <n>,
-     "currentAgent": "<steps[n].agent>",
-     "phase": "executing",
-     "state": "in_progress",
-     "awaitingHumanGate": false
-   }
-   ```
-5. Вызови subagent для `currentAgent` с контекстом slug и артефактов.
-6. Hook `chain-team-phases.sh` продолжит цепочку по `pipeline.json`, если `autoChain: true`.
+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 .cursor/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`.
 
 ## Артефакты для handoff
 
@@ -47,3 +44,7 @@ description: Continue an agent-team task after a human gate, pause, or review ch
 | 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 |
+
+## Metrics
+
+On human-gate resume, the hook action above appends `human_gate_ended` under the per-task lock **before** any new `attempt_started`. Agents must not calculate durations.

package/presets/cursor/go/commands/task.md

@@ -47,3 +47,7 @@ description: Route a natural-language task through the agent-team pipeline: task
 ## Legacy
 
 `/feature-start` и `/feature-continue` остаются совместимыми; для новых задач предпочитай `/task`.
+
+## Metrics
+
+Initialize `metrics.json` before the first invocation with frozen task dimensions and `task_started`; add one `activeAttempts[attemptId]` entry plus `attempt_started` per scheduled agent. On `/task-continue`, append `human_gate_ended` (referencing the stored gate event) before activating the next attempt. Do not calculate durations in agents.

package/presets/cursor/go/commands/technical-retro.md

@@ -79,3 +79,7 @@ description: Facilitate a technical retrospective for a period, incident, releas
 - Не приписывать цитаты и факты без входа.
 - Не выдавать HR‑рекомендации.
 - Если просят только шаблон — **шаблон повестки** без выдуманного контента.
+
+### 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.