@caddis/cli 0.0.0 → 0.2.0

package/bundles/antigravity-plugin-extras/skills/onboard-project/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: onboard-project
+context: fork
+description: Bootstrap a new project's AI configuration by generating copilot-instructions.md and populating project-config.md. Idempotent — safe to re-run on existing projects.
+---
+
+# Onboard Project Skill
+
+## Purpose
+
+Entry point for the portable AI resources pool. When copied to a new project, this skill bootstraps the project-specific configuration that agents need to function correctly.
+
+**What it produces:**
+1. `copilot-instructions.md` — project-specific context for the AI assistant
+2. `project-config.md` — populated with project values (profile + placeholders)
+3. `agent-docs/ARTIFACTS.md` — artifact manifest (if missing)
+
+---
+
+## When to Use
+
+- Setting up AI resources on a **new project** for the first time
+- After copying the `.github/` (or `.cursor/`) portable pool to a new repo
+- When `project-config.md` has a blank profile and empty placeholder values
+- To add missing sections to an existing `copilot-instructions.md`
+
+---
+
+## Behavior: Idempotent & Non-Destructive
+
+> **CRITICAL**: This skill NEVER overwrites or degrades existing content.
+
+| Scenario | Behavior |
+|----------|----------|
+| `copilot-instructions.md` does not exist | Create from template, populate from user Q&A |
+| `copilot-instructions.md` exists | Read it, compare sections vs. template, append ONLY missing sections with `<!-- Added by onboard-project -->` marker |
+| `project-config.md` has blank profile | Ask user for values, populate |
+| `project-config.md` has profile set | Skip — already configured |
+| `agent-docs/ARTIFACTS.md` missing | Create from template |
+| `agent-docs/ARTIFACTS.md` exists | Skip — already configured |
+
+**Conflict resolution**: If existing content contradicts template defaults, **keep the user's version**. It's more battle-tested.
+
+---
+
+## Steps
+
+### Step 1: Check Current State
+
+Read the following files (if they exist):
+1. `project-config.md` — check if profile is set, if placeholders are filled
+2. `copilot-instructions.md` — check which sections already exist
+3. `agent-docs/ARTIFACTS.md` — check if manifest exists
+
+Report what exists and what's missing before proceeding.
+
+### Step 2: Gather Project Information
+
+Ask the user for information needed to populate the configuration. Skip questions where answers can be inferred from existing files.
+
+**Required information:**
+
+| Category | Questions |
+|----------|-----------|
+| **Identity** | Project name? Organization name? One-line description? |
+| **Tech Stack** | Language(s)? Frontend framework? Backend framework? Database type? |
+| **Branding** | Primary brand color (hex)? Dark color? Light color? Additional brand colors? |
+| **Infrastructure** | Deployment environment (cloud/on-premise/hybrid)? Air-gapped? Authentication method? |
+| **Logging** | Logging library? (loguru, logging, structlog, etc.) |
+| **Shared Libraries** | Any shared/internal libraries? Paths? |
+| **Project Structure** | Entry point file? Source root? Key directories? |
+| **Data Sources** | Database name(s)? Connection method? Key tables? |
+| **Key Conventions** | Query externalization? Path resolution patterns? CSS scoping method? Component reuse patterns? |
+| **Commands** | How to run the app? Run tests? Lint? Build? |
+| **Recipe** | Delivery workflow pattern? (`enterprise-dashboard` for data-to-UI dashboards, or blank for generic projects) |
+
+### Step 3: Populate project-config.md
+
+1. Set the `profile` field (use org name slug, e.g., `acme`, `myorg`, or leave blank if no profile needed)
+2. If using a profile, create a Profile Definition section with:
+   - Core Placeholders table (`<ORG_NAME>`, `<BRAND_PRIMARY>`, `<BRAND_DARK>`, `<BRAND_LIGHT>`, `<DB_TYPE>`, `<DEPLOY_ENV>`, `<LOGGING_LIB>`, `<SHARED_LIBS>`)
+   - Brand Color Palette table (if provided)
+   - Tech Stack table
+   - Data Sources table
+   - Project Structure block
+   - Key Conventions list
+3. If not using a profile, fill in the "Step 2: Project Values" table directly
+4. If user specified a recipe:
+   - Verify `.github/recipes/{recipe}.recipe.md` exists in the pool
+   - Set the `recipe` field in the Step 1 table: `| **recipe** | {recipe} |`
+   - If recipe file is missing, warn but continue — recipe is optional
+
+### Step 4: Create or Update copilot-instructions.md
+
+**Template sections** (check each — add only what's missing):
+
+```markdown
+# {Project Name} — AI Assistant Context
+
+## Project Overview
+{One paragraph: what the project does, who it's for, key goals}
+
+## Architecture
+{High-level architecture: components, data flow, key patterns}
+
+## Tech Stack
+{Table: Layer → Technology}
+
+## Data Sources
+{Table: Source → Table/Collection → Description}
+
+## Key Patterns & Conventions
+{Bullet list of project-specific patterns the AI must follow}
+
+## Database Access
+{Connection method, query patterns, ORM/raw SQL, caching}
+
+## Project Structure
+{Directory tree of key folders}
+
+## Deployment
+{How the app is deployed, environment specifics}
+
+## Key Commands
+{Run, test, lint, build commands}
+```
+
+**Merge logic for existing files:**
+1. Parse existing `copilot-instructions.md` into sections (by `##` headings)
+2. If the file contains `<!-- junai:start -->` … `<!-- junai:end -->` sentinel markers, leave that block untouched — it is managed by the junai extension
+3. For each template section, check if an equivalent heading exists outside the managed block (fuzzy match — "Tech Stack" matches "Technology Stack", "Stack", etc.)
+4. If section exists → **skip it** (preserve user's content entirely)
+5. If section is missing → **append it** before the managed section (or at the end if no managed section) with marker:
+   ```markdown
+   <!-- Added by onboard-project — review and customize -->
+   ## {Section Title}
+   {Template content populated with project values}
+   ```
+5. Never reorder, rewrite, or delete existing sections
+
+### Step 5: Create agent-docs/ARTIFACTS.md (if missing)
+
+If `agent-docs/ARTIFACTS.md` does not exist, create it using the standard template:
+
+```markdown
+# Agent Artifacts
+
+> **For agents**: Only read artifacts with status `current`. Ignore `superseded` and `archived`.
+> **For humans**: This is a working directory for inter-agent communication. Do not include in project documentation.
+
+## How to Read This Manifest
+
+- **chain_id**: Links all artifacts in a feature chain (format: `FEAT-YYYY-MMDD-{slug}`)
+- **status**: `current` (active) | `superseded` (replaced) | `archived` (historical) | `completed` (done)
+- **approval**: `pending` (awaiting review) | `approved` (proceed) | `revision-requested` (needs changes)
+
+## Artifacts
+
+| Date | Agent | Type | Description | Path | Status | Approval | Chain ID |
+|------|-------|------|-------------|------|--------|----------|----------|
+| | | | | | | | |
+```
+
+Also create the subfolder structure if missing:
+- `agent-docs/intents/`
+- `agent-docs/escalations/`
+- `agent-docs/prd/`
+- `agent-docs/architecture/`
+- `agent-docs/ux/mockups/`
+- `agent-docs/ux/reviews/`
+- `agent-docs/security/`
+- `agent-docs/reviews/`
+- `agent-docs/debug/`
+- `agent-docs/testing/`
+- `agent-docs/.archive/`
+
+### Step 6: Summary
+
+Report what was done:
+- Files created vs. updated
+- Sections added to existing `copilot-instructions.md` (if any)
+- Profile set in `project-config.md`
+- Next steps (e.g., "Review the added sections and customize them")
+
+---
+
+## Important Notes
+
+- All paths in this skill are relative. The skill works regardless of whether the AI resources folder is at `.github/`, `.cursor/`, or any other location.
+- The `copilot-instructions.md` file is project-specific and should NOT be committed to the portable pool. It stays in the project repo. The junai extension manages only a sentinel-delimited `<!-- junai:start -->` … `<!-- junai:end -->` section — never edit content inside those markers (it will be refreshed on the next Update). Add your project content outside the markers.
+- `project-config.md` IS part of the portable pool as a template. When the profile section is filled in, it becomes project-specific.
+- The `recipe` field in `project-config.md` is optional. Projects without a recipe work exactly as before — agents use their built-in expertise and plan-embedded skills. Recipes add automatic cross-project baseline loading for repeatable delivery patterns.

package/bundles/antigravity-plugin-extras/skills/performance-testing/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: performance-testing
+description: Performance testing, load testing, and benchmarking for APIs, databases, and web applications. Use when planning load tests, setting performance budgets, profiling bottlenecks, or validating scalability. Covers Locust, k6, pytest-benchmark, browser performance, and database query profiling.
+---
+
+# Performance Testing Skill
+
+Measure before you optimise. This skill covers how to define performance budgets, write load tests, benchmark critical paths, and profile bottlenecks.
+
+## 1. When to Apply This Skill
+
+**Trigger conditions:**
+- "How will this perform under load?"
+- "We need load testing"
+- "Set performance budgets"
+- "Profile this slow endpoint"
+- Pre-launch performance validation
+- After performance incidents or SLA breaches
+
+## 2. Performance Budget Template
+
+Define budgets before testing. Every metric needs a target.
+
+```markdown
+# Performance Budget: {Service/Feature}
+
+## Response Time Targets
+| Endpoint / Action | p50 | p95 | p99 | Max |
+|-------------------|-----|-----|-----|-----|
+| GET /api/items | <100ms | <250ms | <500ms | <1s |
+| POST /api/orders | <200ms | <500ms | <1s | <2s |
+| Dashboard page load | <1.5s | <3s | <5s | <8s |
+
+## Throughput Targets
+| Scenario | Target RPS | Concurrent Users |
+|----------|-----------|-----------------|
+| Normal load | 100 rps | 50 |
+| Peak load | 500 rps | 200 |
+| Stress test | 1000 rps | 500 |
+
+## Resource Limits
+| Resource | Threshold |
+|----------|-----------|
+| CPU | <70% at normal load |
+| Memory | <80% at peak load |
+| DB connections | <80% of pool size |
+| Error rate | <0.1% at normal load |
+```
+
+## 3. Load Testing with Locust (Python)
+
+```python
+from locust import HttpUser, task, between
+
+class APIUser(HttpUser):
+    wait_time = between(1, 3)
+
+    @task(3)
+    def list_items(self):
+        self.client.get("/api/items", name="GET /api/items")
+
+    @task(1)
+    def create_item(self):
+        self.client.post(
+            "/api/items",
+            json={"name": "test", "value": 42},
+            name="POST /api/items",
+        )
+
+    def on_start(self):
+        """Authenticate once per simulated user."""
+        resp = self.client.post("/api/auth/login", json={
+            "username": "loadtest",
+            "password": "test-password",  # Use env var in real tests
+        })
+        self.client.headers["Authorization"] = f"Bearer {resp.json()['token']}"
+```
+
+Run: `locust -f load_test.py --host=http://localhost:8000 --users=100 --spawn-rate=10`
+
+## 4. Load Testing with k6 (JavaScript)
+
+```javascript
+import http from 'k6/http';
+import { check, sleep } from 'k6';
+
+export const options = {
+  stages: [
+    { duration: '1m', target: 50 },   // Ramp up
+    { duration: '3m', target: 50 },   // Sustain
+    { duration: '1m', target: 200 },  // Peak
+    { duration: '2m', target: 200 },  // Sustain peak
+    { duration: '1m', target: 0 },    // Ramp down
+  ],
+  thresholds: {
+    http_req_duration: ['p(95)<500', 'p(99)<1000'],
+    http_req_failed: ['rate<0.01'],
+  },
+};
+
+export default function () {
+  const res = http.get('http://localhost:8000/api/items');
+  check(res, {
+    'status is 200': (r) => r.status === 200,
+    'response time < 500ms': (r) => r.timings.duration < 500,
+  });
+  sleep(1);
+}
+```
+
+## 5. Python Benchmarking with pytest-benchmark
+
+```python
+import pytest
+
+def fibonacci(n: int) -> int:
+    if n <= 1:
+        return n
+    a, b = 0, 1
+    for _ in range(2, n + 1):
+        a, b = b, a + b
+    return b
+
+def test_fibonacci_benchmark(benchmark):
+    result = benchmark(fibonacci, 100)
+    assert result == 354224848179261915075
+```
+
+Run: `pytest --benchmark-only --benchmark-sort=mean`
+
+## 6. Database Query Profiling
+
+### SQL Server
+```sql
+-- Enable actual execution plan + IO statistics
+SET STATISTICS IO ON;
+SET STATISTICS TIME ON;
+
+-- Run the slow query
+SELECT ...
+
+-- Check for table scans, missing indexes
+-- Key metrics: logical reads, CPU time, elapsed time
+```
+
+### Python profiling with cProfile
+```python
+import cProfile
+import pstats
+
+def profile_function(func, *args):
+    """Profile a function and print top 20 cumulative time entries."""
+    profiler = cProfile.Profile()
+    profiler.enable()
+    result = func(*args)
+    profiler.disable()
+
+    stats = pstats.Stats(profiler)
+    stats.sort_stats("cumulative")
+    stats.print_stats(20)
+    return result
+```
+
+## 7. Browser Performance Testing
+
+### Core Web Vitals Targets
+
+| Metric | Good | Needs Improvement | Poor |
+|--------|------|-------------------|------|
+| LCP (Largest Contentful Paint) | ≤2.5s | ≤4.0s | >4.0s |
+| INP (Interaction to Next Paint) | ≤200ms | ≤500ms | >500ms |
+| CLS (Cumulative Layout Shift) | ≤0.1 | ≤0.25 | >0.25 |
+
+### Lighthouse CI Check
+```bash
+npx @lhci/cli autorun --collect.url=http://localhost:3000 \
+  --assert.preset=lighthouse:recommended \
+  --assert.assertions.categories:performance=error:minScore:0.9
+```
+
+## 8. Test Types and When to Use Them
+
+| Type | Purpose | Tool | When |
+|------|---------|------|------|
+| **Load test** | Validate normal traffic capacity | Locust, k6 | Pre-launch, after scaling changes |
+| **Stress test** | Find breaking point | k6 (ramping) | Capacity planning |
+| **Soak test** | Detect memory leaks, connection exhaustion | Locust (long run) | Before major releases |
+| **Spike test** | Validate autoscaling / recovery | k6 (sudden ramp) | Event-driven apps |
+| **Benchmark** | Compare implementations | pytest-benchmark | During optimisation |
+| **Profile** | Find hotspots | cProfile, py-spy | After identifying slow endpoint |
+
+## 9. Reporting Template
+
+```markdown
+# Performance Test Report: {Date}
+
+## Test Configuration
+- Tool: {Locust/k6}
+- Duration: {minutes}
+- Peak users: {n}
+- Environment: {staging/production-like}
+
+## Results vs Budget
+| Metric | Budget | Actual | Status |
+|--------|--------|--------|--------|
+| p95 response time | <500ms | {n}ms | ✅/❌ |
+| Error rate | <0.1% | {n}% | ✅/❌ |
+| Throughput | >100 rps | {n} rps | ✅/❌ |
+
+## Bottlenecks Found
+1. {description} — {root cause} — {recommendation}
+
+## Recommendations
+- {action items}
+```
+
+## 10. Anti-Patterns
+
+| Anti-Pattern | Problem | Fix |
+|---|---|---|
+| Testing against localhost only | Misses network latency, DNS, TLS | Test against staging environment |
+| No warm-up phase | Cold caches skew results | Add 1-2 min ramp-up |
+| Ignoring error rate | High throughput ≠ success | Always check error rate alongside latency |
+| Single-metric focus | p50 looks fine but p99 is 10s | Report p50, p95, p99, and max |
+| Testing with empty database | Production has millions of rows | Use production-sized test data |
+| No baseline comparison | Can't tell if results are better/worse | Always compare against previous run |

package/bundles/antigravity-plugin-extras/skills/pipeline-state/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: pipeline-state
+description: Read and write `.github/pipeline-state.json` to track stage progress, artefacts, supervision gates, and handoff payloads in the agent pipeline.
+---
+
+# Pipeline State Skill
+
+**Skill ID:** `workflow/pipeline-state`  
+**Used by:** Orchestrator, Plan, Implement, Tester, Code Reviewer  
+**Purpose:** Read and write `.github/pipeline-state.json` to track pipeline position, stage status, and supervision gates.
+
+---
+
+## When to Use This Skill
+
+Load this skill when:
+- Starting the Orchestrator agent on a new or resuming pipeline
+- An agent completes its stage and needs to mark it done
+- Checking if upstream gates are approved before proceeding
+- Setting `blocked_by` when a validation failure is detected
+
+---
+
+## Pipeline State File Location
+
+```
+.github/pipeline-state.json
+```
+
+This file is **project-specific** — it lives in the project repo, NOT in junai. Use `.github/pipeline-state.template.json` from junai as the blank starting template.
+
+---
+
+## Schema Reference
+
+```json
+{
+  "project": "<project-name>",
+  "feature": "<feature-slug>",
+  "pipeline_version": "1.0",
+  "current_stage": "<stage-name>",
+  "stages": {
+    "intent":    { "status": "not_started | in_progress | complete | blocked", "artefact": "<path-or-null>", "completed_at": "<ISO-timestamp-or-null>" },
+    "prd":       { "status": "...", "artefact": "...", "completed_at": "..." },
+    "architect": { "status": "...", "artefact": "...", "completed_at": "..." },
+    "plan":      { "status": "...", "artefact": "...", "completed_at": "..." },
+    "implement": { "status": "...", "artefact": "...", "completed_at": "..." },
+    "tester":    { "status": "...", "artefact": "...", "completed_at": "..." },
+    "review":    { "status": "...", "artefact": "...", "completed_at": "..." }
+  },
+  "supervision_gates": {
+    "intent_approved": false,
+    "adr_approved": false,
+    "plan_approved": false,
+    "review_approved": false
+  },
+  "blocked_by": null,
+  "last_updated": "<ISO-timestamp>"
+}
+```
+
+### Stage Status Values
+| Value | Meaning |
+|-------|---------|
+| `not_started` | Stage not yet begun |
+| `in_progress` | Agent is actively working on this stage |
+| `complete` | Artefact produced and `approval: approved` confirmed |
+| `blocked` | Cannot proceed — see `blocked_by` field |
+
+---
+
+## Read Operations
+
+### Check current stage
+```
+Read: .github/pipeline-state.json → .current_stage
+```
+
+### Check if a gate is approved
+```
+Read: .github/pipeline-state.json → .supervision_gates.<gate_name>
+Returns: true | false
+```
+
+### Check upstream artefact approval
+```
+Read: <artefact_path from previous stage> → YAML header → approval field
+Expected value: "approved"
+```
+
+### Check for blocking escalations
+```
+List files in: agent-docs/escalations/
+If any file contains severity: "blocking" → surface to user, do NOT proceed
+```
+
+---
+
+## Write Operations
+
+### Mark stage as in_progress
+```json
+{
+  "current_stage": "<new-stage>",
+  "stages": {
+    "<new-stage>": { "status": "in_progress" }
+  },
+  "last_updated": "<current-ISO-timestamp>"
+}
+```
+
+### Mark stage as complete
+```json
+{
+  "stages": {
+    "<completed-stage>": {
+      "status": "complete",
+      "artefact": "<path-to-artefact>",
+      "completed_at": "<current-ISO-timestamp>"
+    }
+  },
+  "last_updated": "<current-ISO-timestamp>"
+}
+```
+
+### Set blocked state
+```json
+{
+  "stages": {
+    "<stage>": { "status": "blocked" }
+  },
+  "blocked_by": "<reason: e.g., 'artefact missing approval field'>",
+  "last_updated": "<current-ISO-timestamp>"
+}
+```
+
+### Approve a supervision gate
+```json
+{
+  "supervision_gates": {
+    "<gate_name>": true
+  },
+  "last_updated": "<current-ISO-timestamp>"
+}
+```
+
+### Clear a blocked state
+```json
+{
+  "blocked_by": null,
+  "stages": {
+    "<stage>": { "status": "in_progress" }
+  },
+  "last_updated": "<current-ISO-timestamp>"
+}
+```
+
+### Write handoff payload before routing (GAP-H6 + GAP-I1)
+
+Before routing to `plan`, `implement`, `tester`, or `code-reviewer`, the Orchestrator writes to `_notes.handoff_payload`:
+
+```json
+{
+  "_notes": {
+    "handoff_payload": {
+      "target_agent": "<implement|tester|code-reviewer|plan>",
+      "scope": "<one-line description of what the agent must do>",
+      "summary": "<brief context from upstream stage>",
+      "required_tests": ["<test 1>", "<test 2>"],
+      "exit_criteria": "<what done looks like>",
+      "upstream_artefact": "<path to artefact produced by the current/previous stage>",
+      "coverage_requirements": [
+        "<component or requirement the receiving agent MUST cover>",
+        "<e.g.: component: Search API integration>",
+        "<e.g.: NFR: WCAG 2.1 AA compliance>"
+      ]
+    }
+  }
+}
+```
+
+> **`coverage_requirements[]` rule (GAP-I1):** Must be non-empty whenever an upstream artefact exists (architecture doc → plan, plan → implement, implement → tester, etc.). The receiving agent maps every item to its output and flags `COVERAGE_GAP: <item>` for any item not covered before starting work.
+>
+> **`pipeline_mode` field:** Set `"pipeline_mode": "supervised"` (default) or `"auto"` in the root of `pipeline-state.json`. Orchestrator §1 reads this to determine whether to HARD STOP after presenting the handoff button (`supervised`) or call `notify_orchestrator()` MCP tool and continue (`auto`). Always default to `supervised` on new pipelines — `auto` is an explicit opt-in.
+
+---
+
+## Initialisation
+
+When `.github/pipeline-state.json` does not exist:
+1. Copy from `.github/pipeline-state.template.json` (available in the junai pool)
+2. Replace `<project-name>` with the value from `project-config.md → profile → project_name`
+3. Replace `<feature-slug>` with the kebab-case feature name from the Intent Document or user input
+4. Set `current_stage` to `"intent"` or the appropriate starting stage
+5. Set `last_updated` to current ISO timestamp
+
+---
+
+## Validation Rules
+
+Before routing to any agent, the Orchestrator MUST verify:
+
+1. **Artefact exists** — the file at `stages[previous_stage].artefact` exists on disk
+2. **Artefact approved** — the YAML header of that artefact contains `approval: approved`
+3. **No blocking escalations** — `agent-docs/escalations/` has no files with `severity: blocking`
+4. **Gate check** — if the transition requires a supervision gate, that gate is `true` in `supervision_gates`
+
+If ANY check fails → set `blocked_by`, report to user, do NOT proceed.