{"id":47689862,"url":"https://github.com/blundergoat/goat-flow","last_synced_at":"2026-05-07T23:13:40.499Z","repository":{"id":345905805,"uuid":"1186576891","full_name":"blundergoat/goat-flow","owner":"blundergoat","description":"A structured workflow system for AI coding agents - harness engineering, execution loop, skills, hooks, and a learning loop. Works with Claude Code, Gemini CLI, Codex.    ","archived":false,"fork":false,"pushed_at":"2026-04-28T21:31:14.000Z","size":6604,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-28T23:17:44.609Z","etag":null,"topics":["agentic-coding","ai-agents","ai-coding","ai-safety","ai-workflow","automation","claude-code","codex","copilot","developer-tools","gemini-cli","harness-engineering","llm","prompt-engineering"],"latest_commit_sha":null,"homepage":"https://goat-flow.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/blundergoat.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-19T19:17:49.000Z","updated_at":"2026-04-28T21:30:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/blundergoat/goat-flow","commit_stats":null,"previous_names":["blundergoat/goat-flow"],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/blundergoat/goat-flow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blundergoat%2Fgoat-flow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blundergoat%2Fgoat-flow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blundergoat%2Fgoat-flow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blundergoat%2Fgoat-flow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blundergoat","download_url":"https://codeload.github.com/blundergoat/goat-flow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blundergoat%2Fgoat-flow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32484353,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["agentic-coding","ai-agents","ai-coding","ai-safety","ai-workflow","automation","claude-code","codex","copilot","developer-tools","gemini-cli","harness-engineering","llm","prompt-engineering"],"created_at":"2026-04-02T15:26:29.959Z","updated_at":"2026-05-07T23:13:40.493Z","avatar_url":"https://github.com/blundergoat.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GOAT Flow\n\n**A dashboard for auditing, configuring, and running your AI coding agents.**\n\nOne command opens a local menu for auditing, deterministic setup, guided agent prompts, and the dashboard. Supports Claude Code, Codex, Gemini CLI, and Copilot CLI.\n\n[![npm version](https://img.shields.io/npm/v/@blundergoat/goat-flow.svg)](https://www.npmjs.com/package/@blundergoat/goat-flow) [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) \n\n```bash\nnpx @blundergoat/goat-flow@latest\n```\noutput:\n```text\nWhat do you want to do?\n  1. Start dashboard\n  2. Install/update goat-flow files\n  3. Generate setup prompt\n  4. Audit current project\n  5. Show project status\n```\n\n**Install locally (optional)**\n\n```bash\nnpm install --save-dev @blundergoat/goat-flow    # npm\npnpm add -D @blundergoat/goat-flow               # pnpm\n```\n\nFor the dashboard's embedded terminal, you'll need `node-pty` to compile. See [Troubleshooting](#troubleshooting) if the terminal doesn't appear.\n\n## Dashboard views\n\n![Dashboard](docs/assets/dashboard-preview.png)\n\n### Home\n\nLive audit results for every supported agent. Per-agent cards show pass/fail across two scopes (GOAT Flow Setup, Agent Setup) with actionable fix hints. An AI Harness section scores each agent across five concerns - Context, Constraints, Verification, Recovery, and Feedback Loop - so you can see exactly where your setup is strong and where it's weak. \"What to do next\" action cards surface the highest-priority gaps. Re-audit after changes without leaving the page.\n\n### Setup\n\nGuided setup flow. Detects your project stack and existing configuration, lets you pick a target agent, then generates a setup prompt you can preview and launch directly in a terminal session. The agent configures your project: instruction file, skills, hooks, and learning loop.\n\n### Prompts\n\nA library of 24 visible preset prompts across six categories: critique, debug, plan, QA, review, and security, plus 2 internal quality prompts used by dashboard workflows. Two-pane layout with search, category filters, and favorites. Select a prompt and launch it in a new terminal, send it to an active session, or copy it to clipboard. Keyboard-navigable: `/` to search, arrows to browse, Enter to launch.\n\nPrompts include structured workflows like pre-walk-through notes with targeted testing plans, multi-lens critiques, full threat assessments, dependency scans, coverage audits, and milestone planning.\n\n### Workspace\n\nSplit layout for terminal work. A sessions rail lists all running terminal sessions (up to 10) with runner, age, and idle indicators. Single-click switching between sessions. The right pane is a full xterm.js terminal with WebSocket-based PTY - run Claude, Codex, Gemini, or Copilot directly in the browser.\n\n### Projects\n\nMulti-project browser. Register multiple project paths, view their audit status at a glance, and \"Audit All\" in one click. Select a project to switch context across the entire dashboard.\n\n### Quality\n\nGenerate agent quality-assessment prompts. Select a target agent, generate the prompt, and preview the full output with embedded audit results.\n\n## What's under the hood\n\nThe dashboard is the interface. Underneath, GOAT Flow installs a harness that makes agents more reliable:\n\n| Component | What it prevents |\n|---|---|\n| **Execution Loop** (READ → SCOPE → ACT → VERIFY) | Guessing at unread code, shipping without checks |\n| **Skills** (seven `/goat-*` commands + dispatcher) | Free-form prompting that drifts mid-task |\n| **Enforcement Hooks** (`deny-dangerous.sh`) | `rm -rf`, all git push, secret file access |\n| **Learning Loop** (footguns, lessons, decisions) | Same mistake recurring next session |\n| **Autonomy Tiers** (Always / Ask First / Never) | Agent overreach, missed approvals |\n\nSkills have phases and human gates. Hooks intercept tool calls before they execute. The learning loop gets read at session start so mistakes compound into context, not repetition.\n\n## Why not just CLAUDE.md / Cursor rules?\n\nInstruction files tell the agent what to do. They don't enforce it.\n\n|  | Instruction file alone | GOAT Flow |\n|---|---|---|\n| Tell the agent the rules | yes | yes |\n| Block dangerous commands at tool level | no | yes |\n| Structured workflows with human gates | no | yes |\n| Capture lessons across sessions | no | yes |\n| Audit whether setup is actually correct | no | yes |\n\nUse an instruction file for rules the agent should *remember*. Use GOAT Flow for rules the agent cannot *skip*.\n\n## Getting started\n\nRequires Node.js 20+.\n\n### 1. Start with the menu\n\n```bash\nnpx @blundergoat/goat-flow@latest\n```\n\nNo install required. Choose dashboard, deterministic install/update, setup prompt generation, audit, or status from the menu.\n\n### 2. Install/update system files\n\nFor a brand new project, copy the goat-flow system files first. This step is deterministic and does not require an agent:\n\n```bash\nnpx @blundergoat/goat-flow@latest install . --agent claude\n```\n\nUse `--force` only when you want to overwrite existing settings, `.goat-flow/config.yaml`, and remove deprecated skills. For outdated or v0.9 projects, the installer automatically updates the config version and cleans deprecated skill directories.\n\nThe install includes `.goat-flow/skill-reference/` with a README index for tool/capability playbooks. Generated or repaired instruction files route agents to that directory before declaring a requested tool unavailable.\n\n### 3. Generate the setup prompt\n\nThe installer copies shared system files. The setup prompt still creates or refreshes project-specific content such as the instruction file, architecture, code map, and real project footguns/lessons.\n\n```bash\nnpx @blundergoat/goat-flow@latest setup . --agent claude\n```\n\nEquivalent deterministic setup/update command:\n\n```bash\nnpx @blundergoat/goat-flow@latest setup . --agent claude --apply\n```\n\n### 4. Re-audit\n\nBack on the Home view, click **Re-audit**. All checks should pass. The AI Harness cards now show scores across the five concerns.\n\n### 5. Use a prompt\n\nOpen the **Prompts** view, pick a workflow (code review, bug diagnosis, UI debugging with browser evidence, security assessment, test planning), and launch it in a terminal session. Each prompt invokes a structured `/goat-*` skill with phases and human gates.\n\n## Multi-agent support\n\nGOAT Flow supports **Claude Code, Codex, Gemini CLI, and Copilot CLI**. All agents share the same execution loop, autonomy tiers, skills, and learning loop. The dashboard's runner switcher (top nav bar) lets you toggle between agents and see per-agent audit results side by side.\n\nRun `npx @blundergoat/goat-flow@latest manifest` to inspect the live agent matrix.\n\n## CLI commands\n\nThe dashboard covers most workflows visually. For CI or scripting, the same features are available as CLI commands:\n\n```bash\nnpx goat-flow dashboard .                  # Launch the dashboard\nnpx goat-flow audit .                      # Run audit (pass/fail output)\nnpx goat-flow audit . --harness            # Add AI harness scoring\nnpx goat-flow audit . --format json        # JSON output for CI\nnpx goat-flow install . --agent claude     # Copy/update system files\nnpx goat-flow setup . --agent claude       # Generate setup prompt\nnpx goat-flow quality . --agent claude     # Generate quality-assessment prompt\nnpx goat-flow status .                     # Project state (bare/partial/v0.9/v1.0/v1.1)\nnpx goat-flow manifest                     # Agent support matrix\n```\n\nThe dashboard prints a tokenized localhost URL. Open that URL from the terminal output; the token is process-local and is removed from the visible address bar after the page boots.\n\nSee [docs/cli.md](docs/cli.md) for the full reference.\n\n## The five harness concerns\n\nEvery major source in harness engineering (Hashimoto, Fowler/Böckeler, Anthropic, HumanLayer) converges on the same concerns. The dashboard's AI Harness section scores each agent across all five:\n\n| Concern | Question |\n|---------|----------|\n| **Context** | Is the agent's context accurate, lean, and useful? |\n| **Constraints** | Do deterministic rules catch failures before the LLM runs? |\n| **Verification** | Can the agent verify its work, and does failure feed back? |\n| **Recovery** | Can the agent resume after crash or interruption? |\n| **Feedback Loop** | Is the harness getting smarter from failures over time? |\n\nSee [docs/audit-and-quality.md](docs/audit-and-quality.md) for the full framework and sources.\n\n## Troubleshooting\n\n**Terminal not showing in dashboard?**\ngoat-flow installs without a C++ toolchain as of v1.2.4. If you need the dashboard's embedded terminal, you'll also need `node-pty` to compile. Install build tools (`sudo apt install build-essential python3` on Debian/Ubuntu, `xcode-select --install` on macOS), then run `npm rebuild node-pty`. If using pnpm: `pnpm approve-builds` (select node-pty). To skip the native build entirely: `npm install @blundergoat/goat-flow --omit=optional`.\n\n**Audit fails on a fresh project?**\nExpected. Run `npx @blundergoat/goat-flow@latest install . --agent claude`, then generate the setup prompt with `npx @blundergoat/goat-flow@latest setup . --agent claude`.\n\n**Audit still fails after setup?**\nRe-run `npx @blundergoat/goat-flow@latest audit . --verbose` to see which check failed. The `howToFix` hint on each failure points at the missing file or config key.\n\n**Agent isn't following the execution loop?**\nRestart the agent session after setup so it re-reads the instruction file. Agents only pick up instruction-file changes on session start.\n\n**Setup prompt looks wrong or incomplete?**\nRegenerate from the dashboard Setup page, which shows detected stack info alongside the prompt.\n\n## Documentation\n\n| Document | What it covers |\n|---|---|\n| [CLI Reference](docs/cli.md) | All commands, flags, and output formats |\n| [Dashboard](docs/dashboard.md) | Views, terminal, API endpoints |\n| [Skills Reference](docs/skills.md) | All 7 skills: modes, phases, gates, outputs |\n| [Audit \u0026 Quality](docs/audit-and-quality.md) | The two evaluation commands, 5 harness concerns, and when to use each |\n\n## Author\n\nBuilt by [Matthew Hansen](https://www.blundergoat.com/about).\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblundergoat%2Fgoat-flow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblundergoat%2Fgoat-flow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblundergoat%2Fgoat-flow/lists"}