@caddis/cli 0.0.0 → 0.1.0

package/bundles/antigravity-plugin/skills/codebase-audit/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: codebase-audit
+context: fork
+description: Systematic codebase audit methodology for unfamiliar codebases before architecture or implementation work. Use for new codebase, unfamiliar codebase, pre-implementation audit, codebase review, technical due diligence, or onboarding to an existing project. Produces AUDIT-FINDINGS.md and QUESTIONS.md. Routes to Architect, Planner, or Code Reviewer agents.
+---
+
+# Codebase Audit Skill
+
+Systematic 6-step audit for entering an unfamiliar codebase before architecture changes, major features, or refactoring. Do not guess patterns — audit first.
+
+## 1. When to Apply This Skill
+
+**Trigger conditions:**
+- "I'm new to this codebase"
+- "Audit this project before we start building"
+- "I need to understand what's here before changing it"
+- "Pre-implementation review"
+- Any major feature in a codebase you haven't worked in this session
+
+**Do not skip the audit** even when the task seems small — hidden coupling causes broken assumptions.
+
+## 2. Audit Scope — 20 Areas
+
+| # | Area | What to Look For |
+|---|---|---|
+| 1 | **Architecture** | Monolith/microservice/monorepo, layer separation, module boundaries |
+| 2 | **Entry Points** | Main files, router setup, CLI entry, exports index |
+| 3 | **Framework & Runtime** | React version, Next.js, FastAPI, Django, Node version, Python version |
+| 4 | **Dependencies** | `package.json`/`pyproject.toml` — packages, versions, peer deps, outdated |
+| 5 | **Code Quality** | Lint config, formatter, TypeScript strict mode, type coverage |
+| 6 | **Testing** | Test runner, coverage %, which layers are tested, missing tests |
+| 7 | **Security Posture** | Auth implementation, env var usage, hardcoded secrets, CORS |
+| 8 | **Documentation** | README completeness, inline comments, API docs |
+| 9 | **Performance Signals** | Caching, lazy loading, database indexes, N+1 queries |
+| 10 | **DevOps / CI** | Build commands, CI config, deployment method, Dockerfile |
+| 11 | **API Design** | REST conventions, versioning, error response format, input validation |
+| 12 | **Data Layer** | ORM vs raw SQL, migration strategy, schema location |
+| 13 | **State Management** | Client state (Zustand, Redux, Context), server state (React Query) |
+| 14 | **Error Handling** | Global error boundary, unhandled promise rejections, logging |
+| 15 | **Environment Config** | `.env.example`, `pydantic-settings`, config validation on startup |
+| 16 | **Dead Code / Tech Debt** | TODOs, commented-out code, unused packages, deprecated calls |
+| 17 | **Naming Conventions** | Consistent file/folder naming, component vs module patterns |
+| 18 | **Shared Libraries** | Utility functions, hooks, services — shared vs duplicated |
+| 19 | **Accessibility** | ARIA usage, keyboard nav, color contrast, skip-nav |
+| 20 | **Observability** | Logging format, tracing, health endpoints, error reporting |
+
+## 3. 6-Step Audit Method
+
+### Step 1 — Map the Repository
+```
+actions:
+  - List top-level directories and understand intent of each
+  - Identify the project type (app, library, monorepo, microservice)
+  - Read README.md fully — note setup instructions, known issues
+  - Check for CONTRIBUTING.md, ARCHITECTURE.md, or ADR folders
+```
+
+### Step 2 — Find Entry Points
+```
+actions:
+  - Identify main application entry (main.py, app.py, src/index.ts, src/main.ts)
+  - Trace the request lifecycle from entry to response (1 complete path)
+  - Identify router/controller/handler layers
+  - Find test entry (jest.config.ts, vite.config.ts, pytest.ini/pyproject.toml)
+  - Find build entry (package.json scripts, Makefile, Dockerfile)
+```
+
+### Step 3 — Dependencies and Versions
+```
+actions:
+  - Read package.json / pyproject.toml — note major dependencies and versions
+  - Check for deprecated or significantly outdated packages
+  - Identify direct vs transitive dependency conflicts
+  - Note peer dependency version mismatches
+  - Check for security advisories (mental note or npm audit / pip-audit)
+```
+
+### Step 4 — Audit by Severity
+```
+For each area in §2, assign:
+  🔴 CRITICAL — Security vulnerability, data loss risk, broken functionality
+  🟡 WARNING  — Performance issue, tech debt, missing validation
+  🟢 NOTE     — Style inconsistency, minor improvement opportunity
+  ⚪ OK       — Meets expectations, no action needed
+```
+
+### Step 5 — Compile Questions
+```
+For every assumption or ambiguity discovered:
+  - Business context: "Why does X exist? Is it still needed?"
+  - Architecture: "Is this pattern intentional or historical?"
+  - Implementation: "Is there a newer pattern preferred for this?"
+  - Scope: "Which areas are off-limits for this change?"
+```
+
+### Step 6 — Write Deliverables
+Write two files in the project root (or `docs/` if it exists):
+- `AUDIT-FINDINGS.md`
+- `QUESTIONS.md`
+
+## 4. Output Templates
+
+### `AUDIT-FINDINGS.md`
+```markdown
+# Codebase Audit Findings
+
+**Project**: [name]
+**Audited**: [date]
+**Scope**: [what was covered]
+
+## Summary
+[2–3 sentence high-level assessment]
+
+## Critical Findings 🔴
+
+### CRIT-001: [Title]
+**File**: `path/to/file.ts` (line N)
+**Issue**: [What is wrong and why]
+**Risk**: [What can go wrong]
+**Recommendation**: [Specific fix]
+
+## Warnings 🟡
+
+### WARN-001: [Title]
+**File**: `path/to/file.py`
+**Issue**: [What needs attention]
+**Recommendation**: [Specific improvement]
+
+## Notes 🟢
+
+- [Minor observations, style, preferences]
+
+## Architecture Overview
+[Brief description of what was found — layers, patterns, notable design decisions]
+
+## Scope for Current Task
+Based on the requested change, these areas are in scope: …
+These areas should NOT be touched: …
+```
+
+### `QUESTIONS.md`
+```markdown
+# Pre-Implementation Questions
+
+**For**: [next agent or human reviewer]
+**Context**: [what we're about to build]
+
+## Blocking Questions (must answer before code changes)
+
+### Q1: [Question]
+**Context**: [why this matters]
+**Impact if wrong**: [what breaks]
+
+### Q2: [Question]
+
+## Advisory Questions (inform decisions but don't block)
+
+### Q3: [Question]
+
+## Assumptions Made
+If we proceed without answers, these assumptions apply:
+- [assumption 1]
+- [assumption 2]
+```
+
+## 5. Severity Tags
+
+| Tag | Code | Meaning |
+|---|---|---|
+| 🔴 Critical | `CRIT-NNN` | Fix before any changes proceed |
+| 🟡 Warning | `WARN-NNN` | Address in current or next sprint |
+| 🟢 Note | `NOTE-NNN` | Backlog item or stylistic observation |
+| ⚪ OK | — | No action needed |
+
+## 6. Handoff Guidance
+
+After completing the audit:
+
+| Finding Type | Route To |
+|---|---|
+| Architecture redesign needed | `@Architect` — provide `AUDIT-FINDINGS.md` |
+| Implementation can proceed with caution | `@Planner` — provide findings + questions |
+| Major quality/security issues | `@Code-Reviewer` + `@Security-Analyst` |
+| Only minor notes, clear path | Proceed directly with `@Implement` or `@Anchor` |
+
+### Prompt template for handoff:
+```
+@[Agent]: I've completed a codebase audit. 
+Findings: [link or inline AUDIT-FINDINGS.md]
+Blocking questions: [key Q from QUESTIONS.md]
+The task is: [original task description]
+Please [design solution / create plan / review / implement] with these findings in mind.
+```
+
+## 7. Checklist
+
+- [ ] README.md read fully
+- [ ] Entry point traced end-to-end (one complete request/render cycle)
+- [ ] All 20 audit areas assessed (even if just ⚪ OK)
+- [ ] Critical findings have file + line citation
+- [ ] `AUDIT-FINDINGS.md` written to disk
+- [ ] `QUESTIONS.md` written to disk
+- [ ] Blocking questions identified separately
+- [ ] Agent handoff prompt prepared

package/bundles/antigravity-plugin/skills/context-curator/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: context-curator
+description: Compress and prioritize codebase context before handing work to reasoning agents, minimizing token waste while preserving the required decision inputs.
+---
+
+# Context Curator Skill
+
+**Skill ID:** `workflow/context-curator`  
+**Used by:** Architect, Plan, Debug, Security Analyst, Orchestrator  
+**Purpose:** Compress and prioritise codebase context before feeding it to reasoning agents. Prevents context bloat and token waste on long-running projects with large codebases.
+
+---
+
+## When to Use This Skill
+
+Load this skill when:
+- A reasoning agent (Architect, Plan, Debug, Security) is about to start and the codebase is large (>50 files)
+- The previous context window was exhausted or truncated
+- Starting a new pipeline stage on an existing feature (context needs refreshing)
+- A handoff has occurred and the new agent needs a clean, relevant context package
+
+---
+
+## The Context Bloat Problem
+
+In long-running projects, agents accumulate unnecessary context:
+- Full file contents when only function signatures are needed
+- Historical artefacts superseded by newer versions
+- Unrelated modules with no bearing on the current task
+- Duplicate information across PRD, architecture, and plan docs
+
+This skill provides a structured protocol to curate a **minimum sufficient context package** for any given task.
+
+---
+
+## Step 1 — Identify the Task Scope
+
+Before curating context, answer these questions:
+1. **What is the current pipeline stage?** (read `pipeline-state.json`)
+2. **What is the feature being worked on?** (read Intent Document or `pipeline-state.json → feature`)
+3. **What specific files/modules will be touched?** (read the Plan if available)
+4. **What upstream artefacts are required?** (check agent's Context Priority Order)
+
+---
+
+## Step 2 — Build the Context Package
+
+Collect ONLY these items, in this order:
+
+If the context package is written as a standalone Markdown handoff or context document, apply `.github/instructions/document-frontmatter.instructions.md`. New context documents require `Original Author`, `Creation Date`, and `Creating Model`; updated context documents must preserve those fields and add or update `Last Author`, `Last Updated`, and `Last Model Used`.
+
+### Tier 1 — Always Include (MUST READ)
+| Item | Source | What to extract |
+|------|--------|-----------------|
+| Intent Document | `agent-docs/intents/<feature>.md` | Goal, Constraints, Success Criteria |
+| Pipeline state | `.github/pipeline-state.json` | Current stage, approved gates |
+| Project config | `project-config.md` | Tech stack, constraints, brand tokens |
+| Current plan step | `.github/plans/<feature>.md` | Current phase/step only |
+
+### Tier 2 — Include When Relevant (SHOULD READ)
+| Item | Source | What to extract |
+|------|--------|-----------------|
+| Previous artefact | `stages[previous_stage].artefact` | Key decisions and output fields |
+| Architecture doc | `agent-docs/architecture/<feature>.md` | Section relevant to current task |
+| PRD | `agent-docs/prd/<feature>.md` | FRs and NFRs for the affected area |
+
+### Tier 3 — Include Only If Room (READ IF NEEDED)
+| Item | Source | What to extract |
+|------|--------|-----------------|
+| Related source files | As specified by plan step | Function signatures + docstrings only |
+| Test files | `tests/` | Failing test names and error messages |
+| Escalations | `agent-docs/escalations/` | Blocking items only |
+
+---
+
+## Step 3 — Compress Each Item
+
+Apply these compression rules:
+
+### For Markdown Documents
+- Extract only the sections relevant to the current task
+- Summarise lists longer than 5 items as: `[N items — <category>]`
+- Drop historical context (superseded requirements, old decisions)
+- Replace repeated boilerplate with `[standard section — omitted]`
+
+### For Source Code Files
+- Include function/class signatures and docstrings only
+- Replace function bodies with `# [body — <N lines>]`
+- Include full body ONLY for functions directly touched by the current task
+- List imports as a single-line summary: `# imports: os, sys, sqlalchemy, ...`
+
+### For JSON/Config Files
+- Include only the keys relevant to the current task
+- Replace unrelated sections with `// [N keys omitted]`
+
+---
+
+## Step 4 — Assemble the Context Summary
+
+Produce a structured **Context Summary Block** to prepend to the agent's task prompt:
+
+```markdown
+## Context Package — <feature-slug> / <stage>
+**Generated:** <ISO-timestamp>
+**Curated for:** @<AgentName>
+
+### Active Task
+<One sentence describing what the agent must do right now>
+
+### Key Constraints (from Intent + project-config)
+- <constraint 1>
+- <constraint 2>
+- <constraint 3>
+
+### Upstream Decision Summary
+- **<PRD/Arch/Plan>:** <one sentence summarising the key decision>
+- **Gate status:** <gate_name>: approved | pending
+
+### Files in Scope
+- `<file path>` — <what it does / why it's relevant>
+- `<file path>` — <what it does / why it's relevant>
+
+### Do NOT touch
+- `<file/module>` — <reason>
+```
+
+---
+
+## Step 5 — Validate the Package
+
+Before handing the context package to the agent, verify:
+
+- [ ] Total context fits comfortably within the model's context window (leave 40% headroom for the agent's output)
+- [ ] No superseded artefacts included (check `agent-docs/ARTIFACTS.md` for supersession notes)
+- [ ] No sensitive data (credentials, PII) included in the package
+- [ ] All required Tier 1 items are present
+
+If context still exceeds the window after compression:
+1. Drop all Tier 3 items
+2. Summarise Tier 2 architecture doc to section headings only
+3. If still too large — split the task into smaller sub-tasks and curate one context package per sub-task
+
+---
+
+## Supersession Check
+
+Before including any artefact, check `agent-docs/ARTIFACTS.md`:
+- If the artefact is listed as `superseded_by: <newer-file>`, use the newer file instead
+- Never include a superseded artefact in a context package
+
+---
+
+## Output
+
+The Context Curator does not produce a persistent artefact. It produces an in-memory Context Summary Block that is passed to the downstream agent as the first section of their task prompt.
+
+If the Context Curator is run by the Orchestrator, the Orchestrator prepends the Context Summary Block to the routing message sent to the next agent.

package/bundles/antigravity-plugin/skills/cross-review/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: cross-review
+description: Cross-vendor code review of the current diff — a second-vendor model (DeepSeek/GLM/any OpenAI-compatible endpoint) reviews your changes to catch bugs a same-vendor reviewer misses
+---
+
+# /caddis:cross-review — a second-vendor set of eyes on your diff
+
+Run a cross-vendor review of the current changes with a DIFFERENT model family than the one that wrote them
+(default **DeepSeek** — the cheapest + most architecturally distinct-from-Claude option). Use after a phase
+is green and before you commit, or for a second opinion on a risky diff. This is the *cross-vendor*
+complement to `/caddis:code-review`, not a replacement.
+
+## Prerequisite (one-time)
+A provider key must be resolvable. Precedence: `REVIEW_API_KEY` > the provider's own env var
+(`DEEPSEEK_API_KEY` / `GLM_API_KEY`) > `OSS_API_KEY` > the keys file (`~/.claudster/keys.env`,
+overridable via `CADDIS_KEYS_FILE`). If your keys file is populated, no env setup is needed.
+Details: the `coding/cross-review` skill and the **Providers & keys** guide.
+
+## Run it
+The tool ships at `.github/tools/oss_review.py` (stdlib-only, no install):
+```
+python .github/tools/oss_review.py                     # DeepSeek eyes (default)
+python .github/tools/oss_review.py --provider glm      # GLM eyes
+python .github/tools/oss_review.py --range $ARGUMENTS  # review a git range, e.g. origin/main..HEAD
+```
+Optional: `--base-url <url>`, `--model <id>` (env always overrides the preset).
+**Alternate the provider between reviews** (DeepSeek one diff, GLM the next) — different model
+families have different blind spots, and alternation maximizes what the pair catches over time.
+
+## Interpret the exit code
+- **0 — REVIEW: CLEAN** → no blocking issues. Proceed.
+- **1 — REVIEW: BLOCKING** → read the printed findings, then **FIX each blocking item** (or explicitly
+  justify why one is a false positive). Re-run until CLEAN.
+- **2 — error** → no verdict parsed, or a git/endpoint failure. Read stderr; do NOT treat as clean.
+- **3 — misconfigured** → `REVIEW_API_KEY` is unset. Set it (see Prerequisite) and re-run.
+
+## Rules
+- Read-only second opinion — the tool never edits, commits, or pushes. YOU apply fixes in the main thread.
+- Treat exit 2/3 as blocking-unknown, never as approval (the tool is fail-closed by design).
+- A different vendor means a different style; weigh its findings on merit, don't cargo-cult them.