@softspark/ai-toolkit 2.10.0 → 2.11.0

package/AGENTS.md

@@ -453,7 +453,7 @@ Skills are invocable commands or auto-loaded knowledge sources:
 - **app-builder**: Full-stack app scaffolding with stack-selection matrix: Next.js, React+Vite, Nuxt, Astro, FastAPI, Django, Laravel, React Native, Flutter, Unity. Triggers: scaffold, bootstrap, new project, starter template, build app, landing page, dashboard, API, mobile app, CLI, e-commerce, game. Load when user wants to start a new project from scratch.
 - **architecture-audit**: Explore codebase organically for architectural friction, discover shallow modules, and propose module-deepening refactors as GitHub issue RFCs using parallel sub-agent interface designs. Use when user wants to improve architecture, find shallow modules, deepen modules, or reduce coupling. Codex-adapted: uses native subagents and plan tracking.
 - **architecture-decision**: Architecture decision making via trade-off analysis in RFC/RFD/ADR format: context, constraints, 3+ options, comparison, recommendation. Triggers: architecture decision, ADR, RFC, RFD, trade-offs, options comparison, design choice, pick between, should we use, evaluate approach. Load when weighing 2+ architectural options or writing decision records.
-- **biz-scan**: Scan codebase for business opportunities and KPIs
+- **biz-scan**: Scans codebase for business opportunities by analyzing database schemas, API endpoints, tracking events, and feature flags to surface underutilized capabilities, missing KPIs, and monetization gaps. Use when the user asks about revenue opportunities, business metrics, KPI coverage, analytics gaps, or monetization analysis of a codebase.
 - **brand-voice**: Loaded when writing documentation, content, README, or user-facing text. Prevents generic LLM rhetoric and enforces direct, technical voice.
 - **briefing**: Generate executive daily briefing across all agents
 - **build**: Build the project with auto-detected toolchain
@@ -478,7 +478,7 @@ Skills are invocable commands or auto-loaded knowledge sources:
 - **documentation-standards**: KB document conventions: YAML frontmatter (7 required fields), 5-category taxonomy (reference/howto/procedures/troubleshooting/best-practices), directory-category matching, validate.sh CI rules. Triggers: kb/, KB document, architecture note, SOP, runbook, howto, frontmatter, knowledge base entry, documentation standard. Load when creating or editing any file under kb/.
 - **ecommerce-patterns**: E-commerce domain patterns: cart, checkout flow, payment providers (Stripe/Adyen), order state machine, inventory, promotions, tax, B2B vs B2C. Triggers: cart, checkout, product, SKU, inventory, payment, Stripe, Shopify, Medusa, Magento, order status, promotion, tax calculation, coupon, refund. Load when working on any e-commerce feature.
 - **evaluate**: Evaluate skill quality and RAG retrieval accuracy
-- **evolve**: Evolve agent definitions via meta-architect
+- **evolve**: Analyzes failure patterns and inefficiencies in agent/skill definitions, then drafts and applies targeted improvements to system prompts, tool permissions, and behavioral rules. Use when the user asks to improve agent behavior, refine skill definitions, update system prompts, or optimize agent configurations based on observed failures.
 - **explain**: Explain code, architecture, or concepts with diagrams
 - **explore**: Explore codebase structure, stack, and architecture
 - **fix**: Auto-fix lint errors, type issues, and simple bugs
@@ -509,13 +509,13 @@ Skills are invocable commands or auto-loaded knowledge sources:
 - **panic**: Emergency stabilization via system-governor agent
 - **performance-profiling**: Performance measurement and optimization: four golden signals (latency/traffic/errors/saturation), p50/p95/p99, baseline-change-measure loop, flame graphs, load testing. Triggers: performance, slow, latency, p99, flame graph, profile, bottleneck, optimization, load test, benchmark, CPU profiling, memory leak. Load when diagnosing or optimizing slow code or services.
 - **persona**: Switch engineering persona at runtime: backend-lead, frontend-lead, devops-eng, junior-dev
-- **plan**: Plan implementation with tasks and success criteria
+- **plan**: Breaks down feature requests and project goals into phased implementation plans with task lists, agent assignments, dependency graphs, and success criteria. Use when the user asks to plan a feature, create an implementation roadmap, break down a coding task, or outline project phases.
 - **plan-writing**: Implementation plan and pre-mortem drafting: phase breakdown, success criteria, risks, rollback plan, acceptance tests, estimated effort. Triggers: implementation plan, pre-mortem, phased plan, project plan, task breakdown, success criteria, rollback strategy, risk register. Load when user asks to write a plan or pre-mortem document.
 - **plugin-creator**: Creates experimental opt-in plugin packs with manifests, conventions, and optional module scaffolding for Claude and Codex runtimes
 - **pr**: Create pull requests with pre-flight validation
 - **prd-to-issues**: Break a PRD into independently-grabbable GitHub issues using vertical slices with HITL/AFK tagging and dependency ordering. Use when user wants to convert a PRD to issues, create tickets, or break down a PRD into work items.
 - **prd-to-plan**: Convert a PRD into a phased implementation plan using tracer-bullet vertical slices. Use when user wants to break down a PRD, create an implementation plan, plan phases from a PRD, or mentions tracer bullets. Codex-adapted: uses native subagents and plan tracking.
-- **predict**: Predict regressions and impact before changes land
+- **predict**: Analyzes code diffs and file changes to identify potential regressions, maps dependency impact across the codebase, and generates a risk-scored impact report. Use when reviewing pull requests, assessing code change risk, checking for breaking changes, or analyzing the blast radius of a diff.
 - **prompt-caching-patterns**: Loaded when user builds with Anthropic API and needs to cut cost or latency via prompt caching. Covers TTL, cache breakpoints, stacking, invalidation, and measuring hit rate.
 - **qa-session**: Interactive QA session where user reports bugs conversationally and agent files GitHub issues with domain language. Explores codebase in background for context. Use when user wants to report bugs, do QA, file issues conversationally, or mentions QA session. Codex-adapted: uses native subagents and plan tracking.
 - **rag-patterns**: RAG architecture: embeddings, chunking strategies, hybrid search (BM25 + vector), reranking, CRAG/self-correcting, multi-hop reasoning, evaluation metrics. Triggers: RAG, embedding, vector search, pgvector, Qdrant, Pinecone, Weaviate, chunking, reranker, retrieval, hybrid search, semantic search, knowledge base, cosine similarity. Load when building or tuning RAG systems.
@@ -536,7 +536,7 @@ Skills are invocable commands or auto-loaded knowledge sources:
 - **swarm**: Execute tasks via Map-Reduce, Consensus, or Relay swarms Codex-adapted: uses native subagents and plan tracking.
 - **swift-patterns**: Swift and iOS development patterns: SwiftUI, Combine, async/await, property wrappers, actors, Swift Package Manager, Core Data, UIKit interop, @MainActor. Triggers: Swift, SwiftUI, Combine, iOS, Xcode, actor, property wrapper, Core Data, SPM, UIKit, @MainActor, @State, @Binding. Load when writing or reviewing Swift code.
 - **tdd**: Test-driven development with red-green-refactor loop and vertical slices. Use when user wants TDD, test-first development, red-green-refactor, or building features with tests driving the implementation. Codex-adapted: uses native subagents and plan tracking.
-- **teams**: Launch pre-configured Agent Teams for common workflows Codex-adapted: uses native subagents and plan tracking.
+- **teams**: Launches pre-configured multi-agent teams for code review, debugging, feature development, security audits, and database migrations. Use when the user asks to start a multi-agent workflow, coordinate agent teams, run a team review, or needs parallel agent collaboration on a complex task. Codex-adapted: uses native subagents and plan tracking.
 - **test**: Run tests with coverage analysis and reporting
 - **testing-patterns**: Testing strategy and craft: pyramid vs trophy, unit/integration/e2e split, fixtures, mocks vs fakes vs stubs, AAA pattern, flaky test diagnosis, coverage goals, property-based testing. Triggers: test, testing strategy, fixture, mock, stub, AAA, unit test, integration test, e2e, Playwright, Cypress, flaky, coverage, TDD, test pyramid. Load when writing, reviewing, or designing test suites.
 - **triage-issue**: Triage a bug by deeply exploring the codebase for root cause, then create a GitHub issue with a TDD-based fix plan. Mostly hands-off — minimal user interaction. Use when user reports a bug, wants to investigate an issue, mentions triage, or wants a fix plan. Codex-adapted: uses native subagents and plan tracking.
@@ -548,12 +548,12 @@ Skills are invocable commands or auto-loaded knowledge sources:
 
 ## Quality Standards
 
-Derived from the immutable safety constitution (5 articles):
+Derived from the immutable safety constitution (6 articles):
 
 **Article I — Safety First**
 - No data loss: never delete files without backup verification or using reversible operations
 - No blind execution: never run LLM-generated code without static analysis or review
-- No infinite loops: all autonomous loops must have a maximum iteration count (max 3)
+- No infinite loops: all autonomous loops must have a maximum iteration count (max 5)
 
 **Article II — Hierarchy of Truth**
 - The Knowledge Base (`kb/`) is the source of truth; if code contradicts KB, check KB freshness
@@ -572,6 +572,12 @@ Derived from the immutable safety constitution (5 articles):
 - Commands like `rm -rf`, `DROP TABLE`, `FORMAT` require explicit user confirmation
 - Operate within assigned model tiers; model tier changes require user approval
 
+**Article VI — Repair Discipline**
+- No dead code: unused code (files, classes, functions, imports, variables) must be removed in the same change that makes it unused; 'pre-existing' or 'out of scope' is not a valid reason
+- Fix every found bug: bugs, gaps, missing tests, or stale docs discovered during a task must be fixed in the same change when directly adjacent to the work; deferral requires explicit user decision
+- Tests and docs follow behavior: behavior changes must carry matching integration and unit tests plus affected documentation in the same change
+- Verify before claiming done: re-read the diff before marking a task complete; no orphaned references, no missing coverage, no stale docs
+
 ## Workflow Guidelines
 
 - **Plan First**: Tasks longer than 1 hour require a plan, success criteria, and pre-mortem

package/CHANGELOG.md

@@ -7,6 +7,38 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v2.11.0 — JSON Wire Format Rules (2026-04-21)
+
+### Added
+- **`app/rules/common/coding-style.md` v1.2.0 — JSON Wire Format Conventions section** — `camelCase` for field names (JSON:API, Google JSON Style, Symfony Serializer + `json_serializable` defaults), `UPPER_SNAKE_CASE` for enum/status/permission values (Protocol Buffers style guide, Google AIP-126 / api-linter, Zalando Rule #240, Java/Kotlin/C++/Python consensus). Explicit call-out that `camelCase` for enum VALUES is an anti-pattern with no major public API precedent.
+- **`app/rules/php/frameworks.md` v1.1.0 — Symfony Serializer section** — documents the `property-names-used-as-is` default, the global-override side effect of `api_platform.name_converter` ([api-platform/core #6101](https://github.com/api-platform/core/issues/6101)), pragmatic `#[SerializedName]` usage (only when justified), and the Symfony 7.3.5+ `ObjectNormalizer` `isXxx` behavior change ([symfony/symfony #62353](https://github.com/symfony/symfony/issues/62353)) that makes pre-7.3.5 `SerializedName` aliases redundant. API Platform section extended with `operation_name` metadata note.
+- **`app/rules/dart/frameworks.md` v1.1.0 — JSON Serialization section** — `json_serializable` `FieldRename.none` default + Effective Dart `lowerCamelCase` = `camelCase` JSON keys without configuration; community recommendation to prefer class-level `fieldRename` over per-field `@JsonKey(name:)`; enum value strategy (`UPPER_SNAKE_CASE` on wire, Dart case names stay `lowerCamelCase`).
+- **`tests/test_rules_content.bats` (3 bats cases)** — smoke tests guarding the three new rule sections (`JSON Wire Format Conventions`, `Symfony Serializer`, `JSON Serialization`). Heading-only checks, intentionally non-brittle. Test count: 666 → 669.
+
+### Notes
+- Changes are additive — no existing rule text removed or reworded. Projects that ran `ai-toolkit install --local` before v2.11.0 will pick up the new sections on next re-run (install is idempotent — existing TOOLKIT markers get replaced, not duplicated).
+- Rules codify documented facts + widely-cited community consensus, not project-specific enforcement. Project-level SOPs (grep gates, migration workflows, whitelists) remain in each project's `kb/procedures/`.
+
+---
+
+## v2.10.1 — Art. VI Enforcement Drift Repair (2026-04-21)
+
+### Fixed
+- **`IMMUTABLE_ARTICLES` extended to include Article 6** (`scripts/config_merger.py`, `scripts/config_validator.py`) — v2.10.0 declared Art. VI immutable in `app/constitution.md` but left the enforcement constant at `{1..5}`, so a downstream `extends:` config with `amendments: [{article: 6, ...}]` would silently override Repair Discipline. Constant now `{1..6}`; error message points at article 7+ as the first allowed project-added article.
+- **`scripts/emission.py::generate_quality_standards()` emits Article VI** — generator hard-coded I–V only, so `AGENTS.md`, `GEMINI.md`, editor rule files, and `llms-full.txt` did not carry Art. VI text after the v2.10.0 release. Added four-clause VI block (no dead code, fix every found bug, tests and docs follow behavior, verify before done). All downstream catalogs regenerated.
+- **"5 articles" / "Articles I-V" literals updated to 6 / I-VI** across `README.md`, `app/ARCHITECTURE.md`, `kb/reference/architecture-overview.md`, `kb/reference/enterprise-config-guide.md`, `scripts/config_cli.py` diff label, and `scripts/schemas/ai-toolkit-config.schema.json` description. Added Article VI row to the Constitution table in `architecture-overview.md`.
+- **Article I.3 "Max 3" aligned to Section 4 "Max 5"** in `app/constitution.md` to resolve a pre-existing internal contradiction. Same iteration cap now quoted in `scripts/emission.py` general/quality guidelines.
+- **SKILL.md improvements from PR #8 by @rohan-tessl** — `biz-scan`, `evolve`, `plan`, `predict`, and `teams` gained richer descriptions with explicit "Use when..." clauses and executable protocol steps; team preset details moved to `teams/reference/presets.md` (progressive disclosure). Repo style applied (no em dashes); `plan/SKILL.md` KB Integration section preserved.
+
+### Added
+- **`scripts/validate.py` article-count drift lint** (`validate_constitution_drift`) — parses `app/constitution.md` for `## Article <roman>:` headings, derives the expected count and max roman numeral, and fails strict validation when `README.md`, `app/ARCHITECTURE.md`, or `kb/reference/*` references a stale `N articles` or `Articles I-<roman>` literal. This is how v2.10.0 drift slipped past CI; it will not next time.
+
+### Notes
+- No skill/agent/hook counts changed. Totals remain: 44 agents, 99 skills, 666 tests.
+- Art. VI text itself (in `app/constitution.md`) unchanged from v2.10.0 — only surfaces and enforcement are reconciled with it.
+
+---
+
 ## v2.10.0 — Constitution Article VI: Repair Discipline (2026-04-21)
 
 ### Added

package/README.md

@@ -6,15 +6,20 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-99-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-666%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-669%20passing-success)](tests/)
 
 ---
 
-## What's New in v2.10.0
+## What's New in v2.11.0
 
-- **Constitution Article VI — Repair Discipline** — four new immutable rules close the "świadome pominięcie / out of scope / separate PR" loophole: no dead code (VI.1), fix every found bug (VI.2), tests and docs follow behavior (VI.3), verify before claiming done (VI.4). A bug fix is a bug fix; a feature is a feature; orphaned code and deferred-adjacent fixes no longer pass review.
-- **`system-governor` gains Art. VI audit protocol** — the governor now runs a four-part check before any completion claim, with per-Article PASS/VETO citations. Scope is intentionally scoped to commit message + PR body + non-`.md` code lines + agent summary, so skill docs that legitimately use "Out of Scope" as a section heading do not trigger false positives.
-- **Rule, skill, and agent reinforcement** — `coding-style` rule (v1.1.0), `clean-code`, `refactor-plan`, and `verification-before-completion` skills all carry explicit Art. VI anchors and checklist rows. Totals unchanged: 44 agents, 99 skills, 666 tests.
+- **JSON wire format rules added to `common/coding-style.md`** — `camelCase` for field names (aligned with JSON:API, Google JSON Style, Symfony Serializer + `json_serializable` defaults), `UPPER_SNAKE_CASE` for enum values (Protocol Buffers, Google AIP-126 / api-linter, Zalando Rule #240, Java/Kotlin/Python consensus). Anti-pattern call-out against `camelCase` for enum values (no major public API uses it).
+- **`php/frameworks.md` — Symfony Serializer section** — documents the property-names-as-is default, the global-override side effect of `api_platform.name_converter` ([api-platform/core #6101](https://github.com/api-platform/core/issues/6101)), pragmatic `#[SerializedName]` usage, and Symfony 7.3.5+ `ObjectNormalizer` `isXxx` behavior change ([#62353](https://github.com/symfony/symfony/issues/62353)) that retires pre-7.3.5 boolean-getter aliases.
+- **`dart/frameworks.md` — JSON Serialization section** — `json_serializable` `FieldRename.none` default + Effective Dart `lowerCamelCase` = `camelCase` output with zero config; community recommendation to prefer class-level `fieldRename` over per-field `@JsonKey(name:)`; enum value wire strategy (`UPPER_SNAKE_CASE`) while keeping Dart enum case names `lowerCamelCase`.
+
+### Previous: v2.10.1 — Art. VI Enforcement Drift Repair
+
+- Art. VI enforcement drift repaired (`IMMUTABLE_ARTICLES` extended to include Article 6; generator emits Article VI text; article-count drift lint added).
+- Constitution self-consistency fixes (Article I.3 aligned with Section 4) and SKILL.md improvements from #8 (merged from @rohan-tessl). Totals unchanged: 44 agents, 99 skills, 666 tests.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -121,7 +126,7 @@ See [CLI Reference](kb/reference/cli-reference.md) for all commands and options.
 | `agents/` | 44 | Specialized agents across 10 categories |
 | `hooks/` | 21 global + 5 skill-scoped | Quality gates, path safety, prompt governance, session lifecycle |
 | `plugins/` | 11 packs | Opt-in domain bundles (security, research, frontend, enterprise, 6 language packs) |
-| `constitution.md` | 5 articles | Machine-enforced safety rules |
+| `constitution.md` | 6 articles | Machine-enforced safety rules |
 | `rules/` | auto-injected | Language-specific and custom rules injected into your configs |
 | `kb/` | reference docs | Architecture, procedures, and best practices |
 
@@ -138,11 +143,11 @@ ai-toolkit/
 │   ├── hooks/           # Hook scripts (21 entries, 12 lifecycle events)
 │   ├── plugins/         # 11 experimental plugin packs (opt-in)
 │   ├── output-styles/   # System prompt output style overrides
-│   ├── constitution.md  # 5 immutable safety articles
+│   ├── constitution.md  # 6 immutable safety articles
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats test suite (666 tests)
+├── tests/               # Bats test suite (669 tests)
 └── CHANGELOG.md
 ```
 

package/app/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ai-toolkit",
   "description": "Professional-grade Claude Code toolkit with persona presets, skill security auditor, expanded lifecycle hooks, experimental opt-in plugin packs, benchmark harvesting, and multi-tool support.",
-  "version": "2.10.0",
+  "version": "2.11.0",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/ARCHITECTURE.md

@@ -266,7 +266,7 @@ Phase 2: IMPLEMENTATION
 ├── hooks.json           # Quality gate hooks (multi-language)
 ├── skills/              # All skills: task, hybrid, knowledge
 ├── output-styles/       # System prompt output style overrides (e.g. golden-rules)
-├── constitution.md      # Immutable safety rules (5 articles)
+├── constitution.md      # Immutable safety rules (6 articles)
 └── settings.local.json  # Local settings + Agent Teams config
 ```
 
@@ -332,7 +332,7 @@ The `inject_section_cli.py` script provides a stable marker-based injection API.
 `scripts/compile_slm.py` compiles the full toolkit (20K+ tokens) into a minimal system prompt for Small Language Models (2K-16K tokens). Pipeline: Parse → Score → Compress → Pack → Emit. Supports 4 compression levels (ultra-light, light, standard, extended), 4 output formats (raw, ollama, json-string, aider), persona-aware scoring, and language-aware rule filtering. Profile `offline-slm` in `manifest.json`. Constitution is always included (non-negotiable).
 
 ### Config Inheritance (`extends`)
-`scripts/config_resolver.py`, `config_merger.py`, `config_validator.py`, `config_cli.py`, `config_scaffold.py`, `config_lock.py`. Enterprise configuration inheritance via `.softspark-toolkit.json` `extends` field. Resolves base configs from npm packages, Git URLs, or local paths. Layered deep merge with constitution immutability (Articles I-V absolute), enforce constraints (`requiredAgents`, `forbidOverride`, `minHookProfile`), override validation (`override: true` + justification), and lock file (`.softspark-toolkit.lock.json`). CLI: `config validate`, `config diff`, `config init`, `config create-base`, `config check`. Integrated into `install --local` and `update --local` flows.
+`scripts/config_resolver.py`, `config_merger.py`, `config_validator.py`, `config_cli.py`, `config_scaffold.py`, `config_lock.py`. Enterprise configuration inheritance via `.softspark-toolkit.json` `extends` field. Resolves base configs from npm packages, Git URLs, or local paths. Layered deep merge with constitution immutability (Articles I-VI absolute), enforce constraints (`requiredAgents`, `forbidOverride`, `minHookProfile`), override validation (`override: true` + justification), and lock file (`.softspark-toolkit.lock.json`). CLI: `config validate`, `config diff`, `config init`, `config create-base`, `config check`. Integrated into `install --local` and `update --local` flows.
 
 ### Project Registry
 `scripts/install_steps/project_registry.py`, `scripts/update_projects.py`, `scripts/projects_cli.py`. Tracks all `--local` installed projects in `~/.softspark/ai-toolkit/projects.json`. `ai-toolkit update` propagates to all registered projects in parallel via `ThreadPoolExecutor`. CLI: `ai-toolkit projects`, `--prune`, `remove <path>`.

package/app/constitution.md

@@ -11,7 +11,7 @@ status: IMMUTABLE
 ## Article I: Safety First
 1. **No Data Loss**: Never delete a file without verifying a backup exists or using `git rm` (which is reversible).
 2. **No Blind Execution**: Never execute code generated by an LLM without static analysis or review.
-3. **No Infinite Loops**: All autonomous loops (Learning, Evolving) must have a maximum iteration count (Max 3).
+3. **No Infinite Loops**: All autonomous loops (Learning, Evolving) must have a maximum iteration count (Max 5, consistent with Section 4).
 
 ### Section 4: Autonomous Loop Limits
 - Autonomous loops (including `/repeat` skill) default to maximum 5 iterations

package/app/rules/common/coding-style.md

@@ -1,7 +1,7 @@
 ---
 language: common
 category: coding-style
-version: "1.1.0"
+version: "1.2.0"
 ---
 
 # Universal Coding Style
@@ -69,6 +69,13 @@ version: "1.1.0"
   `1. [Step] → verify: [check]`
 - Strong success criteria enable independent looping. Weak criteria ("make it work") require clarification — ask first.
 
+## JSON Wire Format Conventions
+- Field names (keys): `camelCase`. Aligns with JSON:API spec, Google JSON Style Guide, and framework defaults (Symfony Serializer, Spring Jackson, `json_serializable` for Dart). No public major API uses `snake_case` keys in modern designs except ecosystem-bound cases (Rails/Django APIs defaulting to ecosystem convention).
+- Enum / status / permission / domain values: `UPPER_SNAKE_CASE`. Community consensus: [Protocol Buffers style guide](https://protobuf.dev/programming-guides/style/) (mandatory), [Google AIP-126 / api-linter](https://linter.aip.dev/126/upper-snake-values) (enforced), [Zalando Rule #240](https://opensource.zalando.com/restful-api-guidelines/), Java/Kotlin/C++/Python enum convention. `lowercase snake_case` (Stripe-style) is a legitimate outlier but not consensus.
+- Avoid `camelCase` for enum values — no major public API uses it, loses visual distinction between keys and values.
+- Pick one convention per project and enforce it with a CI grep gate. Mixing conventions inside a single API surface is the worst outcome.
+- External contracts (Stripe, GitHub, webhooks you receive) follow their own convention — map to your project convention at the adapter boundary, do not leak their keys past it.
+
 ## Anti-Patterns to Avoid
 - God classes/modules with 500+ lines and multiple responsibilities.
 - Deep nesting (>3 levels): use early returns and extract functions.

package/app/rules/dart/frameworks.md

@@ -1,7 +1,7 @@
 ---
 language: dart
 category: frameworks
-version: "1.0.0"
+version: "1.1.0"
 ---
 
 # Dart Frameworks
@@ -27,6 +27,14 @@ version: "1.0.0"
 - Set timeouts on every request: `connectTimeout`, `receiveTimeout`.
 - Use `CancelToken` for cancelling in-flight requests on navigation.
 
+## JSON Serialization
+- Use `json_serializable` (+ `build_runner`) for generated `fromJson`/`toJson`. Default `fieldRename: FieldRename.none` uses Dart property names as-is — combined with Effective Dart `lowerCamelCase`, this produces `camelCase` JSON keys with zero configuration.
+- Flutter docs recommend: *"best if both server and client follow the same naming strategy"* ([Flutter — JSON and serialization](https://docs.flutter.dev/data-and-backend/serialization/json)). When they do, no mapping is needed.
+- When server uses a different convention, prefer `@JsonSerializable(fieldRename: FieldRename.snake)` at the class level (or globally in `build.yaml`) over sprinkling `@JsonKey(name:)` on every field. Community recommendation from the `json_serializable` docs and pub.dev guides.
+- Use individual `@JsonKey(name: '...')` only for exceptional cases: external API with mixed conventions, reserved Dart keyword collision (`class`, `is`, `new`), or legacy field rename during deprecation window. Document the reason in a comment.
+- For enum / status / permission values on the wire: `UPPER_SNAKE_CASE` is the cross-language community consensus (see `common/coding-style.md` — JSON Wire Format Conventions). Dart enum case names themselves stay `lowerCamelCase` per Effective Dart; map them to uppercase strings in `fromJson`/`toJson` (`value.toUpperCase()` + `switch`).
+- Write unit tests asserting both directions (`fromJson` + `toJson`) with explicit expected keys. Catches contract drift at CI time.
+
 ## Local Storage
 - Use `shared_preferences` for simple key-value persistence.
 - Use `drift` (formerly Moor) for type-safe SQLite with reactive queries.

package/app/rules/php/frameworks.md

@@ -1,7 +1,7 @@
 ---
 language: php
 category: frameworks
-version: "1.0.0"
+version: "1.1.0"
 ---
 
 # PHP Frameworks
@@ -36,12 +36,21 @@ version: "1.0.0"
 - Use migrations: `bin/console doctrine:migrations:diff` and `migrate`.
 - Use lifecycle callbacks (`@PrePersist`, `@PostUpdate`) for entity events.
 
+## Symfony Serializer
+- Default behavior uses property names as-is. Combined with PSR-12 `camelCase` property names, JSON output is `camelCase` with zero configuration.
+- Avoid adding `api_platform.name_converter: CamelCaseToSnakeCaseNameConverter` globally. Known side-effect ([api-platform/core #6101](https://github.com/api-platform/core/issues/6101)): overrides the project-wide `MetadataAwareNameConverter`, affecting Messenger serializers, custom normalizers, and CLI JSON output — not just the HTTP API.
+- Use `#[SerializedName]` only when justified: legacy field alias during rename, external contract mapping, ObjectNormalizer cross-version stabilization. Community practice ([Symfony docs](https://symfony.com/doc/current/serializer.html), Sylius, SymfonyCasts): prefer clean property/getter naming over aliases. When using, document the reason next to the attribute.
+- Symfony 7.3.5+ `ObjectNormalizer` produces `isActive` natively for a `isActive(): bool` getter ([symfony/symfony #62353](https://github.com/symfony/symfony/issues/62353)). Older `#[SerializedName('isActive')]` aliases added for pre-7.3.5 `ObjectNormalizer` (which produced `active`) are redundant after upgrade — remove them.
+- Avoid duplicate getters like `isActive()` + `getIsActive()` on the same property — `ObjectNormalizer` treats them as two fields and serializes ambiguously. Keep one (`isXxx()` for booleans, `getXxx()` otherwise).
+
 ## API Platform
 - Use API Platform for rapid REST/GraphQL API generation from entities.
 - Use `#[ApiResource]` attribute for automatic CRUD endpoint generation.
 - Use custom state providers and processors for business logic.
 - Use serialization groups for controlling response shape.
 - Use filters for query parameter support: pagination, search, ordering.
+- Property names on `ApiResource` DTOs drive JSON keys directly (see Symfony Serializer above). Write them in `camelCase` — that is both the Symfony default and the dominant JSON API convention.
+- Use `operation_name` in `extraProperties` for dispatch metadata (e.g., `extraProperties: ['operation_name' => 'club_activate']`). The key `operation_name` and its `snake_case` values are framework metadata, not JSON wire keys — keeping them `snake_case` is expected.
 
 ## Livewire (Laravel)
 - Use Livewire components for reactive UI without JavaScript.

package/app/skills/biz-scan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: biz-scan
-description: "Scan codebase for business opportunities and KPIs"
+description: "Scans codebase for business opportunities by analyzing database schemas, API endpoints, tracking events, and feature flags to surface underutilized capabilities, missing KPIs, and monetization gaps. Use when the user asks about revenue opportunities, business metrics, KPI coverage, analytics gaps, or monetization analysis of a codebase."
 effort: medium
 disable-model-invocation: true
 argument-hint: "[area]"
@@ -13,18 +13,74 @@ allowed-tools: Read, Grep, Glob
 
 $ARGUMENTS
 
-Triggers the Business Intelligence agent to find opportunities.
+Triggers the Business Intelligence agent to analyze the codebase for business opportunities and KPI gaps.
 
 ## Usage
 
 ```bash
 /biz-scan [scope]
-# Example: /biz-scan schema
-# Example: /biz-scan all
+# /biz-scan schema     : focus on database models and entity relationships
+# /biz-scan api        : focus on API endpoints and data exposure
+# /biz-scan all        : full codebase scan
 ```
 
 ## Protocol
-1. **Model Scan**: Read DB schema / Entities.
-2. **Logic Scan**: Read Controllers / UseCases.
-3. **Synthesis**: Match Data vs Business Goals.
-4. **Report**: Generate Opportunity Report.
+
+### 1. Model Scan: Analyze Data Layer
+
+Scan for business-relevant data structures:
+
+```bash
+# Find database models, schemas, entities
+grep -rl "model\|schema\|entity\|migration" --include="*.py" --include="*.ts" --include="*.rb" .
+# Find ORM definitions
+grep -rl "prisma\|sequelize\|typeorm\|sqlalchemy\|activerecord" .
+```
+
+Catalog: entity names, relationships, fields that map to business concepts (revenue, subscription, usage, billing).
+
+### 2. Logic Scan: Analyze Business Logic
+
+Scan controllers, services, and use cases:
+
+```bash
+# Find API endpoints and handlers
+grep -rn "router\.\|app\.\(get\|post\|put\|delete\)\|@Controller\|@app\.route" --include="*.ts" --include="*.py" --include="*.js" .
+# Find tracking/analytics events
+grep -rn "track\|analytics\|event\|metric\|log_event" --include="*.ts" --include="*.py" --include="*.js" .
+```
+
+Catalog: exposed endpoints, tracked events, feature flags, A/B tests.
+
+### 3. Synthesis: Match Data vs. Business Goals
+
+Cross-reference findings to identify:
+
+| Category | What to Look For |
+|----------|-----------------|
+| **Missing KPIs** | Entities with no associated tracking events |
+| **Underutilized features** | Endpoints with no analytics or feature-flag coverage |
+| **Monetization gaps** | Subscription/billing entities without conversion tracking |
+| **Data exposure** | Rich internal data not surfaced via API |
+
+### 4. Report: Generate Opportunity Report
+
+Output a structured markdown report:
+
+```markdown
+## Business Opportunity Report: [scope]
+
+### KPI Coverage
+| Entity/Feature | Tracked Events | Gap |
+|---------------|---------------|-----|
+| [name] | [events or "none"] | [what's missing] |
+
+### Opportunities (ranked by estimated impact)
+1. **[Opportunity]**: [description, affected entities, suggested action]
+
+### Quick Wins
+- [ ] Add tracking to [feature], estimated lift: [low/med/high]
+
+### Data Exposure Gaps
+- [Entity] has [N fields] not exposed via any API endpoint
+```

package/app/skills/evolve/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: evolve
-description: "Evolve agent definitions via meta-architect"
+description: "Analyzes failure patterns and inefficiencies in agent/skill definitions, then drafts and applies targeted improvements to system prompts, tool permissions, and behavioral rules. Use when the user asks to improve agent behavior, refine skill definitions, update system prompts, or optimize agent configurations based on observed failures."
 effort: medium
 disable-model-invocation: true
 context: fork
@@ -10,18 +10,58 @@ allowed-tools: Read, Edit, Grep, Glob
 
 # Evolve Command
 
-Triggers the Meta-Architect to improve the system.
+$ARGUMENTS
+
+Triggers the Meta-Architect to improve agent and skill definitions based on observed patterns.
 
 ## Usage
 
 ```bash
 /evolve [source]
-# Example: /evolve learnings (Analyze kb/learnings)
-# Example: /evolve last-failure (Analyze last error log)
+# /evolve learnings        : analyze kb/learnings/ for recurring failure patterns
+# /evolve last-failure     : analyze the most recent error log
+# /evolve agents           : audit all agent definitions for gaps
 ```
 
 ## Protocol
-1. **Analyze**: Read input source for patterns of failure/inefficiency.
-2. **Design**: Draft changes to `.claude/agents/` or `.claude/skills/`.
-3. **Implement**: Apply changes.
-4. **Report**: Document what evolved.
+
+### 1. Analyze
+
+Read the input source and extract actionable patterns:
+
+- **learnings**: grep `kb/learnings/` for entries tagged `failure`, `retry`, `timeout`, or `inefficiency`
+- **last-failure**: read the most recent file in `kb/learnings/` and identify root cause
+- **agents**: scan all `.md` files in `app/agents/` for missing tools, vague prompts, or mismatched model tiers
+
+### 2. Design
+
+Draft changes targeting the identified patterns:
+
+| Target | File Location | Change Type |
+|--------|--------------|-------------|
+| Agent definitions | `app/agents/*.md` | Frontmatter (tools, model), system prompt text |
+| Skill definitions | `app/skills/*/SKILL.md` | Description, workflow steps, allowed-tools |
+| Rules | `app/rules/` | New or updated rule files |
+
+Show the proposed diff to the user before applying.
+
+### 3. Implement
+
+Apply approved changes. After each edit:
+
+- Run `python3 scripts/validate.py` to confirm structural integrity
+- Verify YAML frontmatter parses without errors
+- Confirm no forbidden patterns (eval, exec, shell=True)
+
+### 4. Report
+
+Create a summary documenting what evolved:
+
+```markdown
+## Evolution Report
+- **Source**: [learnings | last-failure | agents]
+- **Pattern found**: [description of failure/inefficiency]
+- **Changes applied**:
+  - `app/agents/[name].md`: [what changed and why]
+- **Validation**: passed / failed
+```

package/app/skills/plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plan
-description: "Plan implementation with tasks and success criteria"
+description: "Breaks down feature requests and project goals into phased implementation plans with task lists, agent assignments, dependency graphs, and success criteria. Use when the user asks to plan a feature, create an implementation roadmap, break down a coding task, or outline project phases."
 user-invocable: true
 effort: high
 argument-hint: "[goal]"
@@ -11,71 +11,14 @@ allowed-tools: Read, Grep, Glob
 
 $ARGUMENTS
 
-Create a structured plan for a new project or feature.
+## Workflow
 
-## Usage
-
-```
-/plan [description]
-```
-
-## What This Command Does
-
-1. **Analyzes** the request
-2. **Identifies** project type and tech stack
-3. **Breaks down** into tasks
-4. **Creates** plan file with agent assignments
-
-## Plan File Output
-
-Creates a `{project-slug}.md` file in project root:
-
-```markdown
-# {Project Name} - Implementation Plan
-
-## Overview
-- **Type**: [Web App / Mobile App / API / etc.]
-- **Stack**: [Tech choices]
-- **Complexity**: [Low / Medium / High]
-
-## Requirements
-1. [Requirement 1]
-2. [Requirement 2]
-
-## Task Breakdown
-
-### Phase 1: Foundation
-- [ ] Task 1 (Agent: backend-specialist)
-- [ ] Task 2 (Agent: database-architect)
-
-### Phase 2: Core Features
-- [ ] Task 3 (Agent: frontend-specialist)
-- [ ] Task 4 (Agent: backend-specialist)
-
-### Phase 3: Polish
-- [ ] Task 5 (Agent: test-engineer)
-- [ ] Task 6 (Agent: devops-implementer)
-
-## Agent Assignment
-
-| Task | Agent | Dependencies |
-|------|-------|--------------|
-| Database | database-architect | None |
-| API | backend-specialist | Database |
-| UI | frontend-specialist | API |
-| Tests | test-engineer | All above |
-
-## File Structure
-```
-project/
-├── src/
-└── ...
-```
-
-## Success Criteria
-- [ ] Criterion 1
-- [ ] Criterion 2
-```
+1. **Analyze scope**: read the goal, scan relevant source files to understand current state
+2. **Detect project type**: match keywords to determine stack and primary agents (see table below)
+3. **Break into phases**: group tasks by dependency order (foundation, core, polish)
+4. **Assign agents**: map each task to the best-fit agent with explicit dependencies
+5. **Write plan file**: create `{project-slug}.md` in project root using [templates/plan-template.md](templates/plan-template.md)
+6. **Validate**: confirm every requirement maps to at least one task, no circular dependencies exist, and success criteria are measurable
 
 ## Project Type Detection
 
@@ -83,44 +26,29 @@ project/
 |----------|------|----------------|
 | landing, website | Static Site | frontend-specialist |
 | dashboard, admin | Web App | frontend + backend |
-| api, rest | API Only | backend-specialist |
+| api, rest, graphql | API Only | backend-specialist |
 | mobile, ios, android | Mobile | mobile-developer |
-| game, unity | Game | game-developer |
+| cli, terminal | CLI Tool | backend-specialist |
 
-## PLAN MODE RULES
+## Planning Constraints
 
-During planning:
-- Create plan documents
-- Define tasks and structure
-- NO code writing
-- NO file creation (except plan)
-
-## Common Rationalizations
-
-| Excuse | Why It's Wrong |
-|--------|----------------|
-| "We already know what to build" | Assumed requirements lead to rework — validate assumptions explicitly |
-| "Planning is wasted time, just start coding" | Unplanned work has 3-5x more rework — 30 min planning saves days |
-| "The requirements will change anyway" | Plans adapt — without one, you can't assess impact of changes |
-| "It's a small feature, no plan needed" | Small features in complex systems have hidden dependencies — map them |
-| "We'll figure it out as we go" | Discovery without structure leads to scope creep and missed edge cases |
-
-## Next Steps
-
-After plan approval:
-1. Use `/orchestrate` to execute with agents
-2. Or manually invoke specific agents
+- Create plan documents only, NO code writing, NO file creation (except the plan)
+- Each task must name affected file(s) and a single owning agent
+- Phases must have explicit dependency edges (`Phase 1 -> Phase 2`)
+- Success criteria must be verifiable (command to run, expected output, or observable behavior)
 
 ## KB Integration
 
 Before planning:
+
 ```python
 smart_query("project template: {type}")
 hybrid_search_kb("architecture {pattern}")
 ```
 
 ## Related Skills
-- Plan approved? → `/orchestrate` or `/workflow` to execute with agents
-- Need requirements first? → `/write-a-prd` for structured product requirements
-- Want to stress-test the plan? → `/grill-me` for Socratic questioning
-- Ready to break into issues? → `/prd-to-plan` → `/triage-issue`
+
+- Plan approved? -> `/orchestrate` or `/workflow` to execute with agents
+- Need requirements first? -> `/write-a-prd` for structured product requirements
+- Want to stress-test the plan? -> `/grill-me` for Socratic questioning
+- Ready to break into issues? -> `/prd-to-plan` -> `/triage-issue`

package/app/skills/predict/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: predict
-description: "Predict regressions and impact before changes land"
+description: "Analyzes code diffs and file changes to identify potential regressions, maps dependency impact across the codebase, and generates a risk-scored impact report. Use when reviewing pull requests, assessing code change risk, checking for breaking changes, or analyzing the blast radius of a diff."
 effort: medium
 disable-model-invocation: true
 argument-hint: "[change description]"
@@ -13,18 +13,66 @@ allowed-tools: Read, Grep, Glob
 
 $ARGUMENTS
 
-Triggers the Predictive Analyst to assess impact.
+Triggers the Predictive Analyst to assess the impact and regression risk of proposed changes.
 
 ## Usage
 
 ```bash
 /predict [path_or_diff]
-# Example: /predict src/auth
-# Example: /predict --diff (analyzes uncommitted changes)
+# /predict src/auth              : analyze all files under src/auth
+# /predict --diff                : analyze uncommitted changes (git diff)
+# /predict src/api/routes.ts     : analyze a single file
 ```
 
 ## Protocol
-1. **Scope**: Identify target files.
-2. **Trace**: Build dependency graph.
-3. **Assess**: Calculate risk score.
-4. **Report**: Generate Impact Prediction.
+
+### 1. Scope: Identify Target Files
+
+- If path provided: collect all files under that path
+- If `--diff`: run `git diff --name-only` to get changed files
+- List each file with its last-modified date and line count
+
+### 2. Trace: Build Dependency Graph
+
+For each target file, find dependents:
+
+```bash
+# Find files that import/require the target
+grep -rl "import.*from.*[target]" --include="*.ts" --include="*.py" --include="*.js" .
+grep -rl "require.*[target]" --include="*.js" --include="*.ts" .
+```
+
+Build a graph: `changed file, direct dependents, transitive dependents (1 level)`
+
+### 3. Assess: Calculate Risk Score
+
+Score each changed file on a 1 to 5 scale:
+
+| Factor | Weight | Scoring |
+|--------|--------|---------|
+| Dependent count | 30% | 0 deps = 1, 1 to 3 = 2, 4 to 10 = 3, 11 to 20 = 4, 21+ = 5 |
+| Test coverage | 30% | Has dedicated test = 1, partial = 3, none = 5 |
+| Change surface | 20% | < 10 lines = 1, 10 to 50 = 2, 50 to 200 = 3, 200+ = 5 |
+| Shared/core file | 20% | Leaf = 1, mid-layer = 3, core/shared = 5 |
+
+**Overall risk** = weighted average rounded to nearest integer.
+
+### 4. Report: Generate Impact Prediction
+
+Output a markdown report:
+
+```markdown
+## Impact Prediction: [scope]
+
+| File | Risk | Dependents | Test Coverage | Notes |
+|------|------|------------|---------------|-------|
+| src/auth/login.ts | 4/5 | 12 files | partial | Core auth flow |
+
+### High-Risk Changes (score >= 4)
+- [file]: [why it's high risk and what to watch]
+
+### Recommended Actions
+- [ ] Add tests for [untested file]
+- [ ] Review [high-dependent file] with extra scrutiny
+- [ ] Run integration tests covering [affected area]
+```

package/app/skills/teams/SKILL.md

@@ -1,21 +1,17 @@
 ---
 name: teams
-description: "Launch pre-configured Agent Teams for common workflows"
+description: "Launches pre-configured multi-agent teams for code review, debugging, feature development, security audits, and database migrations. Use when the user asks to start a multi-agent workflow, coordinate agent teams, run a team review, or needs parallel agent collaboration on a complex task."
 effort: max
 user-invocable: true
 argument-hint: "<preset> [task-description]"
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Agent, TeamCreate, TeamDelete, SendMessage, TaskCreate, TaskList, TaskUpdate, TaskGet
 ---
 
-# /teams - Agent Teams Presets
+# /teams: Agent Teams Presets
 
 $ARGUMENTS
 
-## What This Does
-
-Launches a pre-configured Agent Teams composition for your task.
-
-Requires: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`
+Launches a pre-configured Agent Teams composition for your task. Requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`.
 
 ## Available Presets
 
@@ -29,70 +25,36 @@ Requires: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`
 | `security` | security-architect, security-auditor, backend-specialist | Security audit |
 | `migration` | database-architect, backend-specialist, devops-implementer | Database migration |
 
-## Usage Examples
+See [reference/presets.md](reference/presets.md) for detailed ownership, aggregation strategies, and output formats for each preset.
+
+## Usage
 
 ```
-/teams review           # Launch review team on current changes
-/teams debug            # Launch debug team for current issue
-/teams feature          # Launch feature team for new feature
-/teams security         # Launch security audit team
-/teams migration        # Launch migration team
+/teams review              # Launch review team on current changes
+/teams debug               # Launch debug team for current issue
+/teams feature add auth    # Launch feature team with task context
+/teams security            # Launch security audit team
 ```
 
-## Preset Definitions
-
-### review
-- **Agents**: code-reviewer (lead), security-auditor, performance-optimizer
-- **Ownership**: code-reviewer owns review summary; others own their domain reports
-- **Aggregation**: consensus — flag issues found by 2+ agents as high priority
-- **Output**: `REVIEW.md` with severity-ranked findings
-
-### debug
-- **Agents**: debugger (lead), backend-specialist, incident-responder
-- **Ownership**: debugger owns root-cause analysis; others own hypothesis testing
-- **Aggregation**: relay — debugger synthesizes findings from others
-- **Output**: `DEBUG_REPORT.md` with root cause and fix
-
-### feature
-- **Agents**: orchestrator (lead), backend-specialist, frontend-specialist, test-engineer
-- **Ownership**: orchestrator owns plan; specialists own their files; test-engineer owns tests
-- **Aggregation**: map-reduce — orchestrator integrates all outputs
-- **Output**: implemented feature + tests
-
-### fullstack
-- **Agents**: backend-specialist, frontend-specialist, database-architect, devops-implementer
-- **Ownership**: each agent owns their layer (API, UI, DB, infra)
-- **Aggregation**: relay — backend-specialist synthesizes integration
-- **Output**: full stack implementation
-
-### research
-- **Agents**: technical-researcher (lead), data-analyst, prompt-engineer
-- **Ownership**: technical-researcher owns synthesis; others own domain findings
-- **Aggregation**: consensus — areas of agreement highlighted
-- **Output**: `RESEARCH.md` with findings and recommendations
-
-### security
-- **Agents**: security-architect (lead), security-auditor, backend-specialist
-- **Ownership**: security-architect owns threat model; auditor owns findings; backend owns remediation
-- **Aggregation**: relay — security-architect integrates all
-- **Output**: `SECURITY_AUDIT.md` with CVSS-scored findings
-
-### migration
-- **Agents**: database-architect (lead), backend-specialist, devops-implementer
-- **Ownership**: database-architect owns schema; backend owns code changes; devops owns deployment
-- **Aggregation**: relay — database-architect coordinates sequence
-- **Output**: migration scripts + rollback plan + deployment runbook
-
-## Steps
-
-1. Parse `$ARGUMENTS` to extract `<preset>` and optional `[task-description]`
-2. Validate preset is one of: review, debug, feature, fullstack, research, security, migration
-3. Check `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` is set; warn if not
-4. Display the team composition and ownership rules
-5. Ask user to confirm before launching
-6. Launch the appropriate agents using the Agent tool with the task description
-7. Apply the aggregation strategy to synthesize results
-8. Produce the defined output document
+## Workflow
+
+1. **Parse** `$ARGUMENTS`: extract `<preset>` and optional `[task-description]`
+2. **Validate** preset is one of: review, debug, feature, fullstack, research, security, migration
+3. **Check environment**: verify `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` is set; warn if missing
+4. **Display** team composition and ownership rules from [reference/presets.md](reference/presets.md)
+5. **Confirm** with user before launching
+6. **Launch agents**: spawn each agent with its assigned scope using the Agent tool:
+   ```
+   Agent({ description: "code-reviewer: PR review lead", prompt: "[task + ownership rules]" })
+   Agent({ description: "security-auditor: security findings", prompt: "[task + domain scope]" })
+   ```
+7. **Aggregate results**: apply the preset's aggregation strategy (consensus, relay, or map-reduce)
+8. **Produce output**: write the defined output document (e.g., `REVIEW.md`, `DEBUG_REPORT.md`)
+
+### Error Handling
+
+- If an agent fails or times out: log the failure, continue with remaining agents, note the gap in the output
+- If agents produce conflicting findings: the lead agent resolves conflicts; flag unresolved disagreements for user review
 
 ## Environment
 

package/app/skills/teams/reference/presets.md

@@ -0,0 +1,52 @@
+# Agent Teams Preset Definitions
+
+Detailed configuration for each `/teams` preset. Each preset defines agents, ownership, aggregation strategy, and output format.
+
+## review
+
+- **Agents**: code-reviewer (lead), security-auditor, performance-optimizer
+- **Ownership**: code-reviewer owns review summary; others own their domain reports
+- **Aggregation**: consensus (flag issues found by 2+ agents as high priority)
+- **Output**: `REVIEW.md` with severity-ranked findings
+
+## debug
+
+- **Agents**: debugger (lead), backend-specialist, incident-responder
+- **Ownership**: debugger owns root-cause analysis; others own hypothesis testing
+- **Aggregation**: relay (debugger synthesizes findings from others)
+- **Output**: `DEBUG_REPORT.md` with root cause and fix
+
+## feature
+
+- **Agents**: orchestrator (lead), backend-specialist, frontend-specialist, test-engineer
+- **Ownership**: orchestrator owns plan; specialists own their files; test-engineer owns tests
+- **Aggregation**: map-reduce (orchestrator integrates all outputs)
+- **Output**: implemented feature + tests
+
+## fullstack
+
+- **Agents**: backend-specialist, frontend-specialist, database-architect, devops-implementer
+- **Ownership**: each agent owns their layer (API, UI, DB, infra)
+- **Aggregation**: relay (backend-specialist synthesizes integration)
+- **Output**: full stack implementation
+
+## research
+
+- **Agents**: technical-researcher (lead), data-analyst, prompt-engineer
+- **Ownership**: technical-researcher owns synthesis; others own domain findings
+- **Aggregation**: consensus (areas of agreement highlighted)
+- **Output**: `RESEARCH.md` with findings and recommendations
+
+## security
+
+- **Agents**: security-architect (lead), security-auditor, backend-specialist
+- **Ownership**: security-architect owns threat model; auditor owns findings; backend owns remediation
+- **Aggregation**: relay (security-architect integrates all)
+- **Output**: `SECURITY_AUDIT.md` with CVSS-scored findings
+
+## migration
+
+- **Agents**: database-architect (lead), backend-specialist, devops-implementer
+- **Ownership**: database-architect owns schema; backend owns code changes; devops owns deployment
+- **Aggregation**: relay (database-architect coordinates sequence)
+- **Output**: migration scripts + rollback plan + deployment runbook

package/kb/reference/architecture-overview.md

@@ -35,7 +35,7 @@ ai-toolkit/
     rules/                   # Rules auto-injected into ~/.claude/CLAUDE.md
     hooks/                   # Hook scripts (copied to ~/.softspark/ai-toolkit/hooks/)
     hooks.json               # Hook definitions (merged into ~/.claude/settings.json)
-    constitution.md          # Immutable safety rules, 5 articles (marker-injected)
+    constitution.md          # Immutable safety rules, 6 articles (marker-injected)
     ARCHITECTURE.md          # System architecture reference (marker-injected)
     CLAUDE.md.template       # Template for project CLAUDE.md (used by init)
     settings.local.json.template
@@ -292,15 +292,16 @@ Agents (code-reviewer, debugger, devops-implementer, ...)
 
 Scripts at `~/.softspark/ai-toolkit/hooks/`. See [hooks-catalog.md](hooks-catalog.md) for details.
 
-## Constitution (5 Articles)
+## Constitution (6 Articles)
 
 | Article | Key Rule |
 |---------|----------|
-| I Safety First | No data loss, no blind execution, max 3 loop iterations |
+| I Safety First | No data loss, no blind execution, max 5 loop iterations |
 | II Hierarchy of Truth | KB is source of truth, research protocol mandatory |
 | III Operational Integrity | Green tests = Done, logs are evidence |
 | IV Self-Preservation | Constitution is read-only, kill switch via system-governor |
 | V Resource Governance | No destructive commands without confirmation |
+| VI Repair Discipline | No dead code, fix every found bug, tests and docs follow behavior, verify before done |
 
 ## Persona Presets
 

package/kb/reference/enterprise-config-guide.md

@@ -175,9 +175,9 @@ Requirements:
 
 ## Constitution Immutability
 
-- **Articles I-V** (toolkit core) are absolutely immutable
+- **Articles I-VI** (toolkit core) are absolutely immutable
 - **Base config articles** are immutable — projects cannot modify them
-- Projects can **only ADD** new articles (article 6+)
+- Projects can **only ADD** new articles (article 7+)
 
 ```json
 {

package/llms-full.txt

@@ -65,7 +65,7 @@
 - **app-builder**: Full-stack app scaffolding with stack-selection matrix: Next.js, React+Vite, Nuxt, Astro, FastAPI, Django, Laravel, React Native, Flutter, Unity. Triggers: scaffold, bootstrap, new project, starter template, build app, landing page, dashboard, API, mobile app, CLI, e-commerce, game. Load when user wants to start a new project from scratch.
 - **architecture-audit**: Explore codebase organically for architectural friction, discover shallow modules, and propose module-deepening refactors as GitHub issue RFCs using parallel sub-agent interface designs. Use when user wants to improve architecture, find shallow modules, deepen modules, or reduce coupling.
 - **architecture-decision**: Architecture decision making via trade-off analysis in RFC/RFD/ADR format: context, constraints, 3+ options, comparison, recommendation. Triggers: architecture decision, ADR, RFC, RFD, trade-offs, options comparison, design choice, pick between, should we use, evaluate approach. Load when weighing 2+ architectural options or writing decision records.
-- **biz-scan**: Scan codebase for business opportunities and KPIs
+- **biz-scan**: Scans codebase for business opportunities by analyzing database schemas, API endpoints, tracking events, and feature flags to surface underutilized capabilities, missing KPIs, and monetization gaps. Use when the user asks about revenue opportunities, business metrics, KPI coverage, analytics gaps, or monetization analysis of a codebase.
 - **brand-voice**: Loaded when writing documentation, content, README, or user-facing text. Prevents generic LLM rhetoric and enforces direct, technical voice.
 - **briefing**: Generate executive daily briefing across all agents
 - **build**: Build the project with auto-detected toolchain
@@ -90,7 +90,7 @@
 - **documentation-standards**: KB document conventions: YAML frontmatter (7 required fields), 5-category taxonomy (reference/howto/procedures/troubleshooting/best-practices), directory-category matching, validate.sh CI rules. Triggers: kb/, KB document, architecture note, SOP, runbook, howto, frontmatter, knowledge base entry, documentation standard. Load when creating or editing any file under kb/.
 - **ecommerce-patterns**: E-commerce domain patterns: cart, checkout flow, payment providers (Stripe/Adyen), order state machine, inventory, promotions, tax, B2B vs B2C. Triggers: cart, checkout, product, SKU, inventory, payment, Stripe, Shopify, Medusa, Magento, order status, promotion, tax calculation, coupon, refund. Load when working on any e-commerce feature.
 - **evaluate**: Evaluate skill quality and RAG retrieval accuracy
-- **evolve**: Evolve agent definitions via meta-architect
+- **evolve**: Analyzes failure patterns and inefficiencies in agent/skill definitions, then drafts and applies targeted improvements to system prompts, tool permissions, and behavioral rules. Use when the user asks to improve agent behavior, refine skill definitions, update system prompts, or optimize agent configurations based on observed failures.
 - **explain**: Explain code, architecture, or concepts with diagrams
 - **explore**: Explore codebase structure, stack, and architecture
 - **fix**: Auto-fix lint errors, type issues, and simple bugs
@@ -121,13 +121,13 @@
 - **panic**: Emergency stabilization via system-governor agent
 - **performance-profiling**: Performance measurement and optimization: four golden signals (latency/traffic/errors/saturation), p50/p95/p99, baseline-change-measure loop, flame graphs, load testing. Triggers: performance, slow, latency, p99, flame graph, profile, bottleneck, optimization, load test, benchmark, CPU profiling, memory leak. Load when diagnosing or optimizing slow code or services.
 - **persona**: Switch engineering persona at runtime: backend-lead, frontend-lead, devops-eng, junior-dev
-- **plan**: Plan implementation with tasks and success criteria
+- **plan**: Breaks down feature requests and project goals into phased implementation plans with task lists, agent assignments, dependency graphs, and success criteria. Use when the user asks to plan a feature, create an implementation roadmap, break down a coding task, or outline project phases.
 - **plan-writing**: Implementation plan and pre-mortem drafting: phase breakdown, success criteria, risks, rollback plan, acceptance tests, estimated effort. Triggers: implementation plan, pre-mortem, phased plan, project plan, task breakdown, success criteria, rollback strategy, risk register. Load when user asks to write a plan or pre-mortem document.
 - **plugin-creator**: Creates experimental opt-in plugin packs with manifests, conventions, and optional module scaffolding for Claude and Codex runtimes
 - **pr**: Create pull requests with pre-flight validation
 - **prd-to-issues**: Break a PRD into independently-grabbable GitHub issues using vertical slices with HITL/AFK tagging and dependency ordering. Use when user wants to convert a PRD to issues, create tickets, or break down a PRD into work items.
 - **prd-to-plan**: Convert a PRD into a phased implementation plan using tracer-bullet vertical slices. Use when user wants to break down a PRD, create an implementation plan, plan phases from a PRD, or mentions tracer bullets.
-- **predict**: Predict regressions and impact before changes land
+- **predict**: Analyzes code diffs and file changes to identify potential regressions, maps dependency impact across the codebase, and generates a risk-scored impact report. Use when reviewing pull requests, assessing code change risk, checking for breaking changes, or analyzing the blast radius of a diff.
 - **prompt-caching-patterns**: Loaded when user builds with Anthropic API and needs to cut cost or latency via prompt caching. Covers TTL, cache breakpoints, stacking, invalidation, and measuring hit rate.
 - **qa-session**: Interactive QA session where user reports bugs conversationally and agent files GitHub issues with domain language. Explores codebase in background for context. Use when user wants to report bugs, do QA, file issues conversationally, or mentions QA session.
 - **rag-patterns**: RAG architecture: embeddings, chunking strategies, hybrid search (BM25 + vector), reranking, CRAG/self-correcting, multi-hop reasoning, evaluation metrics. Triggers: RAG, embedding, vector search, pgvector, Qdrant, Pinecone, Weaviate, chunking, reranker, retrieval, hybrid search, semantic search, knowledge base, cosine similarity. Load when building or tuning RAG systems.
@@ -148,7 +148,7 @@
 - **swarm**: Execute tasks via Map-Reduce, Consensus, or Relay swarms
 - **swift-patterns**: Swift and iOS development patterns: SwiftUI, Combine, async/await, property wrappers, actors, Swift Package Manager, Core Data, UIKit interop, @MainActor. Triggers: Swift, SwiftUI, Combine, iOS, Xcode, actor, property wrapper, Core Data, SPM, UIKit, @MainActor, @State, @Binding. Load when writing or reviewing Swift code.
 - **tdd**: Test-driven development with red-green-refactor loop and vertical slices. Use when user wants TDD, test-first development, red-green-refactor, or building features with tests driving the implementation.
-- **teams**: Launch pre-configured Agent Teams for common workflows
+- **teams**: Launches pre-configured multi-agent teams for code review, debugging, feature development, security audits, and database migrations. Use when the user asks to start a multi-agent workflow, coordinate agent teams, run a team review, or needs parallel agent collaboration on a complex task.
 - **test**: Run tests with coverage analysis and reporting
 - **testing-patterns**: Testing strategy and craft: pyramid vs trophy, unit/integration/e2e split, fixtures, mocks vs fakes vs stubs, AAA pattern, flaky test diagnosis, coverage goals, property-based testing. Triggers: test, testing strategy, fixture, mock, stub, AAA, unit test, integration test, e2e, Playwright, Cypress, flaky, coverage, TDD, test pyramid. Load when writing, reviewing, or designing test suites.
 - **triage-issue**: Triage a bug by deeply exploring the codebase for root cause, then create a GitHub issue with a TDD-based fix plan. Mostly hands-off — minimal user interaction. Use when user reports a bug, wants to investigate an issue, mentions triage, or wants a fix plan.
@@ -4630,7 +4630,7 @@ ai-toolkit/
     rules/                   # Rules auto-injected into ~/.claude/CLAUDE.md
     hooks/                   # Hook scripts (copied to ~/.softspark/ai-toolkit/hooks/)
     hooks.json               # Hook definitions (merged into ~/.claude/settings.json)
-    constitution.md          # Immutable safety rules, 5 articles (marker-injected)
+    constitution.md          # Immutable safety rules, 6 articles (marker-injected)
     ARCHITECTURE.md          # System architecture reference (marker-injected)
     CLAUDE.md.template       # Template for project CLAUDE.md (used by init)
     settings.local.json.template
@@ -4887,15 +4887,16 @@ Agents (code-reviewer, debugger, devops-implementer, ...)
 
 Scripts at `~/.softspark/ai-toolkit/hooks/`. See [hooks-catalog.md](hooks-catalog.md) for details.
 
-## Constitution (5 Articles)
+## Constitution (6 Articles)
 
 | Article | Key Rule |
 |---------|----------|
-| I Safety First | No data loss, no blind execution, max 3 loop iterations |
+| I Safety First | No data loss, no blind execution, max 5 loop iterations |
 | II Hierarchy of Truth | KB is source of truth, research protocol mandatory |
 | III Operational Integrity | Green tests = Done, logs are evidence |
 | IV Self-Preservation | Constitution is read-only, kill switch via system-governor |
 | V Resource Governance | No destructive commands without confirmation |
+| VI Repair Discipline | No dead code, fix every found bug, tests and docs follow behavior, verify before done |
 
 ## Persona Presets
 
@@ -6520,9 +6521,9 @@ Requirements:
 
 ## Constitution Immutability
 
-- **Articles I-V** (toolkit core) are absolutely immutable
+- **Articles I-VI** (toolkit core) are absolutely immutable
 - **Base config articles** are immutable — projects cannot modify them
-- Projects can **only ADD** new articles (article 6+)
+- Projects can **only ADD** new articles (article 7+)
 
 ```json
 {

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.10.0",
+  "version": "2.11.0",
   "components": {
     "agents": {
       "description": "44 specialized agents (orchestrator, backend, frontend, security, devops, etc.)",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "2.10.0",
+  "version": "2.11.0",
   "description": "AI coding toolkit: 99 skills, 44 agents, 12-editor write-through (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo, Aider, Augment, Antigravity, Codex, opencode), machine-enforced safety constitution, SARIF audit, signed npm provenance.",
   "keywords": [
     "claude",

package/scripts/config_cli.py

@@ -217,7 +217,7 @@ def _diff_constitution(base: dict, project: dict) -> None:
     if base_articles or proj_articles:
         print()
         print("  Constitution:")
-        print("    = Articles I-V              (immutable)")
+        print("    = Articles I-VI             (immutable)")
         for num, art in sorted(base_articles.items()):
             print(f"    = Article {num}: {art['title']}  (inherited from base)")
         for num, art in sorted(proj_articles.items()):

package/scripts/config_merger.py

@@ -2,7 +2,7 @@
 """Config merger for ai-toolkit extends system.
 
 Implements layered deep merge with:
-- Constitution immutability (Articles I-V absolute, base articles immutable)
+- Constitution immutability (Articles I-VI absolute, base articles immutable)
 - Agent merge with requiredAgents enforcement
 - Override validation (override:true + justification required)
 - enforce block constraints (minHookProfile, requiredPlugins, forbidOverride, requiredAgents)
@@ -22,7 +22,7 @@ from typing import Any
 # Constants
 # ---------------------------------------------------------------------------
 
-IMMUTABLE_ARTICLES = frozenset({1, 2, 3, 4, 5})
+IMMUTABLE_ARTICLES = frozenset({1, 2, 3, 4, 5, 6})
 
 HOOK_PROFILE_ORDER = {"minimal": 0, "standard": 1, "strict": 2}
 
@@ -163,7 +163,7 @@ def _merge_constitution(
     """Merge constitution — additions only, no modifications.
 
     Rules:
-    1. Articles I-V (1-5) are ABSOLUTELY immutable — toolkit core.
+    1. Articles I-VI (1-6) are ABSOLUTELY immutable — toolkit core.
     2. Articles defined by base configs are immutable — projects cannot modify.
     3. Projects can ADD new articles with article numbers not in base.
     """
@@ -177,8 +177,8 @@ def _merge_constitution(
         if article_num in IMMUTABLE_ARTICLES:
             raise ConfigMergeError(
                 f"Cannot modify Constitution Article {article_num} — immutable.\n"
-                f"Articles I-V are defined by ai-toolkit and cannot be overridden.\n"
-                f"You can ADD new articles (article 6+)."
+                f"Articles I-VI are defined by ai-toolkit and cannot be overridden.\n"
+                f"You can ADD new articles (article 7+)."
             )
         if article_num in base_amendments:
             raise ConfigMergeError(

package/scripts/config_validator.py

@@ -21,7 +21,7 @@ from typing import Any
 VALID_PROFILES = {"minimal", "standard", "strict", "full", "offline-slm"}
 VALID_HOOK_PROFILES = {"minimal", "standard", "strict"}
 HOOK_PROFILE_ORDER = {"minimal": 0, "standard": 1, "strict": 2}
-IMMUTABLE_ARTICLES = frozenset({1, 2, 3, 4, 5})
+IMMUTABLE_ARTICLES = frozenset({1, 2, 3, 4, 5, 6})
 MIN_JUSTIFICATION_LEN = 20
 
 

package/scripts/emission.py

@@ -147,7 +147,7 @@ def generate_general_guidelines() -> str:
     lines = [
         "## General Guidelines",
         "",
-        '- Apply "Safety First": no data loss, no blind execution, max 3 loop iterations',
+        '- Apply "Safety First": no data loss, no blind execution, max 5 loop iterations',
         "- Research before acting: check existing code and context before proposing changes",
         "- Use structured commits: feat/fix/docs/refactor/test/chore prefixes",
         "- Quality gates: lint must pass, types must check, tests must be green before done",
@@ -162,7 +162,7 @@ def generate_quality_standards() -> str:
     lines = [
         "## Quality Standards",
         "",
-        "Derived from the immutable safety constitution (5 articles):",
+        "Derived from the immutable safety constitution (6 articles):",
         "",
         "**Article I — Safety First**",
         "- No data loss: never delete files without backup verification"
@@ -170,7 +170,7 @@ def generate_quality_standards() -> str:
         "- No blind execution: never run LLM-generated code without"
         " static analysis or review",
         "- No infinite loops: all autonomous loops must have a maximum"
-        " iteration count (max 3)",
+        " iteration count (max 5)",
         "",
         "**Article II — Hierarchy of Truth**",
         "- The Knowledge Base (`kb/`) is the source of truth;"
@@ -196,6 +196,21 @@ def generate_quality_standards() -> str:
         " user confirmation",
         "- Operate within assigned model tiers; model tier changes"
         " require user approval",
+        "",
+        "**Article VI — Repair Discipline**",
+        "- No dead code: unused code (files, classes, functions, imports,"
+        " variables) must be removed in the same change that makes it"
+        " unused; 'pre-existing' or 'out of scope' is not a valid reason",
+        "- Fix every found bug: bugs, gaps, missing tests, or stale docs"
+        " discovered during a task must be fixed in the same change when"
+        " directly adjacent to the work; deferral requires explicit user"
+        " decision",
+        "- Tests and docs follow behavior: behavior changes must carry"
+        " matching integration and unit tests plus affected documentation"
+        " in the same change",
+        "- Verify before claiming done: re-read the diff before marking"
+        " a task complete; no orphaned references, no missing coverage,"
+        " no stale docs",
     ]
     return "\n".join(lines)
 
@@ -233,7 +248,7 @@ def generate_quality_guidelines() -> str:
         "## Quality Guidelines",
         "",
         '- **Safety First**: No data loss, no blind execution,'
-        " maximum 3 autonomous loop iterations",
+        " maximum 5 autonomous loop iterations",
         "- **No Blind Execution**: Never run LLM-generated code"
         " without static analysis or review",
         '- **Tests are Sacred**: "Green Tests" is the only definition of Done;'

package/scripts/schemas/ai-toolkit-config.schema.json

@@ -81,7 +81,7 @@
     "constitution": {
       "type": "object",
       "additionalProperties": false,
-      "description": "Constitution amendments. Articles I-V are immutable. Base articles are immutable. Projects can only ADD new articles.",
+      "description": "Constitution amendments. Articles I-VI are immutable. Base articles are immutable. Projects can only ADD new articles (7+).",
       "properties": {
         "amendments": {
           "type": "array",

package/scripts/validate.py

@@ -664,6 +664,66 @@ def _validate_version_sync(tk_dir: Path, vr: ValidationResult) -> None:
                     )
 
 
+ROMAN_NUMERALS = ["I", "II", "III", "IV", "V", "VI", "VII", "VIII", "IX", "X"]
+
+
+def validate_constitution_drift(tk_dir: Path, vr: ValidationResult) -> None:
+    """Detect article-count drift between constitution.md and downstream docs."""
+    print()
+    print("## Constitution Drift")
+
+    constitution = tk_dir / "app" / "constitution.md"
+    if not constitution.is_file():
+        return
+
+    content = constitution.read_text(encoding="utf-8")
+    matches = re.findall(r"^## Article ([IVX]+):", content, re.MULTILINE)
+    if not matches:
+        vr.error("Constitution has no '## Article <roman>:' headings")
+        return
+
+    count = len(matches)
+    if count > len(ROMAN_NUMERALS):
+        vr.error(f"Constitution has {count} articles (more than {len(ROMAN_NUMERALS)} supported)")
+        return
+    max_roman = ROMAN_NUMERALS[count - 1]
+
+    docs = [
+        tk_dir / "README.md",
+        tk_dir / "app" / "ARCHITECTURE.md",
+        tk_dir / "kb" / "reference" / "architecture-overview.md",
+        tk_dir / "kb" / "reference" / "enterprise-config-guide.md",
+    ]
+
+    count_pat = re.compile(r"\b(\d+)\s+(?:immutable\s+safety\s+)?articles?\b", re.IGNORECASE)
+    range_pat = re.compile(r"\bArticles?\s+I-([IVX]+)\b")
+    drift = 0
+    for doc in docs:
+        if not doc.is_file():
+            continue
+        text = doc.read_text(encoding="utf-8")
+        for m in count_pat.finditer(text):
+            n = int(m.group(1))
+            if 1 <= n <= len(ROMAN_NUMERALS) and n != count:
+                vr.error(
+                    f"{doc.relative_to(tk_dir)} references '{n} articles' "
+                    f"but constitution has {count}"
+                )
+                drift += 1
+        for m in range_pat.finditer(text):
+            end = m.group(1).upper()
+            if end != max_roman and end in ROMAN_NUMERALS:
+                vr.error(
+                    f"{doc.relative_to(tk_dir)} references 'Articles I-{end}' "
+                    f"but constitution has I-{max_roman}"
+                )
+                drift += 1
+
+    if drift == 0:
+        print(f"  OK: constitution has {count} articles (I-{max_roman}), docs consistent")
+    print()
+
+
 def validate_content_quality(tk_dir: Path, vr: ValidationResult) -> None:
     """Check content quality: name matches directory, non-empty body."""
     print()
@@ -709,6 +769,7 @@ def _run_all_checks(tk_dir: Path, vr: ValidationResult) -> tuple[int, int, str]:
     validate_kb_documents(tk_dir, vr)
     validate_core_files(tk_dir, vr)
     actual_tests = validate_metadata_contracts(tk_dir, agent_count, skill_count, vr)
+    validate_constitution_drift(tk_dir, vr)
     validate_content_quality(tk_dir, vr)
     return agent_count, skill_count, actual_tests