{"id":35886866,"url":"https://github.com/metazen11/workflow-hub","last_synced_at":"2026-01-08T21:03:29.167Z","repository":{"id":331253410,"uuid":"1122315500","full_name":"metazen11/workflow-hub","owner":"metazen11","description":"Open source agentic team workflow - AI agents collaborate through Kanban pipeline (PM→DEV→QA→SEC) with human-in-the-loop approval gates","archived":false,"fork":false,"pushed_at":"2026-01-04T13:30:51.000Z","size":46409,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-05T01:27:03.947Z","etag":null,"topics":["agentic","ai-agents","automation","code-quality","developer-tools","devops","django","kanban","llm","local-first","multi-agent","open-source","pipeline","python","tdd","workflow"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/metazen11.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"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":"CLA.md"}},"created_at":"2025-12-24T13:32:09.000Z","updated_at":"2026-01-04T13:30:55.000Z","dependencies_parsed_at":null,"dependency_job_id":"e420b1fc-6a7c-49ac-a959-12d2ee8a3cbf","html_url":"https://github.com/metazen11/workflow-hub","commit_stats":null,"previous_names":["metazen11/workflow-hub"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/metazen11/workflow-hub","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metazen11%2Fworkflow-hub","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metazen11%2Fworkflow-hub/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metazen11%2Fworkflow-hub/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metazen11%2Fworkflow-hub/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/metazen11","download_url":"https://codeload.github.com/metazen11/workflow-hub/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metazen11%2Fworkflow-hub/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28248941,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2026-01-08T02:00:06.591Z","response_time":241,"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","ai-agents","automation","code-quality","developer-tools","devops","django","kanban","llm","local-first","multi-agent","open-source","pipeline","python","tdd","workflow"],"created_at":"2026-01-08T21:02:16.580Z","updated_at":"2026-01-08T21:03:29.161Z","avatar_url":"https://github.com/metazen11.png","language":"Python","readme":"# Workflow Hub\n\n[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)\n[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)\n\n**Open source agentic team workflow** - AI agents collaborate through a Kanban-style pipeline with human-in-the-loop approval gates.\n\n\u003e 🤖 **Multi-agent AI development workflow** where PM, Developer, QA, and Security agents work together autonomously while humans maintain control at critical checkpoints.\n\n---\n\n## Why Workflow Hub?\n\nModern AI coding assistants are powerful but chaotic. Workflow Hub brings **structure and accountability** to agentic development:\n\n- **Agents work in defined roles** - PM breaks down requirements, DEV implements, QA writes tests, SEC reviews for vulnerabilities\n- **Quality gates prevent bad code** - No deployment without passing tests and security review\n- **Human-in-the-loop** - You approve what gets deployed, not the AI\n- **Full audit trail** - See exactly what each agent did and why\n- **Local-first** - Your code, your LLMs, your control\n\n```\n┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌──────────┐\n│   PM    │ → │   DEV   │ → │   QA    │ → │   SEC   │ → │  DEPLOY  │\n│  Agent  │    │  Agent  │    │  Agent  │    │  Agent  │    │ (Human)  │\n└─────────┘    └─────────┘    └─────────┘    └─────────┘    └──────────┘\n     │              │              │              │              │\n   Specs        Code +         Tests +       Security       Approved\n   Tasks        Impl          Coverage        Scan          Release\n## Features\n\n- **Multi-Agent Pipeline** - PM → DEV → QA → SEC → Deploy with automated handoffs\n- **Job Queue System** - Priority-based queuing for LLM requests and agent executions to prevent resource contention\n- **Database-Backed Queue** - Persistent job storage ensuring no jobs are lost during restarts\n- **Background Processing** - Dedicated workers process jobs without blocking the main application\n- **Priority Scheduling** - Critical operations get higher priority (CRITICAL, HIGH, NORMAL, LOW)\n- **Timeout Management** - Automatic timeout handling for long-running jobs\n- **Comprehensive Error Handling** - Robust job state tracking and recovery mechanisms\n\n## Prerequisites\n- **Kanban Dashboard** - Visual task board showing agent progress through stages\n- **TDD Enforced** - QA agent writes tests first, DEV makes them pass\n- **Security Gates** - Automated vulnerability scanning before deployment\n- **Local LLM Support** - Use Ollama, Docker Model Runner, or cloud APIs\n- **Project Discovery** - Auto-detect tech stack, dependencies, and structure\n- **Credential Vault** - Secure storage for API keys, SSH keys, tokens\n- **Environment Management** - Configure dev, staging, production\n- **Webhook Integration** - n8n-compatible for external automation\n- **Full Audit Trail** - Every action logged and traceable\n\n## Prerequisites\n\n- **Python 3.9+**\n- **Docker Desktop** (for PostgreSQL and LLM models)\n- **Goose CLI** (optional, for agent execution)\n\n## Quick Installation\n\nThe fastest way to get started:\n\n```bash\ngit clone https://github.com/metazen11/workflow-hub.git\ncd workflow-hub\n./scripts/install.sh\n```\n\nThis script will:\n1. Check prerequisites (Python, Docker)\n2. Create Python virtual environment\n3. Install dependencies\n4. Configure environment (.env)\n5. Start PostgreSQL via Docker\n6. Run database migrations\n7. Seed agent role configurations\n8. Pull LLM models (qwen3-coder, qwen3-vl)\n\n**Options:**\n```bash\n./scripts/install.sh --skip-models   # Skip LLM model download\n./scripts/install.sh --skip-docker   # Skip Docker service startup\n```\n\nAfter installation:\n```bash\nsource venv/bin/activate\nsource .env\npython manage.py runserver 0.0.0.0:8000\n```\n\nThen open: http://localhost:8000/ui/\n\n## Manual Installation\n\n### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/metazen11/workflow-hub.git\ncd workflow-hub\n```\n\n### 2. Start PostgreSQL\n\nUsing Docker (recommended):\n```bash\ndocker compose -f docker/docker-compose.yml up -d\n```\n\nOr connect to an existing PostgreSQL instance.\n\n### 3. Set Up Python Environment\n\n```bash\npython3 -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\npip install -r requirements.txt\n```\n\n### 4. Configure Environment\n\n```bash\n# Copy example environment file\ncp .env.example .env\n\n# Edit .env with your settings:\n# - Set DATABASE_URL to your PostgreSQL connection string\n# - Generate a new DJANGO_SECRET_KEY\n# - Configure LLM settings if using agents\n```\n\n**Generate Django Secret Key:**\n```bash\npython -c \"from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())\"\n```\n\n### 5. Run Database Migrations\n\n```bash\nsource venv/bin/activate\nsource .env\nalembic upgrade head\n```\n\n### 6. Seed Role Configurations\n\n```bash\npython scripts/seed_role_configs.py\n```\n\n### 7. Pull LLM Models (Optional)\n\nFor agent execution via Docker Model Runner:\n```bash\ndocker model pull ai/qwen3-coder    # Code generation\ndocker model pull ai/qwen3-vl       # Vision/screenshots\n```\n\n### 8. Start the Server\n\n```bash\npython manage.py runserver 0.0.0.0:8000\n```\n\n### 9. Open the Dashboard\n\nNavigate to http://localhost:8000/ui/\n\n## Architecture\n\n```\nPM → DEV → QA → SEC → READY_FOR_COMMIT → MERGED → READY_FOR_DEPLOY → DEPLOYED\n              ↓        ↓\n          QA_FAILED  SEC_FAILED (can retry)\n```\n\n## Goose AI Integration\n\nWorkflow Hub includes an integrated Goose AI assistant that provides:\n\n- **Direct Integration** - No separate Goose webserver required\n- **Context Awareness** - The assistant understands your current workflow project\n- **Seamless Access** - Full AI capabilities accessible through Workflow Hub UI\n\n```\nPM → DEV → QA → SEC → READY_FOR_COMMIT → MERGED → READY_FOR_DEPLOY → DEPLOYED\n              ↓        ↓\n          QA_FAILED  SEC_FAILED (can retry)\n```\n\n## Job Queue System\n\nWorkflow Hub uses a priority-based job queue to manage LLM requests and agent executions. This is essential because:\n\n- Local LLMs (via Docker Model Runner) and Goose agents can only process one request at a time\n- Prevents resource contention and ensures orderly execution\n- Provides priority-based scheduling for critical operations\n- Supports background processing of non-blocking tasks\n\n```\nLLM Queue      Agent Queue      Vision Queue\nPriority       Priority         Low Priority\n```\n\n```\nPM → DEV → QA → SEC → READY_FOR_COMMIT → MERGED → READY_FOR_DEPLOY → DEPLOYED\n              ↓        ↓\n          QA_FAILED  SEC_FAILED (can retry)\n```\n\n**Gate Enforcement:**\n- QA must pass before Security review\n- Security must pass before code is ready for commit\n- Human approval required for deployment\n\n## Multi-Agent Workflow\n\nEach agent has a specific role and responsibilities:\n\n| Agent | Role | Responsibility |\n|-------|------|----------------|\n| **PM** | Product Manager | Defines requirements, updates `_spec/*.md` |\n| **DEV** | Developer | Implements code to satisfy tests |\n| **QA** | Quality Assurance | Writes failing tests first (TDD) |\n| **Security** | Security Engineer | Converts threat intel into tests/scanners |\n\n### Running Agents\n\nUse the workflow CLI to run agents:\n\n```bash\n# Run the full pipeline for a project\n./wf pipeline --project-id 1\n\n# Run a single agent\n./wf run pm --run-id 1\n./wf run dev --run-id 1\n./wf run qa --run-id 1\n./wf run sec --run-id 1\n```\n\nOr use the agent runner script directly:\n```bash\npython scripts/agent_runner.py pipeline --run-id 328\n```\n\n## Dashboard UI\n\nThe dashboard provides a visual interface for:\n\n- **Home** (`/ui/`): Kanban board of all runs, stats, activity feed\n- **Projects** (`/ui/projects/`): List and manage projects\n- **Project Detail** (`/ui/project/{id}/`):\n  - Overview with tech stack, commands, key files\n  - Tasks management\n  - Credentials storage (API keys, SSH keys, tokens)\n  - Environment configuration (dev, staging, prod)\n  - Project settings\n- **Bug Reports** (`/ui/bugs/`): Track and manage bugs\n- **Runs** (`/ui/runs/`): Monitor pipeline runs\n\n## API Reference\n\n### Job Queue\n\n```bash\n# Get queue status\ncurl http://localhost:8000/api/queue/status\n\n# Enqueue job\ncurl -X POST http://localhost:8000/api/queue/enqueue \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"job_type\": \"llm_complete\",\n    \"request_data\": {\"prompt\": \"Hello\"},\n    \"priority\": 3,\n    \"timeout\": 300\n  }'\n\n# Cancel job\ncurl -X POST http://localhost:8000/api/queue/jobs/{id}/cancel\n```\n\n### Projects\n\n```bash\n# List projects\ncurl http://localhost:8000/api/projects\n\n# Create project\ncurl -X POST http://localhost:8000/api/projects/create \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"My Project\", \"description\": \"...\", \"repo_path\": \"/path/to/repo\"}'\n\n# Get project with full context (for orchestrator)\ncurl http://localhost:8000/api/projects/{id}/context\n\n# Update project\ncurl -X PATCH http://localhost:8000/api/projects/{id}/update \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"languages\": [\"python\"], \"frameworks\": [\"django\"]}'\n\n# Execute project pipeline\ncurl -X POST http://localhost:8000/api/projects/{id}/execute\n```\n\n### Credentials\n\n```bash\n# List credentials for a project\ncurl http://localhost:8000/api/projects/{id}/credentials\n\n# Create credential\ncurl -X POST http://localhost:8000/api/projects/{id}/credentials/create \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"GitHub API\",\n    \"credential_type\": \"api_key\",\n    \"service\": \"github\",\n    \"api_key_encrypted\": \"your_api_key\"\n  }'\n\n# Delete credential\ncurl -X DELETE http://localhost:8000/api/credentials/{id}/delete\n```\n\n### Environments\n\n```bash\n# List environments for a project\ncurl http://localhost:8000/api/projects/{id}/environments\n\n# Create environment\ncurl -X POST http://localhost:8000/api/projects/{id}/environments/create \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"Production\",\n    \"env_type\": \"production\",\n    \"url\": \"https://app.example.com\",\n    \"ssh_host\": \"server.example.com\",\n    \"ssh_user\": \"deploy\"\n  }'\n```\n\n### Tasks\n\n```bash\n# Create task\ncurl -X POST http://localhost:8000/api/projects/{id}/tasks/create \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"task_id\": \"T1\", \"title\": \"Implement login form\"}'\n\n# Update task status\ncurl -X POST http://localhost:8000/api/tasks/{id}/status \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"status\": \"in_progress\"}'\n\n# Execute single task through pipeline\ncurl -X POST http://localhost:8000/api/tasks/{id}/execute\n```\n\n### Runs (Development Cycles)\n\n```bash\n# Create a run\ncurl -X POST http://localhost:8000/api/projects/{id}/runs/create \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"Run 2025-12-26_01\"}'\n\n# Get run details\ncurl http://localhost:8000/api/runs/{id}\n\n# Submit agent report\ncurl -X POST http://localhost:8000/api/runs/{id}/report \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"role\": \"qa\",\n    \"status\": \"pass\",\n    \"summary\": \"All 35 tests pass\",\n    \"details\": {\"tests_run\": 35, \"tests_passed\": 35}\n  }'\n\n# Advance to next state\ncurl -X POST http://localhost:8000/api/runs/{id}/advance\n\n# Retry from failed state\ncurl -X POST http://localhost:8000/api/runs/{id}/retry\n\n# Reset to DEV state (from QA/SEC failed)\ncurl -X POST http://localhost:8000/api/runs/{id}/reset-to-dev\n\n# Human approval for deployment\ncurl -X POST http://localhost:8000/api/runs/{id}/approve-deploy\n```\n\n### Bug Reports\n\n```bash\n# List bugs\ncurl http://localhost:8000/api/bugs\n\n# Create bug\ncurl -X POST http://localhost:8000/api/bugs/create \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"title\": \"Login button not working\",\n    \"description\": \"...\",\n    \"app_name\": \"frontend\"\n  }'\n\n# Update bug status\ncurl -X POST http://localhost:8000/api/bugs/{id}/status \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"status\": \"resolved\"}'\n```\n\n### Webhooks\n\n```bash\n# Create webhook (for n8n integration)\ncurl -X POST http://localhost:8000/api/webhooks/create \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"Slack Notifications\",\n    \"url\": \"https://your-n8n-instance/webhook/...\",\n    \"events\": [\"run.state_changed\", \"bug.created\"]\n  }'\n```\n\n## Running Tests\n\n```bash\nsource venv/bin/activate\npytest tests/ -v\n```\n\n## Project Structure\n\n```\napp/\n├── db/              # SQLAlchemy engine/session\n├── models/          # Project, Task, Run, Credential, Environment, etc.\n├── services/        # Business logic (RunService, WebhookService)\n├── views/           # API and UI views\n├── templates/       # Django templates\n├── static/          # CSS and JavaScript\n└── urls.py          # URL routing\n\nscripts/             # Agent runner, CLI tools\n_spec/               # Specifications (PM-managed)\n├── BRIEF.md         # Current sprint goal\n├── HANDOFF.md       # Session handoff notes\n└── ...\n\ndocs/                # Additional documentation\ntests/               # Pytest test suite\nalembic/             # Database migrations\ndocker/              # Docker compose files\n```\n\n## Key Rules\n\n1. **QA writes tests first** (TDD) - Dev does not weaken tests\n2. **Only PM updates `_spec/*.md`** - Single source of truth\n3. **Tests define truth** - If tests pass, feature is done\n4. **Human approval for deploy** - No automated deployments\n5. **Every action is logged** - Full audit trail\n\n## Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `DATABASE_URL` | PostgreSQL connection string | Required |\n| `DJANGO_SECRET_KEY` | Django secret key | Required in production |\n| `WORKFLOW_HUB_URL` | Hub URL for agents | `http://localhost:8000` |\n| `WORKFLOW_MAX_ITER` | Max retry iterations | `3` |\n| `GOOSE_PROVIDER` | LLM provider (ollama) | `ollama` |\n| `OLLAMA_HOST` | Ollama/Docker Model Runner URL | `http://localhost:12434` |\n| `GOOSE_MODEL` | Model for agent code generation | `ai/qwen3-coder:latest` |\n| `VISION_MODEL` | Model for screenshot analysis | `ai/qwen3-vl` |\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributor License Agreement](CLA.md) before submitting a pull request.\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Add your name to [CONTRIBUTORS.md](CONTRIBUTORS.md)\n4. Commit your changes (`git commit -m 'Add amazing feature'`)\n5. Push to the branch (`git push origin feature/amazing-feature`)\n6. Open a Pull Request\n\n## License\n\nThis project is licensed under the **GNU Affero General Public License v3.0** - see the [LICENSE](LICENSE) file for details.\n\nThis means:\n- ✅ You can use, modify, and distribute this software\n- ✅ You can use it commercially\n- ⚠️ If you modify and host it as a service, you must release your source code\n- ⚠️ Derivative works must use the same license\n\nCopyright (c) 2025 Mauricio Zuniga\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetazen11%2Fworkflow-hub","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmetazen11%2Fworkflow-hub","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetazen11%2Fworkflow-hub/lists"}