{"id":50774553,"url":"https://github.com/dporkka/dev-plane","last_synced_at":"2026-06-11T22:02:22.675Z","repository":{"id":363817497,"uuid":"1261474989","full_name":"dporkka/dev-plane","owner":"dporkka","description":"AI development control plane. Takes tasks from prompts, GitHub issues, Linear tickets, Slack/Discord commands, or voice and turns them into isolated branches, code changes, tests, reviews, pull requests, and deployment-gated releases.","archived":false,"fork":false,"pushed_at":"2026-06-10T12:37:42.000Z","size":524,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-10T14:20:13.606Z","etag":null,"topics":["ai-agents","ai-development","go","linear","nats","orchestration","orchestrator","task-management","temporal"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dporkka.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/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":null,"dco":null,"cla":null}},"created_at":"2026-06-06T18:29:06.000Z","updated_at":"2026-06-09T13:48:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dporkka/dev-plane","commit_stats":null,"previous_names":["dporkka/dev-plane"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/dporkka/dev-plane","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dporkka%2Fdev-plane","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dporkka%2Fdev-plane/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dporkka%2Fdev-plane/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dporkka%2Fdev-plane/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dporkka","download_url":"https://codeload.github.com/dporkka/dev-plane/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dporkka%2Fdev-plane/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34219510,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","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-agents","ai-development","go","linear","nats","orchestration","orchestrator","task-management","temporal"],"created_at":"2026-06-11T22:02:21.664Z","updated_at":"2026-06-11T22:02:22.669Z","avatar_url":"https://github.com/dporkka.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AI Dev Control Plane\n\n\u003e A production-grade, self-hostable AI development control plane. Takes tasks from\n\u003e prompts, GitHub issues, Linear tickets, Slack/Discord commands, or voice and turns\n\u003e them into isolated branches, code changes, tests, reviews, pull requests, and\n\u003e deployment-gated releases.\n\n[![Go Version](https://img.shields.io/badge/Go-1.23+-00ADD8?logo=go)](https://go.dev)\n[![Next.js](https://img.shields.io/badge/Next.js-16-000000?logo=next.js)](https://nextjs.org)\n[![NATS](https://img.shields.io/badge/NATS-JetStream-27AAE1?logo=nats.io)](https://nats.io)\n[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\n---\n\n## Architecture\n\n```\n +-------------------+       +-------------------+       +-------------------+\n |   Next.js 16      |\u003c-----\u003e|   Go API Server   |\u003c-----\u003e|   NATS JetStream  |\n |   (Port 3000)     |  HTTP |   (Port 8080)     |  NATS |   (Port 4222)     |\n |                   |       |                   |       |                   |\n | - CodeMirror 6    |       | - Chi Router      |       | - Event Bus       |\n | - shadcn/ui       |       | - SQLC + Goose    |       | - Task Streams    |\n | - Zustand         |       | - JWT + OAuth     |       | - Pub/Sub         |\n | - TanStack Query  |       | - SSE Stream      |       | - Persistence     |\n +-------------------+       +--------+----------+       +-------------------+\n                                      |\n                                      |  gRPC / HTTP\n                                      v\n +-------------------+       +-------------------+       +-------------------+\n |   Go Worker       |\u003c-----\u003e|   Go Runner       |       |   Temporal        |\n |   (Background)    |  NATS |   (Port 8082)     |       |   (Port 7233)     |\n |                   |       |                   |       |                   |\n | - Task Processor  |       | - Docker Sandbox  |       | - Workflows       |\n | - Agent Orchestr. |       | - Git Operations  |       | - Durability      |\n | - Event Consumer  |       | - Code Execution  |       | - (Optional)      |\n +-------------------+       +-------------------+       +-------------------+\n\n +-------------------+       +-------------------+\n |   GitHub App      |       |   AI Providers    |\n |   (Webhooks)      |       |   (Bifrost/Direct)|\n |                   |       |                   |\n | - Issue Sync      |       | - OpenAI          |\n | - PR Management   |       | - Anthropic       |\n | - Webhook Events  |       | - Bifrost Gateway |\n +-------------------+       +-------------------+\n```\n\n---\n\n## Tech Stack\n\n### Frontend\n- **Next.js 16** with App Router\n- **React 19** + TypeScript 5\n- **Tailwind CSS 4** + shadcn/ui components\n- **CodeMirror 6** for code editing\n- **Zustand** for state management\n- **TanStack Query** for API fetching\n- **Server-Sent Events** for live updates\n\n### Backend\n- **Go 1.23+** with Chi router\n- **SQLC** for type-safe database queries\n- **Goose** for database migrations\n- **log/slog** for structured logging\n- **JWT** + OAuth2 for authentication\n\n### Infrastructure\n- **NATS JetStream** for event streaming\n- **Temporal** (optional) for durable workflows\n- **SQLite** (local) / **PostgreSQL** (cloud)\n- **Docker** + Docker Compose for local dev\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- [Go 1.23+](https://go.dev/dl/)\n- [Node.js 20+](https://nodejs.org/)\n- [Docker](https://docs.docker.com/get-docker/) \u0026 Docker Compose\n- [Git](https://git-scm.com/)\n\n### 1. Clone \u0026 Setup\n\n```bash\n# Clone the repository\ngit clone \u003crepo-url\u003e ai-dev-control-plane\ncd ai-dev-control-plane\n\n# Copy environment template\ncp .env.example .env\n\n# (Optional) Edit .env with your GitHub App credentials\n# nano .env\n```\n\n### 2. Start Development Environment\n\n```bash\n# Start everything (Docker services + all apps)\nmake dev\n\n# Or start services individually:\nmake docker-up       # Start NATS, Temporal (optional)\nmake migrate         # Run database migrations\nmake dev-api         # Start API server (port 8080)\nmake dev-web         # Start Next.js (port 3000)\nmake dev-worker      # Start worker service\n```\n\n### 3. Access the Application\n\n| Service | URL | Description |\n|---|---|---|\n| Web UI | http://localhost:3000 | Next.js frontend |\n| API | http://localhost:8080 | Go API server |\n| NATS | nats://localhost:4222 | Message bus |\n| NATS Monitor | http://localhost:8222 | NATS dashboard |\n| Temporal UI | http://localhost:8233 | Workflow UI (if enabled) |\n\n### Optional AgentVault Logging\n\nDev Plane can capture task lifecycle events into a local AgentVault inbox:\n\n```bash\nAGENTVAULT_URL=http://127.0.0.1:47321\nAGENTVAULT_TOKEN=\u003ctoken printed by agentvault serve\u003e\nAGENTVAULT_PROJECT=dev-plane\n```\n\nWhen configured, task creation events are posted to AgentVault's `/capture` endpoint. Logging is best-effort; Dev Plane continues working if AgentVault is offline.\n\n### Dev Plan Brief Handoff\n\nDev Plan Builder's Brief bundles can create implementation tasks through:\n\n```http\nPOST /api/v1/projects/{projectID}/brief-handoffs\n```\n\nThe endpoint accepts `repository_id` plus a `brief_url`, `brief_zip_url`, or inline `documents` array, then creates a normal task with `source=dev_plan_brief` and stores the brief pointers in `spec`/`metadata`.\n\n---\n\n## Available Commands\n\n### Development\n\n| Command | Description |\n|---|---|\n| `make dev` | Start all services (docker-up, migrate, web/api/worker) |\n| `make dev-web` | Start Next.js dev server |\n| `make dev-api` | Start Go API (with Air hot reload if available) |\n| `make dev-worker` | Start Go worker |\n| `make dev-runner` | Start Go runner service |\n\n### Docker\n\n| Command | Description |\n|---|---|\n| `make docker-up` | Start Docker services (NATS, etc.) |\n| `make docker-down` | Stop Docker services |\n| `make docker-logs` | Follow all service logs |\n| `make docker-status` | Show service status |\n| `make docker-down-volumes` | Stop and remove volumes (DESTRUCTIVE) |\n\n### Database\n\n| Command | Description |\n|---|---|\n| `make migrate` | Run Goose migrations |\n| `make db-reset` | Delete DB and recreate (DESTRUCTIVE) |\n| `make db-status` | Show migration status |\n| `make gen-db` | Generate SQLC typed code |\n\n### Testing\n\n| Command | Description |\n|---|---|\n| `make test` | Run all Go tests |\n| `make test-api` | Run API tests (verbose) |\n| `make test-worker` | Run worker tests |\n| `make test-race` | Run tests with race detector |\n| `make test-coverage` | Generate coverage report |\n\n### Linting \u0026 Build\n\n| Command | Description |\n|---|---|\n| `make lint` | Run all linters (Go + frontend) |\n| `make lint-go` | Run Go vet across all modules |\n| `make lint-web` | Run npm lint |\n| `make build` | Build all binaries + frontend |\n| `make clean` | Remove build artifacts |\n| `make fmt` | Format all Go code |\n\n### Utilities\n\n| Command | Description |\n|---|---|\n| `make install-tools` | Install dev tools (Air, Goose, SQLC) |\n| `make deps` | Download Go dependencies |\n| `make help` | Show this help |\n\n---\n\n## Project Structure\n\n```\nai-dev-control-plane/\n|_ Makefile                          # Root build orchestration\n|_ docker-compose.yml                # Local services (NATS, Temporal)\n|_ .env.example                      # Environment template\n|_ go.work                           # Go workspace\n|_ go.work.sum\n|\n|_ apps/\n|  |_ web/                           # Next.js 16 frontend\n|  |  |_ app/                        # App Router\n|  |  |_ components/                 # React components\n|  |  |_ lib/                        # Client utilities\n|  |  |_ package.json\n|  |  |_ next.config.js\n|  |  |_ tailwind.config.ts\n|  |  |_ tsconfig.json\n|  |\n|  |_ api/                           # Go control plane API\n|  |  |_ cmd/api/main.go\n|  |  |_ internal/\n|  |  |  |_ server/server.go\n|  |  |  |_ handlers/\n|  |  |  |_ middleware/\n|  |  |  |_ config/config.go\n|  |  |  |_ auth/\n|  |  |_ go.mod\n|  |  |_ go.sum\n|  |\n|  |_ worker/                        # Go background workers\n|  |  |_ cmd/worker/main.go\n|  |  |_ internal/\n|  |  |_ go.mod\n|  |  |_ go.sum\n|  |\n|  |_ runner/                        # Go sandbox/runtime service\n|     |_ cmd/runner/main.go\n|     |_ internal/\n|     |_ go.mod\n|     |_ go.sum\n|\n|_ packages/\n|  |_ db/                            # Database: schema, migrations, SQLC\n|  |  |_ schema.sql\n|  |  |_ migrations/                 # Goose migrations\n|  |  |_ queries/                    # SQLC query files\n|  |  |_ sqlc.yaml\n|  |  |_ gen/                        # Generated SQLC code\n|  |  |_ adapters/                   # DB adapters (SQLite/Postgres)\n|  |  |_ db.go                       # Unified DB interface\n|  |\n|  |_ agents/                        # Agent interfaces, tool definitions\n|  |_ runtimes/                      # Runtime provider interface\n|  |_ repo-intel/                    # Repo indexing basics\n|  |_ events/                        # NATS event schemas + bus\n|  |_ models/                        # Shared domain models\n|  |_ policies/                      # Permission + policy engine\n|  |_ gateway/                       # GitHub, webhook handlers\n|\n|_ infra/\n   |_ docker/\n      |_ api.Dockerfile              # API multi-stage build\n      |_ worker.Dockerfile           # Worker multi-stage build\n      |_ runner.Dockerfile           # Runner with Docker-in-Docker\n      |_ web.Dockerfile              # Next.js standalone build\n```\n\n---\n\n## Development Guide\n\n### Go Workspace\n\nThis project uses Go 1.23 workspaces. The root `go.work` file includes all\nmodules. To work on a specific module:\n\n```bash\n# Sync workspace dependencies\ngo work sync\n\n# Run a specific module's tests\ncd apps/api \u0026\u0026 go test ./...\n\n# Build a specific binary\ncd apps/api \u0026\u0026 go build -o ../../bin/api cmd/api/main.go\n```\n\n### Adding Migrations\n\n```bash\n# Create a new migration\ncd packages/db \u0026\u0026 goose -dir migrations create add_users_table sql\n\n# Edit the generated .sql file, then:\nmake migrate       # Apply migrations\nmake db-status     # Check status\n```\n\n### Generating SQLC Code\n\nAfter modifying `schema.sql` or query files in `packages/db/queries/`:\n\n```bash\nmake gen-db\n```\n\n### Hot Reload\n\nInstall [Air](https://github.com/air-verse/air) for automatic Go server restart\non file changes:\n\n```bash\nmake install-tools    # Installs Air, Goose, SQLC\nmake dev-api          # Auto-uses Air if available\n```\n\n---\n\n## Environment Variables\n\nAll variables are defined in `.env.example`. Key categories:\n\n| Category | Variables | Description |\n|---|---|---|\n| **Database** | `DATABASE_URL` | SQLite (local) or Postgres (cloud) |\n| **Auth** | `JWT_SECRET`, `GITHUB_*` | JWT signing + GitHub OAuth/App |\n| **Services** | `NATS_URL`, `TEMPORAL_HOST` | Message bus + workflow engine |\n| **Ports** | `PORT`, `WEB_PORT` | Service port bindings |\n| **AI** | `BIFROST_URL`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, `GROQ_API_KEY`, `FIREWORKS_API_KEY` | AI provider configuration |\n| **Runtime** | `RUNNER_BASE_DIR`, `DOCKER_HOST` | Sandbox settings |\n| **Frontend** | `NEXT_PUBLIC_*` | Public frontend config |\n| **Features** | `ENABLE_TEMPORAL`, `REQUIRE_RISK_APPROVAL` | Feature toggles |\n\nSee `.env.example` for full documentation and default values.\n\n---\n\n## Database Setup\n\n### SQLite (Default -- Local Development)\n\n```bash\n# Migrations run automatically with `make dev`\n# DB file is created at: ./data/dev.db\n\n# Reset database (DESTRUCTIVE):\nmake db-reset\n```\n\n### PostgreSQL (Cloud/Production)\n\n```bash\n# 1. Uncomment postgres service in docker-compose.yml\n# 2. Update DATABASE_URL in .env:\nDATABASE_URL=postgres://user:pass@localhost:5432/aicp?sslmode=disable\n# 3. Start services:\ndocker-compose up -d postgres\nmake migrate\n```\n\n### Migration Compatibility\n\nMigration files must be compatible with **both SQLite and PostgreSQL**:\n- Use standard SQL types (`TEXT`, `INTEGER`, `BOOLEAN`)\n- Use `JSONB` in schema (adapters handle SQLite translation)\n- Avoid database-specific features in migrations\n\n---\n\n## NATS / JetStream Setup\n\nNATS starts automatically with `make docker-up`. JetStream is enabled for\npersistent event streaming.\n\n```bash\n# Start NATS\nmake docker-up\n\n# Check NATS health\ncurl http://localhost:8222/healthz\n\n# View NATS dashboard\nopen http://localhost:8222\n\n# Stream logs\nmake docker-logs-nats\n```\n\nStreams are created automatically by the application on startup:\n- `AICP_TASKS` -- Task lifecycle events\n- `AICP_AGENT_RUNS` -- Agent execution events\n- `AICP_AUDIT` -- Audit log events\n\n---\n\n## GitHub App Configuration\n\n### 1. Create a GitHub App\n\n1. Go to **Settings \u003e Developer settings \u003e GitHub Apps \u003e New GitHub App**\n2. Fill in the required fields:\n   - **GitHub App name**: Your app name\n   - **Homepage URL**: `http://localhost:3000`\n   - **Webhook URL**: `https://your-ngrok.ngrok.io/webhooks/github`\n   - **Webhook secret**: Generate a secure random string\n\n3. Set permissions:\n   - **Repository**: Read \u0026 Write (code, issues, pull requests)\n   - **Commit statuses**: Read \u0026 Write\n   - **Webhooks**: Read\n\n4. Subscribe to events:\n   - Pull request\n   - Push\n   - Issues\n   - Create (branches/tags)\n\n5. Generate a private key and download the `.pem` file\n\n### 2. Configure Environment\n\n```bash\n# .env\nGITHUB_APP_ID=your-app-id\nGITHUB_APP_PRIVATE_KEY=\"-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----\"\nGITHUB_APP_WEBHOOK_SECRET=your-webhook-secret\nGITHUB_CLIENT_ID=your-client-id\nGITHUB_CLIENT_SECRET=your-client-secret\nGITHUB_TOKEN=your-github-app-installation-or-fine-scoped-token\n```\n\n### 3. Install the App\n\nInstall the GitHub App on your repositories to start receiving webhooks.\n\n---\n\n## Docker Services\n\n### Available Services\n\n| Service | Image | Port | Purpose |\n|---|---|---|---|\n| NATS | `nats:2.10-alpine` | 4222, 8222 | Event bus + JetStream |\n| Temporal | `temporalio/auto-setup:1.25` | 7233, 8233 | Workflow engine (optional) |\n\n### Operations\n\n```bash\n# Start all core services\nmake docker-up\n\n# Start with Temporal\nmake docker-up\n# In another terminal:\ndocker-compose --profile temporal up -d\n\n# View logs\nmake docker-logs\n\n# Stop everything\nmake docker-down\n\n# Full reset (removes volumes!)\nmake clean-all\n```\n\n---\n\n## Phase Roadmap\n\n### Phase 1: Foundation (Current)\n- [x] Monorepo structure with Go workspace\n- [x] Next.js frontend shell with CodeMirror 6\n- [x] Go API with Chi router + JWT auth\n- [x] Database abstraction (SQLite/Postgres)\n- [x] Goose migrations + SQLC code generation\n- [x] NATS JetStream event bus\n- [x] Docker Compose local services\n- [x] Multi-stage Dockerfiles\n- [x] GitHub integration (OAuth + App webhooks)\n- [x] Makefile orchestration\n\n### Phase 2: Agent Runtime\n- [x] Docker sandboxed code execution\n- [x] Agent tool system (read, edit, test, git)\n- [ ] Multi-model provider support\n- [x] Spec generation + approval flow\n- [x] Branch isolation + workspace management\n\n### Phase 3: Collaboration\n- [x] Team management + RBAC\n- [x] Review workflows (human-in-the-loop)\n- [x] PR auto-creation\n- [ ] Merge/deployment gating\n- [x] Audit logging\n\n### Phase 4: Integrations\n- [ ] Linear ticket sync\n- [ ] Slack/Discord bot commands\n- [ ] Voice input (whisper)\n- [ ] Webhook extensibility\n- [ ] Public API + SDK\n\n---\n\n## Contributing\n\n1. **Fork** the repository\n2. **Create a branch**: `git checkout -b feat/my-feature`\n3. **Make your changes** with tests\n4. **Run checks**: `make lint \u0026\u0026 make test`\n5. **Commit**: `git commit -m \"feat: add my feature\"`\n6. **Push**: `git push origin feat/my-feature`\n7. **Open a Pull Request**\n\n### Commit Convention\n\nWe follow conventional commits:\n- `feat:` -- New feature\n- `fix:` -- Bug fix\n- `docs:` -- Documentation\n- `refactor:` -- Code refactoring\n- `test:` -- Adding tests\n- `chore:` -- Maintenance tasks\n\n---\n\n## License\n\nMIT License. See [LICENSE](LICENSE) for details.\n\n---\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/your-org/ai-dev-control-plane/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/your-org/ai-dev-control-plane/discussions)\n- **Documentation**: See `/docs` directory\n\n---\n\n\u003cp align=\"center\"\u003e\n  Built with Go + Next.js + NATS\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdporkka%2Fdev-plane","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdporkka%2Fdev-plane","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdporkka%2Fdev-plane/lists"}