@sixfactors-ai/codeloop 0.1.0

package/starters/node-typescript.yaml

@@ -0,0 +1,56 @@
+# 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"
+
+commit:
+  types: [feat, fix, refactor, docs, test, chore, perf]
+  format: "type(scope): message"
+
+codeloop:
+  critical_frequency: 3
+  promote_frequency: 10
+  max_knowledge_lines: 200

package/starters/python.yaml

@@ -0,0 +1,50 @@
+# 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"
+
+commit:
+  types: [feat, fix, refactor, docs, test, chore, perf]
+  format: "type(scope): message"
+
+codeloop:
+  critical_frequency: 3
+  promote_frequency: 10
+  max_knowledge_lines: 200

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,245 @@
+---
+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.2.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.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

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
+---
+
+<!-- codeloop-version: 0.2.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,83 @@
+---
+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.2.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. Read `.codeloop/config.yaml` for project context (scopes, conventions)
+3. Read `.codeloop/gotchas.md` — scan for relevant gotchas that could affect the plan
+4. 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.