@groupby/ai-dev 0.5.11 → 0.5.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groupby/ai-dev",
-  "version": "0.5.11",
+  "version": "0.5.13",
   "description": "Interactive installer for Rezolve Ai development content",
   "type": "module",
   "bin": {

package/teams/brain-studio/skills/docs-init/SKILL.md

@@ -0,0 +1,405 @@
+---
+name: docs-init
+description: Use when the user wants to initialize or refresh the fast-layer summary docs (`docs/*.md`), `CLAUDE.md`, and `README.md` from the current repo state. The authoritative source of truth stays in `docs/architecture/`; these summaries index and link into it. Triggered by `/docs-init` or requests like "update the docs", "refresh project documentation", "init docs", "bring docs up to date".
+---
+
+# docs-init
+
+Generate and audit the **fast/index layer** of project documentation. This layer
+indexes and links into the authoritative `docs/architecture/`, never duplicating
+it and never fabricating facts.
+
+This is a **standalone utility** — not part of the main AI workflow pipeline.
+Run it any time, independently of tickets or implementation.
+
+## Two documentation layers
+
+This project has two doc layers. Keep them distinct:
+
+1. **`docs/architecture/`** — the authoritative, detailed source of truth.
+   13+ files covering system overview, module structure, state management, data
+   flow, auth, tenancy, feature flags, services, integrations, build, testing,
+   code conventions, git workflow. **This skill never modifies these — it only
+   reads them.**
+
+2. **Fast layer (this skill manages it)** — `docs/*.md` summaries
+   (`architecture.md`, `local-setup.md`, `conventions.md`, `operations.md`,
+   `decisions.md`) plus `CLAUDE.md` and `README.md` as thin indexes. These are
+   executive summaries for quick human onboarding and quick AI context. They
+   **summarize and link into** `docs/architecture/` — they never replace or
+   duplicate it.
+
+## The fast-layer structure
+
+```text
+README.md                ← 30-second landing page + links
+CLAUDE.md                ← thin index for AI agents (~40 lines)
+docs/
+  architecture.md        ← summary: system, packages, domain model
+  local-setup.md         ← prerequisites, run, test commands
+  conventions.md         ← summary: code style, testing, PR norms
+  operations.md          ← deploy, secrets, observability
+  decisions.md           ← append-only "why" log (ADR-lite)
+```
+
+Every `docs/*.md` summary MUST start with a disclaimer block naming
+`docs/architecture/` as the authoritative source. Two rules govern it:
+
+**Which convention to use:**
+- New file (init mode), or an existing file with no disclaimer → use the
+  `> **Note:**` template below.
+- Existing file that already has a disclaimer (e.g. a `> **Scope:**` /
+  `> **Referenced from:**` block) → **preserve it as-is**. Do not swap
+  conventions; mixing them is noise, not an improvement.
+
+**The Doc Routing Table link is conditional.** The base disclaimer always points
+to `docs/architecture/`. Append the Doc Routing Table sentence **only if
+`.github/copilot-instructions.md` actually exists in the repo** (confirm with
+`ls` first). If it does not exist, omit that sentence — never emit a link to a
+file that is not there.
+
+Base (always):
+
+```markdown
+> **Note:** This is an executive summary for quick AI context. The
+> authoritative source of truth is `docs/architecture/`.
+```
+
+Append only when `.github/copilot-instructions.md` exists:
+
+```markdown
+> See the [Doc Routing Table](../.github/copilot-instructions.md) for which
+> architecture doc to consult for each task type.
+```
+
+## Procedure
+
+### 1. Detect mode
+
+- Check for `README.md`, `CLAUDE.md`, and each of the five `docs/*.md` summaries.
+- If three or more summaries are missing → **init mode**.
+- Otherwise → **refresh mode**.
+- Announce the detected mode before proceeding.
+
+### 2. Scan sources
+
+The primary source for the fast layer is `docs/architecture/` — **not raw code**:
+
+- Read the relevant `docs/architecture/*.md` files to extract facts.
+- Cross-reference actual code only where architecture docs may be stale.
+- `package.json` — versions, dependencies, and **yarn scripts** (the run/build/
+  test commands).
+- `.github/workflows/` — CI details and triggers.
+- `helm/`, `Dockerfile` — deploy details.
+- `docs/architecture/13-git-workflow.md` — commit/PR conventions.
+
+For refresh mode, also run `git log --since="<doc-mtime>"` per summary to narrow
+attention to recent changes a summary may not yet reflect.
+
+### 3a. Init mode — draft (do NOT write yet)
+
+Draft the seven fast-layer files in memory using the **canonical templates**
+below. Content comes from `docs/architecture/` — summarize and link, do not
+duplicate. Every `docs/*.md` starts with the `> **Note:**` disclaimer. Leave
+honest placeholders where no authoritative source exists yet. Do not fabricate.
+
+**Verification checklist — apply to every claim before including it.** The core
+rule: **every fact in a summary must trace to `docs/architecture/`, or to real
+source when the architecture docs are silent or stale.**
+
+1. **Commands** — Before writing any `yarn <script>` / `npm run <script>`,
+   confirm the script exists in `package.json`. Never guess script names.
+2. **Config keys** — Quote exact property paths from the actual config file
+   (`.env`, JSON, YAML, Helm values). Do not paraphrase or use placeholder
+   syntax like `${...}`.
+3. **Directory contents** — `ls` the directory before describing what it
+   contains. Never say "contains X" without checking.
+4. **Credentials** — Never instruct placing credentials in a repo-tracked file.
+   Recommend user-home config (`~/.npmrc`) or environment variables instead.
+5. **CI/CD triggers** — Read the actual GitHub Actions `on:` block. List all
+   branches/events accurately; do not guess.
+6. **Scope qualifiers** — When stating "all X do Y," verify there are no
+   exceptions before writing it.
+7. **File references** — When describing what a file is for, trace its
+   references (grep the filename) so the description matches actual usage.
+8. **Architecture-doc links** — When a summary section points to
+   `docs/architecture/NN-*.md`, confirm that file exists and covers that topic.
+9. **Cross-references resolve** — Every link in `CLAUDE.md`, `README.md`, and
+   the disclaimer's conditional Routing Table line must point to a file that
+   exists. `ls` before linking; omit or fix any link whose target is absent.
+
+Targets: `CLAUDE.md` ≤ 40 lines, `README.md` ≤ 30 lines, each `docs/*.md`
+summary ≤ 80 lines.
+
+**Do not write these files to disk yet.** Continue to step 4, where the drafts
+are summarized in the audit report and the user approves before any file is
+created.
+
+### 3b. Refresh mode — audit each summary
+
+For each existing summary, compare against `docs/architecture/` and code, and
+classify findings into three buckets:
+
+- **Outdated** — the summary states something no longer true.
+- **Drifted** — correct but missing material that `docs/architecture/` or the
+  code now contains.
+- **New opportunities** — content the summary does not have but probably should.
+
+`decisions.md` is **append-only**: propose new entries on approval, but never
+rewrite or remove existing ones.
+
+### 4. Report to the user (human-readable, NOT a diff)
+
+In **init mode**, the report summarizes what each new file will contain (one
+paragraph per file) and the "Proposed actions" list reads as `Create <path>`
+items. In **refresh mode**, it follows the per-file findings format below.
+
+```markdown
+# Documentation audit — <YYYY-MM-DD>
+
+Mode: <init | refresh>
+
+## Summary
+<2-3 sentences: what was created or what needs attention overall>
+
+## Per-file findings
+
+### docs/architecture.md (summary)
+**Outdated:** ...
+**Drifted:** ...
+**New opportunities:** ...
+
+(... continue for each file ...)
+
+## Proposed actions
+Numbered list of concrete edits. Group by file. Each item is one sentence — no diffs.
+
+## Verified against source
+- Commands: <which package.json scripts were confirmed>
+- Config keys: <which files were read for exact names>
+- Directories: <which directories were listed>
+- Workflow triggers: <which workflow files were read>
+- Architecture links: <which docs/architecture/ files were confirmed>
+- Line limits: <CLAUDE.md ≤40, README.md ≤30, each docs/*.md ≤80 — confirmed>
+- Credentials: <confirm no repo-tracked file instructions>
+
+## Awaiting your approval
+Reply "apply" to make the changes, "apply <numbers>" to apply a subset
+(e.g. "apply 1,3,5"), or "skip" to make no changes.
+```
+
+If a bucket is empty for a file, write `(none)` — do not omit it. This makes it
+obvious the check ran.
+
+### 5. Apply on approval
+
+- On `apply` — create or edit each affected file. In init mode, create all seven
+  fast-layer files from the step-3a drafts. In refresh mode, edit existing files
+  in place. Preserve `> **Note:**` and `> **Scope:**` blocks. Do not reorganize
+  content across files. Do not change file names.
+- On `apply <numbers>` — apply only the selected proposed actions.
+- On `skip` — make no edits or creations; thank the user and exit.
+- After applying, print a short summary of which files changed and suggest a
+  commit message.
+
+## Hard rules
+
+- **Apply edits only after explicit user approval.** No fast-layer file is
+  written before the user replies `apply` or `apply <numbers>`.
+- **Never touch `docs/architecture/`.** It is authoritative and managed
+  separately. Read it; never edit it.
+- **`decisions.md` is append-only.** New entries on approval; existing entries
+  are never edited or removed.
+- **Preserve every `> **Note:**` and `> **Scope:**` block** verbatim on edit.
+- **Do not move content between files.** Each file's scope is the convention.
+  If content fits none of the five, mention it in the report and ask.
+- **Do not fabricate.** If the repo has no dashboards, runbooks, or decisions
+  yet, leave honest placeholders or empty sections.
+- **Verify every factual claim** against `docs/architecture/` or source before
+  including it. See the verification checklist in step 3a.
+- **Summaries link, never duplicate.** Reference architecture docs by relative
+  path (e.g. "See `docs/architecture/03-state-management.md` for details")
+  instead of copying their content.
+- **Never reference repo-tracked files for credentials.** Use `~/.npmrc` or
+  environment variables.
+- **Qualify universal statements.** If writing "all X do Y," verify there are no
+  exceptions and add qualifiers if needed.
+- **Do not delete sections without flagging them** in the report.
+- **Do not edit `.github/`, CI files, or source code.** This skill only touches
+  the fast-layer docs.
+- **Keep line limits:** `CLAUDE.md` ≤ 40, `README.md` ≤ 30, each `docs/*.md`
+  ≤ 80. If pointers no longer fit, ask before expanding.
+
+## Common mistakes
+
+- Duplicating content from `docs/architecture/` into summaries (summarize and
+  link, do not copy).
+- Treating summaries as the source of truth — they are NOT.
+- Editing `docs/architecture/` files (out of scope for this skill).
+- Removing the `> **Note:**` disclaimer from a summary.
+- Making changes before user approval.
+- Fabricating operations info (dashboards, runbook URLs) that does not exist.
+- Guessing a `yarn` script name instead of confirming it in `package.json`.
+
+## Canonical templates
+
+When in init mode, use these summary-shaped skeletons. Each section holds 1–2
+sentences plus a link into `docs/architecture/` — not the details themselves.
+Fill from the architecture-doc scan.
+
+### `docs/architecture.md`
+
+```markdown
+# Architecture (summary)
+
+> <disclaimer block — see "The fast-layer structure" section.
+> Always points to `docs/architecture/`; append the Doc Routing Table line
+> only if `.github/copilot-instructions.md` exists.>
+
+## Overview
+<one paragraph: what this system is. → `docs/architecture/01-*.md`>
+
+## Module Structure
+<top-level layout in 2-3 lines. → `docs/architecture/02-*.md`>
+
+## State & Data Flow
+<one line each. → `docs/architecture/03-state-management.md`, `…-data-flow.md`>
+
+## Cross-Cutting Concerns
+<auth, tenancy, feature flags — one line each, with links into docs/architecture/>
+```
+
+### `docs/local-setup.md`
+
+```markdown
+# Local Setup (summary)
+
+> <disclaimer block — see "The fast-layer structure" section.
+> Always points to `docs/architecture/`; append the Doc Routing Table line
+> only if `.github/copilot-instructions.md` exists.>
+
+## Prerequisites
+<node/yarn versions and required tooling — confirmed from package.json>
+
+## Run / Build / Test
+<the actual `yarn <script>` commands, confirmed in package.json>
+
+## Environment
+<key env vars, exact names. → relevant docs/architecture/ doc>
+
+## Troubleshooting
+<common gotchas, or an honest placeholder if none documented yet>
+```
+
+### `docs/conventions.md`
+
+```markdown
+# Conventions (summary)
+
+> <disclaimer block — see "The fast-layer structure" section.
+> Always points to `docs/architecture/`; append the Doc Routing Table line
+> only if `.github/copilot-instructions.md` exists.>
+
+## Code Style
+<one line. → `docs/architecture/` code-conventions doc>
+
+## Testing
+<framework + philosophy in 1-2 lines. → testing doc>
+
+## PRs & Commits
+<commit/PR norms. → `docs/architecture/13-git-workflow.md`>
+```
+
+### `docs/operations.md`
+
+```markdown
+# Operations (summary)
+
+> <disclaimer block — see "The fast-layer structure" section.
+> Always points to `docs/architecture/`; append the Doc Routing Table line
+> only if `.github/copilot-instructions.md` exists.>
+
+## Deploy
+<pipeline + environments in 1-2 lines. → relevant docs/architecture/ doc>
+
+## Secrets
+<where secrets come from — never a repo-tracked file>
+
+## Observability
+<dashboards/alerts, or an honest placeholder if none exist yet>
+```
+
+### `docs/decisions.md`
+
+```markdown
+# Decisions
+
+> **Scope:** Short, append-only log of *why* this codebase is the way it is.
+> Captures decisions whose rationale is not obvious from reading the code.
+> Do **not** put how-to instructions here.
+
+## Format
+
+Append a new entry as a new top-level section. Don't edit prior entries — if a
+decision is reversed, add a new entry that supersedes the old one.
+
+Each entry:
+- **Context:** what prompted the decision
+- **Decision:** what we chose
+- **Consequence:** what this means going forward (and what we give up)
+
+## Entries
+
+*(No entries yet.)*
+```
+
+### `CLAUDE.md`
+
+```markdown
+# CLAUDE.md
+
+Index for AI coding agents. Keep this file short — point to `docs/` for substance.
+
+## What this repo is
+
+<one-paragraph description from the architecture-doc scan>
+
+## Where things live
+
+- **Architecture, domain model, module layout** → [docs/architecture.md](docs/architecture.md)
+- **Build / run / test commands** → [docs/local-setup.md](docs/local-setup.md)
+- **Code style, testing, PR rules** → [docs/conventions.md](docs/conventions.md)
+- **Deploy, secrets, observability** → [docs/operations.md](docs/operations.md)
+- **Why things are the way they are** → [docs/decisions.md](docs/decisions.md)
+
+> **Note:** `docs/*.md` files are executive summaries; the authoritative source
+> is `docs/architecture/`. (If `.github/copilot-instructions.md` exists, route
+> via its Doc Routing Table.)
+
+## Rules for working in this repo
+
+<3-6 short bullets — only repo-specific gotchas an agent must follow every turn.
+Do not duplicate detail that lives in docs/>
+```
+
+### `README.md`
+
+```markdown
+# <repo name>
+
+<one-paragraph description>
+
+## Quick start
+
+<3-5 lines: the shortest possible happy path, using confirmed yarn scripts>
+
+Requires <prereqs>. For detail see [docs/local-setup.md](docs/local-setup.md).
+
+## Documentation
+
+- [Architecture](docs/architecture.md) — system overview, domain model, layout
+- [Local setup](docs/local-setup.md) — full setup, tasks, troubleshooting
+- [Conventions](docs/conventions.md) — code style, testing, PR rules
+- [Operations](docs/operations.md) — deploy, secrets, observability
+- [Decisions](docs/decisions.md) — why things are the way they are
+```

package/teams/rangers/skills/team-code-review/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: team-code-review
 description: >-
-  Review current changes against the repository's AI routing docs, working agreement, architecture, code-review checklist, and changed files. Use for phase reviews, final branch reviews, PR readiness checks, or focused reviews where findings should be prioritized before summary.
+  Review current changes against the repository's AI routing docs, working agreement, architecture, code-review checklist, and changed files. Scores the change across review axes (correctness, readability, architecture, security, performance) and tags each finding with a severity label so blockers are obvious. Use for phase reviews, final branch reviews, PR readiness checks, or focused reviews where findings should be prioritized before summary.
 ---
 
 # Team Code Review
@@ -28,39 +28,59 @@ Use this skill for read-first review work. The project docs define the review st
    - architecture or task-specific docs named by the router
 4. Inspect changed files and nearby code before writing findings.
 
-## Review Standards
+## Review Axes
 
-Prioritize defects and regressions over style. Check:
+Review the change across these axes and score each one. Scoring forces a deliberate pass over every axis instead of stopping at the first issue found.
 
-- correctness and user-visible behavior
-- architecture and documented conventions
-- security, permissions, and sensitive data handling
-- error handling and failure states
-- performance and lifecycle cleanup
-- accessibility for UI work
-- test coverage and validation gaps
-- docs drift caused by the change
+- **Correctness** — user-visible behavior, edge cases, error handling and failure states, test coverage and validation gaps.
+- **Readability** — clarity, naming, and complexity. Could another engineer follow this without explanation?
+- **Architecture** — documented conventions, module boundaries, and docs drift caused by the change.
+- **Security** — input validation, permissions, auth, and sensitive data handling.
+- **Performance** — inefficient or expensive code, and lifecycle cleanup.
 
-If the code contradicts project docs, treat that as a finding unless the change deliberately updates the documented target state.
+For UI work, also review accessibility (semantic markup, keyboard navigation, focus management) under Readability and Correctness.
+
+Prioritize defects and regressions over style. If the code contradicts project docs, treat that as a finding unless the change deliberately updates the documented target state.
+
+## Severity Labels
+
+Tag every finding so the reader instantly knows what blocks merge versus what is optional:
+
+| Label | Meaning |
+|---|---|
+| `Critical:` | Blocks merge — security hole, data loss, broken or wrong behavior. |
+| `Required:` | Must change before merge, but not merge-breaking on its own. |
+| `Consider:` | Worth evaluating. A suggestion, not a blocker. |
+| `Nit:` | Optional minor or style feedback. |
+| `FYI:` | Informational only, no action needed. |
 
 ## Output
 
-Lead with findings ordered by severity. Include tight file and line references when possible.
+Group findings by axis, and prefix each with its severity label. Include tight file and line references when possible. Lead with the axes that have the most severe findings.
 
 Use this shape:
 
 ```markdown
 ## Findings
-- [P1/P2/P3] file:line - Issue and impact.
+
+### Correctness
+- Critical: file:line - Issue and impact.
+- Consider: file:line - Issue and impact.
+
+### Security
+- Critical: file:line - Issue and impact.
+
+### Readability
+- Nit: file:line - Issue and impact.
 
 ## Open Questions
 - [Question]
 
 ## Summary
-[Brief assessment]
+[Brief assessment, with a per-axis read and the total count by severity, e.g. "2 critical, 1 consider, 1 nit. Blocks merge until criticals are fixed."]
 
 ## Validation Gaps
 - [Gap]
 ```
 
-If the project workflow requires a review artifact, write it to the documented scratch location, commonly `tmp/review-phase-XX.md` or `tmp/review-final.md`.
+Only include axes that have findings. If the project workflow requires a review artifact, write it to the documented scratch location, commonly `tmp/review-phase-XX.md` or `tmp/review-final.md`.