{"id":33311725,"url":"https://github.com/andresharpe/dotbot","last_synced_at":"2026-05-14T17:38:26.752Z","repository":{"id":334305006,"uuid":"1140923624","full_name":"andresharpe/dotbot","owner":"andresharpe","description":"Structured, auditable AI-assisted development for teams. Zero-dependency MCP server, web dashboard, and multi-provider AI CLI support.","archived":false,"fork":false,"pushed_at":"2026-05-10T16:10:22.000Z","size":8814,"stargazers_count":49,"open_issues_count":54,"forks_count":23,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-05-10T17:29:17.241Z","etag":null,"topics":["ai-assisted-development","ai-coding","claude","developer-tools","gemini","mcp-server","model-context-protocol","openai-codex","powershell","workflow-engine"],"latest_commit_sha":null,"homepage":null,"language":"PowerShell","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/andresharpe.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":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":"docs/roadmap/DOTBOT-V4-ROADMAP-DRAFT-V1.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-01-23T23:54:40.000Z","updated_at":"2026-05-10T16:10:26.000Z","dependencies_parsed_at":"2026-01-24T12:08:47.108Z","dependency_job_id":null,"html_url":"https://github.com/andresharpe/dotbot","commit_stats":null,"previous_names":["andresharpe/dotbot-v3","andresharpe/dotbot"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/andresharpe/dotbot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andresharpe%2Fdotbot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andresharpe%2Fdotbot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andresharpe%2Fdotbot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andresharpe%2Fdotbot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andresharpe","download_url":"https://codeload.github.com/andresharpe/dotbot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andresharpe%2Fdotbot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33035987,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"online","status_checked_at":"2026-05-14T02:00:06.663Z","response_time":57,"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":["ai-assisted-development","ai-coding","claude","developer-tools","gemini","mcp-server","model-context-protocol","openai-codex","powershell","workflow-engine"],"created_at":"2025-11-19T05:05:41.272Z","updated_at":"2026-05-14T17:38:26.745Z","avatar_url":"https://github.com/andresharpe.png","language":"PowerShell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dotbot\n\n**Structured, auditable AI-assisted development for teams.**\n\n![Overview](assets/overview.png)\n\n## What is dotbot?\n\nMost AI coding tools give you a result but no record of how you got there - no trail of decisions for teammates to follow, no way to continue work across sessions, and no framework for managing large projects.\n\ndotbot wraps AI-assisted coding in a managed, transparent workflow where every step is tracked:\n\n### Multi-workflow platform\n- **Workflow-driven pipelines** - Define multi-step pipelines in `workflow.yaml` manifests with tasks, dependencies, form configuration, MCP servers, and environment requirements. A project can have multiple workflows installed simultaneously, each run, re-run, and stopped independently.\n- **Typed task system** - Tasks can be `prompt` (AI-executed), `script` (PowerShell, no LLM), `mcp` (tool call), `task_gen` (generates sub-tasks dynamically), or `prompt_template` (AI with a workflow-specific prompt). Script, MCP, and task_gen tasks bypass the AI entirely - they auto-promote past analysis, skip worktree isolation, and skip verification hooks. This enables deterministic pipeline stages within AI-orchestrated workflows.\n- **Enterprise registries** - Teams publish workflows, stacks, tools, and skills in git-hosted or local registries. `dotbot registry add` links a registry (private or public); `dotbot init -Workflow registry:name` installs from it. Registries are validated against a `registry.yaml` manifest with version compatibility checks and auth-failure hints for GitHub, Azure DevOps, and GitLab.\n- **Workflows and stacks** - **Workflows** (e.g. `start-from-jira`) define operational pipelines - what dotbot does. **Stacks** (e.g. `dotnet`, `dotnet-blazor`) add tech-specific skills, hooks, and MCP tools - what tech the project uses. Stacks compose additively with `extends` chains. Settings deep-merge across `default -\u003e workflows -\u003e stacks`.\n\n### Execution engine\n- **Two-phase execution** - Analysis resolves ambiguity, identifies files, and builds a context package. Implementation consumes that package and writes code. Tasks flow: `todo -\u003e analysing -\u003e analysed -\u003e in-progress -\u003e done`.\n- **Per-task git worktree isolation** - Each task runs in its own worktree on an isolated branch, squash-merged back to main on completion.\n- **Per-task model selection** - Tasks can specify a model (e.g. Sonnet for simple tasks, Opus for complex ones) that overrides the process-level default. Use cheaper models where they suffice to reduce token spend.\n- **Multi-slot concurrent execution** - The workflow engine runs multiple tasks from the same workflow in parallel with slot-aware locking, shortening wall-clock time for large task queues.\n- **Multi-provider** - Switch between **Claude**, **Codex**, and **Gemini** from the Settings tab. Each provider has its own CLI wrapper, stream parser, and model configuration.\n- **Configurable permission modes** - Choose how each provider handles permission checks during autonomous execution. Claude supports bypass and auto mode (AI-classified safety); Codex supports bypass and full-auto; Gemini supports YOLO and auto-edit. The dashboard detects installed providers, their versions, and authentication status.\n\n### Dashboard and observability\n- **Web dashboard** - Seven-tab UI (Overview, Product, Roadmap, Processes, Decisions, Workflow, Settings) with workflow cards showing progress pills, per-workflow run/stop controls, and pipeline-phase filtering.\n- **Manifest-driven workflow** - The workflow dialog is driven by `workflow.yaml` form modes with visibility flags for prompt, file upload, interview, and auto-workflow options.\n- **JSONL audit trail** - Session logs capture token counts, costs, turn boundaries, wall-clock gaps, agent completion reasons, and error details. Every AI session, question, answer, and code change is version-controlled.\n- **Project health diagnostics** - `dotbot doctor` scans for stale locks, orphaned worktrees, settings integrity, dependency issues, and task queue health.\n\n### Collaboration and control\n- **Operator steering** - Guide the AI mid-session through a heartbeat/whisper system. `/status` and `/verify` slash commands work during autonomous execution.\n- **Project interview** - Guided requirements-gathering flow that produces product documents, then generates a task roadmap automatically.\n- **Human-in-the-loop Q\u0026A** - When a task needs human input, dotbot routes questions to stakeholders via **Teams**, **Email**, or **Jira**.\n- **Designed for teams** - The entire `.bot/` directory lives in your repo. Task queues, session histories, and plans are visible to everyone through git.\n\n### Foundation\n- **Zero-dependency tooling** - MCP server and web UI are pure PowerShell. No npm, pip, or Docker required. Cross-platform on Windows, macOS, and Linux.\n- **Security** - PathSanitizer strips absolute paths from AI output, privacy scan covers the full repo, and pre-commit hooks run gitleaks on staged files.\n\n## Prerequisites\n\n**Required:**\n- **PowerShell 7+** - [Download](https://aka.ms/powershell)\n- **Git** - [Download](https://git-scm.com/downloads)\n- **AI CLI** (at least one) - [Claude CLI](https://docs.anthropic.com/en/docs/claude-cli), [Codex CLI](https://github.com/openai/codex), or [Gemini CLI](https://github.com/google-gemini/gemini-cli)\n\n**Recommended MCP servers:**\n- **[Playwright MCP](https://github.com/anthropics/anthropic-quickstarts/tree/main/mcp-playwright)** - Browser automation for UI testing and verification.\n- **[Context7 MCP](https://github.com/upstash/context7)** - Library documentation lookup to reduce hallucination.\n\n## Quick Start\n\n### 1. Install dotbot globally (one-time)\n\n```powershell\nInstall-Module Dotbot -Scope CurrentUser\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eAlternative install methods\u003c/strong\u003e (CI/CD pipelines, contributors, or environments without PowerShellGet)\u003c/summary\u003e\n\n**One-liner (CI/CD, scripts):**\n```powershell\nirm https://raw.githubusercontent.com/andresharpe/dotbot/main/install-remote.ps1 | iex\n```\n\n**Git clone (contributors):**\n```powershell\ncd ~\ngit clone https://github.com/andresharpe/dotbot dotbot-install\ncd dotbot-install\npwsh install.ps1\n```\n\n\u003c/details\u003e\n\nRestart your terminal so the `dotbot` command is available.\n\n### 2. Add dotbot to your project\n\n```powershell\ncd your-project\ndotbot init\n```\n\nThis creates a `.bot/` directory with the MCP server, web UI, autonomous runtime, agents, skills, and workflows.\n\n\u003e **Keep `.bot/` tracked in git.**\n\u003e\n\u003e - dotbot commits `.bot/` during `dotbot init` because task worktrees use junctions/symlinks back to shared state, and integrity checks rely on git visibility.\n\u003e - If you add `.bot/` to `.gitignore` (or a global ignore file), worktree creation and the MCP server will fail silently.\n\u003e - The only paths meant to be ignored are already covered by `.bot/.gitignore` (`.control/`, `profile/`, runtime state).\n\u003e - Framework files under `.bot/systems/`, `.bot/hooks/`, and `.bot/recipes/` are protected by a pre-commit hook — direct edits are rejected; run `dotbot init --force` to update them.\n\u003e - A committed SHA256 manifest at `.bot/.manifest.json` (regenerated by `dotbot init --force`) lets the verify hook catch tampering that bypassed the pre-commit guard via `git commit --no-verify`.\n\n#### Workflows and Stacks\n\n```powershell\ndotbot init -Workflow start-from-jira               # Install a workflow\ndotbot init -Stack dotnet-blazor,dotnet-ef             # Install stacks\ndotbot init -Workflow start-from-jira -Stack dotnet  # Both\ndotbot list                                            # List available workflows and stacks\n```\n\n- **Workflow** - Defines a multi-step pipeline with tasks, dependencies, scripts, and form configuration via `workflow.yaml`. A project can have multiple workflows installed. Each can be run and re-run independently (`dotbot run \u003cname\u003e`).\n- **Stack** (composable) - Adds tech-specific skills, hooks, verify scripts, and MCP tools. Stacks can declare `extends` to auto-include a parent (e.g. `dotnet-blazor` extends `dotnet`).\n\nApply order: `default` -\u003e workflows -\u003e stacks (dependency-resolved). Settings are deep-merged; files are overlaid.\n\n#### Enterprise Registries\n\nTeams can publish workflows, stacks, tools, and skills in a git repo with a `registry.yaml` manifest:\n\n```powershell\ndotbot registry add myorg https://github.com/myorg/dotbot-extensions.git\ndotbot registry add myorg C:\\repos\\myorg-dotbot-extensions  # Local path\ndotbot registry update                                       # Update all registries\ndotbot registry update myorg                                 # Update one registry\ndotbot init -Workflow myorg:custom-workflow                  # Use from registry\n```\n\n### 3. Configure MCP Server\n\nAdd to your AI tool's MCP settings (Claude, Warp, etc.):\n\n```json\n{\n  \"mcpServers\": {\n    \"dotbot\": {\n      \"command\": \"pwsh\",\n      \"args\": [\"-NoProfile\", \"-File\", \".bot/systems/mcp/dotbot-mcp.ps1\"]\n    }\n  }\n}\n```\n\n### 4. Start the UI\n\n```powershell\n.bot\\go.ps1\n```\n\nOpens the web dashboard (default port 8686, auto-selects next available if busy).\n\n## Screenshots\n\n![Overview](assets/overview.png)\n![Product](assets/product.png)\n![Workflow](assets/workflow.png)\n![Settings](assets/settings.png)\n\n## Commands\n\n```powershell\ndotbot help                    # Show all commands\ndotbot init                    # Add dotbot to current project\ndotbot init -Force             # Reinitialize (preserves workspace data)\ndotbot init -Workflow \u003cname\u003e   # Install with a workflow\ndotbot init -Stack \u003cname\u003e      # Install with a tech stack\ndotbot list                    # List available workflows and stacks\ndotbot run \u003cworkflow\u003e          # Run/rerun a workflow\ndotbot workflow add \u003cname\u003e     # Add a workflow to existing project\ndotbot workflow remove \u003cname\u003e  # Remove an installed workflow\ndotbot workflow list           # List installed workflows\ndotbot registry add \u003cn\u003e \u003csrc\u003e  # Add an enterprise extension registry\ndotbot registry update [name]  # Update registry (all or named)\ndotbot registry list           # List registries and available content\ndotbot doctor                  # Run project health checks\ndotbot status                  # Check installation status\ndotbot update                  # Update global installation\n```\n\n**Updating via PowerShell Gallery:**\n```powershell\nUpdate-Module Dotbot\n```\n\n## Architecture\n\n```\n.bot/\n├── systems/            # Core systems\n│   ├── mcp/            # MCP server (stdio, auto-discovers tools)\n│   │   ├── tools/      # One folder per tool (metadata.yaml + script.ps1)\n│   │   └── modules/    # NotificationClient, PathSanitizer, SessionTracking\n│   ├── ui/             # Pure PowerShell HTTP server + vanilla JS frontend\n│   └── runtime/        # Autonomous loop, worktree manager, provider CLIs\n│       └── ProviderCLI/  # Stream parsers for Claude, Codex, Gemini\n├── workflows/          # Installed workflows (each with workflow.yaml + recipes/)\n│   └── \u003cname\u003e/         # workflow.yaml, recipes/, (optional systems/, workspace/)\n├── settings/           # Default settings + provider configurations\n│   ├── settings.default.json\n│   ├── theme.default.json\n│   └── providers/      # claude.json, codex.json, gemini.json\n├── recipes/            # AI content\n│   ├── agents/         # Specialized personas (implementer, planner, reviewer, tester)\n│   ├── skills/         # Reusable capabilities (status, verify, write-test-plan, write-unit-tests)\n│   ├── prompts/        # Numbered step-by-step processes (00-interview → 99-autonomous-task)\n│   ├── includes/       # Shared prompt fragments\n│   └── research/       # Research templates\n├── workspace/          # Version-controlled runtime state\n│   ├── tasks/          # Task queue (todo/analysing/analysed/in-progress/done/…)\n│   ├── sessions/       # Session history + run logs\n│   ├── product/        # Product docs (mission, tech stack, entity model)\n│   ├── plans/          # Execution plans\n│   ├── decisions/      # Architecture decision records\n│   └── reports/        # Generated reports\n├── hooks/              # Project-specific scripts (dev, scripts, verify)\n├── init.ps1            # IDE integration setup\n└── go.ps1              # Launch UI server\n```\n\n## MCP Tools\n\nThe dotbot MCP server exposes 33 tools, auto-discovered from `systems/mcp/tools/`:\n\n**Task Management** (15): `task_create`, `task_create_bulk`, `task_get_next`, `task_get_context`, `task_list`, `task_get_stats`, `task_mark_todo`, `task_mark_analysing`, `task_mark_analysed`, `task_mark_in_progress`, `task_mark_done`, `task_mark_needs_input`, `task_mark_skipped`, `task_answer_question`, `task_approve_split`\n\n**Decision Tracking** (7): `decision_create`, `decision_get`, `decision_list`, `decision_update`, `decision_mark_accepted`, `decision_mark_deprecated`, `decision_mark_superseded`\n\n**Session Management** (5): `session_initialize`, `session_get_state`, `session_get_stats`, `session_update`, `session_increment_completed`\n\n**Plans** (3): `plan_create`, `plan_get`, `plan_update`\n\n**Steering**: `steering_heartbeat`\n\n**Development**: `dev_start`, `dev_stop`\n\nWorkflows and stacks can add their own tools (e.g. `start-from-jira` adds `repo_clone`, `repo_list`, `atlassian_download`, `research_status`).\n\nSee `.bot/README.md` for full tool documentation.\n\n## Testing\n\nFour-layer test pyramid with ~500 assertions:\n\n| Layer | What it covers | Credentials |\n|-------|---------------|-------------|\n| 1 - Structure | Syntax validation, module exports, workflow manifest parsing, task creation, condition evaluation, multi-workflow isolation | None |\n| 2 - Components | MCP tool lifecycle, task types, decision tracking, provider CLI, notification client, workflow integration, UI server startup | None |\n| 3 - Mock Provider | Analysis/execution flows with mock Claude CLI, rate limit detection, stream parsing | None |\n| 4 - E2E | Full end-to-end with real AI provider API | API key |\n\n```powershell\npwsh tests/Run-Tests.ps1            # Run layers 1-3\npwsh tests/Run-Tests.ps1 -Layer 1   # Structure tests\npwsh tests/Run-Tests.ps1 -Layer 2   # Component tests\npwsh tests/Run-Tests.ps1 -Layer 3   # Mock provider tests\npwsh tests/Run-Tests.ps1 -Layer 4   # E2E (requires API key)\n```\n\nCI runs layers 1-3 on every push and PR across Windows, macOS, and Linux. Layer 4 runs on schedule or manual trigger.\n\n## Troubleshooting\n\n**`dotbot` command not found after install** - Restart your terminal. The installer adds `~/dotbot/bin` to your PATH.\n\n**Script execution blocked on Windows** - Run `Set-ExecutionPolicy RemoteSigned -Scope CurrentUser` and try again.\n\n**PowerShell version error** - Requires PowerShell 7+. Check with `$PSVersionTable.PSVersion` and [upgrade](https://aka.ms/powershell) if needed.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandresharpe%2Fdotbot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandresharpe%2Fdotbot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandresharpe%2Fdotbot/lists"}