@groupby/ai-dev 0.5.1 → 0.5.4

package/teams/snpd/skills/council-review/scripts/summarize_review_config.py

@@ -0,0 +1,226 @@
+#!/usr/bin/env python3
+"""Summarize PR review and CI configuration for a repository.
+
+Repo-agnostic: takes the repository root as its argument (defaults to the current
+directory) and works on any project. Uses only the Python standard library so it
+can run in sandboxes without installing PyYAML or other dependencies.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+from pathlib import Path
+
+
+GUIDANCE_FILES = [
+    ".github/copilot-instructions.md",
+    "CLAUDE.md",
+    "AGENTS.md",
+    "README.md",
+    "docs/conventions.md",
+    "docs/project-rule.md",
+    "docs/source-control.md",
+]
+
+REVIEW_FILES = [
+    ".github/workflows/claude-pr-review.yml",
+    ".github/workflows/claude.yml",
+    ".github/workflows/build-pr.yaml",
+    ".github/PULL_REQUEST_TEMPLATE.md",
+    ".github/CODEOWNERS",
+]
+
+BUILD_FILES = [
+    "build.gradle",
+    "build.gradle.kts",
+    "settings.gradle",
+    "gradle.properties",
+    "pom.xml",
+    "go.mod",
+    "Makefile",
+    "pyproject.toml",
+    "requirements.txt",
+    "package.json",
+]
+
+KEYWORDS = [
+    "Micronaut",
+    "Java 21",
+    "Java 17",
+    "Spring",
+    "Lombok",
+    "Spock",
+    "JUnit",
+    "Mockito",
+    "Testcontainers",
+    "JOOQ",
+    "jOOQ",
+    "Flyway",
+    "PostgreSQL",
+    "Mongo",
+    "Redis",
+    "Google Retail",
+    "Command Center",
+    "Pub/Sub",
+    "BigQuery",
+    "LaunchDarkly",
+    "ANTLR",
+    "Kafka",
+    "JWT",
+    "Docker",
+    "Jib",
+]
+
+
+def read(path: Path) -> str:
+    try:
+        return path.read_text(errors="replace")
+    except FileNotFoundError:
+        return ""
+
+
+def existing(root: Path, paths: list[str]) -> list[Path]:
+    return [root / path for path in paths if (root / path).exists()]
+
+
+def first_match(pattern: str, text: str) -> str | None:
+    match = re.search(pattern, text, re.MULTILINE)
+    return match.group(1).strip() if match else None
+
+
+def command_lines(text: str) -> list[str]:
+    commands: list[str] = []
+    for line in text.splitlines():
+        stripped = line.strip()
+        candidate = stripped
+        if stripped.startswith("run:"):
+            candidate = stripped.removeprefix("run:").strip()
+        if re.match(r"^(\.?/gradlew|gradle|mvn|make|go\s+test|pytest|npm|pnpm|yarn|docker)\b", candidate):
+            commands.append(candidate)
+    return commands
+
+
+def pr_checkboxes(text: str) -> list[str]:
+    checks = []
+    for line in text.splitlines():
+        if re.match(r"\s*-\s+\[[ xX]\]", line):
+            checks.append(line.strip())
+    return checks
+
+
+def collect_keywords(text: str) -> list[str]:
+    found = []
+    lower_text = text.lower()
+    for keyword in KEYWORDS:
+        if keyword.lower() in lower_text:
+            found.append(keyword)
+    normalized = []
+    seen = set()
+    for keyword in found:
+        key = keyword.lower()
+        if key not in seen:
+            seen.add(key)
+            normalized.append(keyword)
+    return sorted(normalized, key=str.lower)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("repo", nargs="?", default=".", help="Repository root")
+    args = parser.parse_args()
+
+    root = Path(args.repo).resolve()
+    print(f"# PR Review Configuration Summary\n")
+    print(f"Repository: `{root}`\n")
+
+    review_files = existing(root, REVIEW_FILES)
+    guidance_files = existing(root, GUIDANCE_FILES)
+    build_files = existing(root, BUILD_FILES)
+
+    print("## Files Found\n")
+    for title, files in [
+        ("Review/CI", review_files),
+        ("Guidance", guidance_files),
+        ("Build", build_files),
+    ]:
+        print(f"### {title}")
+        if files:
+            for path in files:
+                print(f"- `{path.relative_to(root)}`")
+        else:
+            print("- none")
+        print()
+
+    claude_text = read(root / ".github/workflows/claude-pr-review.yml")
+    if not claude_text:
+        claude_text = read(root / ".github/workflows/claude.yml")
+    build_text = read(root / ".github/workflows/build-pr.yaml")
+    pr_template = read(root / ".github/PULL_REQUEST_TEMPLATE.md")
+    codeowners = read(root / ".github/CODEOWNERS")
+    guidance_text = "\n\n".join(read(path) for path in guidance_files)
+    build_texts = "\n\n".join(read(path) for path in build_files)
+
+    print("## Claude Review\n")
+    if claude_text:
+        triggers = re.findall(r"types:\s*\[([^\]]+)\]", claude_text)
+        model = first_match(r"--model\s+([^\s]+)", claude_text)
+        print(f"- Workflow present: yes")
+        print(f"- Trigger type lists: {', '.join(triggers) if triggers else 'not parsed'}")
+        print(f"- Model: {model or 'not parsed'}")
+        print("- Standard focus areas present:")
+        for area in ["Code Quality", "Security", "Performance", "Testing", "Documentation"]:
+            print(f"  - {area}: {'yes' if area in claude_text else 'not found'}")
+    else:
+        print("- Workflow present: no")
+    print()
+
+    print("## PR CI Commands\n")
+    commands = command_lines(build_text)
+    if commands:
+        for command in commands:
+            print(f"- `{command}`")
+    else:
+        print("- none parsed")
+    print()
+
+    java_version = first_match(r"java-version:\s*['\"]?([^'\"\n]+)", build_text)
+    if java_version:
+        print(f"Java version from PR workflow: `{java_version}`\n")
+
+    print("## PR Template Checks\n")
+    checks = pr_checkboxes(pr_template)
+    if checks:
+        for check in checks:
+            print(f"- {check}")
+    else:
+        print("- none")
+    print()
+
+    print("## CODEOWNERS\n")
+    owners = [line.strip() for line in codeowners.splitlines() if line.strip() and not line.strip().startswith("#")]
+    if owners:
+        for owner in owners:
+            print(f"- `{owner}`")
+    else:
+        print("- none")
+    print()
+
+    print("## Detected Keywords\n")
+    keywords = collect_keywords("\n\n".join([guidance_text, build_texts, claude_text, build_text]))
+    if keywords:
+        for keyword in keywords:
+            print(f"- {keyword}")
+    else:
+        print("- none")
+    print()
+
+    print("## Suggested Next Steps\n")
+    print("- Review changed files against the discovered keywords and guidance files.")
+    print("- Run targeted tests first, then the PR build command if feasible.")
+    print("- Run `git diff --check` before final output.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -1,6 +1,6 @@
 ---
 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".
+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. Generates the canonical `/docs` structure and verifies every claim against source files before including it. 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
@@ -37,6 +37,11 @@ Preserve this block on every edit.
 - 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
@@ -44,19 +49,28 @@ Preserve this block on every edit.
 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.
+  `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/`).
-- **Domain types:** entity/model/record classes; group by package.
+- **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 / 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.
+- **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.
@@ -68,6 +82,32 @@ Draft the seven files in memory using the canonical templates below. Every
 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
@@ -143,6 +183,15 @@ renamed.
 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
@@ -176,6 +225,16 @@ This makes it obvious that the check ran.
   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.**
@@ -341,3 +400,4 @@ Requires <prereqs>. For detail see [docs/local-setup.md](docs/local-setup.md).
 - [Operations](docs/operations.md) — deploy, secrets, observability, runbooks
 - [Decisions](docs/decisions.md) — why things are the way they are
 ```
+