@groupby/ai-dev 0.5.9 → 0.5.10

package/package.json

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

package/teams/rangers/resources/project-doc-contract.md

@@ -0,0 +1,41 @@
+# Rangers Project Documentation Contract
+
+Rangers skills expect project-specific truth to live in each project repo, not in shared skills.
+
+## Preferred Entrypoints
+
+- `docs/ai/index.md` - primary AI context routing table
+- `docs/ai/working-agreement.md` - non-negotiable team and workflow rules
+- `docs/project/ai-context.md` - project-specific routing, priorities, and domain language
+- `.github/copilot-instructions.md` - compatibility shim for GitHub Copilot
+
+## Common Supporting Docs
+
+- `docs/project/architecture.md`
+- `docs/project/decision-log.md`
+- `docs/project/phase-plan.md`
+- `docs/ai/workflow.md`
+- `docs/ai/code-review-checklist.md`
+- `docs/ai/component-patterns.md`
+- `docs/ai/styling.md`
+- `docs/ai/state-management.md`
+- API or contract docs under `docs/project/` or `docs/ai/`
+
+## Operating Rules
+
+- Load the router first, then follow its task-specific map.
+- Load the smallest useful context set.
+- Treat project docs as the intended target state unless the user says otherwise.
+- Keep review artifacts, snapshots, and scratch planning notes in gitignored project scratch space such as `tmp/`.
+- Update project docs when implementation changes durable architecture, workflow, API contracts, or conventions.
+
+## Skill-First Scaffolding Expectations
+
+Generated project scaffolding should install Rangers skills alongside the project docs, then expose them to the LLM clients the team actually uses.
+
+- Copy full skills to `docs/ai/skills/<skill-name>/`.
+- Create lightweight skill stubs in `.github/skills/<skill-name>/SKILL.md` for Copilot when `.github/` is present.
+- Create lightweight skill stubs in `.claude/skills/<skill-name>/SKILL.md` for Claude Code when `.claude/` is present.
+- Preserve each skill's `name` and `description` frontmatter in client stubs so plain-text requests such as "run a code review" can trigger the right skill.
+- Keep `docs/ai/index.md` as the project routing table, but have it route task types to skills first and local docs second.
+- Do not require Codex-specific metadata such as `agents/openai.yaml` unless a project explicitly supports Codex users.

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

@@ -0,0 +1,66 @@
+---
+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.
+---
+
+# Team Code Review
+
+## Purpose
+
+Use this skill for read-first review work. The project docs define the review standard; the changed files define the review surface.
+
+## Review Setup
+
+1. Determine the diff under review:
+   - prefer `git diff origin/main...HEAD` for branch review
+   - fall back to `git diff HEAD` for unstaged or local-only changes
+   - use a user-specified base if provided
+2. Load the project router:
+   - `docs/ai/index.md`
+   - `.github/copilot-instructions.md`
+   - `docs/project/ai-context.md`
+   - `docs/ai/resources/project-doc-contract.md`, if no project router exists
+3. Load review-specific docs:
+   - working agreement
+   - workflow
+   - code review checklist
+   - architecture or task-specific docs named by the router
+4. Inspect changed files and nearby code before writing findings.
+
+## Review Standards
+
+Prioritize defects and regressions over style. Check:
+
+- 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
+
+If the code contradicts project docs, treat that as a finding unless the change deliberately updates the documented target state.
+
+## Output
+
+Lead with findings ordered by severity. Include tight file and line references when possible.
+
+Use this shape:
+
+```markdown
+## Findings
+- [P1/P2/P3] file:line - Issue and impact.
+
+## Open Questions
+- [Question]
+
+## Summary
+[Brief assessment]
+
+## 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`.

package/teams/rangers/skills/team-development/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: team-development
+description: >-
+  Guide normal implementation work by loading a project's AI router, working agreement, architecture docs, and task-specific docs before editing. Use for feature work, bug fixes, refactors, UI changes, API integration, and documentation updates in repos that expose project-owned AI context.
+---
+
+# Team Development
+
+## Purpose
+
+Use this skill as the default implementation workflow for Rangers projects. It keeps shared process in the skill and project truth in the project docs.
+
+## Context Loading
+
+1. Read the project router first:
+   - prefer `docs/ai/index.md`
+   - also check `.github/copilot-instructions.md`
+   - use `docs/project/ai-context.md` for project-specific priorities
+   - use `docs/ai/resources/project-doc-contract.md` as a fallback contract if no project router exists
+2. Always load the working agreement if present.
+3. Load only task-relevant docs from the router. Common routes:
+   - UI/components: component patterns, styling, frontend scope
+   - API/data/state: API contract, state management, architecture
+   - architecture decisions: architecture docs and decision log
+   - phase work: workflow, phase plan, review checklist
+4. If the task requires comparing or migrating many docs, use `team-docs-snapshot`.
+
+## Implementation Flow
+
+1. Check git status and current branch.
+2. Inspect the relevant files before editing.
+3. Make a short working plan when the change spans multiple files or behaviors.
+4. Edit narrowly and follow established local patterns.
+5. Update project docs when the implementation changes architecture, workflow, API contracts, or durable conventions.
+6. Run the smallest meaningful validation for the changed surface.
+7. Summarize changed files, validation, and any remaining risks.
+
+## Rules
+
+- Let project docs define the target state. If code and docs disagree, flag the mismatch or update docs as part of the work.
+- Do not load every doc by default.
+- Do not turn project-specific facts into shared skill instructions.
+- Keep scratch notes and reviews in the location the project workflow specifies, commonly `tmp/`.

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.