ocak 0.1.0

data/lib/ocak/templates/hooks/post_edit_lint.sh.erb

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# PostToolUse hook for Edit|Write — runs the appropriate linter/formatter on the changed file.
+# Receives JSON on stdin with tool_input.file_path.
+# Exits 0 always (non-blocking) — linting feedback is advisory.
+
+set -euo pipefail
+
+INPUT=$(cat)
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+[ -z "$FILE" ] && exit 0
+[ ! -f "$FILE" ] && exit 0
+
+PROJECT_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
+
+<%- if language == "ruby" -%>
+<%- if lint_command -%>
+case "$FILE" in
+  *.rb)
+    cd "$PROJECT_DIR"
+    <%= lint_command %> "$FILE" > /dev/null 2>&1 || true
+    ;;
+esac
+<%- end -%>
+<%- elsif language == "typescript" || language == "javascript" -%>
+case "$FILE" in
+  *.ts|*.tsx|*.js|*.jsx|*.json|*.css)
+    cd "$PROJECT_DIR"
+<%- if lint_command -%>
+    <%= lint_command.sub(/ \./, "") %> "$FILE" > /dev/null 2>&1 || true
+<%- end -%>
+    ;;
+esac
+<%- elsif language == "python" -%>
+case "$FILE" in
+  *.py)
+    cd "$PROJECT_DIR"
+<%- if lint_command -%>
+    <%= lint_command.sub(/ \./, "") %> "$FILE" > /dev/null 2>&1 || true
+<%- end -%>
+<%- if format_command -%>
+    <%= format_command.sub(/ \./, "") %> "$FILE" > /dev/null 2>&1 || true
+<%- end -%>
+    ;;
+esac
+<%- elsif language == "rust" -%>
+cd "$PROJECT_DIR"
+cargo fmt > /dev/null 2>&1 || true
+<%- elsif language == "go" -%>
+case "$FILE" in
+  *.go)
+    gofmt -w "$FILE" > /dev/null 2>&1 || true
+    ;;
+esac
+<%- end -%>
+
+exit 0

data/lib/ocak/templates/hooks/task_completed_test.sh.erb

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# TaskCompleted hook — runs the test suite for the project.
+# Blocks completion (exit 2) if tests fail. Stderr goes to Claude as feedback.
+
+set -uo pipefail
+
+PROJECT_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
+cd "$PROJECT_DIR"
+
+FAILURES=()
+
+<%- if test_command -%>
+# Run tests
+if ! <%= test_command %> 2>&1; then
+  FAILURES+=("Tests failed: <%= test_command %>")
+fi
+<%- end -%>
+
+<%- if lint_command && !lint_command.include?("--fix") && !lint_command.include?("--write") && !lint_command.include?("-A") -%>
+# Run linter (check only, no auto-fix)
+if ! <%= lint_command %> 2>&1; then
+  FAILURES+=("Lint failed: <%= lint_command %>")
+fi
+<%- end -%>
+
+if [ ${#FAILURES[@]} -gt 0 ]; then
+  echo "Checks failed. Fix before completing:" >&2
+  for f in "${FAILURES[@]}"; do
+    echo "  - $f" >&2
+  done
+  exit 2
+fi
+
+exit 0

data/lib/ocak/templates/ocak.yml.erb

@@ -0,0 +1,99 @@
+# Ocak pipeline configuration
+# Generated by `ocak init` — customize as needed
+
+# Auto-detected project stack
+stack:
+  language: <%= language %>
+<%- if framework -%>
+  framework: <%= framework %>
+<%- end -%>
+<%- if test_command -%>
+  test_command: "<%= test_command %>"
+<%- end -%>
+<%- if lint_command -%>
+  lint_command: "<%= lint_command %>"
+<%- end -%>
+<%- if setup_command -%>
+  setup_command: "<%= setup_command %>"
+<%- end -%>
+<%- if format_command -%>
+  format_command: "<%= format_command %>"
+<%- end -%>
+<%- unless security_commands.empty? -%>
+  security_commands:
+<%- security_commands.each do |cmd| -%>
+    - "<%= cmd %>"
+<%- end -%>
+<%- end -%>
+
+# Pipeline settings
+pipeline:
+  max_parallel: 3
+  poll_interval: 60
+  worktree_dir: ".claude/worktrees"
+  log_dir: "logs/pipeline"
+  # cost_budget: 5.00  # Max USD per issue pipeline (uncomment to enable)
+
+# Safety — controls which issues the pipeline will process
+# Default (no config): only issues created by the current `gh` user
+safety:
+  allowed_authors: []            # Empty = current gh user only. Add usernames to allow others.
+  # require_comment: "auto-ready"  # Require this exact comment from an allowed author
+  max_issues_per_run: 5          # Circuit breaker: max issues processed per poll cycle
+
+# GitHub label state machine
+labels:
+  ready: "auto-ready"
+  in_progress: "in-progress"
+  completed: "completed"
+  failed: "pipeline-failed"
+
+# Pipeline steps — customize by adding/removing/reordering
+# Each step can optionally specify `model:` to override the default (haiku|sonnet|opus)
+steps:
+  - agent: implementer
+    role: implement
+  - agent: reviewer
+    role: review
+  - agent: implementer
+    role: fix
+    condition: has_findings
+  - agent: reviewer
+    role: verify
+    condition: had_fixes
+  - agent: security_reviewer
+    role: security
+  - agent: implementer
+    role: fix
+    condition: has_findings
+    complexity: full          # skipped for simple issues
+  - agent: documenter
+    role: document
+    complexity: full          # skipped for simple issues
+  - agent: auditor
+    role: audit
+    complexity: full          # skipped for simple issues
+  - agent: merger
+    role: merge
+
+# Agent file paths — override to use custom agents
+agents:
+  implementer: .claude/agents/implementer.md
+  reviewer: .claude/agents/reviewer.md
+  security_reviewer: .claude/agents/security-reviewer.md
+  documenter: .claude/agents/documenter.md
+  merger: .claude/agents/merger.md
+  pipeline: .claude/agents/pipeline.md
+  planner: .claude/agents/planner.md
+  auditor: .claude/agents/auditor.md
+<%- if defined?(monorepo) && monorepo -%>
+
+# Monorepo — detected packages/workspaces
+# Configure per-package test/lint commands here if needed
+monorepo:
+  detected: true
+  packages:
+<%- packages.each do |pkg| -%>
+    - "<%= pkg %>"
+<%- end -%>
+<%- end -%>

data/lib/ocak/templates/skills/audit/SKILL.md.erb

@@ -0,0 +1,132 @@
+---
+name: audit
+description: Comprehensive codebase audit — security, error handling, patterns, tests, data, dependencies
+disable-model-invocation: true
+---
+
+# /audit — Codebase Audit
+
+Run a comprehensive sweep of the codebase across multiple dimensions. Produces a prioritized report with actionable findings.
+
+## Input
+
+Optional scope argument: $ARGUMENTS
+
+Supported scopes: `security`, `errors`, `patterns`, `tests`, `data`, `dependencies`, or empty for all.
+
+## Process
+
+### Phase 1: Orientation
+
+1. Read CLAUDE.md for architecture and conventions
+2. Map the project structure using Glob to understand directories and file organization
+
+### Phase 2: Static Analysis Tools
+
+Run all available tools and capture output. Do NOT stop if a tool fails.
+
+```bash
+<%- if lint_command -%>
+<%= lint_command.sub(/ -A| --fix| --write/, "") %> 2>&1 || true
+<%- end -%>
+<%- security_commands.each do |cmd| -%>
+<%= cmd %> 2>&1 || true
+<%- end -%>
+```
+
+### Phase 3: Manual Analysis
+
+For each dimension below, perform targeted searches and reads. Only run dimensions matching $ARGUMENTS (or all if no argument).
+
+#### Security (`security`)
+
+Search for and evaluate:
+- Auth gaps — endpoints or handlers missing authentication
+- Unvalidated inputs — user data used without validation
+- SQL/command injection — string interpolation in queries or shell commands
+- Hardcoded secrets — passwords, API keys, tokens in source code
+- Mass assignment — unfiltered parameters in create/update operations
+
+#### Error Handling (`errors`)
+
+- Bare rescue/catch blocks without specific types
+- Swallowed exceptions (caught with no re-raise, logging, or handling)
+- Inconsistent error response patterns
+- Missing error handling in external calls (HTTP, database, file I/O)
+
+#### Bad Patterns (`patterns`)
+
+- God classes/modules (files > 200 lines)
+- TODO/FIXME/HACK/XXX comments
+- Dead code or commented-out code
+- Code duplication
+- Tight coupling between unrelated modules
+
+#### Test Gaps (`tests`)
+
+- Public methods/functions without corresponding tests
+- Tests that don't assert anything meaningful
+- Skipped or pending tests
+- Missing edge case and error path tests
+
+#### Data Issues (`data`)
+
+- N+1 query candidates
+- Missing database indexes
+- Unbounded queries (no limit/pagination)
+- Incorrect data types (e.g., float for money)
+
+#### Dependencies (`dependencies`)
+
+- Outdated packages with known vulnerabilities
+- Unused dependencies
+- Overly broad version constraints
+
+### Phase 4: Report
+
+Output findings grouped by severity. Every finding must have a specific file path and line number.
+
+```
+# Codebase Audit Report
+
+**Scope**: [all | security | errors | patterns | tests | data | dependencies]
+
+## Critical (fix immediately)
+
+### [Finding title]
+**File**: `path/to/file:42`
+**Category**: [Security | Error Handling | Pattern | Test Gap | Data | Dependency]
+**Issue**: [Specific description of what's wrong]
+**Impact**: [What could go wrong]
+**Fix**: [Exact steps to remediate]
+
+## High (fix soon)
+...
+
+## Medium (should fix)
+...
+
+## Low (consider fixing)
+...
+
+## Summary
+
+| Category | Critical | High | Medium | Low |
+|----------|----------|------|--------|-----|
+| Security | N | N | N | N |
+| Error Handling | N | N | N | N |
+| Patterns | N | N | N | N |
+| Test Gaps | N | N | N | N |
+| Data | N | N | N | N |
+| Dependencies | N | N | N | N |
+| **Total** | **N** | **N** | **N** | **N** |
+```
+
+### Phase 5: Issue Generation
+
+After presenting the report, offer:
+
+> I found N critical and N high findings. Want me to generate GitHub issues for them?
+> Each issue will follow the /design format so they can be processed by the autonomous pipeline.
+
+If the user accepts, generate issues using the /design format and offer to create them with `gh issue create --label "auto-ready"`.

data/lib/ocak/templates/skills/debt/SKILL.md.erb

@@ -0,0 +1,128 @@
+---
+name: debt
+description: Technical debt tracker — TODOs, suppressed rules, skipped tests, churn hotspots
+disable-model-invocation: true
+---
+
+# /debt — Technical Debt Tracker
+
+Tracks and ranks technical debt across the codebase. Combines static markers (TODOs, suppressions), test gaps, and git churn to identify the riskiest areas.
+
+## Process
+
+### Phase 1: Collect Debt Markers
+
+#### TODO/FIXME/HACK Comments
+
+```bash
+grep -rn "TODO\|FIXME\|HACK\|XXX\|OPTIMIZE\|REFACTOR" \
+  --include="*.<%= language == "ruby" ? "rb" : language == "python" ? "py" : language == "rust" ? "rs" : language == "go" ? "go" : "{ts,tsx,js,jsx}" %>" \
+  --exclude-dir=node_modules --exclude-dir=vendor --exclude-dir=.git --exclude-dir=target \
+  . 2>/dev/null || true
+```
+
+For each marker, read the surrounding context (3-5 lines) to understand what the debt is.
+
+#### Suppressed Linter Rules
+
+```bash
+<%- if language == "ruby" -%>
+grep -rn "rubocop:disable" --include="*.rb" . 2>/dev/null || true
+<%- elsif language == "typescript" || language == "javascript" -%>
+grep -rn "eslint-disable\|biome-ignore\|@ts-ignore\|@ts-expect-error\|@ts-nocheck" \
+  --include="*.ts" --include="*.tsx" --include="*.js" \
+  --exclude-dir=node_modules . 2>/dev/null || true
+grep -rn "as any\|as unknown" --include="*.ts" --include="*.tsx" \
+  --exclude-dir=node_modules . 2>/dev/null || true
+<%- elsif language == "python" -%>
+grep -rn "# noqa\|# type: ignore\|# pylint: disable" --include="*.py" . 2>/dev/null || true
+<%- elsif language == "rust" -%>
+grep -rn "#\[allow(" --include="*.rs" . 2>/dev/null || true
+<%- elsif language == "go" -%>
+grep -rn "//nolint\|// nolint" --include="*.go" . 2>/dev/null || true
+<%- end -%>
+```
+
+#### Skipped/Pending Tests
+
+```bash
+<%- if language == "ruby" -%>
+grep -rn "skip\b\|pending\b" --include="*_test.rb" --include="*_spec.rb" . 2>/dev/null || true
+<%- elsif language == "typescript" || language == "javascript" -%>
+grep -rn "it\.skip\|test\.skip\|describe\.skip\|xit\|xdescribe\|xtest\|\.todo(" \
+  --include="*.test.ts" --include="*.test.tsx" --include="*.test.js" --include="*.spec.ts" \
+  --exclude-dir=node_modules . 2>/dev/null || true
+<%- elsif language == "python" -%>
+grep -rn "@pytest.mark.skip\|@unittest.skip\|pytest.skip" --include="*.py" . 2>/dev/null || true
+<%- elsif language == "rust" -%>
+grep -rn "#\[ignore\]" --include="*.rs" . 2>/dev/null || true
+<%- end -%>
+```
+
+### Phase 2: Git Churn Analysis
+
+Find files that change most frequently — high churn signals instability or ongoing debt.
+
+```bash
+# Top 30 most frequently changed files in the last 6 months
+git log --since="6 months ago" --name-only --pretty=format: | \
+  grep -v '^$' | sort | uniq -c | sort -rn | head -30
+```
+
+### Phase 3: Test Coverage Cross-Reference
+
+For the top 20 highest-churn files, check if they have corresponding tests.
+
+### Phase 4: Risk Scoring
+
+Score each debt item on a 1-10 scale based on:
+
+| Factor | Weight | Description |
+|--------|--------|-------------|
+| **Churn** | 3x | Files changed 10+ times in 6 months = high churn |
+| **Test coverage** | 3x | No tests = maximum risk |
+| **Suppressed rules** | 2x | Disabled lint/type checks = hidden issues |
+| **Age** | 1x | Old TODOs (> 3 months) = likely forgotten |
+| **Blast radius** | 1x | Shared code (base classes, lib) = wider impact |
+
+### Phase 5: Output
+
+```
+# Technical Debt Report
+
+**Total debt items**: N
+
+## Risk-Ranked Debt
+
+### 1. `path/to/file` — Risk: 9/10
+**Churn**: N changes in 6 months
+**Tests**: N tests (N public methods untested)
+**Suppressions**: N
+**Markers**: N TODOs, N HACKs
+**Details**:
+- Line 42: `TODO: description` (added date)
+- Line 78: suppressed lint rule — reason
+
+## Debt by Category
+
+| Category | Count | Oldest |
+|----------|-------|--------|
+| TODO | N | [date] |
+| FIXME | N | [date] |
+| HACK | N | [date] |
+| Suppressed rules | N | - |
+| Skipped tests | N | - |
+| Untested high-churn files | N | - |
+
+## Churn Hotspots
+Files with high churn and low test coverage:
+- `path/to/file` — N changes, N tests
+```
+
+### Phase 6: Issue Generation
+
+After presenting the report, offer:
+
+> The top N items are high-risk debt. Want me to generate GitHub issues for them?
+
+If accepted, generate one issue per high-risk item using the /design format with the `auto-ready` label.

data/lib/ocak/templates/skills/design/SKILL.md.erb

@@ -0,0 +1,131 @@
+---
+name: design
+description: Interactive issue design — researches the codebase and produces implementation-ready GitHub issues
+disable-model-invocation: true
+---
+
+# /design — Issue Design Skill
+
+You are helping the user design a GitHub issue that a Claude agent with ZERO prior context can pick up and implement completely. The issue must be specific enough that an implementer needs nothing beyond the issue body and CLAUDE.md.
+
+## Input
+
+The user's rough description is: $ARGUMENTS
+
+If $ARGUMENTS is empty, ask what they want to build or fix.
+
+## Process
+
+### Phase 1: Research
+
+Before asking any questions, silently research the codebase to understand what exists:
+
+1. Read CLAUDE.md for conventions, patterns, and architecture
+2. Use Glob and Grep to find files related to the user's description
+3. Read the most relevant files to understand current behavior, patterns, and data models
+4. Identify which areas of the codebase this touches
+5. Find existing tests, controllers, services, and routes that are relevant
+6. Check for similar patterns already implemented that the issue should follow
+
+### Phase 2: Clarify
+
+Ask the user 2-5 targeted questions. Focus on:
+
+- **Intent**: What problem does this solve? Who benefits?
+- **Scope**: What's the minimum viable version? What should be explicitly excluded?
+- **Behavior**: What should happen in edge cases? What error states exist?
+- **Priority**: Is this blocking other work?
+
+Do NOT ask questions you can answer from the codebase. Do NOT ask generic questions — be specific based on what you found in Phase 1.
+
+### Phase 3: Draft Issue
+
+Write the issue in this exact format:
+
+```markdown
+## Context
+
+[1-3 sentences: what part of the system this touches, why it matters, specific modules/files involved]
+
+**Relevant files:**
+- `path/to/file` — [what it does]
+- [list ALL files the implementer will need to read or modify]
+
+## Current Behavior
+
+[What happens now, or "This feature does not exist yet." Be specific — include actual code behavior]
+
+## Desired Behavior
+
+[Exactly what should change. Use concrete examples:]
+
+**Example 1:** When [specific input/action], the system should [specific output/behavior].
+
+## Acceptance Criteria
+
+- [ ] When [specific condition], then [specific observable result]
+- [ ] When [edge case], then [specific handling]
+- [ ] When [error condition], then [specific error response/behavior]
+- [ ] [Each criterion must be independently testable]
+
+## Implementation Guide
+
+[Specific files to create/modify, with the approach:]
+- Create `path/to/new_file` — [what it does, key methods]
+- Modify `path/to/existing_file` — [what to add/change]
+
+### Patterns to Follow
+- Follow the pattern in `path/to/example` for [specific pattern]
+- Match the structure in `path/to/reference` for [specific convention]
+
+## Security Considerations
+
+[One of:]
+- N/A — no security surface
+- Auth: [who can access this, what scoping is needed]
+- Validation: [what input must be validated]
+- Data exposure: [what sensitive data could leak]
+
+## Test Requirements
+
+- `path/to/test_file`: [specific test cases]
+- Edge cases: [list specific edge cases to test]
+- Error cases: [list specific error scenarios]
+
+## Documentation
+
+- [ ] [Specific doc updates needed, or "No documentation changes required"]
+
+## Out of Scope
+
+- [Thing that might seem related but is NOT part of this issue]
+- [Another boundary — be explicit to prevent scope creep]
+
+## Dependencies
+
+- [Issue #N must be completed first because...], or
+- None
+```
+
+### Phase 4: Review & Create
+
+1. Show the draft to the user
+2. Ask if anything needs adjustment
+3. After approval, offer to create the issue:
+
+```bash
+gh issue create \
+  --title "Brief imperative title (under 70 chars)" \
+  --body "..." \
+  --label "auto-ready"
+```
+
+If the user described multiple things, break them into separate issues.
+
+## Writing Style
+
+- Direct and specific — like a senior engineer writing for a contractor
+- No vague language: never say "improve", "clean up", "refactor" without specifying exactly what changes
+- Every file path must be real and verified against the codebase
+- Every pattern reference must point to an actual existing file
+- Acceptance criteria must be testable by running a specific command or request

data/lib/ocak/templates/skills/scan_file/SKILL.md.erb

@@ -0,0 +1,113 @@
+---
+name: scan-file
+description: Deep single-file analysis — bugs, security, patterns, test coverage
+disable-model-invocation: true
+argument-hint: <file-path>
+---
+
+# /scan-file — Single File Analysis
+
+Deep analysis of a single file and its dependency graph. Finds bugs, security issues, bad patterns, missing error handling, and test gaps.
+
+## Input
+
+File path: $ARGUMENTS
+
+If $ARGUMENTS is empty, ask which file to scan.
+
+## Process
+
+### Phase 1: Read the Target File
+
+1. Read the file specified by $ARGUMENTS in full
+2. Identify the file's role based on its location and contents
+
+### Phase 2: Read Dependencies
+
+Find and read all files this file imports, requires, or inherits from (skip third-party packages).
+
+### Phase 3: Find the Test File
+
+Determine the corresponding test file based on project conventions. If the test file exists, read it. If it doesn't exist, note this as a finding.
+
+### Phase 4: Analysis
+
+Check every line for:
+
+#### Bugs
+- Off-by-one errors in loops or ranges
+- Nil/null reference risks
+- Race conditions in concurrent code
+- Incorrect method signatures or wrong argument order
+- Missing return values
+
+#### Security
+- SQL injection (string interpolation in queries)
+- Command injection (system calls with user input)
+- Path traversal (file operations with user-supplied paths)
+- Missing authorization checks
+- Information leakage in error messages
+- Hardcoded secrets
+
+#### Patterns
+- Violations of project conventions (read CLAUDE.md for reference)
+- Methods that are too long (> 20 lines)
+- Classes with too many responsibilities
+- Dead code (unreachable branches, unused variables)
+
+#### Error Handling
+- Bare rescue/catch without specific exception types
+- Swallowed exceptions
+- Missing error handling for external calls
+- Inconsistent error response format
+
+#### Edge Cases
+- Empty collections (`.first` on possibly empty array)
+- Zero/negative values in calculations
+- Very large inputs (unbounded queries, no pagination)
+- Concurrent access (race conditions)
+
+#### Test Coverage
+Compare the public interface of the target file against the test file:
+- List every public method/exported function
+- For each, check if the test file has a corresponding test
+- Check if error paths are tested
+- Check if edge cases are tested
+
+### Phase 5: Output
+
+```
+# Scan: `path/to/file`
+
+## Summary
+[1-2 sentence overview]
+
+## Findings
+
+### Line N: [Title]
+**Severity**: Critical / High / Medium / Low
+**Category**: Bug / Security / Pattern / Error Handling / Edge Case
+**Issue**: [What's wrong]
+**Fix**: [Exact fix]
+
+## Test Coverage
+
+| Method/Function | Tested | Edge Cases | Error Path |
+|----------------|--------|------------|------------|
+| `method_name` | yes/no | yes/no | yes/no |
+
+**Missing tests**:
+- `method_name` with nil input
+- [specific untested scenarios]
+
+## Score: N/10
+[Brief justification]
+```
+
+### Phase 6: Offer Actions
+
+After presenting findings, offer:
+
+1. **Fix issues** — "Want me to fix the issues I found?"
+2. **Generate issue** — "Want me to create a GitHub issue for these findings?"
+3. **Both** — Fix what's safe to fix inline, create an issue for the rest