@groupby/ai-dev 0.5.0 → 0.5.1

package/package.json

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

package/teams/snpd/github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,20 @@
+[S4R-1234](https://rezolvetech.atlassian.net/browse/S4R-1234)
+
+## Description
+
+A high-level description of what is changed by this PR.
+
+## Checks
+
+- [ ] Unit Tests
+- [ ] Update 'vault' variables
+- [ ] Feature flag added / updated / removed
+- [ ] Update documentation (diagram, confluence pages, content inside "/docs" directory, swagger)
+
+## AI Development Checklist
+
+- [ ] Spec/requirement linked: <!-- link here -->
+- [ ] AI tool used: <!-- Copilot / Claude / Agent / Other -->
+- [ ] Tests generated/refined with AI
+- [ ] AI review pass completed
+- [ ] Repo context files are still accurate (update if not)

package/teams/snpd/skills/docs-init/SKILL.md

@@ -0,0 +1,343 @@
+---
+name: docs-init
+description: Use when the user wants to initialize or refresh the canonical `/docs` folder, `CLAUDE.md`, and `README.md` based on the current repo state. Creates the five canonical docs if missing; audits them for drift against the code if present. Triggered by `/docs-init` or requests like "update the docs", "create the docs", "refresh project documentation", "init docs", "bring docs up to date".
+---
+
+# docs-init
+
+Initialize or refresh project documentation. Works in two modes automatically:
+
+- **Init mode** — `/docs` is missing or incomplete. Create the canonical
+  five-file structure from a fresh repo scan.
+- **Refresh mode** — `/docs` exists. Audit each file against the current
+  code and report what is outdated, drifted, or newly worth documenting.
+  Apply updates only after the user approves the human-readable report.
+
+## The Canonical Structure
+
+```text
+README.md                ← 30-second landing page + links into docs/
+CLAUDE.md                ← thin index for AI agents
+docs/
+  architecture.md        ← system, packages, domain model, cross-cutting concerns
+  local-setup.md         ← prerequisites, run, test, troubleshooting
+  conventions.md         ← code style, testing, API, migrations, PR norms
+  operations.md          ← deploy, secrets, observability, runbooks
+  decisions.md           ← append-only "why" log (ADR-lite)
+```
+
+Every doc under `docs/` MUST start with a `> **Scope:**` block explaining
+what belongs there, what does not, and where it is referenced from.
+Preserve this block on every edit.
+
+## Procedure
+
+### 1. Detect mode
+
+- Check for `README.md`, `CLAUDE.md`, and each of the five `docs/*.md` files.
+- If three or more are missing → **init mode**.
+- Otherwise → **refresh mode**.
+- Announce the detected mode to the user before proceeding.
+
+### 2. Scan the repo
+
+Gather facts from the actual code, not assumptions:
+
+- **Stack & build:** `build.gradle` / `pom.xml` / `package.json` /
+  `Cargo.toml` / `go.mod` / `pyproject.toml` / equivalent — language
+  version, framework, key libraries.
+- **Run commands:** README scripts, build-tool tasks (`./gradlew tasks`,
+  `npm run`, `make`, `cargo`, `go`, `pytest`, etc.), `docker-compose.yml`.
+- **Package layout:** top-level dirs under `src/` (or `lib/`, `app/`).
+- **Domain types:** entity/model/record classes; group by package.
+- **Tests:** test framework, conventions, fixture locations.
+- **Migrations:** Flyway / Liquibase / equivalent paths and naming.
+- **CI/CD:** files under `.github/workflows/` (or equivalent).
+- **Deploy:** `helm/`, `k8s/`, `terraform/`, Dockerfile, `Procfile`.
+- **Observability:** OpenTelemetry / logging configuration.
+- **Secrets:** Vault references, sealed-secrets, etc.
+- **API surface:** controller annotations, OpenAPI spec, route definitions.
+
+For refresh mode, also collect `git log --since="<doc-mtime>"` per doc to
+narrow attention to changes the doc may not yet reflect.
+
+### 3a. Init mode — draft (do NOT write yet)
+
+Draft the seven files in memory using the canonical templates below. Every
+`docs/` file starts with the `Scope` block. Leave honest placeholders where
+the repo does not yet have the answer (e.g. operations runbooks, dashboard
+links). Do not fabricate.
+
+Targets: `CLAUDE.md` ≤ 40 lines, `README.md` ≤ 30 lines.
+
+**Do not write these files to disk yet.** Continue to step 4, where the
+draft contents are summarized in the audit report and the user approves
+before any file is created.
+
+### 3b. Refresh mode — audit each file
+
+For each existing doc, classify findings into three buckets:
+
+- **Outdated** — the doc states something that is no longer true (a removed
+  command, a renamed package, a retired workflow, a wrong version number).
+- **Drifted** — the doc is technically correct but missing material the
+  code now contains (a new package, a new build task, a new workflow, a
+  new env profile).
+- **New opportunities** — content the doc does not have but probably
+  should (a recently added feature area, a new observability surface).
+
+`decisions.md` is **append-only**: propose new entries on approval, but
+never rewrite or remove existing ones.
+
+### 4. Report to the user (human-friendly, NOT a diff)
+
+In **init mode**, the report summarizes what each new file will contain
+(one paragraph per file describing scope and key sections drafted), and
+the "Proposed actions" list reads as `Create <path>` items.
+
+In **refresh mode**, the report follows the per-file findings format
+below.
+
+Output a single readable report in this exact shape:
+
+```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
+**Outdated:**
+- The package list mentions `legacy/` but that directory was removed in <commit>.
+- Lists framework version X.Y; build file now pins X.Z.
+
+**Drifted:**
+- A new top-level package is not mentioned.
+
+**New opportunities:**
+- A retry strategy was added in <PR>; worth a short paragraph.
+
+### docs/local-setup.md
+**Outdated:**
+- (none)
+
+**Drifted:**
+- A new build/test task was added in <commit> but the doc does not list it.
+
+(... continue for each file ...)
+
+### CLAUDE.md
+**Outdated:** (none)
+**Drifted:** Pointer to `docs/operations.md` is missing.
+
+### README.md
+**Outdated:** Quick-start references an old env-var value that has been
+renamed.
+
+## Proposed actions
+
+Numbered list of concrete edits I would make if you approve. Group by
+file. Each item is one sentence — no diffs.
+
+## 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 the bucket.
+This makes it obvious that the check ran.
+
+### 5. Apply on approval
+
+- On `apply` — create or edit each affected file. In init mode this means
+  creating all seven files from the drafts in step 3a. In refresh mode
+  it means editing existing files in place. Preserve `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 were created or
+  changed and suggest a commit message.
+
+## Hard rules
+
+- **Apply edits only after explicit user approval.** No file under `docs/`,
+  `CLAUDE.md`, or `README.md` is edited before the user replies `apply` or
+  `apply <numbers>`.
+- **`decisions.md` is append-only.** New entries may be added on approval;
+  existing entries are never edited or removed.
+- **Preserve every `> **Scope:**` block** verbatim on edited docs.
+- **Do not move content between files.** Each file's scope is the
+  convention. If content does not fit any of the five, mention it in the
+  report and ask whether to create a new file or fold it elsewhere.
+- **Do not fabricate.** If the repo has no dashboards, no runbooks, no
+  decisions yet, leave honest placeholders or empty sections.
+- **Do not delete sections without flagging them.** Surfacing a removal
+  belongs in the report, not as a silent edit.
+- **Do not edit `.github/PULL_REQUEST_TEMPLATE.md`, CI files, or code.**
+  This skill only touches docs.
+- **Keep `CLAUDE.md` ≤ 40 lines and `README.md` ≤ 30 lines** after edit.
+  If pointers no longer fit, ask before expanding.
+
+## Canonical templates
+
+When in init mode, use these skeletons. Fill from the repo scan.
+
+### `docs/architecture.md`
+
+```markdown
+# Architecture
+
+> **Scope:** What this system is, how it's structured, and the domain it models.
+> Put here: tech stack, package/module layout, key components, domain entities,
+> cross-cutting concerns (auth, multi-tenancy, observability).
+> Do **not** put here: how to run it (→ local-setup.md), how to deploy it
+> (→ operations.md), code style (→ conventions.md).
+>
+> **Referenced from:** `README.md` and `CLAUDE.md`.
+
+## Overview
+## Package Structure
+## Key Libraries
+## Domain Model
+## Cross-Cutting Concerns
+```
+
+### `docs/local-setup.md`
+
+```markdown
+# Local Setup
+
+> **Scope:** Everything needed to clone, run, and test on a fresh machine.
+> Put here: prerequisites, full setup steps, env vars, build/test commands,
+> troubleshooting.
+> Do **not** put here: deployment (→ operations.md), architecture
+> (→ architecture.md).
+>
+> **Referenced from:** `README.md` quick-start (links here for detail) and `CLAUDE.md`.
+
+## Prerequisites
+## Run the Service
+## Common Tasks
+## Environment Profiles
+## Troubleshooting
+```
+
+### `docs/conventions.md`
+
+```markdown
+# Conventions
+
+> **Scope:** How we write and review code in this repo.
+> Put here: language conventions, testing philosophy, naming rules, API
+> rules, migration rules, PR norms.
+> Do **not** put here: architecture (→ architecture.md), ops (→ operations.md).
+>
+> **Referenced from:** `CLAUDE.md` (so AI agents follow these) and `README.md`.
+
+## Code Style
+## Testing
+## API Conventions
+## Database Migrations
+## PRs and Commits
+```
+
+### `docs/operations.md`
+
+```markdown
+# Operations
+
+> **Scope:** What happens after merge — deploy, run, observe, recover.
+> Put here: deploy pipelines, environments, secrets source, dashboards,
+> alerts, runbooks.
+> Do **not** put here: architecture (→ architecture.md), local dev
+> (→ local-setup.md).
+>
+> **Referenced from:** `README.md` and `CLAUDE.md`.
+
+## Deploy
+## Secrets
+## Observability
+## Common Runbooks
+## On-Call
+```
+
+### `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.
+> Put here: framework choices, trade-offs taken, deliberate deviations.
+> Do **not** put here: how-to instructions, code-level comments.
+>
+> **Referenced from:** `CLAUDE.md`, and linked from PRs that introduce a
+> non-obvious choice.
+
+## 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're giving up)
+
+## Entries
+
+*(No entries yet.)*
+```
+
+### `CLAUDE.md`
+
+```markdown
+# CLAUDE.md
+
+Index for AI coding agents (Claude Code, Copilot CLI). Keep this file short —
+point to `docs/` for substance.
+
+## What this repo is
+
+<one-paragraph description from the repo scan>
+
+## Where things live
+
+- **Architecture, domain model, package layout** → [docs/architecture.md](docs/architecture.md)
+- **Build / run / test commands** → [docs/local-setup.md](docs/local-setup.md)
+- **Code style, testing conventions, API/migration rules** → [docs/conventions.md](docs/conventions.md)
+- **Deploy, secrets, observability, runbooks** → [docs/operations.md](docs/operations.md)
+- **Why things are the way they are** → [docs/decisions.md](docs/decisions.md)
+
+## Rules for working in this repo
+
+<3-6 short bullets — only repo-specific gotchas an agent must follow on
+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>
+
+Requires <prereqs>. For detail see [docs/local-setup.md](docs/local-setup.md).
+
+## Documentation
+
+- [Architecture](docs/architecture.md) — system overview, domain model, package layout
+- [Local setup](docs/local-setup.md) — full setup, tasks, troubleshooting
+- [Conventions](docs/conventions.md) — code style, testing, API & migration rules
+- [Operations](docs/operations.md) — deploy, secrets, observability, runbooks
+- [Decisions](docs/decisions.md) — why things are the way they are
+```