ocak 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 17cdf9a84ce2be155679a0087de97b587ca6746cab5556eebfac6107b501651b
+  data.tar.gz: 972f1ea39c842e6b3719b8a8dfd2af1618f358105c5c9ec1c69e376b1c2ea2f1
+SHA512:
+  metadata.gz: a20c0599a4a31c6eda56617a9cbb34c73b6dbbbcb41fdf712917659288474dc9a4eb795f90b848b9732022060aab79a395cce7673848d0dec112410b849b94f8
+  data.tar.gz: 96bf0277c41027c9335e62628fc4dca32a77c932cf861cfe5205981c74911278308181449793e9568e4f453a8f7d7630b1981b798e7492333a9d1b58fecf7d61

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Clay Harmon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,268 @@
+# Ocak
+
+*Ocak (pronounced "oh-JAHK") is Turkish for "forge" or "hearth" — the place where raw material meets fire and becomes something useful. Also: let 'em cook.*
+
+Multi-agent pipeline that processes GitHub issues autonomously with Claude Code. You write an issue, label it, and ocak runs it through implement -> review -> fix -> security review -> document -> audit -> merge. Each issue gets its own worktree so they can run in parallel.
+
+## Quick Start
+
+```bash
+gem install ocak
+
+# In your project directory:
+ocak init
+
+# Create an issue (interactive):
+# Inside Claude Code, run /design
+
+# Process all ready issues:
+ocak run --once --watch
+
+# Or run a single issue:
+ocak run --single 42 --watch
+```
+
+## How It Works
+
+### The Pipeline
+
+```
+  /design        Label           Pipeline
+  ┌──────┐    ┌──────────┐    ┌───────────────────────────────────────────┐
+  │ User │───>│auto-ready│───>│ implement → review → fix → security →    │
+  │ idea │    │  label   │    │ document → audit → merge PR              │
+  └──────┘    └──────────┘    └───────────────────────────────────────────┘
+                                 │           │          │
+                                 ▼           ▼          ▼
+                              worktree   read-only   sequential
+                              per issue  reviews     rebase+merge
+```
+
+1. **Design** — `/design` in Claude Code walks you through creating an issue thats detailed enough for agents to work from
+2. **Label** — slap the `auto-ready` label on it
+3. **Plan** — planner agent figures out which issues can safely run in parallel
+4. **Execute** — each issue gets a worktree, runs through the pipeline steps
+5. **Merge** — completed work gets rebased, tested, and merged sequentially
+
+### Agents
+
+8 agents, each with scoped tool permisions:
+
+| Agent | Role | Tools | Model |
+|-------|------|-------|-------|
+| **implementer** | Write code and tests | Read, Write, Edit, Bash | opus |
+| **reviewer** | Check patterns, tests, quality | Read, Grep, Glob (read-only) | sonnet |
+| **security-reviewer** | OWASP Top 10, auth, injection | Read, Grep, Glob, Bash | sonnet |
+| **auditor** | Pre-merge gate on changed files | Read, Grep, Glob (read-only) | sonnet |
+| **documenter** | Add missing docs | Read, Write, Edit | sonnet |
+| **merger** | Create PR, merge, close issue | Read, Grep, Bash | sonnet |
+| **planner** | Determine safe parallelization | Read, Grep, Glob (read-only) | sonnet |
+| **pipeline** | Self-contained orchestrator | All tools | opus |
+
+### Skills
+
+Interactive skills for when you want to be in the loop:
+
+- `/design` — walks through your codebase, asks questions, produces a detailed issue
+- `/audit [scope]` — codebase sweep for security, patterns, tests, data, dependencies
+- `/scan-file <path>` — deep single-file analysis with test coverage check
+- `/debt` — tech debt tracker with risk scoring
+
+### Label State Machine
+
+```
+auto-ready ──→ in-progress ──→ completed
+                    │
+                    └──→ pipeline-failed
+```
+
+## Configuration
+
+`ocak init` generates `ocak.yml` at your project root:
+
+```yaml
+# Auto-detected project stack
+stack:
+  language: ruby
+  framework: rails
+  test_command: "bundle exec rspec"
+  lint_command: "bundle exec rubocop -A"
+  security_commands:
+    - "bundle exec brakeman -q"
+    - "bundle exec bundler-audit check"
+
+# Pipeline settings
+pipeline:
+  max_parallel: 3        # Concurrent worktrees
+  poll_interval: 60      # Seconds between polls
+  worktree_dir: ".claude/worktrees"
+  log_dir: "logs/pipeline"
+
+# GitHub labels
+labels:
+  ready: "auto-ready"
+  in_progress: "in-progress"
+  completed: "completed"
+  failed: "pipeline-failed"
+
+# Pipeline steps — add, remove, reorder as you like
+steps:
+  - agent: implementer
+    role: implement
+  - agent: reviewer
+    role: review
+  - agent: implementer
+    role: fix
+    condition: has_findings     # Only runs if reviewer found issues
+  - agent: reviewer
+    role: verify
+    condition: had_fixes        # Only runs if fixes were made
+  - agent: security_reviewer
+    role: security
+  - agent: implementer
+    role: fix
+    condition: has_findings
+  - agent: documenter
+    role: document
+  - agent: auditor
+    role: audit
+  - agent: merger
+    role: merge
+
+# Override agent files
+agents:
+  implementer: .claude/agents/implementer.md
+  reviewer: .claude/agents/reviewer.md
+  # ...
+```
+
+## Customization
+
+### Swap Agents
+
+Point any agent at a custom file:
+
+```yaml
+agents:
+  reviewer: .claude/agents/my-custom-reviewer.md
+```
+
+### Change Pipeline Steps
+
+Remove steps you don't need, add your own, reorder them:
+
+```yaml
+steps:
+  - agent: implementer
+    role: implement
+  - agent: reviewer
+    role: review
+  - agent: merger
+    role: merge
+```
+
+### Add Custom Agents
+
+Create a markdown file with YAML frontmatter:
+
+```markdown
+---
+name: my-agent
+description: Does something specific
+tools: Read, Glob, Grep, Bash
+model: sonnet
+---
+
+# My Custom Agent
+
+[Instructions for the agent...]
+```
+
+Then reference it in `ocak.yml`:
+
+```yaml
+agents:
+  my_agent: .claude/agents/my-agent.md
+
+steps:
+  - agent: my_agent
+    role: custom_step
+```
+
+## Writing Good Issues
+
+The `/design` skill produces issues formatted for zero-context agents. Think of it as writing a ticket for a contractor who's never seen your codebase — everthing they need should be in the issue body. The key sections:
+
+- **Context** — what part of the system, with specific file paths
+- **Acceptance Criteria** — "when X, then Y" format, each independantly testable
+- **Implementation Guide** — exact files to create/modify
+- **Patterns to Follow** — references to actual files in the codebase
+- **Security Considerations** — auth, validation, data exposure
+- **Test Requirements** — specific test cases with file paths
+- **Out of Scope** — explicit boundaries so it doesnt scope creep
+
+## CLI Reference
+
+```
+ocak init [--force] [--no-ai]    Set up pipeline in current project
+ocak run [options]                Run the pipeline
+  --watch                         Stream agent activity with color
+  --single N                      Run one issue, no worktrees
+  --dry-run                       Show plan without executing
+  --once                          Process current batch and exit
+  --max-parallel N                Limit concurrency (default: 3)
+  --poll-interval N               Seconds between polls (default: 60)
+ocak status                       Show pipeline state
+ocak clean                        Remove stale worktrees
+ocak design [description]         Launch issue design session
+ocak audit [scope]                Run codebase audit
+ocak debt                         Track technical debt
+```
+
+## FAQ
+
+**How much does it cost?**
+
+Depends on the issue. Simple stuff is $2-5, complex issues can be $10-15. The implementer runs on opus which is the expensive part, reviews on sonnet are pretty cheap. You can see costs in the `--watch` output.
+
+**Is it safe?**
+
+Reasonably. Review agents are read-only (no Write/Edit tools), merging is sequential so you don't get conflicts, and failed piplines get labeled and logged. You can always `--dry-run` first to see what it would do.
+
+**What if it breaks?**
+
+Issues get labeled `pipeline-failed` with a comment explaining what went wrong. Worktrees get cleaned up automatically. Run `ocak clean` to remove any stragglers, and check `logs/pipeline/` for detailed logs.
+
+**Can I run one issue manually?**
+
+```bash
+ocak run --single 42 --watch
+```
+
+Runs the full pipeline for issue #42 in your current checkout (no worktree).
+
+**How do I pause it?**
+
+Kill the `ocak run` process. Issues that are `in-progress` will keep their label — remove it manually or let the next run pick them back up.
+
+**What languages does it support?**
+
+`ocak init` auto-detects Ruby, TypeScript/JavaScript, Python, Rust, Go, Java, and Elixir. Agents get generated with stack-specific instructions. For anything else you get generic agents that you can customize.
+
+## Development
+
+```bash
+git clone https://github.com/clayharmon/ocak
+cd ocak
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## Contributing
+
+Bug reports and pull requests welcome on GitHub.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/bin/ocak

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'ocak'
+require 'ocak/cli'
+
+Dry::CLI.new(Ocak::CLI::Commands).call

data/lib/ocak/agent_generator.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require 'erb'
+require 'fileutils'
+
+module Ocak
+  class AgentGenerator
+    AGENT_TEMPLATES = %w[
+      implementer reviewer security_reviewer documenter
+      merger pipeline planner auditor
+    ].freeze
+
+    SKILL_TEMPLATES = %w[design audit scan_file debt].freeze
+
+    def initialize(stack:, project_dir:, use_ai: true, logger: nil)
+      @stack = stack
+      @project_dir = project_dir
+      @use_ai = use_ai
+      @logger = logger
+    end
+
+    def generate_agents(output_dir)
+      FileUtils.mkdir_p(output_dir)
+
+      AGENT_TEMPLATES.each do |agent|
+        template_path = File.join(Ocak.templates_dir, 'agents', "#{agent}.md.erb")
+        output_name = agent.tr('_', '-')
+        output_path = File.join(output_dir, "#{output_name}.md")
+
+        content = render_template(template_path)
+        File.write(output_path, content)
+        @logger&.info("Generated agent: #{output_name}.md")
+      end
+
+      enhance_with_ai(output_dir) if @use_ai
+    end
+
+    def generate_skills(output_dir)
+      SKILL_TEMPLATES.each do |skill|
+        skill_dir = File.join(output_dir, skill.tr('_', '-'))
+        FileUtils.mkdir_p(skill_dir)
+
+        template_path = File.join(Ocak.templates_dir, 'skills', skill, 'SKILL.md.erb')
+        output_path = File.join(skill_dir, 'SKILL.md')
+
+        content = render_template(template_path)
+        File.write(output_path, content)
+        @logger&.info("Generated skill: #{skill.tr('_', '-')}/SKILL.md")
+      end
+    end
+
+    def generate_hooks(output_dir)
+      FileUtils.mkdir_p(output_dir)
+
+      %w[post_edit_lint task_completed_test].each do |hook|
+        template_path = File.join(Ocak.templates_dir, 'hooks', "#{hook}.sh.erb")
+        output_name = hook.tr('_', '-')
+        output_path = File.join(output_dir, "#{output_name}.sh")
+
+        content = render_template(template_path)
+        File.write(output_path, content)
+        File.chmod(0o755, output_path)
+        @logger&.info("Generated hook: #{output_name}.sh")
+      end
+    end
+
+    def generate_config(output_path)
+      template_path = File.join(Ocak.templates_dir, 'ocak.yml.erb')
+      content = render_template(template_path)
+      File.write(output_path, content)
+      @logger&.info('Generated ocak.yml')
+    end
+
+    private
+
+    def render_template(template_path)
+      template = ERB.new(File.read(template_path), trim_mode: '-')
+      template.result(template_binding)
+    end
+
+    def template_binding
+      language = @stack.language
+      framework = @stack.framework
+      test_command = @stack.test_command
+      lint_command = @stack.lint_command
+      format_command = @stack.format_command
+      security_commands = @stack.security_commands
+      setup_command = @stack.setup_command
+      monorepo = @stack.respond_to?(:monorepo) ? @stack.monorepo : false
+      packages = @stack.respond_to?(:packages) ? (@stack.packages || []) : []
+      project_dir = @project_dir
+
+      binding
+    end
+
+    def enhance_with_ai(output_dir)
+      return unless claude_available?
+
+      @logger&.info('Enhancing agents with project analysis via Claude...')
+
+      # Read project context
+      context = gather_project_context
+      return if context.empty?
+
+      AGENT_TEMPLATES.each do |agent|
+        output_name = agent.tr('_', '-')
+        agent_path = File.join(output_dir, "#{output_name}.md")
+        current_content = File.read(agent_path)
+
+        prompt = build_enhancement_prompt(agent, current_content, context)
+        result = run_claude_prompt(prompt)
+
+        if result && !result.strip.empty? && result.include?('---')
+          File.write(agent_path, result)
+          @logger&.info("Enhanced agent with project context: #{output_name}.md")
+        end
+      end
+    end
+
+    def gather_project_context
+      parts = []
+
+      claude_md = File.join(@project_dir, 'CLAUDE.md')
+      parts << "## CLAUDE.md\n#{File.read(claude_md)}" if File.exist?(claude_md)
+
+      readme = File.join(@project_dir, 'README.md')
+      parts << "## README.md\n#{File.read(readme)[0..2000]}" if File.exist?(readme)
+
+      parts.join("\n\n")
+    end
+
+    def build_enhancement_prompt(_agent, template_content, context)
+      <<~PROMPT
+        You are customizing a Claude Code agent for a specific project.
+
+        Here is the project context:
+        #{context}
+
+        Here is the base agent template:
+        #{template_content}
+
+        Customize this agent to reference this project's actual conventions, file paths,
+        and patterns. Keep the same structure (YAML frontmatter + markdown). Keep the same
+        tool permissions. Make the instructions more specific to this project.
+
+        Output ONLY the complete agent markdown file, nothing else.
+      PROMPT
+    end
+
+    def claude_available?
+      _, _, status = Open3.capture3('which', 'claude')
+      status.success?
+    rescue Errno::ENOENT
+      false
+    end
+
+    def run_claude_prompt(prompt)
+      stdout, _, status = Open3.capture3(
+        'claude', '-p',
+        '--output-format', 'text',
+        '--model', 'haiku',
+        '--allowedTools', 'Read,Glob,Grep',
+        '--', prompt,
+        chdir: @project_dir
+      )
+      status.success? ? stdout : nil
+    rescue Errno::ENOENT
+      nil
+    end
+  end
+end

data/lib/ocak/claude_runner.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require 'open3'
+require 'json'
+require_relative 'process_runner'
+require_relative 'stream_parser'
+
+module Ocak
+  class ClaudeRunner
+    AgentResult = Struct.new(:success, :output, :cost_usd, :duration_ms,
+                             :num_turns, :files_edited) do
+      def success? = success
+      def blocking_findings? = output.to_s.include?("\u{1F534}")
+      def warnings?          = output.to_s.include?("\u{1F7E1}")
+    end
+
+    FailedStatus = Struct.new(:success?) do
+      def self.instance = new(false)
+    end
+
+    AGENT_TOOLS = {
+      'implementer' => 'Read,Write,Edit,Glob,Grep,Bash',
+      'reviewer' => 'Read,Grep,Glob,Bash',
+      'security-reviewer' => 'Read,Grep,Glob,Bash',
+      'auditor' => 'Read,Grep,Glob,Bash',
+      'documenter' => 'Read,Write,Edit,Glob,Grep,Bash',
+      'merger' => 'Read,Glob,Grep,Bash',
+      'pipeline' => 'Read,Write,Edit,Glob,Grep,Bash',
+      'planner' => 'Read,Glob,Grep,Bash'
+    }.freeze
+
+    AGENT_MODELS = {
+      'planner' => 'haiku',
+      'reviewer' => 'sonnet',
+      'security-reviewer' => 'sonnet',
+      'auditor' => 'sonnet',
+      'documenter' => 'sonnet',
+      'merger' => 'sonnet',
+      'implementer' => nil,
+      'pipeline' => nil
+    }.freeze
+
+    TIMEOUT = 600 # 10 minutes per agent invocation
+    MAX_RETRIES = 2
+    RETRY_DELAYS = [5, 15].freeze
+
+    TRANSIENT_PATTERNS = [
+      /connection.*reset/i,
+      /timed?\s*out/i,
+      /ECONNREFUSED/,
+      /rate\s*limit/i,
+      /503|502|429/,
+      /overloaded/i
+    ].freeze
+
+    def initialize(config:, logger:, watch: nil)
+      @config = config
+      @logger = logger
+      @watch = watch
+    end
+
+    def run_agent(agent_name, prompt, chdir: nil, model: nil, retries: MAX_RETRIES)
+      chdir ||= @config.project_dir
+      agent_file = @config.agent_path(agent_name)
+
+      unless File.exist?(agent_file)
+        @logger.error("Agent file not found: #{agent_file}", agent: agent_name)
+        return AgentResult.new(success: false, output: "Agent file not found: #{agent_file}")
+      end
+
+      instructions = File.read(agent_file)
+      full_prompt = "#{instructions}\n\n---\n\nTask: #{prompt}"
+      allowed_tools = AGENT_TOOLS.fetch(agent_name, 'Read,Glob,Grep,Bash')
+      agent_model = model || AGENT_MODELS[agent_name]
+
+      run_with_retry(agent_name, full_prompt, allowed_tools, agent_model, chdir: chdir, retries: retries)
+    end
+
+    # Run a raw prompt without agent file (for planner, init analysis, etc.)
+    def run_prompt(prompt, allowed_tools: 'Read,Glob,Grep,Bash', chdir: nil, model: nil)
+      chdir ||= @config.project_dir
+
+      stdout, _, status = run_claude(prompt, allowed_tools, chdir: chdir, model: model)
+
+      # Try to extract result from stream-json, fall back to raw stdout
+      result_text = extract_result_from_stream(stdout) || stdout
+      success = status.respond_to?(:success?) && status.success?
+
+      AgentResult.new(success: success, output: result_text)
+    end
+
+    private
+
+    def run_with_retry(agent_name, full_prompt, allowed_tools, model, chdir:, retries:)
+      attempts = 0
+
+      loop do
+        @logger.info("Running agent: #{agent_name}#{" (model: #{model})" if model}", agent: agent_name)
+
+        parser = StreamParser.new(agent_name, @logger)
+        line_handler = build_line_handler(agent_name, parser)
+
+        _, stderr, status = run_claude(full_prompt, allowed_tools, chdir: chdir, on_line: line_handler, model: model)
+        result = build_agent_result(parser, status, stderr, agent_name)
+
+        return result if result.success? || attempts >= retries || !transient_failure?(result, stderr.to_s)
+
+        attempts += 1
+        delay = RETRY_DELAYS[attempts - 1] || RETRY_DELAYS.last
+        @logger.warn("Transient failure, retrying #{agent_name} (attempt #{attempts + 1}/#{retries + 1}) " \
+                     "after #{delay}s...", agent: agent_name)
+        sleep delay
+      end
+    end
+
+    def transient_failure?(result, stderr)
+      combined = "#{result.output}\n#{stderr}"
+      TRANSIENT_PATTERNS.any? { |pat| combined.match?(pat) }
+    end
+
+    def build_agent_result(parser, status, stderr, agent_name)
+      output = parser.result_text || ''
+      exit_ok = status.respond_to?(:success?) && status.success?
+      success = parser.success? && exit_ok
+
+      @logger.info("Finished (exit: #{exit_ok}, stream: #{parser.success?})", agent: agent_name)
+      @logger.warn("Stderr: #{stderr[0..300]}", agent: agent_name) unless stderr.to_s.empty?
+
+      AgentResult.new(
+        success: success,
+        output: output,
+        cost_usd: parser.cost_usd,
+        duration_ms: parser.duration_ms,
+        num_turns: parser.num_turns,
+        files_edited: parser.files_edited
+      )
+    end
+
+    def build_line_handler(agent_name, parser)
+      lambda do |line|
+        events = parser.parse_line(line)
+        events.each { |event| @watch&.emit(agent_name, event) }
+      end
+    end
+
+    def run_claude(prompt, allowed_tools, chdir:, on_line: nil, model: nil)
+      cmd = [
+        'claude', '-p',
+        '--verbose',
+        '--output-format', 'stream-json',
+        '--allowedTools', allowed_tools
+      ]
+      cmd.push('--model', model) if model
+      cmd.push('--', prompt)
+
+      ProcessRunner.run(cmd, chdir: chdir, timeout: TIMEOUT, on_line: on_line)
+    end
+
+    def extract_result_from_stream(raw)
+      raw.each_line do |line|
+        data = JSON.parse(line.strip)
+        return data['result'] if data['type'] == 'result'
+      rescue JSON::ParserError
+        next
+      end
+      nil
+    end
+  end
+end

data/lib/ocak/cli.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'dry/cli'
+require_relative 'commands/init'
+require_relative 'commands/run'
+require_relative 'commands/design'
+require_relative 'commands/audit'
+require_relative 'commands/debt'
+require_relative 'commands/status'
+require_relative 'commands/clean'
+require_relative 'commands/resume'
+
+module Ocak
+  module CLI
+    module Commands
+      extend Dry::CLI::Registry
+
+      register 'init',   Ocak::Commands::Init
+      register 'run',    Ocak::Commands::Run
+      register 'design', Ocak::Commands::Design
+      register 'audit',  Ocak::Commands::Audit
+      register 'debt',   Ocak::Commands::Debt
+      register 'status', Ocak::Commands::Status
+      register 'clean',  Ocak::Commands::Clean
+      register 'resume', Ocak::Commands::Resume
+    end
+  end
+end

data/lib/ocak/commands/audit.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Ocak
+  module Commands
+    class Audit < Dry::CLI::Command
+      desc 'Run codebase audit'
+
+      argument :scope, type: :string, required: false,
+                       desc: 'Audit scope: security, tests, patterns, debt, dependencies, or all'
+
+      def call(scope: nil, **)
+        skill_path = File.join(Dir.pwd, '.claude', 'skills', 'audit', 'SKILL.md')
+
+        unless File.exist?(skill_path)
+          warn 'No audit skill found. Run `ocak init` first.'
+          exit 1
+        end
+
+        puts "Starting audit#{" (scope: #{scope})" if scope}..."
+        puts 'Run this inside Claude Code:'
+        puts "  /audit#{" #{scope}" if scope}"
+      end
+    end
+  end
+end