@protoboxai/codeloop 0.3.0

package/templates/commands/debug.md

@@ -0,0 +1,142 @@
+---
+description: Investigate production issues — search logs, check health, create regression tasks
+argument-hint: [pattern] [--health] [--recent]
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion
+---
+
+<!-- codeloop-version: 0.3.0 -->
+
+# /debug
+
+Investigate production issues using configured log and health commands.
+
+## Usage
+
+```bash
+/debug                   # Check health + show recent errors
+/debug <pattern>         # Search logs for a specific pattern
+/debug --health          # Health check only
+/debug --recent          # Show recent log entries (last 50 lines)
+```
+
+## Phase 1: Load Config
+
+1. Read `.codeloop/config.yaml` — load the `debug` section:
+   ```yaml
+   debug:
+     logs: "fly logs --app myapp"
+     health: "curl -sf https://myapp.fly.dev/health"
+   ```
+
+2. If no `debug` section → stop with:
+   "No debug commands configured. Add them to `.codeloop/config.yaml` under `debug`."
+
+3. Read `.codeloop/board.json` — find the active task for context
+
+## Phase 2: Health Check
+
+If `debug.health` is configured (always run unless `<pattern>` provided without `--health`):
+
+1. Run the health command
+2. Parse the response:
+   - Exit 0 + valid response → HEALTHY
+   - Non-zero exit or timeout → UNHEALTHY
+3. Report:
+   ```
+   **Health**: ✓ healthy (200 OK, 120ms)
+   ```
+   or:
+   ```
+   **Health**: ✗ unhealthy (connection refused)
+   ```
+
+## Phase 3: Search Logs
+
+### Default (no pattern)
+
+Run `debug.logs` and capture the last 50 lines. Scan for common error patterns:
+- `Error`, `ERROR`, `Exception`, `FATAL`
+- Stack traces (indented lines starting with `at ` or `Traceback`)
+- HTTP 5xx status codes
+- Connection refused / timeout patterns
+
+Summarize findings:
+```
+## Recent Errors (last 50 lines)
+
+Found 3 error entries:
+
+1. **TypeError: Cannot read property 'id' of undefined**
+   at src/auth/middleware.ts:42
+   Occurred 2x in last 50 lines
+
+2. **MongoServerError: connection pool closed**
+   at node_modules/mongodb/...
+   Occurred 1x
+```
+
+### With pattern
+
+Run the `debug.logs` command and pipe through `grep` with the user's pattern:
+```bash
+fly logs --app myapp | grep "auth"
+```
+
+Show matching lines and context. Summarize:
+- How many matches found
+- Timestamps of first and last match
+- Common patterns in matches
+
+## Phase 4: Cross-Reference
+
+If the active task has commits:
+1. List recent commits from the task
+2. Check if any error patterns correlate with recently changed files
+3. Report correlations:
+   ```
+   ### Possible Correlation
+
+   Error in `src/auth/middleware.ts:42` — this file was modified in commit abc1234
+   ("feat(auth): add token refresh") from the current task.
+   ```
+
+## Phase 5: Regression Task
+
+If issues are found, use AskUserQuestion:
+
+- **Create regression task** — add a new task to the board
+- **Investigate further** — continue debugging with another pattern
+- **No action** — acknowledge and stop
+
+If creating a regression task:
+1. Read `.codeloop/board.json`
+2. Add a new task:
+   - Title: "Fix: <error summary>"
+   - Status: `backlog`
+   - Labels: `regression`, `env:prod-fail` (or appropriate env)
+   - Description: error details, log excerpt, and correlation info
+3. Write updated board
+4. Report: "Regression task t-XXX created on the board."
+
+## Phase 6: Report
+
+```
+## Debug Summary
+
+**Environment**: production
+**Health**: ✓ healthy
+**Errors found**: 3 in last 50 lines
+**Pattern searched**: "auth"
+**Matches**: 7 entries
+
+### Action Taken
+Created regression task t-005: "Fix: TypeError in auth middleware"
+```
+
+## Rules
+
+- **Read-only by default.** This skill investigates — it doesn't fix or deploy.
+- **Respect rate limits.** Don't hammer log endpoints. One query per debug session unless the user asks for more.
+- **Surface correlations, don't blame.** "This file was changed recently" ≠ "this commit caused the bug."
+- **Create tasks, not panic.** Regressions get tracked on the board — systematic, not reactive.
+- **Config is required.** Without debug commands in config, this skill can't do anything. Guide the user to set them up.

package/templates/commands/deploy.md

@@ -0,0 +1,144 @@
+---
+description: Deploy to staging or production with verification gates
+argument-hint: <staging|prod> [--force]
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion
+---
+
+<!-- codeloop-version: 0.3.0 -->
+
+# /deploy
+
+Deploy to staging or production with pre-deploy gates and post-deploy verification.
+
+## Usage
+
+```bash
+/deploy staging          # Deploy to staging + verify
+/deploy prod             # Deploy to production (requires staging pass)
+/deploy staging --force  # Skip pre-deploy gate check
+/deploy prod --force     # Skip staging requirement (use with caution)
+```
+
+## Phase 1: Pre-Deploy Gate
+
+1. Read `.codeloop/config.yaml` — load the `deploy` section:
+   ```yaml
+   deploy:
+     staging:
+       command: "make deploy-staging"
+       verify: "make smoke-test-staging"
+     production:
+       command: "make deploy-prod"
+       verify: "make smoke-test-prod"
+       requires: staging
+   ```
+
+2. If no `deploy` section, no command for the target environment, or the command is an empty string → stop with:
+   "No deploy command configured for `<env>`. Add it to `.codeloop/config.yaml` under `deploy.<env>.command`."
+   **Important**: An empty string (`command: ""`) means "not configured" — do NOT execute it.
+
+3. Read `.codeloop/board.json` — find the active task
+
+4. **Gate checks** (skip with `--force`):
+   - For `staging`: task must have `env:local-pass` label (set by `/qa`)
+   - For `prod`: task must have `env:staging-pass` label AND the `production.requires` field is checked
+   - If gate fails → show what's missing and stop
+
+5. Show the deploy plan and confirm:
+   ```
+   ## Deploy Plan
+
+   **Target**: staging
+   **Task**: t-003 — Add user authentication
+   **Command**: make deploy-staging
+   **Verify**: make smoke-test-staging
+
+   Proceed?
+   ```
+   Use AskUserQuestion: **Deploy** / **Abort**
+
+## Phase 2: Deploy
+
+1. Run the deploy command from config
+2. Capture stdout/stderr
+3. If command exits non-zero → report failure and stop:
+   ```
+   ## Deploy Failed
+
+   **Target**: staging
+   **Exit code**: 1
+   **Output**: (last 30 lines)
+   ...
+
+   Deploy aborted. Fix the issue and retry with `/deploy staging`.
+   ```
+
+## Phase 3: Verify
+
+If a `verify` command is configured for this environment:
+
+1. Wait 5 seconds for the deployment to stabilize (configurable services may need warm-up)
+2. Run the verify command
+3. If verify exits non-zero → report failure:
+   ```
+   ## Verification Failed
+
+   **Target**: staging
+   **Deploy**: succeeded
+   **Verify**: FAILED
+   **Output**: (last 30 lines)
+   ...
+
+   The deployment succeeded but verification failed.
+   Check the verify command output and re-run `/deploy staging` after fixing.
+   ```
+
+If no verify command → skip verification, report deploy-only result.
+
+## Phase 4: Board Sync
+
+On successful deploy + verify:
+
+1. Update the active task in `.codeloop/board.json`:
+   - For staging: add label `env:staging-pass`, remove any `env:staging-fail`
+   - For prod: add label `env:prod-pass`, remove any `env:prod-fail`
+   - Write updated board
+
+2. On failure:
+   - Add label `env:staging-fail` or `env:prod-fail`
+   - Write updated board
+
+## Phase 5: Report
+
+```
+## Deploy Complete
+
+**Target**: staging
+**Task**: t-003 — Add user authentication
+**Deploy**: ✓ succeeded
+**Verify**: ✓ passed
+**Label**: env:staging-pass
+
+Next: `/deploy prod` when ready.
+```
+
+Or for production:
+```
+## Deploy Complete
+
+**Target**: production
+**Task**: t-003 — Add user authentication
+**Deploy**: ✓ succeeded
+**Verify**: ✓ passed
+**Label**: env:prod-pass
+
+Task is production-verified. Close with `/manage close` or `/ship`.
+```
+
+## Rules
+
+- **Never deploy without confirmation.** Always show the plan and ask.
+- **Respect the gate chain.** `local-pass` → `staging-pass` → `prod-pass`. Don't skip stages without `--force`.
+- **`--force` is tracked.** If used, add a `deploy:forced` label to the task — visible on the board.
+- **Verify is not optional.** If a verify command is configured, it runs. Failures are reported even though the deploy succeeded.
+- **This skill runs commands — it doesn't know your infra.** The user is responsible for configuring correct deploy and verify commands.

package/templates/commands/design.md

@@ -0,0 +1,102 @@
+---
+description: Architecture before code — generate lightweight spec from codebase analysis
+argument-hint: [description]
+allowed-tools: Read, Write, Edit, Glob, Grep, AskUserQuestion, EnterPlanMode
+---
+
+<!-- codeloop-version: 0.3.0 -->
+
+# /design
+
+Understand a codebase and generate an architectural spec before planning implementation.
+
+## Usage
+
+```bash
+/design                    # Analyze current project, prompt for focus area
+/design <description>      # Generate spec for a specific feature or change
+```
+
+## Phase 1: Discover
+
+1. Read `.codeloop/config.yaml` for project context (scopes, structure)
+2. Scan the project structure — identify key directories, entry points, and config files:
+   - Package managers: `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`
+   - Framework configs: `next.config.*`, `vite.config.*`, `tsconfig.json`, `Dockerfile`
+   - Entry points: `src/index.*`, `src/main.*`, `cmd/`, `app/`
+3. Identify the tech stack, dependencies, and architectural patterns already in use
+4. Read `.codeloop/patterns.md` for established patterns
+5. Read `.codeloop/gotchas.md` for known pitfalls
+
+## Phase 2: Analyze
+
+Based on the task description, deep-dive into the relevant parts of the codebase:
+
+1. Map the modules and their boundaries (imports, exports, interfaces)
+2. Identify data flow — how data moves through the system
+3. Find integration points — where the new work connects to existing code
+4. Check for existing abstractions that should be reused vs. new ones needed
+5. Note any constraints (framework conventions, dependency versions, API contracts)
+
+## Phase 3: Spec
+
+Write the design spec to `tasks/design-<slug>.md`:
+
+```markdown
+# Design: <title>
+
+## Goals
+- <What this achieves for the user>
+- <What this achieves technically>
+
+## Approach
+<High-level strategy — 2-3 sentences max>
+
+## Architecture
+
+### Current State
+<Brief description of how the relevant parts work today>
+
+### Proposed Changes
+<What changes and why>
+
+### Files to Change
+| File | Change | Rationale |
+|------|--------|-----------|
+| `path/to/file.ts` | Add X | Because Y |
+
+### New Files (if any)
+| File | Purpose |
+|------|---------|
+| `path/to/new.ts` | Description |
+
+## Risks
+- <Risk 1 — and mitigation>
+- <Risk 2 — and mitigation>
+
+## Alternatives Considered
+- <Alternative 1 — why rejected>
+
+## Dependencies
+- <External libs, APIs, or services needed>
+
+## Open Questions
+- <Anything that needs clarification before implementation>
+```
+
+## Phase 4: Board Sync
+
+If `.codeloop/board.json` exists:
+1. Read the board
+2. Create a new task with `status: "planned"` and title matching the design
+3. Add steps derived from the "Files to Change" section
+4. Write the updated board back
+
+## Rules
+
+- **Don't write code.** This is analysis and specification only.
+- **Keep it lightweight.** The spec should fit on one screen — if it's longer, the scope is too big.
+- **Flag unknowns.** If you're not sure about something, put it in Open Questions rather than guessing.
+- **Reuse patterns.** If `.codeloop/patterns.md` has a relevant pattern, reference it — don't reinvent.
+- **One spec per feature.** Don't combine unrelated changes into one design doc.
+- **Next step: `/plan`** — after the design is written, run `/plan` to create the implementation plan. `/plan` will read the design spec automatically.

package/templates/commands/manage.md

@@ -0,0 +1,77 @@
+---
+description: Track task progress — read/update tasks/todo.md
+allowed-tools: Read, Write, Edit, Glob, Grep, AskUserQuestion
+---
+
+<!-- codeloop-version: 0.3.0 -->
+
+# /manage
+
+Track progress on the current task. Read and update `tasks/todo.md`.
+
+## Usage
+
+```bash
+/manage              # Show current task status
+/manage done <n>     # Mark step N as complete
+/manage add <step>   # Add a new step
+/manage close        # Mark task as done (moves to Done column)
+/manage summary      # Generate progress summary
+```
+
+## How It Works
+
+### Show Status (default)
+
+1. Read `tasks/todo.md`
+2. Show:
+   - Task title and context
+   - Checklist with completion status
+   - Next uncompleted step highlighted
+
+### Mark Complete (`done <n>`)
+
+1. Read `tasks/todo.md`
+2. Change step N from `- [ ]` to `- [x]`
+3. **Board sync** — if `.codeloop/board.json` exists:
+   - Read the board JSON
+   - Find the matching task: search by exact title from `tasks/todo.md`'s `# Task:` heading. If no exact match, use the first task with status `planned`, `in_progress`, or `backlog` (in that priority order)
+   - If no task found, warn: "Board sync skipped — no matching task found in board.json"
+   - Update the corresponding step's `done` field to `true`
+   - Update task status based on progress:
+     - First step marked done → set status to `in_progress`
+     - All steps marked done → set status to `review`
+   - Write the updated board back to `.codeloop/board.json`
+4. If all steps complete, show completion summary
+
+### Close Task (`close`)
+
+1. Read `tasks/todo.md` — verify all steps are `- [x]` (complete)
+2. If steps remain incomplete, warn: "N steps still unchecked — close anyway?" (use AskUserQuestion)
+3. **Board sync** — if `.codeloop/board.json` exists:
+   - Find the matching task (same lookup as `done <n>`)
+   - Set task status to `done`
+   - Write the updated board back to `.codeloop/board.json`
+4. Archive: rename `tasks/todo.md` to `tasks/done/<title-slug>.md` (create dir if needed)
+5. Show: "Task closed. Board updated."
+
+### Add Step (`add <step>`)
+
+1. Read `tasks/todo.md`
+2. Append new step to the plan
+3. Show updated checklist
+
+### Summary (`summary`)
+
+Generate a concise summary of:
+- What's done
+- What's remaining
+- Any blockers or gotchas encountered
+- Time/effort estimate for remaining work
+
+## Rules
+
+- **tasks/todo.md is the source of truth.** All task state lives here.
+- **Update as you go.** Don't wait until the end to mark things complete.
+- **Be honest about blockers.** If stuck, say so in the summary.
+- **Verify before marking done.** Each step should have evidence of completion.

package/templates/commands/plan.md

@@ -0,0 +1,84 @@
+---
+description: Plan a task — write spec to tasks/todo.md, enter plan mode
+allowed-tools: Read, Write, Edit, Glob, Grep, AskUserQuestion, EnterPlanMode
+---
+
+<!-- codeloop-version: 0.3.0 -->
+
+# /plan
+
+Plan before building. Write specs to `tasks/todo.md`, get approval, then execute.
+
+## Usage
+
+```bash
+/plan                    # Start planning (enter plan mode)
+/plan <description>      # Plan a specific task
+```
+
+## Phase 1: Understand
+
+1. Read the task description (from argument or ask the user)
+2. Check for an existing design spec in `tasks/design-*.md` — if one exists for this task, use it as the starting point (goals, approach, files to change, risks)
+3. Read `.codeloop/config.yaml` for project context (scopes, conventions)
+4. Read `.codeloop/gotchas.md` — scan for relevant gotchas that could affect the plan
+5. Read `.codeloop/patterns.md` — check for established patterns to follow
+
+## Phase 2: Plan
+
+Enter plan mode and explore the codebase:
+
+1. Identify affected files and modules
+2. Check for existing patterns that should be followed
+3. Consider gotchas that apply to the planned changes
+4. Write the plan to `tasks/todo.md` using test-first structure:
+
+```markdown
+# Task: <title>
+
+## Context
+<Why this task exists, what problem it solves>
+
+## Acceptance Criteria
+- <criterion 1 — what must be true when done>
+- <criterion 2>
+
+## Tests (RED)
+Define failing tests before writing implementation code:
+- <test case 1>
+- <test case 2>
+
+## Plan
+- [ ] Step 1: Write tests for acceptance criteria (RED)
+- [ ] Step 2: Write minimum code to pass tests (GREEN)
+- [ ] Step 3: Refactor while tests stay green
+- [ ] ...
+
+## Gotchas to Watch
+- <relevant gotchas from .codeloop/gotchas.md>
+
+## Files to Change
+- `path/to/file.ts` — <what changes>
+```
+
+5. **Board sync** — if `.codeloop/board.json` exists, create a task on the board:
+   - Read `.codeloop/board.json`
+   - Add a new task with `status: "planned"`, title matching the plan title, and steps matching the plan checklist
+   - Write the updated board back to `.codeloop/board.json`
+
+6. Exit plan mode for user approval
+
+## Phase 3: Execute
+
+After approval, work through the plan:
+
+1. Mark each step as you complete it (update `tasks/todo.md`)
+2. If the plan needs adjustment, update it and explain why
+3. Verify each step works before moving to the next
+
+## Rules
+
+- **3+ steps = always plan first.** Don't wing it.
+- **Stop and re-plan if things go sideways.** The plan is a living document.
+- **Staff engineer bar.** Before marking complete: "Would a staff engineer approve this?"
+- **Gotchas are warnings.** Check `.codeloop/gotchas.md` before each risky step.

package/templates/commands/qa.md

@@ -0,0 +1,155 @@
+---
+description: Quality gate — run all checks before promoting a task
+argument-hint: [--strict] [--skip-tests]
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion
+---
+
+<!-- codeloop-version: 0.3.0 -->
+
+# /qa
+
+The quality gate between coding and deployment. Runs all configured checks and gates task promotion.
+
+> **When to use `/qa` vs `/test`**: `/test` is for quick dev feedback — run a suite, check coverage, iterate. `/qa` is the formal gate — it runs everything (`quality_checks` + `diff_scan` + full test suite + coverage threshold + integrity checks) and sets the `env:local-pass` label that unlocks `/deploy staging`. Use `/qa` when the task is code-complete and ready for promotion.
+
+## Usage
+
+```bash
+/qa                # Run full QA suite for active task
+/qa --strict       # Fail on warnings too (not just errors)
+/qa --skip-tests   # Skip test suite (only run static checks)
+```
+
+## Phase 1: Gather Context
+
+1. Read `.codeloop/config.yaml` — load `test`, `quality_checks`, `diff_scan` sections
+2. Read `.codeloop/board.json` — find the active task (first `in_progress`, then `planned`)
+3. Get the git diff since the task started:
+   - If the task has commits, diff from the first commit to HEAD
+   - If no commits yet, diff from HEAD (unstaged + staged changes)
+4. Map changed files to scopes (same logic as `/commit` Phase 1)
+
+## Phase 2: Run Checks
+
+Execute each check category in order. A failure in any REQUIRED check blocks promotion.
+
+### 2.1 Static Analysis
+
+Run `quality_checks` from config for active scopes:
+
+```yaml
+quality_checks:
+  backend:
+    - name: "Typecheck"
+      command: "npx tsc --noEmit 2>&1 | tail -20"
+```
+
+Each check: run command, capture output, exit 0 = PASS, non-zero = FAIL.
+
+### 2.2 Diff Scan
+
+Run `diff_scan` rules from config against the diff (same as `/commit` Phase 1.5):
+
+```yaml
+diff_scan:
+  - pattern: "console\\.log"
+    files: "*.ts,*.js"
+    severity: CRITICAL
+    message: "console.log in production code"
+```
+
+### 2.3 Test Suite
+
+Run the test command from config (same as `/test`):
+
+```yaml
+test:
+  command: "npm test"
+  coverage_threshold: 80
+  integrity_checks: true
+```
+
+Parse results: pass/fail/skip counts and coverage percentage.
+
+If `integrity_checks: true`, scan test output for suspicious patterns:
+- Tests with zero assertions
+- `expect(true).toBe(true)` or equivalent no-op assertions
+- Skipped tests (`.skip`, `@pytest.mark.skip`) — count but don't fail
+- Caught exceptions that are silently swallowed
+
+### 2.4 Coverage Gate
+
+If `test.coverage_threshold` is set:
+- Coverage >= threshold → PASS
+- Coverage < threshold → FAIL with gap report
+
+Pass `--skip-tests` to bypass 2.3 and 2.4 (only run static checks).
+
+## Phase 3: Report
+
+```
+## QA Report
+
+**Task**: t-003 — Add user authentication
+**Scopes**: backend, tests
+**Mode**: standard (--strict would fail on warnings too)
+
+### Results
+
+| Check | Status | Details |
+|-------|--------|---------|
+| Typecheck | ✓ PASS | Clean |
+| Lint | ✓ PASS | Clean |
+| Diff scan | ⚠ WARN | 1 TODO comment found |
+| Tests | ✓ PASS | 42/42 passed (3.2s) |
+| Coverage | ✓ PASS | 84% (threshold: 80%) |
+| Integrity | ✓ PASS | No suspicious patterns |
+
+### Verdict: PASS (1 warning)
+
+Ready to promote to review.
+```
+
+Verdicts:
+- **PASS** — all required checks pass, warnings are informational
+- **WARN** — warnings present but no failures (blocked in `--strict` mode)
+- **FAIL** — one or more required checks failed, promotion blocked
+
+### On FAIL
+
+Show each failure with details:
+- What failed and why
+- The specific output or pattern that triggered it
+- Suggestion for how to fix
+
+Use AskUserQuestion:
+- **Fix issues** — stop, user fixes and re-runs `/qa`
+- **Override and promote** — bypass the gate (adds `qa:override` label)
+- **Abort** — stop entirely
+
+### On PASS
+
+Continue to Phase 4.
+
+## Phase 4: Promote
+
+If all checks pass (or user overrides):
+
+1. **Board sync** — update the active task:
+   - Set status to `review`
+   - Add label: `env:local-pass`
+   - Add label: `qa:pass` (or `qa:override` if overridden)
+   - Remove any existing `qa:fail` label
+   - Write updated board
+
+2. **History** — append to `.codeloop/test-history.json` if tests were run
+
+3. Report: "Task t-003 promoted to review. Ready for `/deploy staging`."
+
+## Rules
+
+- **The gate is the contract.** `/qa` is what prevents "it works on my machine."
+- **Don't skip tests unless asked.** The `--skip-tests` flag exists for iteration speed, not for cheating.
+- **Warnings are informational in standard mode.** They don't block unless `--strict`.
+- **Override is tracked.** `qa:override` label is visible on the board — it's a code smell, not a secret.
+- **Run before every deploy.** `/deploy` checks for the `env:local-pass` label.