@groupby/ai-dev 0.5.0 → 0.5.1

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

@@ -0,0 +1,402 @@
+---
+name: docs-init-v2
+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-v2` or requests like "update the docs v2", "create the docs v2", "refresh project documentation v2", "init docs v2".
+---
+
+# 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**.
+- **Exception:** If canonical files are missing but the repo has substantial
+  existing documentation (e.g. `docs/` with other files, detailed README,
+  wiki-style markdown), treat as **refresh mode** — bridge existing docs
+  into the canonical structure rather than creating from scratch. Mention
+  existing docs in the report and propose how to integrate or link them.
+- 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` / `setup.py` /
+  `requirements.txt` / `Makefile` / 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/`,
+  `cmd/`, `internal/`, `pkg/` for Go, `dags/`/`jobs/` for Airflow,
+  `packages/`/`apps/` for monorepos, `manifests/` for infra repos).
+- **Domain types:** entity/model/record/struct/schema classes; group by
+  package or module.
+- **Tests:** test framework, conventions, fixture locations.
+- **Migrations:** Flyway / Liquibase / Alembic / Knex / equivalent paths
+  and naming.
+- **CI/CD:** files under `.github/workflows/`, `.circleci/`, `Jenkinsfile`,
+  `cloudbuild.yaml`, or equivalent. Note the CI system in use.
+- **Deploy:** `helm/`, `k8s/`, `kustomize/`, `terraform/`, Dockerfile,
+  `Procfile`, Argo CD manifests.
+- **Observability:** OpenTelemetry / logging / Prometheus / Datadog config.
+- **Secrets:** Vault references, sealed-secrets, workload identity, ADC,
+  env var injection.
+- **API surface:** controller annotations, OpenAPI spec, route definitions,
+  proto definitions, GraphQL schema.
+
+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.
+
+**Verification checklist — apply to every claim before including it:**
+
+1. **Commands** — Before writing any `./gradlew <task>`, `npm run <script>`,
+   `make <target>`, `go <cmd>`, or similar, confirm the task exists (check
+   `build.gradle` tasks, `package.json` scripts, Makefile targets, workflow
+   files). Never guess task names.
+2. **Config keys** — Quote exact property paths from the actual config file
+   (YAML, properties, JSON, TOML, `.env`, Helm values, Kustomize overlays).
+   Do not paraphrase or use placeholder syntax like `${...}`.
+3. **Directory contents** — List (`ls`) the directory before describing what it
+   contains. Never say "contains templates only" or "contains X" without
+   checking.
+4. **Credentials** — Never instruct placing credentials in a repo-tracked file.
+   Recommend user-home config instead: `~/.gradle/gradle.properties`,
+   `~/.m2/settings.xml`, `~/.npmrc`, `~/.pypirc`, `~/.docker/config.json`,
+   or environment variables / Application Default Credentials (ADC).
+5. **Submodule commands** — Use `git submodule update --init --recursive`
+   (pinned commit). Never use `--remote` (breaks reproducible builds).
+6. **CI/CD triggers** — Read the actual trigger/filter syntax for the CI system
+   in use (GitHub Actions `on:` block, CircleCI `filters:`, Jenkins pipeline
+   triggers, etc.). List all branches/events accurately.
+7. **Scope qualifiers** — When stating "all X do Y," verify there are no
+   exceptions (e.g. health, metrics, actuator endpoints outside the API prefix).
+8. **File references** — When describing what a file is used for, trace its
+   references (grep for the filename) so the description matches actual usage.
+
+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.
+
+## Verified against source
+
+List what was checked to ensure accuracy:
+- Commands: <which tasks were confirmed and how>
+- Config keys: <which files were read for exact property names>
+- Directories: <which directories were listed>
+- Workflow triggers: <which workflow files were read>
+- 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 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.
+- **Verify every factual claim.** Before including any command, config key,
+  directory description, or workflow trigger in the docs, confirm it against
+  the actual source file. See the verification checklist in step 3a.
+- **Never reference repo-tracked files for credentials.** Always use
+  user-home paths (`~/.gradle/gradle.properties`, `~/.m2/settings.xml`,
+  `~/.npmrc`, `~/.pypirc`) or environment variables / ADC.
+- **Never use `--remote` in submodule commands.** Use pinned commits for
+  reproducible builds.
+- **Qualify universal statements.** If writing "all endpoints do X," verify
+  there are no exceptions and add qualifiers if needed.
+- **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
+```

package/teams/snpd/skills/draft-plan/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: draft-plan
+description: Use when the user invokes `/draft-plan` (or asks to "draft a plan", "plan this spec"). Reads a spec file from `.claude/artifacts/` (typically a `*-spec.md` produced by /jira-spec), performs a deep codebase review, drafts a high-level implementation plan, and discusses it with the user. On approval, writes the plan to a sibling `*-plan.md` file and stops — does not start implementation. Only runs when explicitly invoked — do NOT auto-trigger on the word "plan".
+---
+
+# draft-plan
+
+Turn a spec into a discussed, approved, high-level implementation plan.
+
+## Inputs
+
+- **Spec file path** — typically `.claude/artifacts/{KEY}_{slug}-spec.md`. The
+  user may pass it explicitly (`/draft-plan S4R-10559_ai-adoption-runbook-spec.md`)
+  or by ticket key (`/draft-plan S4R-10559`).
+- **If no argument is given:** list all `*-spec.md` files in `.claude/artifacts/`
+  with their last-modified dates and ask which one to plan.
+- **Do not invent a spec.** If no matching spec file exists, stop and tell the
+  user to run `/jira-spec` first.
+
+## Workflow
+
+### 1. Read the spec verbatim
+
+- Read the entire spec file.
+- Pay attention to: Original Description, Acceptance Criteria, AI-gathered
+  Implementation Notes, Open Questions. The first two are authoritative; the
+  third is a starting hypothesis, not a constraint.
+
+### 2. Investigate the codebase (deeper than `/jira-spec`)
+
+The spec used **medium-depth** scanning — file lists and excerpts. This skill
+uses **deep** scanning. For each likely touch point:
+
+- Read the relevant files **end-to-end**, not just excerpts.
+- Trace data flow across layers (e.g. controller → service → repository →
+  migration) for any feature that crosses them.
+- Identify shared abstractions the change must conform to (factories,
+  interfaces, base classes, validators, mappers).
+- Find related tests and fixtures — understand the existing test shape before
+  proposing new tests.
+- Check `docs/architecture.md`, `docs/conventions.md`, and any
+  `docs/decisions.md` entries for constraints the plan must respect.
+  If those files do not exist, fall back to `CLAUDE.md` / `AGENTS.md`
+  and the top-level `README.md`.
+- Run `git log --oneline -- <path>` on key files to see recent changes that
+  suggest active areas / patterns.
+
+Time-box this: deep does not mean exhaustive. Stop when you can describe the
+shape of the change confidently, not when you've read everything.
+
+### 3. Draft the plan structure (in chat, not yet written)
+
+Present the plan to the user in chat first, using this shape:
+
+```markdown
+# Plan preview — {KEY}: {short summary}
+
+## Goal
+<1–2 sentences in plain English. Tied to the spec's Acceptance Criteria.>
+
+## Approach
+<3–6 sentences describing the chosen direction. Why this shape rather than
+alternatives. Reference architecture/conventions docs where they constrain
+the choice.>
+
+## Affected areas
+
+### <Module or layer 1, e.g. "api/ — HTTP layer">
+- `path/to/file` — what role this file plays in the change
+- `path/to/other` — likewise
+
+### <Module or layer 2>
+- ...
+
+(Group by module/layer, not by file. List files that will change or that the
+change must conform to. Do NOT cite line numbers or specific methods unless
+the user digs in.)
+
+## Sequencing
+1. <First phase — what gets done, in what order, why this order>
+2. <Second phase>
+3. <Third phase>
+
+(Each phase should be independently committable / reviewable where possible.)
+
+## Test strategy
+- <Which existing test classes will be extended; which new tests are needed,
+  by surface (integration / unit / fixture-based). No specific test method
+  names yet.>
+
+## Risks & open questions
+- <Anything that could derail the plan. Performance, data migration,
+  backwards compatibility, etc.>
+- <Anything the spec leaves ambiguous that the user should decide before
+  implementation.>
+
+## Out of scope
+- <Explicit non-goals — things that look related but won't be addressed in
+  this plan.>
+```
+
+### 4. Discuss with the user
+
+After presenting the plan, ask the user:
+
+> *"Does this plan capture the right approach? Reply with `approve` to write
+> the plan to a file, or tell me what to change."*
+
+Iterate:
+
+- If the user asks "why did you choose X over Y?" — explain, and if the
+  answer changes the plan, update it.
+- If the user asks for more detail on a specific area (e.g. "go deeper on
+  how validation will work") — investigate further and add that detail to
+  the plan. **Detail captured during discussion is the exception that
+  earns its way in.** Without an explicit ask, keep the plan high-level.
+- If the user disagrees with the approach — revise. Do not write a plan
+  the user hasn't endorsed.
+- Track decisions made during the discussion in a running "Decisions"
+  section that gets included on write.
+
+### 5. Write the plan on approval, then stop
+
+Trigger: user replies `approve` (or equivalent: "ok write it", "looks good,
+save it", etc.).
+
+- **Output path:** derive from the spec path by replacing the `-spec` suffix
+  with `-plan`.
+  - `S4R-10559_ai-adoption-runbook-spec.md` → `S4R-10559_ai-adoption-runbook-plan.md`
+  - Both files live in `.claude/artifacts/`.
+- **If the plan file already exists,** ask before overwriting.
+- Write the plan using the same structure as the in-chat preview, plus:
+  - A header block with the spec file, ticket key, and the date the plan
+    was approved.
+  - A "Decisions during planning" section capturing anything the user
+    clarified, chose, or ruled out during the discussion.
+- After writing, report the absolute path of the saved file and a
+  one-line summary of what was written. **Then stop.**
+
+### What "stop" means after approval
+
+Approval authorizes **writing the plan file — nothing else.** After the
+file is written, this skill is done. Do **not**:
+
+- Start implementation, even partially or "to show what it would look like".
+- Edit any source file, test, config, build file, migration, CI workflow,
+  or any other doc.
+- Create a branch, stage changes, or run a build / test / lint.
+- Ask "want me to start implementing now?", "should I create the first
+  commit?", or similar follow-up prompts.
+- Suggest next actions beyond a single closing line pointing at the file
+  ("Plan saved at `<path>` — open a fresh session to implement.").
+
+Implementation happens in a separate session that reads the saved plan.
+
+## Content rules
+
+- **High-level by default.** No line numbers. No code snippets. No
+  literal method bodies. No specific SQL. No exact JSON shapes.
+- **Affected files are allowed.** Pointing at `path/to/Service` is fine;
+  saying "change line 142 to call `foo()`" is not.
+- **Deeper detail enters only via discussion.** If the user asks
+  "what specifically changes in CategoryValidationTree?", you may add a
+  short paragraph describing the conceptual change. Still no line-level
+  prescriptions.
+- **No invented requirements.** The plan must trace to the spec. If the
+  spec is silent on something the plan needs, surface it as an open
+  question, not a silent decision.
+- **Verify every file path cited in "Affected areas".** Before presenting
+  the plan, confirm each listed path actually exists in the repo. If a
+  file is expected to be created by this work, mark it `(new)`. If a path
+  was a guess that turned out wrong, fix or remove it. Hallucinated paths
+  waste implementation time.
+- **Acceptance Criteria from the spec must be addressable.** Each AC
+  should map to something in "Affected areas" or "Test strategy".
+- **No implementation, ever.** Approval means "save the plan", not "start
+  coding". The skill ends after the file is written.
+
+## Hard rules
+
+- **Do not write the plan file until the user approves.** Discussion
+  happens in chat; the file is the artifact of agreement.
+- **Do not modify the spec file.** Specs are append-only audit records.
+- **Do not write to `~/.claude/`.** Plans live in the repo's
+  `.claude/artifacts/` only.
+- **One plan file per spec.** Do not append to a different spec's plan.
+
+## Common mistakes
+
+- Starting the deep scan before reading the spec end-to-end.
+- Writing the plan to disk before the user has approved it.
+- Treating approval as a green light to start coding. Approval saves the
+  plan; the skill stops there.
+- Offering to "kick off implementation" after writing the file.
+- Including code snippets or line numbers to look thorough — this makes
+  the plan rot fast and discourages the implementer from thinking.
+- Skipping the "Out of scope" section. Explicit non-goals prevent scope
+  creep during implementation.
+- Treating the spec's AI-gathered Implementation Notes as authoritative.
+  They are guesses from a shallower scan; verify before relying on them.
+- Producing a plan that doesn't trace back to Acceptance Criteria.