@groupby/ai-dev 0.5.9 → 0.5.11

package/teams/rangers/skills/team-docs-snapshot/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: team-docs-snapshot
+description: >-
+  Collect AI/project documentation from a repository into a temporary review folder. Use when documentation needs to be pulled together for orientation, planning, review, migration, or skill-authoring analysis without loading every source file into the active context.
+---
+
+# Team Docs Snapshot
+
+## Purpose
+
+Use this skill to gather a project's AI-facing documentation into a disposable snapshot. Prefer it when the task is about understanding or migrating docs, comparing routing systems, reviewing documentation drift, or preparing a compact handoff for another session.
+
+## Workflow
+
+1. Identify the target repository root.
+2. Check for a project routing contract before collecting files:
+   - `docs/ai/index.md`
+   - `docs/project/ai-context.md`
+   - `.github/copilot-instructions.md`
+   - `AGENTS.md`
+3. Run the bundled collector from the project root or pass `--root` explicitly:
+
+   ```sh
+   python3 docs/ai/skills/team-docs-snapshot/scripts/collect_project_docs.py --root .
+   ```
+
+   If the skill is being used from the shared repo source instead of an installed project copy, run the script from this skill folder:
+
+   ```sh
+   python3 teams/rangers/skills/team-docs-snapshot/scripts/collect_project_docs.py --root /path/to/project
+   ```
+
+4. Read the generated `MANIFEST.md` first. Use it to decide which copied docs to load next.
+5. Treat the snapshot as scratch material. Do not commit it unless the user explicitly asks.
+
+## Collector Options
+
+- `--out <dir>` writes to a specific snapshot directory.
+- `--include <glob>` adds extra files. Repeat it for multiple patterns.
+- `--exclude <glob>` removes files from the default or included matches.
+- `--combined` also writes `COMBINED.md` for tools that need one linear document.
+
+Default collection includes common project guidance docs:
+
+- `docs/ai/**/*.md`
+- `docs/project/**/*.md`
+- `.github/copilot-instructions.md`
+- `AGENTS.md`
+- `README.md`
+
+## Output Expectations
+
+When reporting back, include only:
+
+- snapshot directory
+- number of files collected
+- notable missing entrypoints
+- recommended docs to read next

package/teams/rangers/skills/team-docs-snapshot/scripts/collect_project_docs.py

@@ -0,0 +1,166 @@
+#!/usr/bin/env python3
+"""Collect project AI/documentation files into a temporary snapshot directory."""
+
+from __future__ import annotations
+
+import argparse
+import fnmatch
+import shutil
+from datetime import datetime
+from pathlib import Path
+
+
+DEFAULT_PATTERNS = [
+    "docs/ai/**/*.md",
+    "docs/project/**/*.md",
+    ".github/copilot-instructions.md",
+    "AGENTS.md",
+    "README.md",
+]
+
+DEFAULT_EXCLUDES = [
+    ".git/**",
+    "node_modules/**",
+    "tmp/**",
+    "dist/**",
+    "build/**",
+]
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Copy project AI-facing docs into a temporary review snapshot.",
+    )
+    parser.add_argument(
+        "--root",
+        default=".",
+        help="Project root to scan. Defaults to the current directory.",
+    )
+    parser.add_argument(
+        "--out",
+        help="Snapshot output directory. Defaults to <root>/tmp/ai-docs-snapshot-<timestamp>.",
+    )
+    parser.add_argument(
+        "--include",
+        action="append",
+        default=[],
+        help="Additional glob to include. Can be repeated.",
+    )
+    parser.add_argument(
+        "--exclude",
+        action="append",
+        default=[],
+        help="Glob to exclude from copied results. Can be repeated.",
+    )
+    parser.add_argument(
+        "--combined",
+        action="store_true",
+        help="Also write COMBINED.md with all copied docs in one file.",
+    )
+    return parser.parse_args()
+
+
+def is_excluded(relative_path: str, patterns: list[str]) -> bool:
+    return any(fnmatch.fnmatch(relative_path, pattern) for pattern in patterns)
+
+
+def collect_matches(root: Path, includes: list[str], excludes: list[str]) -> list[Path]:
+    matches: set[Path] = set()
+    for pattern in includes:
+        for match in root.glob(pattern):
+            if match.is_file():
+                matches.add(match.resolve())
+
+    root_resolved = root.resolve()
+    filtered: list[Path] = []
+    for match in matches:
+        try:
+            relative = match.relative_to(root_resolved).as_posix()
+        except ValueError:
+            continue
+        if not is_excluded(relative, excludes):
+            filtered.append(match)
+
+    return sorted(filtered, key=lambda path: path.relative_to(root_resolved).as_posix())
+
+
+def write_manifest(root: Path, out_dir: Path, files: list[Path], missing: list[str]) -> None:
+    lines = [
+        "# Project Docs Snapshot",
+        "",
+        f"Source root: `{root}`",
+        f"Generated: `{datetime.now().isoformat(timespec='seconds')}`",
+        f"Files collected: {len(files)}",
+        "",
+        "## Files",
+        "",
+    ]
+    for file_path in files:
+        relative = file_path.relative_to(root).as_posix()
+        lines.append(f"- `{relative}`")
+
+    if missing:
+        lines.extend(["", "## Missing Common Entrypoints", ""])
+        for pattern in missing:
+            lines.append(f"- `{pattern}`")
+
+    out_dir.joinpath("MANIFEST.md").write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+def write_combined(root: Path, out_dir: Path, files: list[Path]) -> None:
+    sections: list[str] = ["# Combined Project Docs", ""]
+    for file_path in files:
+        relative = file_path.relative_to(root).as_posix()
+        sections.extend([f"## {relative}", ""])
+        try:
+            sections.append(file_path.read_text(encoding="utf-8"))
+        except UnicodeDecodeError:
+            sections.append("[Skipped: file is not UTF-8 text]")
+        sections.append("")
+    out_dir.joinpath("COMBINED.md").write_text("\n".join(sections), encoding="utf-8")
+
+
+def main() -> int:
+    args = parse_args()
+    root = Path(args.root).expanduser().resolve()
+    if not root.is_dir():
+        raise SystemExit(f"Project root does not exist or is not a directory: {root}")
+
+    timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+    out_dir = (
+        Path(args.out).expanduser().resolve()
+        if args.out
+        else root / "tmp" / f"ai-docs-snapshot-{timestamp}"
+    )
+    out_dir.mkdir(parents=True, exist_ok=False)
+
+    includes = DEFAULT_PATTERNS + args.include
+    excludes = DEFAULT_EXCLUDES + args.exclude
+    files = collect_matches(root, includes, excludes)
+
+    missing = []
+    for pattern in DEFAULT_PATTERNS:
+        if not any(root.glob(pattern)):
+            missing.append(pattern)
+
+    for file_path in files:
+        relative = file_path.relative_to(root)
+        destination = out_dir / relative
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(file_path, destination)
+
+    write_manifest(root, out_dir, files, missing)
+    if args.combined:
+        write_combined(root, out_dir, files)
+
+    print(f"Snapshot: {out_dir}")
+    print(f"Files collected: {len(files)}")
+    if missing:
+        print("Missing common entrypoints:")
+        for pattern in missing:
+            print(f"- {pattern}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/teams/rangers/skills/team-phase-planning/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: team-phase-planning
+description: >-
+  Break project work into reviewable phases using the repo's routing docs, workflow, phase plan, architecture, and decision log. Use when planning a feature slice, sequencing Jira tickets, defining review gates, or turning broad work into implementable phases.
+---
+
+# Team Phase Planning
+
+## Purpose
+
+Use this skill to convert broad work into small phases that can be implemented, validated, and reviewed independently.
+
+## Context Loading
+
+1. Read the project router:
+   - `docs/ai/index.md`
+   - `docs/project/ai-context.md`
+   - `.github/copilot-instructions.md`, if present
+   - `docs/ai/resources/project-doc-contract.md`, if no project router exists
+2. Read the working agreement and workflow docs.
+3. Load task-specific planning docs:
+   - phase plan
+   - decision log
+   - architecture docs
+   - API or frontend scope docs when the work touches those surfaces
+4. For large or unfamiliar doc sets, use `team-docs-snapshot` and read its manifest first.
+
+## Planning Flow
+
+1. State the goal and non-goals.
+2. Identify dependencies, unknowns, and project constraints.
+3. Split the work into phases that each have:
+   - user-visible or reviewable scope
+   - files or areas likely to change
+   - validation plan
+   - review gate
+   - docs that may need updates
+4. Put risky discovery early.
+5. Keep phases small enough that a reviewer can understand the diff without reconstructing the entire project.
+
+## Output Format
+
+Use this shape unless the user asks otherwise:
+
+```markdown
+# Plan: [Work Name]
+
+## Goal
+[One paragraph]
+
+## Assumptions
+- [Assumption]
+
+## Phases
+### Phase 1: [Name]
+Scope:
+Validation:
+Review gate:
+Docs impact:
+
+## Open Questions
+- [Question]
+```

package/teams/rangers/skills/team-project-orientation/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: team-project-orientation
+description: >-
+  Orient to an unfamiliar repository through its AI routing docs, project docs, README, architecture notes, and working agreement. Use when entering a repo, moving a task into a new chat, preparing implementation, or auditing whether the project exposes enough context for AI-assisted work.
+---
+
+# Team Project Orientation
+
+## Purpose
+
+Use this skill to build a small, accurate mental model of a project without reading the whole repo. The goal is to find the project's own context router, then load the smallest useful set of docs.
+
+## Orientation Flow
+
+1. Inspect the repo shape:
+   - `README.md`
+   - `AGENTS.md`
+   - package or workspace manifests
+   - top-level app, package, and docs folders
+2. Locate the AI/project routing entrypoints, in this order:
+   - `docs/ai/index.md`
+   - `.github/copilot-instructions.md`
+   - `docs/project/ai-context.md`
+   - `docs/ai/working-agreement.md`
+   - `docs/ai/resources/project-doc-contract.md`, if this team resource is installed
+3. If a routing table exists, follow it. Always prefer its task-specific guidance over generic assumptions.
+4. If no router exists, infer a temporary route from common docs:
+   - architecture: `docs/**/architecture*.md`
+   - product/context: `docs/**/product*.md`, `docs/**/overview*.md`
+   - decisions: `docs/**/decision*.md`, `docs/**/adr*.md`
+   - workflow: `docs/**/workflow*.md`, `docs/**/phase*.md`
+   - contracts: `docs/**/*contract*.md`, `docs/**/*api*.md`
+5. For broad documentation analysis, use `team-docs-snapshot` before loading many files.
+
+## Orientation Notes
+
+Keep the output concise and project-owned:
+
+- purpose and product/domain
+- main apps/packages and how they fit together
+- tech stack and validation commands, when documented
+- AI routing map and any missing entrypoints
+- implementation rules that look non-negotiable
+- risks or ambiguities to resolve before coding
+
+Do not copy project knowledge into a reusable skill. Project facts belong in that repo's docs.