@protoboxai/codeloop 0.3.0

package/starters/node-typescript.yaml

@@ -0,0 +1,108 @@
+# Codeloop Configuration
+# Node.js + TypeScript starter
+
+project:
+  name: "my-project"
+
+scopes:
+  backend:
+    paths: ["src/**", "lib/**"]
+    gotcha_sections: ["Backend", "Database", "API"]
+    pattern_sections: ["Backend", "API", "Error Handling"]
+  frontend:
+    paths: ["app/**", "components/**", "pages/**"]
+    gotcha_sections: ["Frontend", "React"]
+    pattern_sections: ["Frontend", "Components"]
+  tests:
+    paths: ["**/*.test.*", "**/*.spec.*", "__tests__/**"]
+    gotcha_sections: ["Testing"]
+    pattern_sections: ["Testing"]
+  config:
+    paths: [".github/**", "Dockerfile*", "docker-compose*", "*.config.*"]
+    gotcha_sections: ["CI", "Config"]
+    pattern_sections: ["CI"]
+
+quality_checks:
+  backend:
+    - name: "Typecheck"
+      command: "npx tsc --noEmit 2>&1 | tail -20"
+  frontend:
+    - name: "Typecheck"
+      command: "npx tsc --noEmit 2>&1 | tail -20"
+
+diff_scan:
+  - pattern: "console\\.log"
+    files: "*.ts,*.tsx,*.js,*.jsx"
+    exclude: "*.test.*,*.spec.*"
+    severity: CRITICAL
+    message: "console.log in production code"
+  - pattern: "\\.env"
+    files: "*"
+    severity: CRITICAL
+    message: ".env file should not be committed"
+  - pattern: "any\\b"
+    files: "*.ts,*.tsx"
+    exclude: "*.test.*,*.spec.*,*.d.ts"
+    severity: WARNING
+    message: "Explicit 'any' type — consider a specific type"
+
+# Testing — used by /test and /qa
+test:
+  command: "npm test"
+  coverage_threshold: 80
+  integrity_checks: true
+
+# Deployment — used by /deploy and /ship
+# Uncomment and fill in your deploy commands:
+# deploy:
+#   staging:
+#     command: "make deploy-staging"    # or "vercel --env preview"
+#     verify: "curl -sf https://staging.example.com/health"
+#   production:
+#     command: "make deploy-prod"       # or "vercel --prod"
+#     verify: "curl -sf https://example.com/health"
+#     requires: staging
+
+# Debugging — used by /debug
+# Uncomment and fill in your log/health commands:
+# debug:
+#   logs: "fly logs --app myapp"       # or "vercel logs"
+#   health: "curl -sf https://example.com/health"
+
+commit:
+  types: [feat, fix, refactor, docs, test, chore, perf]
+  format: "type(scope): message"
+
+# Watch mode — used by `codeloop watch`
+watch:
+  enabled: true
+  idle_timeout: 300
+  signals:
+    file_change: true
+    git_commit: true
+    test_result: true
+    build_status: true
+    idle: true
+  ignore:
+    - node_modules
+    - dist
+    - .git
+    - "*.log"
+
+# Unattended runs — used by `codeloop run --agent` and `codeloop schedule install`.
+# The command gets the stage brief; {brief} becomes the shell-quoted path to it.
+# agents:
+#   default: claude
+#   claude:
+#     cmd: "claude -p --permission-mode acceptEdits < {brief}"
+#     timeout_minutes: 20        # the agent is killed after this
+#     max_runs_per_day: 20       # agent starts across the project in any 24 hours
+#   codex:
+#     cmd: "codex exec - < {brief}"
+# run:
+#   agent: true                  # plain `codeloop run` starts agents too
+
+codeloop:
+  critical_frequency: 3
+  promote_frequency: 10
+  max_knowledge_lines: 200

package/starters/python.yaml

@@ -0,0 +1,105 @@
+# Codeloop Configuration
+# Python starter
+
+project:
+  name: "my-project"
+
+scopes:
+  backend:
+    paths: ["src/**", "app/**", "lib/**"]
+    gotcha_sections: ["Backend", "Database", "API"]
+    pattern_sections: ["Backend", "API"]
+  tests:
+    paths: ["tests/**", "**/*_test.py", "**/test_*.py"]
+    gotcha_sections: ["Testing"]
+    pattern_sections: ["Testing"]
+  config:
+    paths: [".github/**", "Dockerfile*", "docker-compose*", "pyproject.toml", "setup.py"]
+    gotcha_sections: ["CI", "Config"]
+    pattern_sections: ["CI"]
+
+quality_checks:
+  backend:
+    - name: "Type check"
+      command: "mypy src/ 2>&1 | tail -20"
+    - name: "Lint"
+      command: "ruff check src/ 2>&1 | tail -20"
+
+diff_scan:
+  - pattern: "print\\("
+    files: "*.py"
+    exclude: "test_*,*_test.py,conftest.py"
+    severity: WARNING
+    message: "print() in production code — use logging"
+  - pattern: "import pdb"
+    files: "*.py"
+    severity: CRITICAL
+    message: "Debugger import left in code"
+  - pattern: "\\.env"
+    files: "*"
+    severity: CRITICAL
+    message: ".env file should not be committed"
+
+# Testing — used by /test and /qa
+test:
+  command: "pytest"
+  coverage_threshold: 80
+  integrity_checks: true
+
+# Deployment — used by /deploy and /ship
+# Uncomment and fill in your deploy commands:
+# deploy:
+#   staging:
+#     command: "make deploy-staging"
+#     verify: "curl -sf https://staging.example.com/health"
+#   production:
+#     command: "make deploy-prod"
+#     verify: "curl -sf https://example.com/health"
+#     requires: staging
+
+# Debugging — used by /debug
+# Uncomment and fill in your log/health commands:
+# debug:
+#   logs: "journalctl -u myapp --no-pager -n 50"
+#   health: "curl -sf https://example.com/health"
+
+commit:
+  types: [feat, fix, refactor, docs, test, chore, perf]
+  format: "type(scope): message"
+
+# Watch mode — used by `codeloop watch`
+watch:
+  enabled: true
+  idle_timeout: 300
+  signals:
+    file_change: true
+    git_commit: true
+    test_result: true
+    build_status: true
+    idle: true
+  ignore:
+    - __pycache__
+    - .venv
+    - venv
+    - dist
+    - .git
+    - "*.log"
+    - "*.pyc"
+
+# Unattended runs — used by `codeloop run --agent` and `codeloop schedule install`.
+# The command gets the stage brief; {brief} becomes the shell-quoted path to it.
+# agents:
+#   default: claude
+#   claude:
+#     cmd: "claude -p --permission-mode acceptEdits < {brief}"
+#     timeout_minutes: 20        # the agent is killed after this
+#     max_runs_per_day: 20       # agent starts across the project in any 24 hours
+#   codex:
+#     cmd: "codex exec - < {brief}"
+# run:
+#   agent: true                  # plain `codeloop run` starts agents too
+
+codeloop:
+  critical_frequency: 3
+  promote_frequency: 10
+  max_knowledge_lines: 200

package/templates/ci/codeloop-pr.yml

@@ -0,0 +1,29 @@
+# Written by `codeloop init --ci github`.
+name: codeloop pr
+on:
+  pull_request:
+
+jobs:
+  gate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm run build --if-present
+      - run: npm test
+      - run: npx --yes @protoboxai/codeloop lane lint
+      - name: Every commit carries a Feature trailer
+        run: |
+          missing=0
+          for sha in $(git log --no-merges --format=%H "origin/${{ github.base_ref }}..HEAD"); do
+            if [ -z "$(git log -1 --format='%(trailers:key=Feature,valueonly)' "$sha")" ]; then
+              echo "::error::commit $sha has no Feature: <card-id> trailer"
+              missing=1
+            fi
+          done
+          exit $missing

package/templates/ci/codeloop-prod.yml

@@ -0,0 +1,27 @@
+# Written by `codeloop init --ci github`. The `production` environment is the human gate: give it
+# required reviewers in the repository settings and the job waits for one of them.
+name: codeloop prod
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  prod:
+    runs-on: ubuntu-latest
+    environment: production
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm run build --if-present
+      - name: Deploy to production
+        run: |
+          cmd=$(npx --yes @protoboxai/codeloop config get deploy.production.command)
+          [ -n "$cmd" ] || cmd=$(npx --yes @protoboxai/codeloop config get deploy.prod.command)
+          if [ -z "$cmd" ]; then
+            echo "deploy.production.command is not set; nothing to deploy"
+            exit 0
+          fi
+          sh -c "$cmd"

package/templates/ci/codeloop-staging.yml

@@ -0,0 +1,34 @@
+# Written by `codeloop init --ci github`. Does nothing until deploy.staging.command is set in .codeloop/config.yaml.
+name: codeloop staging
+on:
+  push:
+    branches: [main]
+
+jobs:
+  staging:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm run build --if-present
+      - name: Deploy to staging
+        id: deploy
+        run: |
+          cmd=$(npx --yes @protoboxai/codeloop config get deploy.staging.command)
+          if [ -z "$cmd" ]; then
+            echo "deploy.staging.command is not set; nothing to deploy"
+            exit 0
+          fi
+          sh -c "$cmd"
+          echo "deployed=true" >> "$GITHUB_OUTPUT"
+      - name: Verify the shipped cards against staging
+        if: steps.deploy.outputs.deployed == 'true'
+        run: |
+          for id in $(git log --format='%(trailers:key=Feature,valueonly)' "${{ github.event.before }}..${{ github.sha }}" | sort -u); do
+            npx --yes @protoboxai/codeloop verify "$id" --env staging --no-record
+          done

package/templates/codeloop/board.json

@@ -0,0 +1,5 @@
+{
+  "version": 1,
+  "columns": ["backlog", "planned", "in_progress", "review", "done"],
+  "tasks": []
+}

package/templates/codeloop/gotchas.md

@@ -0,0 +1,13 @@
+# Gotchas
+
+Cross-cutting gotchas discovered during development. Sorted by frequency (highest first).
+New entries added via `/commit` and `/reflect`. Frequency incremented when re-encountered.
+
+Frequency determines severity in `/commit` review:
+- `freq >= 3` → CRITICAL (blocks commit unless overridden)
+- `freq 1-2` → WARNING (non-blocking)
+- `freq >= 10` → Consider promoting to `rules.md`
+
+---
+
+<!-- Add gotchas below, organized by section. Sections should match your config.yaml gotcha_sections. -->

package/templates/codeloop/patterns.md

@@ -0,0 +1,15 @@
+# Patterns
+
+Proven patterns used in this project. Confidence levels based on adoption.
+New entries added via `/commit` and `/reflect`.
+
+Confidence levels:
+- **HIGH** — Used consistently, well-tested
+- **MEDIUM** — Used in some places, works well
+- **LOW** — Experimental, needs more validation
+
+HIGH-confidence patterns are checked during `/commit` review — deviations trigger warnings.
+
+---
+
+<!-- Add patterns below, organized by section. Sections should match your config.yaml pattern_sections. -->

package/templates/codeloop/principles.md

@@ -0,0 +1,49 @@
+# Operating Principles
+
+These principles guide how Claude Code works in this project. They're loaded as context for all flywheel skills.
+
+---
+
+## 1. Plan Mode Default
+
+3+ steps = plan first. Write the plan to `tasks/todo.md`. Get approval before building. STOP and re-plan if things go sideways.
+
+## 2. Subagent Strategy
+
+Offload research and exploration to subagents. One task per subagent. Keep the main context clean for implementation work.
+
+## 3. Self-Improvement Loop
+
+After any correction or discovery:
+- Capture gotchas and patterns via `/commit` or `/reflect`
+- Frequency = severity: the more something recurs, the more critical it becomes
+- `freq >= 3` = CRITICAL in next `/commit` review
+
+## 4. Verification Before Done
+
+Never mark a task complete without proof. Run tests, check logs, verify the output. Ask yourself: "Would a staff engineer approve this?"
+
+## 5. Demand Elegance (Balanced)
+
+For non-trivial changes, pause and ask "is there a more elegant way?" Skip this for simple fixes — don't over-engineer.
+
+## 6. Autonomous Bug Fixing
+
+Given a bug? Just fix it. Zero hand-holding. Point at evidence, resolve it. Don't ask for permission to investigate.
+
+## 7. Simplicity First
+
+Minimal code, minimal impact. Touch only what's necessary. The right amount of complexity is the minimum needed for the current task.
+
+## 8. No Laziness
+
+Root causes only. Don't patch symptoms. Don't skip hard problems. Don't leave broken things behind.
+
+## 9. TDD Default
+
+Write acceptance criteria first. Define tests before code. Follow RED → GREEN → REFACTOR:
+1. **RED** — Write failing tests that define what "done" looks like
+2. **GREEN** — Write the minimum code to make tests pass
+3. **REFACTOR** — Clean up while tests stay green
+
+Not every change needs full TDD, but any non-trivial feature or bug fix benefits from defining expected behavior before implementation.

package/templates/codeloop/rules.md

@@ -0,0 +1,23 @@
+# Rules
+
+Non-negotiable rules for this project. These are always loaded as CRITICAL by `/commit`.
+
+Add project-specific rules here. Start with these universals:
+
+---
+
+## 1. Errors = Failure
+
+Never rationalize error codes. 404/401/500 means something is broken — fix it or report it.
+
+## 2. Verify Before Claiming Done
+
+A feature "works" when the **user can see/use the result**, not when code compiles. Run the tests, check the output, prove it works.
+
+## 3. Own It
+
+Complete ALL tasks. No "next steps" lists, no "TODO later", no deferring. If something is broken, fix it. If something is missing, add it.
+
+## 4. No Destructive Operations Without Confirmation
+
+`git push`, `git stash`, `git rebase`, force deletes — always confirm with the user first. These affect shared state and can destroy work.

package/templates/commands/commit.md

@@ -0,0 +1,255 @@
+---
+description: Review + reflect + commit in one flow
+argument-hint: [type] [scope] [message] OR [--wip]
+allowed-tools: Bash(git:*), Read, Edit, Write, Glob, Grep, AskUserQuestion
+---
+
+<!-- codeloop-version: 0.3.0 -->
+
+# /commit
+
+Three-phase commit: **Review → Reflect → Commit**.
+
+## Quick Usage
+
+```bash
+/commit                                       # Full flow: review → reflect → commit (auto-generate message)
+/commit feat auth "add login endpoints"       # Full flow with explicit message
+/commit --wip                                 # Skip review + reflect, WIP commit with --no-verify
+```
+
+---
+
+## Phase 1: Review
+
+### 1.1 Get the diff
+
+```bash
+git diff HEAD --name-only
+git status --short
+```
+
+If nothing to commit → say "Nothing to commit" and **stop**.
+
+### 1.2 Determine scopes from changed paths
+
+Read `.codeloop/config.yaml` and map changed files to scopes using the `scopes` section:
+
+```yaml
+scopes:
+  backend:
+    paths: ["src/**", "lib/**"]
+    gotcha_sections: ["Backend", "Database"]
+    pattern_sections: ["Backend", "API"]
+```
+
+Match each changed file against scope paths. A file can match multiple scopes.
+
+If no config.yaml exists, use a single "all" scope that loads everything.
+
+### 1.3 Load dynamic rubrics
+
+Read these files and extract rules matching the active scopes:
+
+1. **`.codeloop/rules.md`** — all rules are always CRITICAL
+2. **`.codeloop/gotchas.md`** — items with `freq >= 3` in matching sections → CRITICAL; `freq 1-2` → WARNING
+3. **`.codeloop/patterns.md`** — HIGH-confidence patterns in matching sections → expectations (deviation = WARNING)
+
+Only load sections relevant to the active scopes. Don't review the entire gotchas file for a docs-only change.
+
+**Scope → rubric section mapping** comes from `config.yaml`:
+- `gotcha_sections` defines which gotcha sections to load for that scope
+- `pattern_sections` defines which pattern sections to load for that scope
+
+### 1.3b Critical wiki pages
+
+If `.codeloop/wiki/` exists, run this with the changed files:
+
+```bash
+codeloop check gotchas --files $(git diff HEAD --name-only)
+```
+
+Exit 1 means a critical page applies to this change. Read each page it prints, confirm the change handles it, then re-run with `--ack "<title>"` for each. Do not commit while it exits 1.
+
+### 1.4 Quality checks
+
+Read `quality_checks` from `.codeloop/config.yaml` and run checks for active scopes:
+
+```yaml
+quality_checks:
+  backend:
+    - name: "Typecheck"
+      command: "npx tsc --noEmit 2>&1 | tail -20"
+```
+
+If any check **fails** → report as a CRITICAL finding.
+
+If no quality_checks defined → skip silently.
+
+### 1.5 Scan diff for violations
+
+Read `diff_scan` rules from `.codeloop/config.yaml`:
+
+```yaml
+diff_scan:
+  - pattern: "console\\.log"
+    files: "*.ts,*.js"
+    exclude: "*.test.*"
+    severity: CRITICAL
+    message: "console.log in production code"
+```
+
+For each rule, scan the actual diff content for matches.
+
+If no diff_scan rules → skip silently.
+
+### 1.6 Output findings
+
+```
+## Review
+
+**Scopes**: backend, frontend
+**Rubrics loaded**: 6 CRITICAL, 3 WARNING from gotchas; 4 patterns checked
+
+| Sev | Finding | File |
+|-----|---------|------|
+| CRITICAL | console.log in service code | src/foo/bar.ts:42 |
+| CRITICAL | Typecheck failed (2 errors) | — |
+| WARNING | Hardcoded string | src/foo/bar.ts:18 |
+| CLEAN | Build passed | — |
+
+**Verdict**: BLOCKED (2 critical)
+```
+
+Verdicts:
+- **CLEAN** — no issues, proceed
+- **WARNINGS** — non-blocking suggestions, proceed to commit
+- **BLOCKED** — critical issues found, must fix before commit
+
+### 1.7 If BLOCKED
+
+Use AskUserQuestion with options:
+- **Fix issues** — stop here, user fixes and re-runs `/commit`
+- **Commit anyway** — override, proceed to Phase 2
+- **Abort** — stop entirely
+
+---
+
+## Phase 2: Reflect (lightweight)
+
+Quickly scan this session for:
+1. **Gotchas** — unexpected behavior, hidden dependencies, bugs found
+2. **Patterns** — approaches that worked well, shortcuts discovered
+
+If anything found → use AskUserQuestion with multiSelect to let user pick what to save.
+
+Save selected items to `.codeloop/gotchas.md` or `.codeloop/patterns.md`.
+
+New gotchas get `[freq:1]`. Place them in the appropriate section (create section if needed).
+
+If nothing worth saving → skip silently, move to Phase 3.
+
+---
+
+## Phase 3: Commit
+
+### 3.1 Stage files
+
+```bash
+git add -A
+git status --short
+```
+
+Show what will be committed.
+
+### 3.2 Build commit message
+
+**If type/scope/message provided as arguments:**
+```
+$TYPE($SCOPE): $MESSAGE
+```
+
+**If auto-generating**, analyze the staged diff:
+- **Type**: Read allowed types from `commit.types` in config.yaml (default: feat, fix, refactor, docs, test, chore, perf)
+- **Scope**: primary directory/feature from changed files
+- **Message**: brief description of the "why", not the "what"
+
+For large commits (10+ files or multiple features), include a body with grouped bullet points.
+
+### 3.3 Create commit
+
+```bash
+git commit -m "$(cat <<'EOF'
+type(scope): message
+
+optional body
+EOF
+)"
+```
+
+### 3.4 Board sync
+
+If `.codeloop/board.json` exists:
+- Read the board JSON
+- Find the active task: first task with status `in_progress`, then `review`, then `planned` (in that priority order)
+- If no task found, warn: "Board sync skipped — no active task found in board.json" (non-blocking, commit still succeeds)
+- Append the new commit SHA to the task's `commits` array
+- Write the updated board back to `.codeloop/board.json`
+
+### 3.5 Report result
+
+```
+## Committed
+
+**Hash**: abc1234
+**Message**: feat(auth): add login endpoints
+**Files**: 5 changed, +120, -30
+```
+
+---
+
+## WIP Mode (`--wip`)
+
+Skip Phase 1 and Phase 2 entirely:
+
+```bash
+git add -A
+git commit -m "chore: WIP" --no-verify
+```
+
+Report the commit hash and stop.
+
+---
+
+## Rubric Evolution
+
+The review gets smarter over time:
+
+```
+Session work → discover gotcha → Phase 2 saves to gotchas.md (freq:1)
+  → re-encountered in future sessions → freq increases via /reflect
+  → next /commit Phase 1 picks it up at higher severity (freq >= 3 = CRITICAL)
+```
+
+No separate rubrics file. `gotchas.md` IS the rubrics source. Frequency = severity.
+
+---
+
+## Commit Types
+
+| Type | When |
+|------|------|
+| `feat` | New feature or capability |
+| `fix` | Bug fix |
+| `refactor` | Code restructuring, no behavior change |
+| `docs` | Documentation only |
+| `test` | Adding/updating tests |
+| `chore` | Maintenance, deps, config |
+| `perf` | Performance improvement |
+
+## Safety Rules
+
+1. **ALWAYS `git add -A` first** — never leave uncommitted work
+2. **Never amend pushed commits**
+3. **Never skip hooks** (except `--wip`)
+4. **Never push** — `/commit` only creates local commits