@sixfactors-ai/codeloop 0.1.1 → 0.2.0

package/starters/generic.yaml

@@ -33,11 +33,48 @@ diff_scan: []
   #   severity: WARNING
   #   message: "TODO comment found"
 
+# Testing — used by /test and /qa
+# test:
+#   command: "npm test"           # or pytest, go test ./..., cargo test
+#   coverage_threshold: 80        # optional, for /qa gate
+#   integrity_checks: true        # scan for fake-pass patterns
+
+# Deployment — used by /deploy and /ship
+# deploy:
+#   staging:
+#     command: ""                  # your staging deploy command
+#     verify: ""                   # post-deploy smoke test
+#   production:
+#     command: ""                  # your production deploy command
+#     verify: ""                   # post-deploy smoke test
+#     requires: staging            # must pass staging first
+
+# Debugging — used by /debug
+# debug:
+#   logs: ""                       # command to tail production logs
+#   health: ""                     # health check URL or command
+
 # Conventional commit types allowed.
 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            # seconds before idle signal
+#   signals:
+#     file_change: true
+#     git_commit: true
+#     test_result: true
+#     build_status: true
+#     idle: true
+#   ignore:
+#     - node_modules
+#     - dist
+#     - .git
+#     - "*.log"
+
 # Codeloop behavior settings.
 codeloop:
   critical_frequency: 3      # Gotchas at this freq or higher → CRITICAL in review

package/starters/go.yaml

@@ -37,10 +37,49 @@ diff_scan:
     severity: WARNING
     message: "panic() in production code — return errors instead"
 
+# Testing — used by /test and /qa
+test:
+  command: "go test ./..."
+  coverage_threshold: 70
+  integrity_checks: false
+
+# 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: "kubectl logs deployment/myapp --tail=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:
+    - vendor
+    - bin
+    - .git
+    - "*.log"
+
 codeloop:
   critical_frequency: 3
   promote_frequency: 10

package/starters/node-typescript.yaml

@@ -46,10 +46,49 @@ diff_scan:
     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"
+
 codeloop:
   critical_frequency: 3
   promote_frequency: 10

package/starters/python.yaml

@@ -40,10 +40,52 @@ diff_scan:
     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"
+
 codeloop:
   critical_frequency: 3
   promote_frequency: 10

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.2.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.2.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.2.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

@@ -1,6 +1,6 @@
 ---
 description: Track task progress — read/update tasks/todo.md
-allowed-tools: Read, Write, Edit, Glob, Grep
+allowed-tools: Read, Write, Edit, Glob, Grep, AskUserQuestion
 ---
 
 <!-- codeloop-version: 0.2.0 -->

package/templates/commands/plan.md

@@ -19,9 +19,10 @@ Plan before building. Write specs to `tasks/todo.md`, get approval, then execute
 ## 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
+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