@protoboxai/codeloop 0.3.0

package/templates/commands/reflect.md

@@ -0,0 +1,93 @@
+---
+description: Session-end reflection — capture what you learned
+allowed-tools: Read, Write, Edit, Glob, Grep, AskUserQuestion, Bash
+---
+
+<!-- codeloop-version: 0.3.0 -->
+
+# /reflect
+
+Pause and think about what happened this session. Propose changes — but **nothing gets written without approval**.
+
+> **Tip:** For lightweight inline reflection during commits, `/commit` Phase 2 handles it automatically. Use standalone `/reflect` for deeper multi-commit session reviews.
+
+## Phase 1: Think
+
+Look back at the session and identify:
+
+1. **Gotchas** — Unexpected behavior, hidden dependencies, undocumented quirks
+2. **Better approaches** — Wrong turns, wasted time, things you'd do differently
+3. **Patterns** — Approaches that worked well, shortcuts discovered
+4. **Frequency updates** — Gotchas re-encountered this session (increment freq)
+
+Read `.codeloop/gotchas.md` and `.codeloop/patterns.md` to check for existing entries that were re-encountered.
+
+## Phase 2: Propose
+
+Present a **numbered list** of everything you want to do. Group by type:
+
+```
+## Proposed changes
+
+### Gotchas
+1. NEW: "<description>" → .codeloop/gotchas.md [freq:1]
+2. INCREMENT: "<existing gotcha>" freq:2 → freq:3
+
+### Patterns
+3. NEW: "<description>" → .codeloop/patterns.md
+
+### Rules
+4. PROMOTE: "<gotcha at freq 10+>" → .codeloop/rules.md
+```
+
+Then use **AskUserQuestion** with multiSelect to let the user pick which items to apply. Include all items as options.
+
+## Phase 3: Apply
+
+Only apply the items the user selected. Skip everything else.
+
+### Writing gotchas
+
+New gotchas follow this format:
+
+```markdown
+### [freq:1] Short descriptive title
+**Applies to:** <scope or context>
+**Source:** Discovered <date>
+
+<Description of the gotcha, what went wrong, and the fix>
+```
+
+Place in the appropriate section (create section if needed, matching config.yaml scope sections).
+
+### Incrementing frequency
+
+Find the existing entry, update `[freq:N]` to `[freq:N+1]`.
+
+### Writing patterns
+
+New patterns follow this format:
+
+```markdown
+### Pattern Title
+**Confidence:** LOW/MEDIUM/HIGH
+**Applies to:** <scope or context>
+
+<Description of the pattern with code example if applicable>
+```
+
+### Promoting to rules
+
+When a gotcha reaches freq >= 10, suggest promoting to `.codeloop/rules.md`:
+1. Write a concise rule in rules.md
+2. Add a note to the gotcha: `**Promoted to rules.md**`
+
+After applying, one-line summary: what was saved and where.
+
+## Rules
+
+- If nothing worth saving, just say "Nothing new to capture" and stop
+- No scoring rubrics, no ceremony
+- Keep knowledge files concise — trim old low-freq entries if files get too long
+- **Never write to any file without approval from Phase 2**
+- Frequency = severity: the more a gotcha recurs, the more important it becomes

package/templates/commands/ship.md

@@ -0,0 +1,187 @@
+---
+description: Close the loop — QA, deploy staging, deploy prod, verify, close task
+argument-hint: [--from-staging] [--dry-run]
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion
+---
+
+<!-- codeloop-version: 0.3.0 -->
+
+# /ship
+
+Orchestrate the full pipeline from QA to production. Takes a task from code-complete to done.
+
+## Usage
+
+```bash
+/ship                    # Full pipeline: QA → staging → prod → close
+/ship --from-staging     # Skip QA + staging (already staging-verified)
+/ship --dry-run          # Show what would happen without executing
+```
+
+## Overview
+
+`/ship` chains together existing skills in sequence:
+
+```
+/qa → /deploy staging → /deploy prod → /manage close
+```
+
+Each step is a gate. If any step fails, the pipeline stops and creates a regression task.
+
+## Phase 1: Pre-Flight
+
+1. Read `.codeloop/config.yaml` — verify `deploy` section exists with non-empty staging and production commands (empty string = not configured → stop)
+2. Read `.codeloop/board.json` — find the active task
+3. If no active task → stop: "No active task found. Use `/plan` to create one."
+4. Check current task labels to determine starting point:
+   - Has `env:prod-pass` → "Task already production-verified. Use `/manage close` to finish."
+   - Has `env:staging-pass` (or `--from-staging`) → skip to production deploy
+   - Has `env:local-pass` → skip to staging deploy
+   - No env labels → start from QA
+
+5. If `--dry-run`, show the plan and stop:
+   ```
+   ## Ship Plan (dry run)
+
+   **Task**: t-003 — Add user authentication
+   **Starting from**: QA (no env labels)
+
+   Steps:
+   1. Run /qa (quality gate)
+   2. Deploy to staging + verify
+   3. Deploy to production + verify
+   4. Close task + archive
+
+   No actions taken.
+   ```
+
+## Phase 2: QA Gate
+
+Skip if task already has `env:local-pass`.
+
+1. Run the same checks as `/qa`:
+   - Quality checks for active scopes
+   - Diff scan
+   - Test suite
+   - Coverage gate
+2. If **FAIL** → stop pipeline, report which check failed, create regression task
+3. If **PASS** → add `env:local-pass` label, continue
+
+Report progress:
+```
+## Ship Progress
+
+[✓] QA gate passed
+[ ] Deploy to staging
+[ ] Deploy to production
+[ ] Close task
+```
+
+## Phase 3: Deploy Staging
+
+Skip if task already has `env:staging-pass`.
+
+1. Run staging deploy command from config
+2. If deploy fails → stop pipeline, add `env:staging-fail` label, create regression task
+3. Wait 5 seconds, run staging verify command
+4. If verify fails → stop pipeline, add `env:staging-fail` label, create regression task
+5. If both succeed → add `env:staging-pass` label, continue
+
+```
+## Ship Progress
+
+[✓] QA gate passed
+[✓] Staging deployed + verified
+[ ] Deploy to production
+[ ] Close task
+```
+
+## Phase 4: Deploy Production
+
+**Always confirm before production deploy:**
+
+```
+## Production Deploy
+
+Task t-003 has passed QA and staging verification.
+
+Ready to deploy to production?
+```
+
+Use AskUserQuestion: **Deploy to production** / **Stop here** / **Abort and rollback**
+
+If confirmed:
+1. Run production deploy command from config
+2. If deploy fails → stop, add `env:prod-fail` label, create regression task
+3. Wait 5 seconds, run production verify command
+4. If verify fails → stop, add `env:prod-fail` label, create regression task
+5. If both succeed → add `env:prod-pass` label, continue
+
+```
+## Ship Progress
+
+[✓] QA gate passed
+[✓] Staging deployed + verified
+[✓] Production deployed + verified
+[ ] Close task
+```
+
+## Phase 5: Close
+
+1. Update the board task:
+   - Set status to `done`
+   - Add label: `shipped`
+2. Archive the task file:
+   - Move `tasks/todo.md` to `tasks/done/<task-slug>.md` (create dir if needed)
+3. Final report
+
+## Phase 6: Report
+
+### On Success
+
+```
+## Shipped ✓
+
+**Task**: t-003 — Add user authentication
+**Pipeline**: QA → staging → production → done
+
+| Stage | Status | Duration |
+|-------|--------|----------|
+| QA | ✓ pass | 12s |
+| Staging | ✓ deployed + verified | 45s |
+| Production | ✓ deployed + verified | 52s |
+
+Task archived to `tasks/done/add-user-authentication.md`.
+Board updated: t-003 → done.
+```
+
+### On Failure
+
+```
+## Ship Failed at: staging deploy
+
+**Task**: t-003 — Add user authentication
+**Failed step**: Deploy to staging
+**Error**: Exit code 1 — "Error: no instances available"
+
+Regression task t-006 created: "Fix: staging deploy failure for auth feature"
+Pipeline stopped. Fix the issue and re-run `/ship --from-staging`.
+```
+
+## Regression Task Creation
+
+When any step fails:
+1. Create a new task on the board:
+   - Title: "Fix: <failure summary>"
+   - Status: `backlog`
+   - Labels: `regression`, `env:<stage>-fail`
+   - Description: full error output, which step failed, and the original task reference
+2. The original task stays at its current status (not moved to done)
+
+## Rules
+
+- **Always confirm production.** Never auto-deploy to production — the human makes the final call.
+- **The pipeline is sequential.** QA → staging → prod. No skipping without explicit flags.
+- **Failure creates tracking.** Every failure gets a regression task — nothing falls through the cracks.
+- **Idempotent resumption.** `/ship` checks labels and skips already-passed stages. Safe to re-run after fixing a failure.
+- **`--from-staging` trusts staging.** Use when you've already verified staging manually or in a previous run.

package/templates/commands/test.md

@@ -0,0 +1,133 @@
+---
+description: Run tests, parse results, track coverage history
+argument-hint: [suite] [--watch] [--coverage]
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+---
+
+<!-- codeloop-version: 0.3.0 -->
+
+# /test
+
+Run tests, parse results, and track coverage over time.
+
+> **When to use `/test` vs `/qa`**: Use `/test` for quick feedback during development — run a specific suite, check coverage, iterate. Use `/qa` when you're ready to promote a task — it runs the full test suite plus static analysis, coverage gates, and integrity checks, and sets the `env:local-pass` label that unlocks `/deploy`. `/test` does NOT set env labels.
+
+## Usage
+
+```bash
+/test                    # Run default test command from config
+/test <suite>            # Run specific test suite or file pattern
+/test --watch            # Run in watch mode (if runner supports it)
+/test --coverage         # Run with coverage reporting
+```
+
+## Phase 1: Detect
+
+1. Read `.codeloop/config.yaml` for the `test` section:
+   ```yaml
+   test:
+     command: "npm test"
+     coverage_threshold: 80
+   ```
+2. If no `test.command` configured, auto-detect the test runner:
+   - `package.json` with `scripts.test` → use `npm test`
+   - `vitest.config.*` → `npx vitest run`
+   - `jest.config.*` → `npx jest`
+   - `pyproject.toml` with `[tool.pytest]` → `pytest`
+   - `go.mod` → `go test ./...`
+   - `Cargo.toml` → `cargo test`
+   - If nothing detected → ask the user what command to run
+
+## Phase 2: Run
+
+1. If `<suite>` argument provided, append it to the test command (e.g., `npm test -- src/auth/`)
+2. If `--watch` flag, append watch flag for the detected runner:
+   - vitest: already defaults to watch in dev, use `npx vitest`
+   - jest: `--watch`
+   - pytest: use `pytest-watch` or `ptw`
+   - go: no native watch — inform user
+3. If `--coverage` flag, append coverage flag:
+   - vitest/jest: `--coverage`
+   - pytest: `--cov`
+   - go: `-cover`
+4. Run the command, capture stdout and stderr
+
+## Phase 3: Parse Results
+
+Parse the test runner output to extract:
+
+| Field | Example |
+|-------|---------|
+| Total tests | 42 |
+| Passed | 40 |
+| Failed | 1 |
+| Skipped | 1 |
+| Duration | 3.2s |
+| Coverage % | 82% (if available) |
+| Failed test names | List of specific failures |
+
+If tests **failed**, show:
+- Each failed test name and file
+- The failure message / assertion error
+- Suggestion: which code is likely broken based on the test file path
+
+## Phase 4: Track History
+
+Update `.codeloop/test-history.json` (create if not exists):
+
+```json
+{
+  "runs": [
+    {
+      "timestamp": "2026-02-21T10:30:00Z",
+      "suite": "all",
+      "total": 42,
+      "passed": 40,
+      "failed": 1,
+      "skipped": 1,
+      "coverage": 82,
+      "duration": 3.2,
+      "commit": "abc1234"
+    }
+  ]
+}
+```
+
+Keep the last 50 runs. Older entries are dropped.
+
+Include the current git commit SHA (from `git rev-parse --short HEAD`).
+
+## Phase 5: Report
+
+```
+## Test Results
+
+**Suite**: all | **Runner**: vitest
+**Result**: 40/42 passed, 1 failed, 1 skipped (3.2s)
+**Coverage**: 82% (threshold: 80% ✓)
+
+### Failures
+- `src/auth/login.test.ts` → "expected 200, got 401"
+
+### Trend (last 5 runs)
+  42 ████████████████████ 100%
+  42 ████████████████████ 100%
+  42 ███████████████████░  95%
+  42 ████████████████████ 100%
+  42 ███████████████████░  95%  ← current
+```
+
+## Phase 6: Board Sync
+
+If `.codeloop/board.json` exists:
+- Find the active task (first `in_progress`, then `planned`)
+- Add label: `tests:pass` or `tests:fail` (replace any existing `tests:*` label)
+- If coverage available, add label: `coverage:82%` (replace any existing `coverage:*` label)
+- Write updated board
+
+## Rules
+
+- **Never modify test files.** This skill only runs and reports — it doesn't fix tests.
+- **Respect the config.** If `test.command` is set, use it. Don't override with auto-detection.
+- **Track everything.** Even skipped tests matter — a rising skip count is a warning sign.
+- **Show the trend.** History makes patterns visible — one failure vs. recurring failure.

package/templates/hooks/commit-msg

@@ -0,0 +1,8 @@
+#!/bin/sh
+# Installed by `codeloop init --hooks`. Adds a `Feature: <card-id>` trailer when the branch name
+# contains a card id (feat/CL-001-lane-engine, fix/c-012-export) and the message has none.
+branch=$(git symbolic-ref --quiet --short HEAD) || exit 0
+id=$(printf '%s' "$branch" | grep -oE '[A-Za-z]{1,10}-[0-9]{1,6}' | head -1)
+[ -n "$id" ] || exit 0
+grep -q '^Feature: ' "$1" && exit 0
+git interpret-trailers --in-place --trailer "Feature: $id" "$1"

package/templates/lanes/analyze.yaml

@@ -0,0 +1,25 @@
+id: analyze
+version: 1
+metric: { name: north_star, source: analytics }
+trigger: { cron: "0 9 * * FRI" }
+wip: 1
+retries: 3
+stages:
+  - id: pull
+    skill: reflect
+    output: growth/{id}/metrics.md
+    done: { cmd: "codeloop check file growth/{id}/metrics.md --has 'north_star:'" }
+  - id: compare
+    skill: reflect
+    output: growth/{id}/compare.md
+    done: { cmd: "codeloop check file growth/{id}/compare.md --has 'delta:'" }
+  - id: judge
+    skill: reflect
+    output: growth/{id}/verdicts.md
+    done: { cmd: "codeloop check file growth/{id}/verdicts.md --has 'verdict:'" }
+    gate: { name: verdicts, approver: owner }
+  - id: findings
+    skill: reflect
+    output: growth/{id}/findings.md
+    done: { cmd: "codeloop check file growth/{id}/findings.md --has 'findings:'" }
+on_done: { start: plan }

package/templates/lanes/build.yaml

@@ -0,0 +1,45 @@
+id: build
+version: 1
+metric: { name: cycle_time_days, source: cards, target: "<5" }
+trigger: { manual: true }
+wip: 2
+retries: 3
+stages:
+  - id: research
+    skill: design
+    output: "{spec}/research.md"
+    done: { cmd: "codeloop check research {id} --min-sources 3" }
+  # Optional per card: a card with nothing to draw writes `screens: none` in its spec and passes without a mock.
+  - id: mock
+    skill: design
+    done: { cmd: "codeloop check mock {id}" }
+    notes:
+      - "Name each screen under `screens:` in the card's spec.md, run `codeloop mock new <card> --topic <topic>`, and draw one <section data-screen> per screen in the file it creates."
+  - id: spec
+    skill: plan
+    output: "{spec}/tasks.md"
+    done: { cmd: "codeloop spec check {id}" }
+    gate: { name: spec, approver: owner }
+  - id: build
+    skill: test
+    done: { cmd: "codeloop task check {id} --all-done && npm test" }
+  - id: verify
+    skill: qa
+    output: evidence/{nnn}/verify.md
+    done: { cmd: "codeloop verify {id}" }
+    gate: { name: local, approver: owner }
+  - id: review
+    skill: commit
+    output: evidence/{nnn}/review.md
+    done: { cmd: "codeloop check file evidence/{nnn}/review.md --has 'verdict: approve'" }
+    gate: { name: pr, approver: reviewer }
+  - id: staging
+    skill: deploy
+    output: evidence/{nnn}/staging.md
+    done: { cmd: "codeloop check file evidence/{nnn}/staging.md --has 'result: pass'" }
+  - id: live
+    skill: ship
+    output: evidence/{nnn}/prod.md
+    done: { cmd: "codeloop check file evidence/{nnn}/prod.md --has 'result: pass'" }
+    gate: { name: prod, approver: owner, outward: true }
+on_done: { start: market }

package/templates/lanes/deploy.yaml

@@ -0,0 +1,24 @@
+id: deploy
+version: 1
+metric: { name: change_failure_rate, source: cards, target: "<15%" }
+trigger: { on: git.tag }
+wip: 1
+retries: 3
+stages:
+  - id: staging
+    skill: deploy
+    output: deploy/{id}/staging.md
+    done: { cmd: "codeloop check file deploy/{id}/staging.md --has 'result: pass'" }
+  - id: verify
+    skill: qa
+    output: deploy/{id}/verify.md
+    done: { cmd: "codeloop check file deploy/{id}/verify.md --has 'result: pass'" }
+  - id: prod
+    skill: ship
+    output: deploy/{id}/prod.md
+    done: { cmd: "codeloop check file deploy/{id}/prod.md --has 'result: pass'" }
+    gate: { name: prod, approver: owner, outward: true }
+  - id: smoke
+    skill: debug
+    output: deploy/{id}/smoke.md
+    done: { cmd: "codeloop check file deploy/{id}/smoke.md --has 'result: pass'" }

package/templates/lanes/learn.yaml

@@ -0,0 +1,20 @@
+id: learn
+version: 1
+metric: { name: repeat_gotcha_rate, source: knowledge }
+trigger: { manual: true }
+wip: 2
+retries: 3
+stages:
+  - id: capture
+    skill: reflect
+    output: learn/{id}/capture.md
+    done: { cmd: "codeloop check file learn/{id}/capture.md --has 'gotcha:'" }
+  - id: bump
+    skill: reflect
+    output: learn/{id}/bump.md
+    done: { cmd: "codeloop check file learn/{id}/bump.md --has 'freq:'" }
+  - id: promote
+    skill: reflect
+    output: learn/{id}/promote.md
+    done: { cmd: "codeloop check file learn/{id}/promote.md --has 'rule:'" }
+    gate: { name: rule, approver: owner }

package/templates/lanes/market.yaml

@@ -0,0 +1,25 @@
+id: market
+version: 1
+metric: { name: signups_from_launch, source: analytics, target: "+10%" }
+trigger: { on: lane.done, lane: build }
+wip: 2
+retries: 3
+stages:
+  - id: brief
+    skill: plan
+    output: marketing/{id}/brief.md
+    done: { cmd: "codeloop check file marketing/{id}/brief.md --has 'audience:' 'claim:' 'metric:'" }
+  - id: draft
+    skill: design
+    output: marketing/{id}/blog.md
+    done: { cmd: "codeloop check file marketing/{id}/blog.md --has 'claim:'" }
+    gate: { name: copy, approver: owner }
+  - id: publish
+    skill: ship
+    output: marketing/{id}/published.md
+    done: { cmd: "codeloop check file marketing/{id}/published.md --has 'url:'" }
+    gate: { name: publish, approver: owner, outward: true }
+  - id: measure
+    skill: reflect
+    output: marketing/{id}/result.md
+    done: { cmd: "codeloop check file marketing/{id}/result.md --has 'verdict:'" }

package/templates/lanes/plan.yaml

@@ -0,0 +1,24 @@
+id: plan
+version: 1
+metric: { name: shipped_cards_that_moved_their_metric, source: cards }
+trigger: { cron: "0 9 * * MON" }
+wip: 1
+retries: 3
+stages:
+  - id: gather
+    skill: reflect
+    output: plan/{id}/signals.md
+    done: { cmd: "codeloop check file plan/{id}/signals.md --has 'signals:'" }
+  - id: research
+    skill: design
+    output: plan/{id}/research.md
+    done: { cmd: "codeloop check file plan/{id}/research.md --has 'verdict:'" }
+  - id: rank
+    skill: manage
+    output: plan/{id}/ranked.md
+    done: { cmd: "codeloop check file plan/{id}/ranked.md --has 'rice:'" }
+  - id: story
+    skill: plan
+    output: plan/{id}/stories.md
+    done: { cmd: "codeloop check file plan/{id}/stories.md --has 'acceptance:'" }
+    gate: { name: backlog, approver: owner }

package/templates/lanes/scan.yaml

@@ -0,0 +1,11 @@
+id: scan
+version: 1
+metric: { name: competitor_proposals_promoted, source: cards }
+trigger: { cron: "0 7 * * MON" }
+wip: 1
+retries: 3
+stages:
+  # The stage is its command: it reads the changelog on each page in .codeloop/wiki/competitors/
+  # and proposes a plan card for what is new. The cards wait in the inbox; nothing starts them.
+  - id: scan
+    done: { cmd: "codeloop scan competitors" }

package/templates/lanes/triage.yaml

@@ -0,0 +1,24 @@
+id: triage
+version: 1
+metric: { name: proposals_accepted_ratio, source: cards }
+trigger: { cron: "0 20 * * *" }
+wip: 1
+retries: 3
+stages:
+  - id: capture
+    skill: debug
+    output: triage/{id}/capture.md
+    done: { cmd: "codeloop check file triage/{id}/capture.md --has 'sources:'" }
+  - id: classify
+    skill: manage
+    output: triage/{id}/classified.md
+    done: { cmd: "codeloop check file triage/{id}/classified.md --has 'category:'" }
+  - id: dedupe
+    skill: manage
+    output: triage/{id}/deduped.md
+    done: { cmd: "codeloop check file triage/{id}/deduped.md --has 'duplicates:'" }
+  - id: file
+    skill: manage
+    output: triage/{id}/proposals.md
+    done: { cmd: "codeloop check file triage/{id}/proposals.md --has 'proposals:'" }
+    gate: { name: proposals, approver: owner }