@groupby/ai-dev 0.5.8 → 0.5.10

package/teams/agentic-checkout/skills/karpathy-guidelines/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: karpathy-guidelines
+description: Behavioral guidelines to reduce common LLM coding mistakes. Use when writing, reviewing, or refactoring code to avoid overcomplication, make surgical changes, surface assumptions, and define verifiable success criteria.
+license: MIT
+---
+
+# Karpathy Guidelines
+
+Behavioral guidelines to reduce common LLM coding mistakes, derived from [Andrej Karpathy's observations](https://x.com/karpathy/status/2015883857489522876) on LLM coding pitfalls.
+
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

package/teams/agentic-checkout/skills/secret-safety/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: secret-safety
+description: Prevent credentials and sensitive tokens from being committed, logged, or pushed. Use before commits, pushes, PRs, and when editing config or examples.
+license: MIT
+---
+
+# Secret Safety
+
+Use this skill before committing, pushing, creating PRs, or editing configuration, examples, logs, credentials, or local
+environment files.
+
+## Rules
+
+- Never commit real credentials, API keys, private keys, tokens, session cookies, certificates, keystores, or populated `.env` files.
+- Keep secrets in environment variables, local untracked files, Vault, Azure Key Vault, GitHub Actions secrets, or another approved secret store.
+- Only commit placeholder examples such as `.env.example`, `.env.sample`, or documentation values that are clearly non-secret.
+- Do not paste secrets into prompts, PR descriptions, logs, commit messages, plans, or generated documentation.
+- If a secret appears in a tracked file, stop and remove it before committing or pushing.
+- If a real secret was committed or pushed, treat it as compromised: rotate/revoke it and remove it from git history using an approved process.
+
+## Checks
+
+Run the harness secret scanner before commit or push:
+
+```bash
+scripts/check-secrets .
+```
+
+When checking a component repository from the harness root, pass the component path:
+
+```bash
+scripts/check-secrets components/<component>
+```
+
+Install the harness pre-push hook for the harness checkout:
+
+```bash
+scripts/install-git-hooks
+```
+
+The scanner is a guardrail, not a guarantee. Also inspect diffs manually for sensitive values.

package/teams/agentic-checkout/skills/sync-components/SKILL.md

@@ -1,76 +1,39 @@
 ---
 name: sync-components
-description: Sync a multi-repository component workspace by cloning repositories listed in components.txt with minimal inspection. Use when asked to sync up, clone, or refresh project components.
+description: Sync component repositories from components.txt using the deterministic harness script.
 license: MIT
 ---
 
 # Sync Components
 
-Use this skill when the user asks to sync up a project's component repositories.
-
-## Goal
-
-Populate `components/` from the entries in `components.txt` using `git clone`, and leave each synced component on the `main` branch.
-
-Keep this workflow lightweight. Do not inspect component source trees, run builds, run tests, scan every repository, or perform broad Git status checks unless the user explicitly asks.
-
-Do not create a shell script, temporary script, generated helper, Makefile target, or wrapper command for this workflow. Running generated scripts often triggers extra approval prompts. Use direct shell commands only.
-
-## Source Of Truth
-
-Read `components.txt` from the framework or workspace checkout.
-
-Each non-empty, non-comment line is either:
-
-- A full Git remote URL, used as-is.
-- A repository name. If the file uses bare repository names, infer the Git remote from the project instructions or ask the user for the organization/remote prefix before cloning.
-
-The local checkout path for each entry is:
-
-```text
-components/<repo-name>
-```
-
-Derive `<repo-name>` from the entry basename and remove a trailing `.git`.
+Use when the user asks to sync, clone, refresh, or update component repositories.
 
 ## Workflow
 
-1. Confirm the current directory is the framework checkout.
-2. Create `components/` if it does not exist.
-3. Read `components.txt`.
-4. For each component entry:
-   - If `components/<repo-name>` does not exist, run:
-
-     ```bash
-     git clone <remote> components/<repo-name>
-     ```
-
-   - If the directory already exists, keep it and report `exists`.
-   - After clone or exists, run:
-
-     ```bash
-     git -C components/<repo-name> checkout main
-     ```
+1. Ask for the user's command approval through the normal Copilot CLI approval flow; do not enable `/allow-all`.
+2. Run exactly one of these commands after approval:
 
-   - If `main` is not available locally, fetch only the main branch and try again:
+   ```bash
+   scripts/sync-components
+   ```
 
-     ```bash
-     git -C components/<repo-name> fetch origin main
-     git -C components/<repo-name> checkout main
-     ```
+   or, when a local fast model summary is useful:
 
-5. Report only cloned, existing, checked-out-main, skipped, and failed component names.
+   ```bash
+   scripts/local-fast-report sync
+   ```
 
-Prefer issuing the `git clone` commands directly from the terminal. It is acceptable to run them one at a time. Do not generate a loop script or ask the user to run a script.
+3. Label `scripts/local-fast-report sync` runs as using the local fast model in any shell command title/description.
+4. Do not run both commands; `scripts/local-fast-report sync` already runs `scripts/sync-components`.
+5. Report cloned, existing, checked-out-main, rebased-main, skipped-dirty, and failed components.
+6. If any component is `skipped-dirty`, stop and ask before destructive cleanup or retry.
 
-## Constraints
+## Rules
 
-- Use direct `git clone` commands for this workflow.
-- Do not create, modify, chmod, or execute any sync script.
-- Do not use heredocs, shell redirection, or generated files to automate cloning.
-- Do not delete, reset, clean, or force checkout any component repository.
-- Do not pull existing repositories unless the user asks to update already-cloned components.
-- Do not fetch existing repositories except `git fetch origin main` when needed to make `main` available for checkout.
-- Do not open or validate component-local instruction files during this sync workflow.
-- Do not run dependency installation, tests, formatters, linters, or builds.
-- Keep all cloned repositories directly under `components/`.
+- Do not reimplement sync with model-driven `git clone`/`fetch`/`checkout`/`rebase` sequences unless the script fails and
+  the user approves manual recovery.
+- Do not bypass the user's normal command approval prompts.
+- Never delete, reset, clean, force-checkout, or discard existing component work without explicit approval for that
+  component.
+- Do not inspect component source, install dependencies, run tests/builds/formatters/linters, or read component-local
+  instructions during sync.

package/teams/agentic-checkout/skills/tdd/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: tdd
+description: Use a test-driven workflow for implementation tasks. Write or update a failing test first, implement the smallest change to pass, then verify and refactor.
+license: MIT
+---
+
+# TDD
+
+Use this skill when the user asks for TDD, test-first development, bug fixes with regression tests, or implementation
+where behavior should be proven by tests.
+
+## Workflow
+
+1. Identify the smallest observable behavior change.
+2. Find the closest existing test file, fixture style, and assertion pattern.
+3. Write or update a focused test before changing production code.
+4. Run the narrowest relevant test command and confirm the test fails for the expected reason.
+5. Implement the smallest production change needed to pass.
+6. Re-run the focused test.
+7. Run the nearest broader relevant test set when the change touches shared behavior, contracts, event payloads, or
+   public APIs.
+8. Refactor only after tests pass, then re-run the focused test.
+
+## Component Commands
+
+Prefer component-local instructions when present. Otherwise use the verification matrix in `AGENTS.md` as the canonical source for install/test/build/lint commands.
+
+For focused tests, use the component's existing test runner syntax for a single file, module, class, or test case.
+
+## Constraints
+
+- Do not make broad refactors before the red/green loop is complete.
+- Do not add new test frameworks or dependencies unless the component already uses them and the change requires it.
+- Do not add large test scaffolding when an existing test style can cover the behavior.
+- Do not skip the failing-test step unless tests cannot run locally or the change is documentation/configuration only.
+- If the failing-test step is skipped, explain why before editing production code.
+- Keep tests focused on observable behavior, not private implementation details.
+- For bug fixes, the first test should fail on the original bug.
+- For new behavior, the first test should encode the expected contract or user-visible behavior.
+
+## Reporting
+
+In the final response, include:
+
+- The test added or changed.
+- The initial failing command and failure summary, if run.
+- The passing verification command.
+- Any broader tests that were skipped and why.

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())