{"id":47300371,"url":"https://github.com/peter-stratton/dark-factory","last_synced_at":"2026-04-25T21:05:13.364Z","repository":{"id":343495687,"uuid":"1170342229","full_name":"peter-stratton/dark-factory","owner":"peter-stratton","description":"Human constraints, interactive planning, autonomous execution.","archived":false,"fork":false,"pushed_at":"2026-03-31T23:54:22.000Z","size":3032,"stargazers_count":4,"open_issues_count":10,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-01T19:20:42.817Z","etag":null,"topics":["ai-agents","autonomous-development","cli","developer-tools","golang"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/peter-stratton.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/roadmap/README.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-02T02:37:00.000Z","updated_at":"2026-03-31T15:07:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/peter-stratton/dark-factory","commit_stats":null,"previous_names":["peter-stratton/dark-factory"],"tags_count":36,"template":false,"template_full_name":null,"purl":"pkg:github/peter-stratton/dark-factory","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-stratton%2Fdark-factory","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-stratton%2Fdark-factory/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-stratton%2Fdark-factory/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-stratton%2Fdark-factory/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/peter-stratton","download_url":"https://codeload.github.com/peter-stratton/dark-factory/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-stratton%2Fdark-factory/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31518643,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T03:10:19.677Z","status":"ssl_error","status_checked_at":"2026-04-07T03:10:13.982Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","autonomous-development","cli","developer-tools","golang"],"created_at":"2026-03-17T01:07:12.012Z","updated_at":"2026-04-25T21:05:13.358Z","avatar_url":"https://github.com/peter-stratton.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"```\n     _            _           __            _\n  __| | __ _ _ __| | __      / _| __ _  ___| |_ ___  _ __ _   _\n / _` |/ _` | '__| |/ /_____| |_ / _` |/ __| __/ _ \\| '__| | | |\n| (_| | (_| | |  |   \u003c______|  _| (_| | (__| || (_) | |  | |_| |\n \\__,_|\\__,_|_|  |_|\\_\\     |_|  \\__,_|\\___|\\__\\___/|_|   \\__, |\n                                                           |___/\n```\n\nA Go CLI built for [Claude Code](https://docs.anthropic.com/en/docs/claude-code)\nthat orchestrates autonomous AI agents to implement GitHub issues, review their\nown work, and merge — without human intervention.\n\n**[Documentation](https://godarkfactory.com)** ·\n**[Getting Started](https://godarkfactory.com/docs/getting-started)** ·\n**[Releases](https://github.com/peter-stratton/dark-factory/releases)**\n\n### Philosophy\n\nThe hard part of software engineering isn't typing code — it's deciding what to\nbuild and how it fits. Dark Factory keeps those decisions with humans. Engineers\nwrite the roadmap, define architecture layers, design conventions, and author\nissue specs. Agents operate within those constraints. The harness *is* the\ndesign.\n\nThis is a collaborative architecture tool, not a \"throw a ticket at an AI and\nhope for the best\" system. The adversarial review model reinforces this: a\nseparate reviewer agent checks whether the code respects the architecture a\nhuman defined, follows conventions a human wrote, and meets acceptance criteria\na human specified. Every judgment call that shapes a codebase stays with the\nhumans who understand it.\n\nDark Factory has been built entirely by its own agent pipeline — every feature\nwas implemented, reviewed, and merged by `godark run`. The humans write specs\nand design harnesses; the agents write code.\n\n## Install\n\n**Homebrew** (macOS):\n\n```bash\nbrew install peter-stratton/dark-factory/godark\n```\n\n**Go install**:\n\n```bash\ngo install github.com/peter-stratton/dark-factory/cmd/godark@latest\n```\n\n**Binary download**: grab a pre-built binary from\n[GitHub Releases](https://github.com/peter-stratton/dark-factory/releases).\n\n### Platform support\n\nDark Factory is built for Claude Code and GitHub. The architecture is designed\naround Claude Code's specific capabilities — session resumption, CLAUDE.md as a\ncontrol surface, slash command skills, and sandboxed execution.\n\n| Layer | Supported |\n|-------|-----------|\n| AI agent | Claude Code (Anthropic) |\n| Version control | GitHub |\n\n### Features\n\n- **Three-agent pipeline** — implementer, quality reviewer, and functional reviewer are independent agents with isolated permissions; reviewers literally cannot edit files\n- **Specification-driven quality gates** — human-authored scenario specs define \"done\"; the functional reviewer generates ephemeral integration tests from specs, not just rubber-stamping the diff\n- **Architecture-as-code enforcement** — machine-readable layer definitions validated by `godark vet`; reviewers check architectural compliance, not just correctness\n- **Structured agent dialogue** — implementer posts reasoning as PR comments, reviewers challenge it; the PR thread is an auditable record of adversarial design review\n- **Full run observability** — local web dashboard with review chain timelines, quality flags, tool traces, and agent dialogue history for every issue\n- **Harness engineering lifecycle** — scaffold, validate, and enforce project constraints with `godark new`, `godark init`, `godark vet`, and six harness types\n- **Auto-detected multi-language support** — detects project type from marker files and configures the sandbox, build, and test commands automatically\n- **Fully sandboxed agent runs by default** — agents execute inside ephemeral Docker containers with no access to the host filesystem or network beyond what's explicitly configured\n- **Single binary, runs on a laptop** — no infrastructure fleet, no MCP server farm; just a Go binary, and Docker\n\n## How it works\n\nGiven a GitHub repo and a milestone, `godark` runs a three-agent development loop:\n\n1. **Fetch** open issues from the milestone, sorted by priority (`p1` → `p2` → `p3` → unlabeled)\n2. **Resolve dependencies** — issues declare `Blocked by: #N` or `Depends on: #N` in their body; skip any whose dependencies are still open\n3. **Implementer** — Claude Code implements the issue, writes unit tests, and opens a PR\n4. **Guard rails** — verify the PR exists, contains `Closes #N`, and didn't touch protected files\n5. **Quality reviewer** — a separate Claude Code instance audits the PR for security, performance, and code quality issues; if it requests changes, the implementer retries before functional review begins\n6. **Functional reviewer** — another Claude Code instance reviews the PR against human-authored scenario specs, generates ephemeral integration tests, and approves or requests changes\n7. **Retry loop** — if either reviewer rejects, the implementer reads the review comments and pushes fixes (max N retries per gate)\n8. **Merge or escalate** — approved PRs are squash-merged; failed PRs are labeled `needs-human-review`\n9. **Punchlist** — for each merged PR, a tool-less punchlist agent generates 3-5 concrete manual acceptance tests (specific config values, commands, expected outcomes) rendered as checkboxes alongside the existing punchlist output\n10. **Repeat** — move to the next unblocked issue\n\n## Quick start\n\n```bash\n# New project\ngodark new my-project --repo owner/my-project\n\n# Existing project\ngodark init --repo owner/my-project\n```\n\nThen open the project in Claude Code and use the built-in skills to define your\narchitecture, conventions, and roadmap. See the\n[Getting Started guide](https://godarkfactory.com/docs/getting-started) for a\nfull walkthrough.\n\n## Documentation\n\nFull documentation is available at **[godarkfactory.com](https://godarkfactory.com)**:\n\n- [Getting Started](https://godarkfactory.com/docs/getting-started) — installation, setup, and tutorial\n- [CLI Reference](https://godarkfactory.com/docs/cli) — all commands, flags, and usage examples\n- [Configuration](https://godarkfactory.com/docs/configuration) — `godark.yaml` deep dive\n- [Skills](https://godarkfactory.com/docs/skills) — slash commands for roadmaps, planning, issues, and more\n- [Licensing \u0026 Adoption](https://godarkfactory.com/docs/licensing) — commercial use, data privacy, and FAQ\n\n## Phase overviews\n\nEach completed phase has a practical overview with real-world examples showing\nwhat was built and how users experience it. These live in\n[`docs/phase-overviews/`](docs/phase-overviews/):\n\n| Phase | Overview |\n|-------|----------|\n| 1 | [Skeleton \u0026 Orchestration](docs/phase-overviews/phase-01-skeleton-and-orchestration.md) — CLI scaffold, config, deps, dry-run |\n| 2 | [Quality \u0026 Vetting](docs/phase-overviews/phase-02-quality-and-vetting.md) — `godark vet` validation framework |\n| 3 | [Docker Sandbox](docs/phase-overviews/phase-03-docker-sandbox.md) — container isolation, auth, cloning |\n| 4 | [Agent Execution](docs/phase-overviews/phase-04-agent-execution.md) — implementer, reviewer, guard rails, retry loop |\n| 5 | [Agent SDK Migration](docs/phase-overviews/phase-05-agent-sdk-migration.md) — SDK wrapper, role permissions, session resumption |\n| 6 | [Multi-Language Support](docs/phase-overviews/phase-06-multi-language-support.md) — auto-detect, runtime config, pluggable Dockerfiles |\n| 7 | [Review Quality \u0026 Dashboard](docs/phase-overviews/phase-07-review-quality-and-dashboard.md) — run data, quality flags, web dashboard |\n| 8 | [Harness Engineering](docs/phase-overviews/phase-08-harness-engineering.md) — harness templates, `godark new`, vet architecture |\n| 9 | [Harness-Aware Agent Execution](docs/phase-overviews/phase-09-harness-aware-agent-execution.md) — harness injection, dialogue, enforcement |\n| 10 | [Deterministic Verification Pipeline](docs/phase-overviews/phase-10-deterministic-verification-pipeline.md) — verify step, auto-fix, bash deny-list |\n| 11 | [Run Analysis \u0026 Prompt Feedback](docs/phase-overviews/phase-11-run-analysis-and-prompt-feedback.md) — `godark analyze`, trends, prompt gaps |\n| 12 | [Complex Project Support](docs/phase-overviews/phase-12-complex-project-support.md) — multi-module, codegen, secrets, CI checks |\n| 13 | [Human-in-the-Loop Review](docs/phase-overviews/phase-13-human-in-the-loop-review.md) — graduated auto-merge, watch command, risk classifier, notifications |\n| 14 | [Bounded Concurrency](docs/phase-overviews/phase-14-bounded-concurrency.md) — wave-barrier dispatcher, RunMode, serial post-wave merge, rate-limit batching, per-issue logs |\n| 15 | *Deferred* — Server Mode \u0026 Centralized Operation |\n| 16 | [Public Release](docs/phase-overviews/phase-16-public-release.md) — ELv2 license, GoReleaser, Homebrew tap, release workflow, CONTRIBUTING.md |\n| 17 | [Configurable Base Branch](docs/phase-overviews/phase-17-configurable-base-branch.md) — base branch config, PR targeting, prompt safety, run data tracking |\n| 18 | [Adaptive Agent Loop](docs/phase-overviews/phase-18-adaptive-agent-loop.md) — recon agent, hybrid retry strategy, handoff context |\n| 19 | [Spring Cleaning](docs/phase-overviews/phase-19-spring-cleaning.md) — unified verdict parsing, typed constants, shared helpers, CLI consolidation |\n| 20 | [Terminal UI](docs/phase-overviews/phase-20-terminal-ui.md) — Bubble Tea TUI, progress reporter, adaptive colors, hybrid output mode |\n| 21 | [Analytics Persistence](docs/phase-overviews/phase-21-analytics-persistence.md) — SQLite stats store, retry recovery rate, cost/duration breakdown, repo stats, flag-based prompt gaps |\n| 23 | [Watch \u0026 Daemon Mode](docs/phase-overviews/phase-23-watch-and-daemon-mode.md) — shared watch package, daemon mode, external merge detection, watch TUI and dashboard |\n| 24 | [Container Resource Tracking](docs/phase-overviews/phase-24-container-resource-tracking.md) — Docker stats capture, per-step memory/CPU, analyze output, dashboard columns, host mode |\n| 25 | [Docker Socket Mount \u0026 Compose Lifecycle](docs/phase-overviews/phase-25-docker-socket-mount-and-compose-lifecycle.md) — compose config, socket mount, up/down lifecycle, env forwarding, doctor checks |\n| 22 | [Analytics Overhaul](docs/phase-overviews/phase-22-analytics-overhaul.md) — first-pass rate, wasted cost, failure reasons, per-repo breakdown, sprint report command |\n| 26 | [Merge Coordinator Agent](docs/phase-overviews/phase-26-merge-coordinator-agent.md) - dedicated conflict resolver, per-issue and rollup integration, telemetry, dashboard step |\n| 27 | [Agent Efficiency \u0026 Resilience](docs/phase-overviews/phase-27-agent-efficiency-and-resilience.md) - per-role judge thresholds, benign kill handling, model overrides, handoff context, generalized recon |\n| 28 | [Container Health Judge](docs/phase-overviews/phase-28-container-health-judge.md) — real-time log streaming, idle/thrash/transport rules, container retry, intervention flow |\n| 29 | [Complete CLI Migration](docs/phase-overviews/phase-29-complete-cli-migration.md) - delete Python runner, simplify Run(), remove --no-sandbox, unconditional Docker, test migration |\n| 30 | [Spec Tightening](docs/phase-overviews/phase-30-spec-tightening.md) - GIVEN/WHEN/THEN validation, phase-scoped vet, spec delta generation, pipeline integration |\n| 31 | [Planner Agent](docs/phase-overviews/phase-31-planner-agent.md) - structured implementation plans, non-blocking pipeline step, implementer prompt injection, model override |\n| 32 | [Decision Flow Tracing](docs/phase-overviews/phase-32-decision-flow-tracing.md) - trace ID generation, SQLite persistence, `godark trace` CLI, dashboard copy button, TUI column |\n| 33 | [Semi-Structured Review](docs/phase-overviews/phase-33-semi-structured-review.md) - semi-formal reviewer prompt, config toggle, consistency quality gate, automatic re-run on contradiction |\n\nTo generate an overview for a newly completed phase, use `/godark-create-phase-overview \u003cphase-number\u003e`.\n\n## Building\n\n```bash\ngo build -o bin/godark ./cmd/godark\ngo test ./...\n```\n\n## Status\n\nSee [docs/roadmap/](docs/roadmap/) for the full development roadmap.\n\n## License\n\nDark Factory is licensed under the [Elastic License 2.0](LICENSE). Free for\ncommercial use — the only restriction is you can't resell it as a hosted\nservice. See the [Licensing \u0026 Adoption](https://godarkfactory.com/docs/licensing)\npage for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeter-stratton%2Fdark-factory","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpeter-stratton%2Fdark-factory","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeter-stratton%2Fdark-factory/lists"}