@bonesofspring/ai-rules 0.2.11 → 0.2.13

package/presets/cursor/php-laravel/skills/debug-investigation/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: debug-investigation
+description: Investigates bugs, failing tests, and unexpected behavior in PHP services with runtime evidence before applying minimal fixes. Use for bugfix tasks, debugger agent runs, or regressions.
+---
+
+# Debug investigation (PHP)
+
+1. Capture failing `composer test` / `vendor/bin/phpunit` / logs / stack traces.
+2. Hypothesize layer (domain vs adapter vs wiring).
+3. Minimal fix + regression test when appropriate.
+4. Document in `debug-report.md`.
+
+## Design guidance
+
+- Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.

package/presets/cursor/php-laravel/skills/feature-delivery/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: feature-delivery
+description: Delivers Laravel backend features end-to-end across routes, Form Requests, Policies, Actions/Services, Eloquent, Jobs/Events, tests, and post-change-test validation. Use when implementing or extending a feature, especially through /task or feature-developer.
+---
+
+# Feature Delivery (Laravel)
+
+1. Read brief, AC, and decomposition.
+2. Follow `feature-delivery-workflow.mdc` + `reference-features.mdc`: routes → Form Request/Policy → Action/Service → Eloquent → Controller/Resource → optional Job/Event → tests.
+3. Wire bindings only in Service Providers when needed.
+4. Add Feature tests for HTTP/DB paths; Unit tests for non-trivial Actions.
+5. After PHP edits: **invoke** `post-change-test.mdc` (+ `php-tooling.mdc`) → `php artisan test` / `composer test`.
+
+## Do / Don't
+
+- **Do** keep controllers thin; validate at Form Requests; authorize via Policies.
+- **Don't** put SQL/business rules in controllers or HTTP types in Models/Actions.
+- **Don't** use Playwright, XCUITest, Blade/Livewire a11y, or yarn lint as this stack's gate.
+
+## Scope discipline
+
+Implement only the current AC / decomposition task. Clarify ambiguity before coding; do not add unrelated hardening or drive-by refactors. See `feature-developer` → **Zero improvisation**.
+
+## Handoff
+
+Summarize by layer + validation. Update `.cursor/team/tasks/<slug>/status.json`.
+
+## Design guidance
+
+- Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.

package/presets/cursor/php-laravel/skills/integration-testing/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: integration-testing
+description: Plans, generates, and heals Laravel Feature/integration tests (HTTP kernel, DB fixtures, Job/Event fakes). Use for integration-test-* agents or Feature coverage.
+---
+
+# Integration testing (Laravel)
+
+1. Read `tests-integration` / `tests-e2e` rules and task brief.
+2. Prefer Feature tests through the HTTP kernel (`$this->postJson` / actingAs); DB via `RefreshDatabase` / factories; fake external HTTP and `Bus::fake` / `Event::fake` when async is in scope.
+3. Use CI job split if the repo already does.
+4. Do not introduce Playwright or XCUITest.
+
+## Agents
+
+`integration-test-planner` → `integration-test-generator` → `integration-test-healer` as needed.

package/presets/cursor/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 `.cursor/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 `.cursor/rules/`, `.cursor/agents/`, `.cursor/skills/`, or **`.cursor/team/conventions.md`** (prefer conventions for project gotchas)
+- One concrete snippet or file path
+- Whether it belongs in always-on vs globs vs skill vs conventions (see `PRESET-CONTRIBUTION` → Building blocks)
+
+Do not apply preset or conventions changes without user approval.

package/presets/cursor/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 `tests-unit.mdc`; heal with `unit-test-healer` when red.
+
+## Agents
+
+`unit-test-planner` → `unit-test-generator` → `unit-test-healer`.

package/presets/cursor/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/cursor/php-laravel/team/README.md

@@ -0,0 +1,28 @@
+# 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 |
+
+## Artifact manifest and receipts
+
+Each slug stores one context index at `.cursor/team/tasks/<slug>/artifact-manifest.json`. Schema v1 is defined by shared core `agent-team/agent-artifact-contracts.md`: every entry declares its producer, status, authoritative paths, acceptance-criteria IDs, decomposition task IDs, timestamps, and a terminal completion receipt.
+
+Producer/consumer rules:
+
+- Read the manifest first and use only the authoritative inputs needed by the current step; fall back to `brief.md`, `decomposition.md`, and `pipeline.json` when it is missing or stale, and report that gap.
+- Producers upsert only their stable entry IDs, preserve foreign entries, and finish with `completed`, `blocked`, `changes_requested`, or `validation_failed` receipt evidence.
+- The router owns `pipeline.json` and its routing entry; analyst, developer, verifier, and reviewer own their named outputs and receipts. Consumers do not edit another producer's receipt.
+- Agents do not mutate `status.json` or `metrics.json`. The orchestration runtime/hook is their single writer. Parallel receipt merges are serialized by the parent/orchestrator.
+
+## 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 orchestration runtime 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; `parallelOutcomes` holds per-agent outcomes for the current parallel join until the step advances. 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 .cursor/team`. It reports role/agent count, completed count, total/average duration, distinct completed run IDs, separate human-gate wait, and incomplete artifacts.

package/presets/cursor/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/cursor/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/cursor/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/cursor/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" }
+  ]
+}