@caddis/cli 0.0.0 → 0.2.0

package/bundles/antigravity-plugin/skills/tdd/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: tdd
+description: Run a strict red-green-refactor TDD cycle for a unit of behavior
+---
+
+# /tdd — red → green → refactor
+
+Build this behavior test-first: **$ARGUMENTS**
+
+If empty, ask what behavior to build and stop. Read the relevant `AGENTS.md` (root + the folder you'll
+touch, e.g. `tests/AGENTS.md`) before starting.
+
+## The cycle — do not skip or reorder
+
+**1. PLAN the cases.** List happy path, edge cases (empty/None/boundary), and error cases. One line each.
+
+**2. RED.** Write the *first* failing test (or a tight parametrized set). Run it. Confirm it fails — and
+fails for the *right reason* (asserts the missing behavior, not an import typo). Show the failure output.
+> If it passes immediately, the test is wrong or the behavior exists — stop and reassess.
+
+**3. GREEN.** Write the **minimum** code to pass. No extra features, no speculative abstraction. Run the
+test. Show it green.
+
+**4. REFACTOR.** Improve names/structure/duplication in both code and test while keeping green. Re-run.
+
+**5. Repeat** for the next case until the behavior is complete.
+
+**6. VERIFY.** Run the full relevant suite so you didn't regress anything. For heavier coverage or a UI
+layer, dispatch the **tester** subagent.
+
+## Rules
+- Never write production code with no failing test demanding it.
+- Test behavior, not internals. Assert what a caller observes.
+- Each test independent; shared setup in fixtures.
+- Show real command output at RED and GREEN — don't claim a state you didn't run.
+
+End by stating: cases covered, final command run + result, and whether a commit is warranted.

package/bundles/antigravity-plugin/skills/tdd-workflow/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: tdd-workflow
+description: "Test-Driven Development workflow — red-green-refactor cycle"
+---
+
+# TDD Workflow
+
+Test-Driven Development using the red-green-refactor cycle. Write tests first, implement minimum code to pass, then refactor with confidence.
+
+## When to Use
+
+- Writing new features or functionality
+- Fixing bugs (write a test that reproduces it first)
+- Refactoring existing code
+- Adding API endpoints or service methods
+
+## Phase 1: PLAN Tests
+
+Map test cases before writing code. For each feature, identify:
+
+1. **Happy path** — expected successful behavior
+2. **Edge cases** — empty input, boundary values, None/null
+3. **Error cases** — invalid input, missing resources, timeouts
+
+```
+Feature: Shorten URL
+  - Happy: valid URL returns short code
+  - Happy: same URL returns same code (idempotent)
+  - Edge: very long URL (2048+ chars)
+  - Error: invalid URL format
+  - Error: empty string
+```
+
+## Phase 2: WRITE Failing Test (Red)
+
+Write one test at a time. It must fail — this proves it tests something real.
+
+```python
+import pytest
+from myapp.shortener import shorten_url
+
+class TestShortenURL:
+    def test_returns_short_code_for_valid_url(self):
+        result = shorten_url("https://example.com/long/path")
+        assert result is not None
+        assert len(result) == 8
+
+    def test_same_url_returns_same_code(self):
+        code1 = shorten_url("https://example.com")
+        code2 = shorten_url("https://example.com")
+        assert code1 == code2
+
+    def test_rejects_invalid_url(self):
+        with pytest.raises(ValueError, match="Invalid URL"):
+            shorten_url("not-a-url")
+
+    @pytest.mark.parametrize("bad_input", ["", "ftp://wrong", None])
+    def test_rejects_bad_inputs(self, bad_input):
+        with pytest.raises(ValueError):
+            shorten_url(bad_input)
+```
+
+Run and confirm failure:
+
+```bash
+pytest tests/test_shortener.py -v
+# Expected: FAILED (module or assertions fail)
+```
+
+## Phase 3: IMPLEMENT Minimum Code (Green)
+
+Write the simplest code that makes the failing test pass. No extras, no optimization.
+
+```python
+import hashlib, re
+
+_store: dict[str, str] = {}
+
+def shorten_url(url: str) -> str:
+    if not url or not re.match(r"https?://\S+", url):
+        raise ValueError("Invalid URL")
+    code = hashlib.sha256(url.encode()).hexdigest()[:8]
+    _store[code] = url
+    return code
+```
+
+Run and confirm green:
+
+```bash
+pytest tests/test_shortener.py -v
+# Expected: PASSED
+```
+
+## Phase 4: REFACTOR
+
+Improve code quality while keeping all tests green.
+
+**Production code:** extract helpers, improve naming, add type hints, remove duplication.
+
+**Test code:** extract fixtures, use `conftest.py`:
+
+```python
+# tests/conftest.py
+import pytest
+
+@pytest.fixture(autouse=True)
+def reset_store():
+    from myapp.shortener import _store
+    _store.clear()
+```
+
+Run after refactoring — still green:
+
+```bash
+pytest tests/test_shortener.py -v
+```
+
+## Phase 5: VERIFY Coverage
+
+```bash
+pip install pytest-cov
+pytest --cov=myapp --cov-report=term-missing tests/
+```
+
+Enforce in CI:
+
+```ini
+# pyproject.toml
+[tool.pytest.ini_options]
+addopts = "--cov=myapp --cov-fail-under=80"
+```
+
+Look at the `Missing` column for untested lines. Common gaps: exception handlers, fallback branches, cleanup code.
+
+## Testing Patterns
+
+### Mocking External Dependencies
+
+```python
+from unittest.mock import patch, MagicMock
+
+def test_fetches_remote_data():
+    mock_resp = MagicMock()
+    mock_resp.json.return_value = {"status": "ok"}
+    mock_resp.status_code = 200
+    with patch("myapp.client.requests.get", return_value=mock_resp):
+        result = fetch_data("https://api.example.com/data")
+        assert result == {"status": "ok"}
+```
+
+### Database Tests
+
+```python
+@pytest.fixture
+def db_session():
+    engine = create_engine("sqlite:///:memory:")
+    Base.metadata.create_all(engine)
+    session = Session(engine)
+    yield session
+    session.close()
+
+def test_creates_user(db_session):
+    user = User(name="Alice", email="alice@test.com")
+    db_session.add(user)
+    db_session.commit()
+    assert db_session.query(User).count() == 1
+```
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Testing internal state (`obj._count`) | Test observable behavior (`obj.get_value()`) |
+| Tests depend on each other | Each test sets up its own data |
+| No assertions in test | Every test must assert something |
+| Testing implementation details | Test what users/callers see |
+
+## Quick Reference
+
+```bash
+pytest                                    # Run all tests
+pytest tests/test_x.py -v                 # Run specific file, verbose
+pytest tests/test_x.py::TestClass::test_y # Run single test
+pytest --cov=myapp --cov-report=term-missing  # Coverage
+pytest -x                                 # Stop at first failure
+pytest --lf                               # Re-run last failures
+ptw -- --cov=myapp                        # Watch mode (pytest-watch)
+```

package/bundles/antigravity-plugin/skills/technical-writing/SKILL.md

@@ -0,0 +1,286 @@
+---
+name: technical-writing
+context: fork
+description: Technical documentation best practices for READMEs, API docs, architecture docs, runbooks, and developer guides. Use when writing or reviewing documentation, creating onboarding guides, or establishing documentation standards.
+---
+
+# Technical Writing Skill
+
+Good documentation is the difference between a project that scales and one that stalls. Write for the reader who has zero context.
+
+## 1. When to Apply This Skill
+
+**Trigger conditions:**
+- Writing or updating a README
+- Creating API documentation
+- Writing architecture decision records (ADRs)
+- Building runbooks or incident playbooks
+- Creating onboarding/developer guides
+- Reviewing documentation for clarity
+
+## 2. Document Types and Templates
+
+### Document Provenance Frontmatter
+
+All descriptive Markdown docs must follow `.github/instructions/document-frontmatter.instructions.md`.
+
+- **New docs**: include `Original Author`, `Creation Date`, and `Creating Model` in YAML frontmatter.
+- **Updated docs**: preserve those original fields and add or update `Last Author`, `Last Updated`, and `Last Model Used`.
+- Use full ISO 8601 UTC timestamps for `Creation Date` and `Last Updated` values.
+- Merge these fields into existing frontmatter instead of replacing document-specific metadata.
+
+### README Structure
+
+Every project README follows this order:
+
+```markdown
+# Project Name
+One-sentence description of what this does and who it's for.
+
+## Quick Start
+Minimum steps to run the project locally (≤5 commands).
+
+## Prerequisites
+- Runtime versions (Python 3.12+, Node 22+)
+- Required tools (Docker, pnpm)
+- Required accounts/access
+
+## Installation
+Step-by-step setup with copy-pasteable commands.
+
+## Usage
+Common tasks with examples.
+
+## Architecture
+Brief overview with a diagram (link to detailed docs).
+
+## Contributing
+How to submit changes, run tests, and follow conventions.
+
+## License
+```
+
+**Rules:**
+- Quick Start must work on a fresh machine in under 5 minutes
+- Every command must be copy-pasteable (no `<placeholder>` without explanation)
+- Test the README by following it literally on a clean environment
+
+### Architecture Decision Record (ADR)
+
+```markdown
+# ADR-{NNN}: {Decision Title}
+
+## Status
+Accepted | Superseded by ADR-{NNN} | Deprecated
+
+## Context
+What problem are we solving? What constraints exist?
+
+## Decision
+What did we decide and why?
+
+## Alternatives Considered
+| Option | Pros | Cons | Why Not |
+|--------|------|------|---------|
+
+## Consequences
+What changes as a result? What new constraints are introduced?
+```
+
+### Runbook/Playbook
+
+```markdown
+# Runbook: {Incident Type}
+
+## Symptoms
+What does the user/monitor see?
+
+## Impact
+Who is affected? What's the blast radius?
+
+## Diagnosis Steps
+1. Check {metric/log/dashboard} — expected: {value}
+2. Run `{command}` — look for {pattern}
+3. ...
+
+## Resolution Steps
+1. {Step with exact command}
+2. {Verification step}
+3. ...
+
+## Escalation
+If not resolved in {time}, contact {team/person}.
+
+## Post-Incident
+- [ ] Update this runbook with new learnings
+- [ ] File ticket for permanent fix
+```
+
+## 3. Writing Principles
+
+### Know Your Reader
+
+| Reader | Needs | Writing Style |
+|--------|-------|--------------|
+| **New developer** | Setup, concepts, where things are | Step-by-step, no assumptions |
+| **Experienced dev** | API reference, edge cases, configuration | Concise, scannable, tables |
+| **Ops/SRE** | Runbooks, monitoring, deployment | Commands, checklists, decision trees |
+| **Stakeholder** | What it does, status, decisions | High-level, diagrams, outcomes |
+
+### The Inverted Pyramid
+
+Put the most important information first. Readers scan, they don't read.
+
+```
+┌─────────────────────────┐
+│    What + Why (lead)    │  ← First paragraph answers the key question
+├─────────────────────────┤
+│  How (details)          │  ← Supporting details, steps, configuration
+├─────────────────────────┤
+│  Reference (appendix)   │  ← Edge cases, history, alternatives
+└─────────────────────────┘
+```
+
+### Plain Language Rules
+
+| Do | Don't |
+|----|-------|
+| "This function returns the user's name" | "This function facilitates the retrieval of the nomenclature associated with the user entity" |
+| "Run `npm install`" | "Execute the package installation command" |
+| "Fails if the file doesn't exist" | "In the event that the specified file is not present in the filesystem, the operation will not succeed" |
+| Short sentences (< 25 words) | Run-on sentences with multiple clauses |
+| Active voice | Passive voice |
+
+## 4. Code Examples in Documentation
+
+### Rules for Code Samples
+
+```python
+# ✅ GOOD: Complete, runnable example with imports
+from datetime import datetime
+from myapp.models import User
+
+def create_user(name: str, email: str) -> User:
+    """Create a user and return the saved instance."""
+    user = User(name=name, email=email, created_at=datetime.now())
+    user.save()
+    return user
+
+# Usage
+user = create_user("Alice", "alice@example.com")
+print(user.id)  # => "usr_abc123"
+```
+
+```python
+# ❌ BAD: Incomplete snippet, no context
+def create_user(name, email):
+    user = User(name=name, email=email)  # What is User? Where is it imported?
+    user.save()  # Does this return something?
+```
+
+**Rules:**
+- Include imports
+- Show expected output in comments
+- Use realistic data (not "foo", "bar", "test")
+- Every example must be copy-pasteable and runnable
+
+## 5. Diagrams
+
+Use diagrams for architecture, data flow, and sequences. Text alone fails for spatial relationships.
+
+### When to Use Each Type
+
+| Diagram | Use For |
+|---------|---------|
+| **Flowchart** | Decision trees, process flows |
+| **Sequence** | API call chains, auth flows |
+| **Architecture** | System overview, service boundaries |
+| **ERD** | Database schema relationships |
+| **State** | Lifecycle transitions (order, ticket) |
+
+### Diagram Rules
+- Label every arrow (what data flows, what triggers the transition)
+- Include a legend if using color coding
+- Keep to 7±2 elements — decompose larger diagrams
+- Store diagrams as code (Mermaid, PlantUML) for version control
+
+## 6. API Documentation
+
+### Endpoint Documentation Template
+
+```markdown
+### `POST /api/v1/customers`
+
+Create a new customer record.
+
+**Auth:** Bearer token required
+
+**Request Body:**
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| name | string | Yes | Customer full name (1-200 chars) |
+| email | string | Yes | Valid email address |
+
+**Response:** `201 Created`
+```json
+{
+  "data": { "id": "cust_abc", "name": "Alice", "email": "alice@example.com" }
+}
+```
+
+**Errors:**
+| Code | When |
+|------|------|
+| 400 | Missing required field |
+| 409 | Email already exists |
+| 422 | Invalid email format |
+```
+
+## 7. Documentation Maintenance
+
+### Keep Docs Near Code
+
+```
+src/
+  auth/
+    login.py
+    README.md        ← Auth module docs live with auth code
+docs/
+  architecture.md    ← System-level docs in docs/
+  runbooks/          ← Operational docs
+```
+
+### Freshness Rules
+
+| Trigger | Action |
+|---------|--------|
+| API endpoint changed | Update API docs in same PR |
+| New environment variable | Update README + .env.example |
+| Architecture decision | Write or update ADR |
+| Production incident | Update or create runbook |
+| New developer onboarded | Test README, fix gaps found |
+
+## 8. Review Checklist
+
+When reviewing documentation:
+
+- [ ] Answers "what does this do?" in the first paragraph
+- [ ] Document frontmatter is present and current
+- [ ] Code examples are complete and runnable
+- [ ] Commands are copy-pasteable
+- [ ] No stale references to old code, endpoints, or config
+- [ ] Diagrams are up to date
+- [ ] Written for the target audience (not the author)
+- [ ] No jargon without definition
+- [ ] Links work and point to current resources
+
+## 9. Anti-Patterns
+
+| Anti-Pattern | Problem | Fix |
+|---|---|---|
+| Docs written once, never updated | Stale docs are worse than no docs | Update in same PR as code changes |
+| Wall of text | Nobody reads it | Use headings, tables, code blocks, diagrams |
+| Documenting obvious code | Noise, maintenance burden | Document "why", not "what" |
+| Screenshots of terminal output | Can't copy-paste, hard to update | Use code blocks with text output |
+| "See the code for details" | Reader has to reverse-engineer | Write the explanation |
+| Assuming reader context | "Just run the usual setup" | Spell out every step |

package/bundles/antigravity-plugin/skills/test-strategy/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: test-strategy
+context: fork
+description: Test planning and strategy for projects of any size. Use when defining what to test, choosing test types, setting coverage goals, building test pyramids, or planning quality gates. Produces TEST-STRATEGY.md with prioritized test plan. Routes to Tester agent for execution.
+---
+
+# Test Strategy Skill
+
+Define what to test, at what level, and why — before writing a single test. Strategy first, implementation second.
+
+## 1. When to Apply This Skill
+
+**Trigger conditions:**
+- "What should we test?"
+- "Create a test plan for this feature"
+- "We need a testing strategy"
+- New project or major feature without existing test coverage
+- Before a Tester agent handoff where scope is unclear
+
+**Do not skip strategy** — writing tests without a plan leads to low-value tests that cover the wrong things.
+
+## 2. The Test Pyramid
+
+Map every test to the right level. Cost increases as you go up.
+
+```
+          ┌──────────┐
+          │   E2E    │  ← Fewest: critical user journeys only
+          │ (Slow)   │     5-10% of total tests
+         ─┼──────────┼─
+         │Integration │  ← Middle: API contracts, DB queries, service boundaries
+         │ (Medium)   │     20-30% of total tests
+        ─┼────────────┼─
+        │    Unit      │  ← Most: pure functions, business logic, edge cases
+        │   (Fast)     │     60-70% of total tests
+        └──────────────┘
+```
+
+### Level Selection Rules
+
+| Level | Test When | Do NOT Test |
+|-------|-----------|-------------|
+| **Unit** | Pure logic, calculations, transformations, validators, parsers | Framework glue, wrappers with no logic |
+| **Integration** | DB queries, API endpoints, service interactions, auth flows | Simple CRUD with no business rules |
+| **E2E** | Critical user journeys (login → action → result), payment flows | Every page variation, admin-only features |
+
+## 3. Strategy Template
+
+Produce this for every feature or project:
+
+```markdown
+# Test Strategy: {Feature Name}
+
+## Risk Assessment
+| Component | Risk Level | Why |
+|-----------|-----------|-----|
+| {component} | High/Med/Low | {data loss, revenue, security, UX} |
+
+## Coverage Plan
+| Layer | Target | What's Covered |
+|-------|--------|----------------|
+| Unit | {n} tests | {list of modules/functions} |
+| Integration | {n} tests | {list of API/DB interactions} |
+| E2E | {n} tests | {list of user journeys} |
+
+## Priority Order (implement in this sequence)
+1. {highest-risk component} — unit tests
+2. {API contracts} — integration tests
+3. {critical journey} — E2E test
+4. ... remaining by descending risk
+
+## Quality Gates
+- [ ] All unit tests pass
+- [ ] Integration tests pass with test DB
+- [ ] E2E critical path passes
+- [ ] Coverage ≥ {target}% on changed files
+```
+
+## 4. Risk-Based Prioritisation
+
+Not all code deserves equal test investment. Prioritise by risk:
+
+### High Risk (test thoroughly)
+- Money/payment logic
+- Authentication and authorisation
+- Data mutations (writes, deletes, migrations)
+- External API integrations
+- Security-sensitive code (input validation, sanitisation)
+
+### Medium Risk (test key paths)
+- Business logic with branching conditions
+- Data transformations and aggregations
+- State management (complex reducers, stores)
+- Error handling and recovery
+
+### Low Risk (test selectively)
+- Display components with no logic
+- Configuration files
+- Static content
+- Simple pass-through functions
+
+## 5. Coverage Goals
+
+Set coverage targets by component risk, not a blanket number.
+
+| Component Type | Minimum Coverage | Rationale |
+|---------------|-----------------|-----------|
+| Business logic / calculations | 90%+ | High cost of bugs |
+| API endpoints / routes | 80%+ | Contract stability |
+| Data access layer | 75%+ | Data integrity |
+| UI components with logic | 70%+ | User-facing bugs |
+| Utility functions | 85%+ | Widely reused |
+| Configuration / glue code | — | Not worth unit testing |
+
+## 6. Test Naming Convention
+
+Every test name answers three questions:
+
+```
+test_{what}_{condition}_{expected_outcome}
+```
+
+Examples:
+```python
+def test_calculate_discount_with_expired_coupon_returns_zero():
+def test_login_with_invalid_password_returns_401():
+def test_export_csv_with_empty_dataset_creates_headers_only():
+```
+
+## 7. When to Update the Strategy
+
+- New risk identified (security audit, incident, production bug)
+- Architecture change (new service, DB migration, API version)
+- Coverage drops below target on consecutive PRs
+- Feature scope expands significantly
+
+## 8. Anti-Patterns to Avoid
+
+| Anti-Pattern | Problem | Fix |
+|---|---|---|
+| Testing implementation details | Brittle, breaks on refactor | Test behaviour and outputs |
+| 100% coverage target | Leads to low-value tests | Risk-based targets per component |
+| Only happy path | Misses edge cases that cause incidents | Add error/boundary tests per risk |
+| Shared mutable state between tests | Flaky, order-dependent | Isolate with setup/teardown |
+| Slow test suite | Developers skip running tests | Keep unit tests under 30s total |
+| Testing mocked-only code | False confidence | Mix unit + integration testing |
+
+## 9. Output Artefact
+
+Produce `TEST-STRATEGY.md` in the project docs or agent-docs directory. Ensure it includes:
+1. Risk assessment table
+2. Coverage plan with test counts per layer
+3. Priority order for implementation
+4. Quality gate checklist
+5. Named test cases for the top 10 highest-risk areas