diff --git a/agent_hub_spec.md b/agent_hub_spec.md
index 2700639..09ff5ac 100644
--- a/agent_hub_spec.md
+++ b/agent_hub_spec.md
@@ -1,128 +1,197 @@
-# Spec Definition: Self-Hosted Agent Hub and Orchestration Platform
+# AgentHub Specification v0.3
 
-Version: 0.1
-Status: Draft
-Primary Example Workflow: Git Issue to Spec to Pull Request
-Working Name: AgentHub
+Status: Accepted baseline for initial development
+License direction: Apache-2.0
+Primary target users: Small engineering teams
+Primary reference workflow: Gitea issue to spec to pull request
+Secondary reference workflow: Generic webhook summarizer
+First vertical slice: Manual workflow → Kimi prompt stage → artifact → approval gate
 
 ---
 
 # 1. Product Summary
 
-AgentHub is a self-hosted, configurable platform for defining, managing, orchestrating, observing, and governing AI agents across arbitrary workflows.
+AgentHub is a self-hosted, general-purpose agent workflow and orchestration platform for small engineering teams.
 
-The platform allows users to define external triggers, connect external systems, configure agents and models, compose workflows, monitor long-running runs, enforce policy gates, route tasks to different agent runtimes, and review all actions through a web interface.
+It provides a control plane for defining, managing, running, observing, and governing AI agents across external systems and workflows.
 
-The initial reference implementation is a Git repository workflow:
+AgentHub is not a single coding agent, Git bot, CrewAI wrapper, or model frontend. It is a platform layer that coordinates:
 
 ```text
-GitHub / GitLab issue
+connectors
+triggers
+monitors
+workflows
+workflow runs
+agent definitions
+agent teams
+model routing
+runtime adapters
+tool grants
+sandboxing
+policies
+approvals
+artifacts
+memory
+observability
+audit logs
+```
+
+The first complete reference workflow is a self-hosted Git workflow:
+
+```text
+Gitea issue
   ↓
-trigger or monitor condition
+label or comment trigger
   ↓
-agent workflow starts
+workflow starts
   ↓
 spec generation
   ↓
+human spec approval
+  ↓
 implementation agent
   ↓
-pull request creation
+branch pushed
   ↓
-review and revision loop
+draft pull request opened
   ↓
-human-approved merge
+CI monitored
+  ↓
+review/revision loop
+  ↓
+human-approved merge or merge-ready state
 ```
 
-However, this Git PR flow is only the first example. The core product is a general-purpose agent orchestration hub.
+AgentHub must remain general enough to support non-Git workflows, such as webhook processing, scheduled monitoring, document generation, support triage, release automation, infrastructure checks, and internal business workflows.
 
 ---
 
-# 2. Product Vision
+# 2. Product Identity
 
-AgentHub should become the self-hosted control plane for AI agents.
+AgentHub is a:
 
-It should allow a team to answer questions like:
+```text
+general-purpose self-hosted agent workflow platform
+```
 
-* Which agents exist?
-* Which models do they use?
-* Which tools can they access?
-* Which workflows can trigger them?
-* What external systems can they monitor?
-* What are they currently doing?
-* What did they change?
-* Which human approvals are required?
-* Which policies blocked or allowed their actions?
-* Which agent runtime performed best for a given task type?
+Its first strong use case is developer automation, but the core architecture must not be Git-specific.
 
-The goal is not just to run agents, but to make agent execution **visible, configurable, repeatable, auditable, and safe**.
+## 2.1 First Target Users
+
+The first target users are:
+
+```text
+small engineering teams
+```
+
+This means the product should prioritize:
+
+* Docker Compose deployment
+* multi-user support
+* team and project support
+* practical approvals
+* visible run history
+* simple configuration
+* useful defaults
+* explicit security boundaries
+* self-hosted operation
+* extensibility without enterprise complexity
 
 ---
 
-# 3. Core Design Principle
+# 3. Product Principles
 
-AgentHub separates two different kinds of orchestration.
+## 3.1 Platform Orchestration vs Agent Orchestration
 
-## 3.1 Platform Orchestration
+AgentHub owns deterministic platform orchestration.
 
-Platform orchestration is deterministic and owned by AgentHub.
+Agent runtimes own task execution.
 
-It handles:
+### AgentHub owns
 
 ```text
-external trigger received
-  ↓
-workflow selected
-  ↓
-policy checked
-  ↓
-stage started
-  ↓
-agent runtime invoked
-  ↓
-artifact collected
-  ↓
-approval requested
-  ↓
-next stage selected
-  ↓
-workflow completed
+workflow state
+stage transitions
+approval gates
+policy checks
+trigger matching
+monitor execution
+runtime selection
+model routing
+artifact handling
+event logs
+audit logs
+secret scoping
+sandbox allocation
+human interaction
 ```
 
-Platform orchestration should be reliable, inspectable, resumable, and auditable.
-
-## 3.2 Agent Orchestration
-
-Agent orchestration may be probabilistic and runtime-specific.
-
-It handles:
+### Agent runtimes own
 
 ```text
-manager agent delegates task
-  ↓
-research agent gathers context
-  ↓
-planner agent proposes plan
-  ↓
-implementation agent makes changes
-  ↓
-review agent critiques output
-  ↓
-judge agent accepts or rejects result
+reasoning loops
+tool use within granted permissions
+multi-agent collaboration
+code editing
+reviewing
+summarizing
+planning
+runtime-specific execution
 ```
 
-Agent orchestration may be powered by:
+## 3.2 Runtime-Agnostic Architecture
 
-* CrewAI
-* LangGraph
-* OpenHands
-* mini-SWE-agent
-* PR-Agent
-* custom scripts
-* custom Docker containers
-* custom Python/TypeScript agents
-* local model workers
+AgentHub must support multiple runtime adapters.
 
-AgentHub should not hard-code one agent framework as the platform. It should provide a runtime adapter interface.
+MVP runtime adapters:
+
+```text
+llm_prompt
+script
+mini_swe_agent
+crewai
+```
+
+Future runtime adapters:
+
+```text
+openhands
+langgraph
+pr_agent
+custom_docker_agent
+http_agent
+local_model_worker
+```
+
+CrewAI is useful for hierarchical teams, planning, spec generation, and review boards. It is not the platform core.
+
+mini-SWE-agent is useful for implementation tasks, especially issue-to-code and bug-fix workflows. It is not the platform core.
+
+## 3.3 Human Control
+
+Agents may propose, prepare, summarize, implement, review, and recommend.
+
+Humans approve sensitive actions.
+
+AgentHub policy gates own sensitive side effects such as:
+
+```text
+posting external comments
+accessing secrets
+indexing memory
+pushing branches
+opening pull requests
+merging pull requests
+running network-enabled sandboxes
+using expensive models
+```
+
+## 3.4 Explicit Context and Memory
+
+AgentHub should not silently remember or index everything.
+
+Memory exists from day one, but indexing is explicit, scoped, inspectable, and permission-controlled.
 
 ---
 
@@ -132,3390 +201,93 @@ AgentHub should not hard-code one agent framework as the platform. It should pro
 
 AgentHub should allow users to:
 
-1. Connect external systems.
-2. Define triggers from external events.
-3. Define monitors that poll or watch external conditions.
-4. Define workflows with stages, branches, approvals, retries, and policies.
-5. Define agents and agent teams.
-6. Define agent hierarchy and delegation patterns.
-7. Route different stages to different agent runtimes.
-8. Route different agents to different models.
-9. Run agents in controlled sandboxes.
-10. Observe all active and historical runs.
-11. Review logs, tool calls, outputs, artifacts, and costs.
-12. Approve or reject workflow stages.
-13. Pause, cancel, retry, or resume workflows.
-14. Enforce security and permission policies.
-15. Use the Git issue-to-PR workflow as the first production example.
+1. Create workspaces.
+2. Create teams.
+3. Create projects.
+4. Connect external systems.
+5. Define event-based triggers.
+6. Define polling or condition-based monitors.
+7. Define YAML-first workflows.
+8. Run workflows manually or from external events.
+9. Configure agents and agent teams.
+10. Configure hierarchical agent teams.
+11. Route different agents to different models.
+12. Route different workflow stages to different runtimes.
+13. Enforce explicit tool grants.
+14. Run agents in Docker sandboxes.
+15. Disable network access by default.
+16. Use vector memory with explicit scoped indexing.
+17. Store artifacts in MinIO.
+18. Require human approvals for sensitive stages.
+19. Allow controlled merge after approval and successful CI when configured.
+20. Record all major events and audit-relevant actions.
+21. Inspect workflow timelines, logs, artifacts, approvals, memory use, and policy decisions.
+22. Support Gitea first, while keeping GitLab, GitHub, and Forgejo support open.
 
 ## 4.2 Engineering Goals
 
 AgentHub should be:
 
-1. Self-hosted.
-2. Runtime-agnostic.
-3. Model-provider-agnostic.
-4. Connector-agnostic.
-5. Workflow-driven.
-6. Observable.
-7. Secure by default.
-8. Extensible through adapters.
-9. Suitable for Docker Compose deployment first.
-10. Suitable for Kubernetes deployment later.
-11. Designed for long-running asynchronous workflows.
-12. Friendly to local models and air-gapped deployments.
+* self-hosted
+* Docker Compose first
+* Kubernetes-compatible later
+* model-provider agnostic
+* runtime-adapter agnostic
+* connector-adapter agnostic
+* workflow-engine swappable later
+* secure by default
+* observable by default
+* auditable by default
+* permissively open-source
 
 ---
 
-# 5. Non-Goals
+# 5. Non-Goals for MVP
 
-Initial versions should not attempt to:
+The MVP should not attempt to:
 
-1. Build a new LLM framework from scratch.
-2. Replace all existing agent frameworks.
-3. Provide a full project management system.
-4. Guarantee correct autonomous decisions.
-5. Automatically execute high-risk actions without approval.
-6. Support every external connector from day one.
-7. Support arbitrary multi-tenant SaaS from day one.
-8. Provide full visual workflow editing in the first MVP.
-9. Replace CI, code review, or deployment systems.
+1. Build a hosted SaaS platform.
+2. Build a visual drag-and-drop workflow editor.
+3. Replace CI systems.
+4. Replace Git provider review workflows.
+5. Automatically merge changes by default.
+6. Support every Git provider completely.
+7. Implement full event sourcing.
+8. Implement Kubernetes runners.
+9. Implement Firecracker or gVisor sandboxes.
+10. Implement full GitOps configuration.
+11. Implement custom RBAC DSLs.
+12. Let agents freely spawn sub-workflows.
+13. Let agents access all tools by default.
+14. Store hidden model reasoning.
+15. Silently index all data into memory.
+16. Build a custom LLM framework from scratch.
 
 ---
 
-# 6. Product Scope
+# 6. Implementation Stack
 
-## 6.1 Core Platform
-
-The platform core includes:
-
-* User interface
-* Backend API
-* Workflow engine
-* Trigger engine
-* Monitor engine
-* Agent registry
-* Model registry
-* Runtime adapter registry
-* Tool registry
-* Connector registry
-* Policy engine
-* Sandbox manager
-* Job queue
-* Event log
-* Audit log
-* Artifact storage
-* Approval system
-* Run monitoring
-
-## 6.2 First Reference Workflow
-
-The first complete workflow should be:
+## 6.1 Final Implementation Decisions
 
 ```text
-Managed Git repository
-  ↓
-Issue labeled or mentioned
-  ↓
-Workflow starts
-  ↓
-Spec generation agent/team
-  ↓
-Optional approval
-  ↓
-Implementation agent
-  ↓
-Branch pushed
-  ↓
-Draft PR opened
-  ↓
-CI monitored
-  ↓
-Review agent/team
-  ↓
-Human review
-  ↓
-Revision agent if needed
-  ↓
-Ready for merge
-```
-
----
-
-# 7. Primary Users
-
-## 7.1 Platform Admin
-
-Responsible for:
-
-* Instance configuration
-* User access
-* Model provider configuration
-* Global policy configuration
-* Connector setup
-* Secret management
-* Runtime adapter management
-
-## 7.2 Workflow Designer
-
-Responsible for:
-
-* Creating workflows
-* Defining triggers
-* Defining monitors
-* Creating approval gates
-* Selecting agents
-* Configuring model routing
-* Defining retry and failure behavior
-
-## 7.3 Agent Operator
-
-Responsible for:
-
-* Monitoring active runs
-* Debugging failed runs
-* Reviewing logs
-* Tuning agent definitions
-* Adjusting prompts
-* Comparing agent performance
-
-## 7.4 Domain Owner
-
-Responsible for:
-
-* Reviewing outputs
-* Approving actions
-* Providing feedback
-* Deciding whether the workflow result is acceptable
-
-For the Git workflow, this user is usually a repository maintainer.
-
-## 7.5 Developer / Reviewer
-
-Responsible for:
-
-* Reviewing generated specs
-* Reviewing generated pull requests
-* Commenting on agent output
-* Approving or requesting changes
-
----
-
-# 8. Core Concepts
-
-## 8.1 Connector
-
-A connector integrates AgentHub with an external system.
-
-Examples:
-
-* GitHub
-* GitLab
-* Gitea
-* Forgejo
-* Jira
-* Linear
-* Slack
-* Matrix
-* Email
-* HTTP webhook
-* RSS feed
-* S3-compatible object storage
-* Kubernetes
-* Internal APIs
-* Databases
-
-Connectors may support:
-
-* Events
-* Actions
-* Polling
-* Resource reading
-* Resource writing
-* Authentication
-* Webhook verification
-* Rate limiting
-
-## 8.2 Trigger
-
-A trigger starts a workflow run.
-
-Examples:
-
-```text
-GitHub issue labeled "agent-ready"
-GitHub comment mentions "@agenthub"
-Slack slash command received
-HTTP webhook received
-Jira issue enters status "Ready for Agent"
-Scheduled cron trigger fires
-Manual UI trigger clicked
-```
-
-Triggers are event-driven.
-
-## 8.3 Monitor
-
-A monitor watches an external condition and starts or advances a workflow when the condition is met.
-
-Examples:
-
-```text
-Check every 10 minutes for failed CI jobs
-Watch open PRs with label "needs-agent-review"
-Watch RSS feed for security advisories
-Watch issue backlog for stale items
-Watch deployment health endpoint
-Watch queue length in an external system
-```
-
-Monitors are polling, subscription-based, or long-running observers.
-
-## 8.4 Workflow
-
-A workflow is a versioned definition of stages, transitions, policies, retries, approvals, and runtime calls.
-
-A workflow can be triggered manually, by external event, by monitor, by schedule, or by another workflow.
-
-## 8.5 Workflow Run
-
-A workflow run is a concrete execution of a workflow definition.
-
-It has:
-
-* Input
-* Current state
-* Stage history
-* Events
-* Artifacts
-* Approvals
-* Logs
-* Errors
-* Final result
-
-## 8.6 Stage
-
-A stage is one step in a workflow.
-
-Stage types:
-
-* Agent stage
-* Script stage
-* Connector action stage
-* Approval stage
-* Wait stage
-* Condition stage
-* Parallel stage
-* Human input stage
-* Sub-workflow stage
-* Notification stage
-* Terminal stage
-
-## 8.7 Agent
-
-An agent is a configured unit capable of performing a task.
-
-An agent definition includes:
-
-* Name
-* Role
-* Runtime
-* Model
-* Tools
-* Prompt templates
-* Permissions
-* Sandbox settings
-* Memory/context settings
-* Output schema
-
-## 8.8 Agent Team
-
-An agent team is a structured group of agents.
-
-Team patterns:
-
-* Sequential team
-* Parallel team
-* Hierarchical team
-* Supervisor-worker team
-* Debate-and-judge team
-* Router-specialist team
-* Review board
-* Swarm-style team
-
-## 8.9 Runtime Adapter
-
-A runtime adapter invokes a specific agent execution backend.
-
-Examples:
-
-* CrewAI adapter
-* mini-SWE-agent adapter
-* OpenHands adapter
-* LangGraph adapter
-* PR-Agent adapter
-* shell command adapter
-* Docker container adapter
-* HTTP agent adapter
-* custom SDK adapter
-
-## 8.10 Model
-
-A model is a configured LLM or model endpoint.
-
-Examples:
-
-* OpenAI model
-* Anthropic model
-* local Ollama model
-* vLLM-hosted model
-* OpenAI-compatible API endpoint
-* OpenRouter model
-* internal model gateway
-
-## 8.11 Tool
-
-A tool is an operation an agent can use.
-
-Examples:
-
-* shell
-* file read/write
-* git
-* browser
-* HTTP client
-* database query
-* GitHub API
-* Slack post
-* Jira update
-* code search
-* vector search
-
-## 8.12 Sandbox
-
-A sandbox is an isolated execution environment for a run.
-
-Examples:
-
-* Docker container
-* Kubernetes job
-* Firecracker microVM
-* gVisor sandbox
-* restricted local process
-
-## 8.13 Artifact
-
-An artifact is any durable output produced by a workflow or agent run.
-
-Examples:
-
-* generated spec
-* patch file
-* pull request URL
-* log bundle
-* test report
-* generated document
-* JSON output
-* screenshot
-* transcript
-* decision record
-
-## 8.14 Policy
-
-A policy controls what is allowed.
-
-Policies may apply to:
-
-* Users
-* Connectors
-* Workflows
-* Stages
-* Agents
-* Tools
-* Models
-* Sandboxes
-* External actions
-* File paths
-* Cost limits
-* Runtime limits
-* Approval requirements
-
-## 8.15 Approval Gate
-
-An approval gate pauses a workflow until a human or external policy approves or rejects the next action.
-
-Examples:
-
-* approve generated spec
-* approve sending email
-* approve PR creation
-* approve production deployment
-* approve merge
-* approve secret access
-* approve high-cost model usage
-
----
-
-# 9. High-Level Architecture
-
-```text
-Web UI
-  ↓
-Backend API
-  ↓
-Workflow Engine
-  ↓
-Job Queue
-  ↓
-Worker Pool
-  ↓
-Runtime Adapters
-  ├─ CrewAI Adapter
-  ├─ mini-SWE-agent Adapter
-  ├─ OpenHands Adapter
-  ├─ LangGraph Adapter
-  ├─ PR-Agent Adapter
-  ├─ Script Adapter
-  └─ HTTP Adapter
-
-Connectors
-  ├─ GitHub
-  ├─ GitLab
-  ├─ Jira
-  ├─ Slack
-  ├─ Webhook
-  └─ Generic HTTP
-
-Platform Services
-  ├─ Policy Engine
-  ├─ Secret Manager
-  ├─ Sandbox Manager
-  ├─ Model Gateway
-  ├─ Artifact Store
-  ├─ Event Store
-  ├─ Audit Log
-  └─ Observability
-```
-
----
-
-# 10. Recommended Initial Technology Stack
-
-## 10.1 MVP Stack
-
-```yaml
-frontend:
-  framework: Next.js
-  language: TypeScript
-  ui: Tailwind + shadcn/ui
-  data_fetching: TanStack Query
-  realtime: Server-Sent Events or WebSocket
-  editor: Monaco Editor
-
-backend:
-  framework: FastAPI
-  language: Python
-  api_style: REST first
-  realtime: SSE first
-  validation: Pydantic
-
-database:
-  primary: PostgreSQL
-
-queue:
-  initial: Redis + RQ or Celery
-  later: Temporal, Hatchet, or durable workflow engine
-
-object_storage:
-  initial: local filesystem or MinIO
-  production: S3-compatible storage
-
-runner:
-  initial: Docker
-  later: Kubernetes Jobs, Firecracker, gVisor
-
-auth:
-  initial: local admin user
-  later: OIDC, OAuth, SAML
-
-deployment:
-  initial: Docker Compose
-  later: Kubernetes Helm chart
-```
-
-## 10.2 Reasoning
-
-FastAPI is a good fit because many agent frameworks are Python-native. Next.js gives a strong UI foundation. Docker-based runners keep the MVP simple. PostgreSQL provides reliable state. Redis is sufficient for early background work.
-
----
-
-# 11. Deployment Model
-
-## 11.1 Local Development
-
-```text
-agenthub-web
-agenthub-api
-agenthub-worker
-postgres
-redis
-minio
-docker-socket-proxy
-```
-
-The Docker socket should not be directly exposed to agent containers. If Docker control is needed, use a restricted proxy or a separate runner service.
-
-## 11.2 Single-Server Self-Hosted
-
-A Docker Compose stack should be enough for an early production deployment.
-
-Required services:
-
-```text
-web
-api
-worker
-postgres
-redis
-minio
-reverse-proxy
-runner
-```
-
-## 11.3 Kubernetes
-
-Future production deployments should support:
-
-```text
-web deployment
-api deployment
-worker deployment
-runner job pods
-postgres
-redis
-object storage
-ingress
-secret manager
-network policies
-observability stack
-```
-
-## 11.4 Air-Gapped Mode
-
-Future air-gapped support should allow:
-
-* Local Git provider
-* Local model server
-* Local package mirrors
-* Internal artifact storage
-* No external network requirement
-* Local-only connector configuration
-* Offline documentation cache
-
----
-
-# 12. User Interface
-
-## 12.1 Main Navigation
-
-```text
-Dashboard
-Workflows
-Runs
-Agents
-Agent Teams
-Models
-Connectors
-Triggers
-Monitors
-Tools
-Sandboxes
-Approvals
-Artifacts
-Policies
-Secrets
-Audit Log
-Settings
-```
-
-## 12.2 Dashboard
-
-The dashboard should show:
-
-* Active workflow runs
-* Waiting approvals
-* Failed runs
-* Recently completed runs
-* Agent runs by status
-* Cost estimates
-* Token usage
-* External trigger activity
-* Connector health
-* Sandbox capacity
-* Recent audit events
-
-## 12.3 Workflow List
-
-Shows:
-
-* Workflow name
-* Version
-* Enabled status
-* Trigger type
-* Last run
-* Success rate
-* Average duration
-* Owner
-* Assigned connectors
-* Actions
-
-Actions:
-
-* Create workflow
-* Duplicate workflow
-* Enable/disable workflow
-* Run manually
-* View runs
-* Edit YAML
-* View graph
-
-## 12.4 Workflow Detail
-
-Tabs:
-
-```text
-Overview
-Definition
-Visual Graph
-Runs
-Triggers
-Monitors
-Policies
-Versions
-Settings
-```
-
-The first version may rely on YAML editing. A visual graph editor can come later.
-
-## 12.5 Run Detail
-
-A run detail page should show:
-
-* Workflow name and version
-* Trigger source
-* Input payload
-* Current stage
-* Stage timeline
-* Active agent runs
-* Logs
-* Artifacts
-* Approval gates
-* Policy decisions
-* Errors
-* Final result
-
-Required actions:
-
-* Cancel run
-* Retry failed stage
-* Resume from stage
-* Approve gate
-* Reject gate
-* Add human comment
-* Download artifacts
-
-## 12.6 Agent Registry UI
-
-Shows:
-
-* Agent name
-* Role
-* Runtime
-* Default model
-* Tools
-* Permissions
-* Success rate
-* Recent runs
-* Enabled status
-
-Actions:
-
-* Create agent
-* Edit agent
-* Test agent
-* Disable agent
-* Duplicate agent
-* View run history
-
-## 12.7 Agent Team UI
-
-Shows:
-
-* Team name
-* Team pattern
-* Members
-* Supervisor or manager
-* Runtime mapping
-* Model routing
-* Recent team runs
-
-Team types:
-
-```text
-sequential
-parallel
-hierarchical
-supervisor_worker
-debate_judge
-router_specialist
-custom_runtime
-```
-
-## 12.8 Model Registry UI
-
-Shows:
-
-* Provider
-* Model name
-* Endpoint
-* Context limit
-* Cost settings
-* Allowed agents
-* Allowed workflows
-* Health status
-* Token usage
-* Cost history
-
-## 12.9 Connector UI
-
-Shows:
-
-* Connector type
-* Authentication status
-* Webhook status
-* Resources discovered
-* Last event received
-* Last successful action
-* Rate-limit state
-* Error history
-
-## 12.10 Approval Inbox
-
-Shows all pending approvals:
-
-* Workflow run
-* Stage
-* Requested action
-* Risk summary
-* Requesting agent
-* Required role
-* Deadline
-* Approve/reject actions
-
----
-
-# 13. Workflow System
-
-## 13.1 Workflow Definition Format
-
-Workflows should be stored as versioned YAML or JSON.
-
-YAML is preferred for authoring.
-
-Example:
-
-```yaml
-id: github-issue-to-pr
-name: Git Issue to PR
-version: 1
-enabled: true
-
-description: >
-  Turns a labeled GitHub issue into a spec, implementation branch, and draft PR.
-
-triggers:
-  - id: issue-labeled
-    connector: github-main
-    event: issue.labeled
-    filter:
-      label: agent-ready
-
-  - id: issue-mentioned
-    connector: github-main
-    event: issue.commented
-    filter:
-      contains: "@agenthub"
-
-inputs:
-  schema:
-    type: object
-    required:
-      - repository
-      - issue_number
-
-variables:
-  spec_required: true
-  create_draft_pr: true
-
-stages:
-  - id: normalize
-    type: connector_action
-    action: github.load_issue_context
-    outputs:
-      issue_context: result
-
-  - id: triage
-    type: agent
-    agent: git-triage-agent
-    input:
-      issue: "{{ issue_context }}"
-    outputs:
-      triage: result
-
-  - id: generate_spec
-    type: agent_team
-    team: git-spec-team
-    input:
-      issue: "{{ issue_context }}"
-      triage: "{{ triage }}"
-    outputs:
-      spec_bundle: result
-
-  - id: approve_spec
-    type: approval
-    when: "{{ variables.spec_required == true }}"
-    title: "Approve generated spec"
-    required_roles:
-      - maintainer
-    input:
-      spec_bundle: "{{ spec_bundle }}"
-
-  - id: implement
-    type: agent
-    agent: mini-swe-implementation-agent
-    input:
-      issue: "{{ issue_context }}"
-      spec_bundle: "{{ spec_bundle }}"
-    outputs:
-      implementation_result: result
-
-  - id: open_pr
-    type: connector_action
-    connector: github-main
-    action: github.open_or_update_pull_request
-    input:
-      implementation: "{{ implementation_result }}"
-      draft: "{{ variables.create_draft_pr }}"
-    outputs:
-      pull_request: result
-
-  - id: wait_for_ci
-    type: wait_for_condition
-    connector: github-main
-    condition: github.pr_checks_completed
-    timeout_minutes: 60
-    input:
-      pull_request: "{{ pull_request }}"
-    outputs:
-      ci_result: result
-
-  - id: review
-    type: agent_team
-    team: pr-review-team
-    input:
-      pull_request: "{{ pull_request }}"
-      spec_bundle: "{{ spec_bundle }}"
-      ci_result: "{{ ci_result }}"
-    outputs:
-      review_result: result
-
-  - id: human_review
-    type: approval
-    title: "Approve PR readiness"
-    required_roles:
-      - maintainer
-    input:
-      pull_request: "{{ pull_request }}"
-      review_result: "{{ review_result }}"
-
-  - id: complete
-    type: terminal
-    status: success
-
-failure:
-  default:
-    action: mark_failed
-    notify:
-      - workflow_owner
-```
-
-## 13.2 Stage Types
-
-### agent
-
-Runs a single configured agent.
-
-### agent_team
-
-Runs a configured team of agents. This may map to CrewAI, LangGraph, or a custom runtime.
-
-### connector_action
-
-Calls an external system.
-
-Examples:
-
-* create GitHub comment
-* update Jira issue
-* send Slack message
-* create branch
-* open pull request
-* query database
-
-### script
-
-Runs a controlled script.
-
-### approval
-
-Pauses execution until a human approves or rejects.
-
-### wait_for_event
-
-Waits for a matching event.
-
-### wait_for_condition
-
-Polls or subscribes until a condition is true.
-
-### condition
-
-Branches based on an expression.
-
-### parallel
-
-Runs multiple stages concurrently.
-
-### subworkflow
-
-Calls another workflow.
-
-### notification
-
-Sends a notification.
-
-### terminal
-
-Ends workflow.
-
-## 13.3 Workflow State Machine
-
-Workflow runs should support these states:
-
-```text
-created
-queued
-running
-waiting
-waiting_for_approval
-waiting_for_event
-waiting_for_condition
-paused
-succeeded
-failed
-cancelled
-timed_out
-```
-
-Stage runs should support:
-
-```text
-pending
-queued
-running
-waiting
-succeeded
-failed
-skipped
-cancelled
-timed_out
-blocked_by_policy
-```
-
-## 13.4 Workflow Versioning
-
-Every workflow edit creates a new version.
-
-A workflow run must always reference the exact workflow version used.
-
-Required fields:
-
-```text
-workflow_id
-workflow_version
-definition_snapshot
-started_at
-started_by
-trigger_event_id
-```
-
-## 13.5 Retry Behavior
-
-Workflow definitions should support:
-
-```yaml
-retry:
-  max_attempts: 2
-  backoff_seconds: 60
-  retry_on:
-    - model_error
-    - connector_timeout
-    - sandbox_error
-```
-
-## 13.6 Failure Behavior
-
-A stage may define failure behavior:
-
-```yaml
-on_failure:
-  action: retry | continue | branch | fail | request_human_input
-  target_stage: revise_plan
-```
-
-## 13.7 Human Input
-
-Some stages should allow a human to provide additional instructions.
-
-Example:
-
-```yaml
-- id: clarify_requirements
-  type: human_input
-  prompt: "The agent needs clarification before proceeding."
-  required_roles:
-    - maintainer
-```
-
----
-
-# 14. Trigger System
-
-## 14.1 Trigger Types
-
-AgentHub should support:
-
-```text
-manual
-webhook_event
-connector_event
-schedule
-monitor_condition
-api_call
-workflow_event
-```
-
-## 14.2 Trigger Definition
-
-Example:
-
-```yaml
-id: github-label-trigger
-name: GitHub Issue Label Trigger
-type: connector_event
-connector: github-main
-event: issue.labeled
-enabled: true
-filter:
-  repository: "org/repo"
-  label: "agent-ready"
-workflow: github-issue-to-pr
-```
-
-## 14.3 Trigger Filtering
-
-Filters should support:
-
-* Exact match
-* Contains
-* Regex
-* JSON path
-* CEL-like expressions later
-* Repository scoping
-* Actor scoping
-* Label scoping
-* Event type scoping
-
-Example:
-
-```yaml
-filter:
-  all:
-    - path: "$.issue.state"
-      equals: "open"
-    - path: "$.label.name"
-      equals: "agent-ready"
-    - path: "$.sender.login"
-      not_in:
-        - dependabot
-```
-
-## 14.4 Trigger Deduplication
-
-Triggers must deduplicate events to avoid duplicate runs.
-
-Deduplication key examples:
-
-```text
-connector_id:event_id
-github:delivery_id
-repository:issue:label:workflow
-```
-
-## 14.5 Trigger Authorization
-
-A trigger must check:
-
-* Connector is enabled
-* Workflow is enabled
-* Actor is authorized, if applicable
-* Policy permits run creation
-* Rate limits are not exceeded
-* Duplicate run does not already exist
-
----
-
-# 15. Monitor System
-
-## 15.1 Monitor Purpose
-
-A monitor observes external state and creates events or advances workflow state.
-
-Unlike triggers, monitors may poll on an interval or maintain subscriptions.
-
-## 15.2 Monitor Examples
-
-```yaml
-id: monitor-pr-ci
-name: Monitor PR CI Status
-type: connector_poll
-connector: github-main
-interval_seconds: 60
-query:
-  repository: org/repo
-  pull_request_label: agent-generated
-condition:
-  checks_completed: true
-workflow_event:
-  type: github.pr_checks_completed
-```
-
-Other examples:
-
-```text
-Watch stale tickets
-Watch external HTTP endpoint
-Watch failed deployment
-Watch unresolved PR comments
-Watch security advisories
-Watch mailbox for specific emails
-Watch queue backlog
-```
-
-## 15.3 Monitor States
-
-```text
-enabled
-disabled
-healthy
-degraded
-failing
-paused
-```
-
-## 15.4 Monitor Outputs
-
-Monitors produce normalized internal events.
-
-Example:
-
-```json
-{
-  "type": "monitor.condition_met",
-  "source": "github-pr-ci-monitor",
-  "resource": {
-    "repository": "org/repo",
-    "pull_request": 42
-  },
-  "payload": {
-    "checks_status": "success"
-  }
-}
-```
-
----
-
-# 16. Agent System
-
-## 16.1 Agent Definition
-
-Example:
-
-```yaml
-id: git-triage-agent
-name: Git Triage Agent
-description: Classifies Git issues and decides whether they are suitable for automation.
-type: single_agent
-runtime: llm_prompt
-enabled: true
-
-model:
-  routing_policy: cheap-reasoning
-  fallback_policy: default-fallback
-
-prompt:
-  system_template: git-triage-system
-  task_template: git-triage-task
-
-tools:
-  - code_search.readonly
-  - github.readonly
-
-permissions:
-  external_actions: false
-  filesystem_write: false
-  network_access: false
-
-output_schema:
-  type: object
-  required:
-    - suitable
-    - complexity
-    - reason
-  properties:
-    suitable:
-      type: boolean
-    complexity:
-      type: string
-      enum:
-        - low
-        - medium
-        - high
-    reason:
-      type: string
-```
-
-## 16.2 Agent Types
-
-```text
-single_agent
-agent_team
-runtime_native_agent
-script_agent
-http_agent
-human_agent
-```
-
-## 16.3 Agent Role Categories
-
-```text
-triage
-planner
-spec_writer
-researcher
-coder
-reviewer
-tester
-security_reviewer
-documentation_writer
-operator
-manager
-judge
-router
-```
-
-## 16.4 Agent Output
-
-Every agent run should return structured output.
-
-Required fields:
-
-```yaml
-status: success | failed | needs_input | blocked
-summary: string
-outputs: object
-artifacts: []
-recommendations: []
-errors: []
-```
-
-## 16.5 Agent Run States
-
-```text
-created
-queued
-preparing
-running
-streaming
-succeeded
-failed
-needs_input
-blocked_by_policy
-cancelled
-timed_out
-```
-
----
-
-# 17. Agent Team and Hierarchy System
-
-## 17.1 Team Definition
-
-Example:
-
-```yaml
-id: git-spec-team
-name: Git Spec Team
-type: hierarchical
-runtime: crewai
-
-manager:
-  agent: engineering-manager-agent
-  model: strong-reasoning
-
-members:
-  - agent: product-spec-agent
-    role: requirements
-    model: strong-writing
-  - agent: architecture-agent
-    role: architecture
-    model: strong-reasoning
-  - agent: test-planner-agent
-    role: testing
-    model: code-reasoning
-  - agent: security-review-agent
-    role: risk
-    model: security-reasoning
-
-process:
-  type: hierarchical
-  max_rounds: 5
-
-outputs:
-  schema: spec_bundle
-```
-
-## 17.2 Supported Team Patterns
-
-### Sequential
-
-Agents run in order.
-
-```text
-researcher → planner → writer → reviewer
-```
-
-### Parallel
-
-Agents run independently and results are combined.
-
-```text
-security reviewer
-architecture reviewer
-test reviewer
-      ↓
-aggregator
-```
-
-### Hierarchical
-
-A manager delegates tasks to workers.
-
-```text
-manager
-  ├─ planner
-  ├─ researcher
-  ├─ coder
-  └─ reviewer
-```
-
-### Debate and Judge
-
-Multiple agents propose or critique, then a judge decides.
-
-```text
-agent A proposal
-agent B critique
-agent C alternative
-      ↓
-judge
-```
-
-### Router Specialist
-
-A router picks the best specialist.
-
-```text
-router
-  ├─ docs agent
-  ├─ code agent
-  ├─ test agent
-  └─ security agent
-```
-
-### Supervisor Worker
-
-A supervisor monitors one or more long-running workers.
-
-```text
-supervisor
-  └─ implementation worker
-```
-
-## 17.3 Team Runtime Mapping
-
-AgentHub should define team hierarchy independently from runtime.
-
-Then adapters map it to concrete runtimes.
-
-Example mappings:
-
-```text
-AgentHub hierarchical team → CrewAI hierarchical process
-AgentHub graph team → LangGraph
-AgentHub coding worker → mini-SWE-agent
-AgentHub review board → CrewAI or custom parallel runner
-```
-
-## 17.4 Manager Agent
-
-A manager agent may:
-
-* Decompose tasks
-* Assign subtasks
-* Review outputs
-* Request revisions
-* Stop execution
-* Escalate to human
-* Select models
-* Select tools
-* Produce final output
-
-Manager actions must still be constrained by platform policy.
-
-## 17.5 Model Routing Within Teams
-
-Each team member may use a different model.
-
-Example:
-
-```yaml
-members:
-  - agent: router
-    model: cheap-fast
-  - agent: planner
-    model: strong-reasoning
-  - agent: coder
-    model: code-specialist
-  - agent: reviewer
-    model: strong-reasoning
-```
-
----
-
-# 18. Runtime Adapter System
-
-## 18.1 Adapter Purpose
-
-Runtime adapters allow AgentHub to invoke different execution systems through a common interface.
-
-## 18.2 Adapter Interface
-
-TypeScript-style interface:
-
-```typescript
-interface RuntimeAdapter {
-  id: string;
-  name: string;
-
-  validateDefinition(definition: RuntimeDefinition): Promise<ValidationResult>;
-
-  prepare(input: RuntimeRunInput): Promise<PreparedRun>;
-
-  start(input: RuntimeRunInput): Promise<RuntimeRunHandle>;
-
-  streamEvents(runId: string): AsyncIterable<RuntimeEvent>;
-
-  cancel(runId: string): Promise<void>;
-
-  collectResult(runId: string): Promise<RuntimeRunResult>;
-
-  cleanup(runId: string): Promise<void>;
-}
-```
-
-## 18.3 RuntimeRunInput
-
-```yaml
-run_id: string
-workflow_run_id: string
-stage_run_id: string
-runtime: string
-agent_or_team_definition: object
-input: object
-context:
-  variables: object
-  artifacts: []
-  secrets: []
-  connector_refs: []
-  policy: object
-limits:
-  timeout_seconds: 3600
-  max_cost_usd: 10
-  max_tokens: 100000
-sandbox:
-  type: docker
-  image: agenthub/runner:latest
-```
-
-## 18.4 RuntimeRunResult
-
-```yaml
-status: success | failed | cancelled | timed_out | needs_input
-summary: string
-outputs: object
-artifacts:
-  - id: string
-    type: string
-    uri: string
-events: []
-cost:
-  input_tokens: number
-  output_tokens: number
-  estimated_usd: number
-errors:
-  - code: string
-    message: string
-```
-
-## 18.5 Initial Adapters
-
-### llm_prompt adapter
-
-A simple single-prompt agent runner.
-
-Use for:
-
-* classification
-* summarization
-* spec generation MVP
-* lightweight decisions
-
-### script adapter
-
-Runs a configured command in a sandbox.
-
-Use for:
-
-* simple deterministic tasks
-* local scripts
-* custom tools
-* testing adapter interface
-
-### docker adapter
-
-Runs arbitrary containerized agent.
-
-Use for:
-
-* custom agents
-* isolated workloads
-* non-Python systems
-
-### CrewAI adapter
-
-Runs a CrewAI crew or flow.
-
-Use for:
-
-* hierarchical teams
-* planning teams
-* review teams
-* multi-agent debate
-
-### mini-SWE-agent adapter
-
-Runs mini-SWE-agent against a repository workspace.
-
-Use for:
-
-* issue-to-code implementation
-* bug fixing
-* test fixing
-* small feature implementation
-
-### PR-Agent adapter
-
-Runs PR review automation.
-
-Use for:
-
-* PR summaries
-* PR review suggestions
-* code review support
-
----
-
-# 19. CrewAI Adapter
-
-## 19.1 Purpose
-
-The CrewAI adapter allows AgentHub to run CrewAI-based crews and flows as workflow stages.
-
-CrewAI should be a supported runtime, not the platform core.
-
-## 19.2 Supported Use Cases
-
-CrewAI is useful for:
-
-* hierarchical planning
-* requirements analysis
-* spec generation
-* review boards
-* risk analysis
-* research tasks
-* multi-perspective critique
-* manager-worker task decomposition
-
-CrewAI is less ideal as the only platform-level orchestrator because AgentHub must own:
-
-* triggers
-* monitors
-* approvals
-* audit logs
-* cross-runtime workflows
-* connector governance
-* sandbox governance
-* workflow versioning
-* long-running run visibility
-
-## 19.3 CrewAI Stage Example
-
-```yaml
-- id: generate_spec
-  type: agent_team
-  runtime: crewai
-  team: git-spec-team
-  input:
-    issue_context: "{{ issue_context }}"
-    repository_context: "{{ repository_context }}"
-  outputs:
-    spec_bundle: result
-```
-
-## 19.4 CrewAI Team Definition Example
-
-```yaml
-id: git-spec-team
-runtime: crewai
-
-crew:
-  process: hierarchical
-  manager_agent: engineering-manager
-  max_iterations: 10
-
-agents:
-  engineering-manager:
-    role: Engineering Manager
-    goal: Coordinate the team and produce a final implementation-ready spec.
-    model: strong-reasoning
-
-  product-analyst:
-    role: Product Analyst
-    goal: Extract requirements, non-goals, acceptance criteria, and open questions.
-    model: strong-writing
-
-  architect:
-    role: Software Architect
-    goal: Identify code architecture impact, integration points, and risks.
-    model: strong-reasoning
-
-  test-planner:
-    role: Test Planner
-    goal: Define test strategy and validation steps.
-    model: code-reasoning
-
-tasks:
-  - id: analyze_issue
-    agent: product-analyst
-    description: Analyze issue and conversation.
-  - id: assess_architecture
-    agent: architect
-    description: Assess implementation implications.
-  - id: create_test_plan
-    agent: test-planner
-    description: Create test plan.
-  - id: finalize_spec
-    agent: engineering-manager
-    description: Produce final spec bundle.
-```
-
-## 19.5 CrewAI Outputs
-
-CrewAI stages must produce structured outputs.
-
-Example:
-
-```yaml
-spec_bundle:
-  problem: string
-  goals: []
-  non_goals: []
-  requirements: []
-  acceptance_criteria: []
-  implementation_plan: []
-  test_plan: []
-  risks: []
-  open_questions: []
-```
-
----
-
-# 20. Model Registry and Routing
-
-## 20.1 Model Provider Definition
-
-```yaml
-id: openai-main
-type: openai
-name: OpenAI Main
-base_url: null
-api_key_secret: openai_api_key
-enabled: true
-```
-
-OpenAI-compatible local endpoint:
-
-```yaml
-id: local-vllm
-type: openai_compatible
-name: Local vLLM
-base_url: http://vllm:8000/v1
-api_key_secret: null
-enabled: true
-```
-
-Ollama:
-
-```yaml
-id: ollama-local
-type: ollama
-name: Local Ollama
-base_url: http://ollama:11434
-enabled: true
-```
-
-## 20.2 Model Definition
-
-```yaml
-id: strong-reasoning
-provider: openai-main
-model_name: gpt-5.1
-context_window: 200000
-input_cost_per_1m_tokens: 0
-output_cost_per_1m_tokens: 0
-enabled: true
-
-capabilities:
-  - reasoning
-  - tool_calling
-  - structured_output
-
-limits:
-  max_tokens_per_run: 100000
-  max_cost_per_run_usd: 10
-```
-
-## 20.3 Model Routing Policy
-
-```yaml
-id: default-model-routing
-rules:
-  - match:
-      task_type: triage
-    model: cheap-fast
-
-  - match:
-      task_type: implementation
-    model: code-specialist
-
-  - match:
-      risk: high
-    model: strong-reasoning
-
-  - match:
-      requires_structured_output: true
-    model: structured-output-model
-
-fallback:
-  model: strong-reasoning
-```
-
-## 20.4 Model Selection Inputs
-
-Model routing may use:
-
-* Agent role
-* Task type
-* Risk level
-* Repository sensitivity
-* Expected cost
-* Required context window
-* Required tool support
-* Required structured output
-* User preference
-* Workflow policy
-
----
-
-# 21. Tool Registry
-
-## 21.1 Tool Definition
-
-```yaml
-id: github.create_comment
-name: Create GitHub Comment
-connector: github-main
-type: connector_action
-description: Posts a comment to a GitHub issue or pull request.
-
-input_schema:
-  type: object
-  required:
-    - repository
-    - issue_number
-    - body
-
-permissions:
-  required:
-    - github:issues:write
-
-risk:
-  level: medium
-  requires_approval: false
-```
-
-## 21.2 Tool Categories
-
-```text
-filesystem
-shell
-git
-http
-browser
-database
-connector_action
-vector_search
-code_search
-notification
-artifact
-human_input
-```
-
-## 21.3 Tool Permissions
-
-Tools must be explicitly granted to agents or teams.
-
-Example:
-
-```yaml
-agent: git-triage-agent
-tools:
-  - github.read_issue
-  - github.list_comments
-  - code_search.readonly
-```
-
-Implementation agent:
-
-```yaml
-agent: mini-swe-implementation-agent
-tools:
-  - filesystem.read
-  - filesystem.write
-  - shell.run
-  - git.commit
-  - git.push
-```
-
-## 21.4 Tool Risk Levels
-
-```text
-low
-medium
-high
-critical
-```
-
-Examples:
-
-```text
-read issue: low
-post comment: medium
-write file: medium
-push branch: high
-merge PR: critical
-access secret: critical
-deploy production: critical
-```
-
----
-
-# 22. Connector System
-
-## 22.1 Connector Interface
-
-```typescript
-interface Connector {
-  id: string;
-  type: string;
-
-  testConnection(): Promise<ConnectorHealth>;
-
-  listResources(input: object): Promise<Resource[]>;
-
-  handleWebhook(request: WebhookRequest): Promise<NormalizedEvent[]>;
-
-  poll?(monitorDefinition: MonitorDefinition): Promise<NormalizedEvent[]>;
-
-  execute(action: string, input: object): Promise<ConnectorActionResult>;
-}
-```
-
-## 22.2 Normalized Event
-
-```json
-{
-  "id": "evt_123",
-  "type": "github.issue.labeled",
-  "connector_id": "github-main",
-  "external_id": "delivery-id",
-  "actor": {
-    "type": "user",
-    "id": "alice"
-  },
-  "resource": {
-    "type": "github_issue",
-    "id": "org/repo#123"
-  },
-  "payload": {},
-  "received_at": "2026-05-29T12:00:00Z"
-}
-```
-
-## 22.3 Initial Connectors
-
-### GitHub Connector
-
-Required for MVP.
-
-Actions:
-
-* list repositories
-* read issue
-* list issue comments
-* post issue comment
-* create branch
-* push commit or support git credential generation
-* open pull request
-* update pull request
-* read PR
-* list review comments
-* read CI/check status
-* add/remove labels
-
-Events:
-
-* issue opened
-* issue edited
-* issue labeled
-* issue commented
-* pull request opened
-* pull request synchronized
-* pull request review submitted
-* check suite completed
-
-### Generic Webhook Connector
-
-Required for generality.
-
-Allows arbitrary systems to trigger workflows.
-
-### HTTP Connector
-
-Allows workflows to call external APIs.
-
-### Slack or Matrix Connector
-
-Useful after MVP for notifications and commands.
-
----
-
-# 23. Policy Engine
-
-## 23.1 Policy Purpose
-
-The policy engine decides whether an action is allowed, denied, or requires approval.
-
-Policies protect against:
-
-* unintended external writes
-* secret leakage
-* unsafe file modifications
-* excessive cost
-* excessive runtime
-* unauthorized trigger usage
-* dangerous tools
-* high-risk model behavior
-* automatic merging
-* production-impacting actions
-
-## 23.2 Policy Decision
-
-```yaml
-decision: allow | deny | require_approval
-reason: string
-matched_rules:
-  - rule_id: string
-risk_level: low | medium | high | critical
-required_approvals:
-  - role: maintainer
-```
-
-## 23.3 Policy Evaluation Points
-
-Evaluate policy before:
-
-* Starting workflow
-* Starting stage
-* Invoking agent
-* Selecting model
-* Granting tool
-* Accessing secret
-* Writing file
-* Running shell command
-* Calling external action
-* Posting external comment
-* Opening PR
-* Merging PR
-* Sending notification
-* Deploying
-* Retrying with elevated permissions
-
-## 23.4 Example Policy
-
-```yaml
-id: default-secure-policy
-name: Default Secure Policy
-
-rules:
-  - id: deny-secret-read
-    effect: deny
-    action: filesystem.read
-    paths:
-      - ".env"
-      - "**/*.pem"
-      - "**/*.key"
-
-  - id: block-ci-edits
-    effect: require_approval
-    action: filesystem.write
-    paths:
-      - ".github/workflows/**"
-
-  - id: block-agent-merge
-    effect: deny
-    action: github.pr.merge
-
-  - id: require-approval-for-external-message
-    effect: require_approval
-    action:
-      - slack.post_message
-      - email.send
-    condition:
-      risk_level: high
-
-  - id: max-cost-per-run
-    effect: deny
-    action: model.invoke
-    condition:
-      estimated_cost_usd_gt: 10
-```
-
----
-
-# 24. Approval System
-
-## 24.1 Approval Types
-
-```text
-stage_approval
-action_approval
-policy_approval
-spec_approval
-merge_approval
-secret_access_approval
-cost_approval
-human_input_request
-```
-
-## 24.2 Approval States
-
-```text
-requested
-approved
-rejected
-expired
-cancelled
-superseded
-```
-
-## 24.3 Approval Request
-
-```yaml
-id: approval_123
-workflow_run_id: run_123
-stage_run_id: stage_456
-type: spec_approval
-title: Approve generated specification
-description: The spec team generated a plan for issue #123.
-risk_level: medium
-requested_by: system
-required_roles:
-  - maintainer
-context:
-  artifact_ids:
-    - artifact_spec_123
-expires_at: null
-```
-
-## 24.4 Approval UI Requirements
-
-The approval screen should show:
-
-* Requested action
-* Why approval is needed
-* Agent summary
-* Risk level
-* Relevant artifacts
-* Policy rules matched
-* Proposed external side effects
-* Approve button
-* Reject button
-* Request changes button
-* Comment field
-
----
-
-# 25. Sandbox and Execution Security
-
-## 25.1 Sandbox Requirements
-
-Every agent run that executes code or tools should run in a sandbox.
-
-Minimum requirements:
-
-* Isolated filesystem
-* CPU limit
-* memory limit
-* disk limit
-* timeout
-* no privileged container
-* no host Docker socket
-* controlled environment variables
-* network disabled by default for high-risk workflows
-* logs captured and redacted
-* artifacts extracted safely
-
-## 25.2 Sandbox Definition
-
-```yaml
-id: default-docker-sandbox
-type: docker
-image: agenthub/runner:latest
-
-limits:
-  cpu: "4"
-  memory: "8Gi"
-  disk: "20Gi"
-  timeout_seconds: 3600
-
-network:
-  enabled: false
-  allowlist: []
-
-mounts:
-  workspace:
-    mode: read_write
-
-security:
-  privileged: false
-  read_only_root: true
-  drop_capabilities: true
-```
-
-## 25.3 Secrets in Sandboxes
-
-Secrets must be:
-
-* opt-in
-* scoped to workflow/stage/agent
-* masked in logs
-* injected only when needed
-* unavailable to untrusted prompts by default
-* never written into artifacts
-* never exposed in external comments
-
----
-
-# 26. Memory and Context
-
-## 26.1 Context Types
-
-AgentHub should distinguish:
-
-```text
-run context
-workflow context
-resource context
-connector context
-repository context
-long-term memory
-retrieved knowledge
-human-provided context
-```
-
-## 26.2 Context Bundle
-
-Each agent run receives a context bundle.
-
-```yaml
-context_bundle:
-  workflow:
-    id: string
-    run_id: string
-    stage_id: string
-
-  inputs: {}
-
-  previous_outputs: {}
-
-  artifacts: []
-
-  resource_context: {}
-
-  instructions:
-    system: string
-    task: string
-
-  constraints:
-    policies: []
-    allowed_tools: []
-    limits: {}
-```
-
-## 26.3 Memory Policy
-
-Long-term memory should not be automatic in MVP.
-
-Future memory should be:
-
-* explicit
-* inspectable
-* erasable
-* scoped
-* permissioned
-* source-cited
-* freshness-aware
-
----
-
-# 27. Artifact System
-
-## 27.1 Artifact Types
-
-```text
-markdown
-json
-yaml
-text
-patch
-diff
-log
-test_report
-html
-image
-screenshot
-pull_request
-external_link
-decision_record
-model_trace
-```
-
-## 27.2 Artifact Metadata
-
-```yaml
-id: artifact_123
-workflow_run_id: run_123
-stage_run_id: stage_456
-type: markdown
-name: spec.md
-uri: s3://agenthub/artifacts/spec.md
-content_type: text/markdown
-created_by: git-spec-team
-created_at: timestamp
-hash: string
-```
-
-## 27.3 Artifact Requirements
-
-Artifacts should be:
-
-* versioned where needed
-* downloadable
-* previewable in UI
-* referenced by later stages
-* available to approval screens
-* immutable once finalized
-* linked to audit events
-
----
-
-# 28. Event and Audit System
-
-## 28.1 Internal Events
-
-AgentHub should append internal events for all important state changes.
-
-Examples:
-
-```text
-workflow.created
-workflow.started
-workflow.stage.started
-workflow.stage.completed
-agent.run.started
-agent.run.completed
-approval.requested
-approval.approved
-policy.denied
-connector.action.executed
-artifact.created
-sandbox.started
-sandbox.stopped
-```
-
-## 28.2 Audit Events
-
-Audit events are security-relevant and should be immutable.
-
-Examples:
-
-```text
-user.login
-connector.created
-secret.created
-policy.updated
-workflow.enabled
-agent.permissions.changed
-external.comment.posted
-pull_request.opened
-approval.granted
-merge.executed
-```
-
-## 28.3 Audit Log Requirements
-
-Audit logs should include:
-
-* actor
-* action
-* target
-* result
-* timestamp
-* IP or service identity where applicable
-* metadata
-* policy decision
-* correlation ID
-
----
-
-# 29. Observability
-
-## 29.1 Logs
-
-Required logs:
-
-* API logs
-* workflow engine logs
-* worker logs
-* runtime adapter logs
-* sandbox logs
-* connector logs
-* model invocation logs
-* policy decision logs
-* audit logs
-
-## 29.2 Metrics
-
-Suggested metrics:
-
-```text
-workflow_runs_total
-workflow_runs_active
-workflow_runs_failed_total
-stage_runs_total
-agent_runs_total
-agent_runs_failed_total
-agent_run_duration_seconds
-model_input_tokens_total
-model_output_tokens_total
-model_cost_usd_total
-connector_events_total
-connector_action_errors_total
-policy_denials_total
-approvals_pending
-sandbox_active_total
-```
-
-## 29.3 Tracing
-
-Every workflow run should have a correlation ID.
-
-The correlation ID should be propagated through:
-
-* trigger processing
-* workflow engine
-* stage execution
-* runtime adapter
-* connector calls
-* sandbox
-* logs
-* artifacts
-
----
-
-# 30. Data Model
-
-## 30.1 Users
-
-```sql
-users (
-  id uuid primary key,
-  email text unique not null,
-  name text,
-  role text not null,
-  created_at timestamptz not null,
-  updated_at timestamptz not null
-)
-```
-
-## 30.2 Connectors
-
-```sql
-connectors (
-  id uuid primary key,
-  name text not null,
-  type text not null,
-  enabled boolean not null default true,
-  config jsonb not null,
-  secret_refs jsonb not null default '[]',
-  health_status text not null default 'unknown',
-  created_at timestamptz not null,
-  updated_at timestamptz not null
-)
-```
-
-## 30.3 Triggers
-
-```sql
-triggers (
-  id uuid primary key,
-  name text not null,
-  type text not null,
-  enabled boolean not null default true,
-  connector_id uuid references connectors(id),
-  workflow_id uuid references workflows(id),
-  definition jsonb not null,
-  created_at timestamptz not null,
-  updated_at timestamptz not null
-)
-```
-
-## 30.4 Monitors
-
-```sql
-monitors (
-  id uuid primary key,
-  name text not null,
-  type text not null,
-  enabled boolean not null default true,
-  connector_id uuid references connectors(id),
-  workflow_id uuid references workflows(id),
-  definition jsonb not null,
-  last_run_at timestamptz,
-  health_status text not null default 'unknown',
-  created_at timestamptz not null,
-  updated_at timestamptz not null
-)
-```
-
-## 30.5 Workflows
-
-```sql
-workflows (
-  id uuid primary key,
-  name text not null,
-  slug text unique not null,
-  enabled boolean not null default false,
-  current_version integer not null default 1,
-  description text,
-  created_by uuid references users(id),
-  created_at timestamptz not null,
-  updated_at timestamptz not null
-)
-```
-
-## 30.6 Workflow Versions
-
-```sql
-workflow_versions (
-  id uuid primary key,
-  workflow_id uuid references workflows(id),
-  version integer not null,
-  definition jsonb not null,
-  created_by uuid references users(id),
-  created_at timestamptz not null,
-  unique(workflow_id, version)
-)
-```
-
-## 30.7 Workflow Runs
-
-```sql
-workflow_runs (
-  id uuid primary key,
-  workflow_id uuid references workflows(id),
-  workflow_version_id uuid references workflow_versions(id),
-  status text not null,
-  trigger_event_id uuid,
-  input jsonb not null,
-  state jsonb not null default '{}',
-  current_stage text,
-  correlation_id text not null,
-  started_by uuid references users(id),
-  started_at timestamptz,
-  completed_at timestamptz,
-  created_at timestamptz not null,
-  updated_at timestamptz not null
-)
-```
-
-## 30.8 Stage Runs
-
-```sql
-stage_runs (
-  id uuid primary key,
-  workflow_run_id uuid references workflow_runs(id),
-  stage_id text not null,
-  stage_type text not null,
-  status text not null,
-  input jsonb not null default '{}',
-  output jsonb,
-  error jsonb,
-  attempts integer not null default 0,
-  started_at timestamptz,
-  completed_at timestamptz,
-  created_at timestamptz not null,
-  updated_at timestamptz not null
-)
-```
-
-## 30.9 Agents
-
-```sql
-agents (
-  id uuid primary key,
-  name text not null,
-  slug text unique not null,
-  type text not null,
-  runtime text not null,
-  enabled boolean not null default true,
-  definition jsonb not null,
-  created_by uuid references users(id),
-  created_at timestamptz not null,
-  updated_at timestamptz not null
-)
-```
-
-## 30.10 Agent Teams
-
-```sql
-agent_teams (
-  id uuid primary key,
-  name text not null,
-  slug text unique not null,
-  type text not null,
-  runtime text,
-  enabled boolean not null default true,
-  definition jsonb not null,
-  created_by uuid references users(id),
-  created_at timestamptz not null,
-  updated_at timestamptz not null
-)
-```
-
-## 30.11 Agent Runs
-
-```sql
-agent_runs (
-  id uuid primary key,
-  workflow_run_id uuid references workflow_runs(id),
-  stage_run_id uuid references stage_runs(id),
-  agent_id uuid references agents(id),
-  agent_team_id uuid references agent_teams(id),
-  runtime text not null,
-  status text not null,
-  input jsonb not null,
-  output jsonb,
-  error jsonb,
-  cost jsonb,
-  started_at timestamptz,
-  completed_at timestamptz,
-  created_at timestamptz not null,
-  updated_at timestamptz not null
-)
-```
-
-## 30.12 Models
-
-```sql
-models (
-  id uuid primary key,
-  name text not null,
-  provider text not null,
-  model_name text not null,
-  enabled boolean not null default true,
-  config jsonb not null,
-  limits jsonb not null default '{}',
-  capabilities jsonb not null default '[]',
-  created_at timestamptz not null,
-  updated_at timestamptz not null
-)
-```
-
-## 30.13 Tools
-
-```sql
-tools (
-  id uuid primary key,
-  name text not null,
-  type text not null,
-  enabled boolean not null default true,
-  definition jsonb not null,
-  risk_level text not null default 'medium',
-  created_at timestamptz not null,
-  updated_at timestamptz not null
-)
-```
-
-## 30.14 Policies
-
-```sql
-policies (
-  id uuid primary key,
-  name text not null,
-  enabled boolean not null default true,
-  scope text not null,
-  definition jsonb not null,
-  created_by uuid references users(id),
-  created_at timestamptz not null,
-  updated_at timestamptz not null
-)
-```
-
-## 30.15 Approvals
-
-```sql
-approvals (
-  id uuid primary key,
-  workflow_run_id uuid references workflow_runs(id),
-  stage_run_id uuid references stage_runs(id),
-  type text not null,
-  status text not null,
-  title text not null,
-  description text,
-  requested_by uuid references users(id),
-  resolved_by uuid references users(id),
-  required_roles jsonb not null default '[]',
-  context jsonb not null default '{}',
-  resolved_comment text,
-  expires_at timestamptz,
-  created_at timestamptz not null,
-  resolved_at timestamptz
-)
-```
-
-## 30.16 Artifacts
-
-```sql
-artifacts (
-  id uuid primary key,
-  workflow_run_id uuid references workflow_runs(id),
-  stage_run_id uuid references stage_runs(id),
-  agent_run_id uuid references agent_runs(id),
-  type text not null,
-  name text not null,
-  uri text not null,
-  content_type text,
-  metadata jsonb not null default '{}',
-  hash text,
-  created_at timestamptz not null
-)
-```
-
-## 30.17 Events
-
-```sql
-events (
-  id uuid primary key,
-  type text not null,
-  source text not null,
-  connector_id uuid references connectors(id),
-  workflow_run_id uuid references workflow_runs(id),
-  correlation_id text,
-  external_id text,
-  actor jsonb,
-  resource jsonb,
-  payload jsonb not null,
-  created_at timestamptz not null
-)
-```
-
-## 30.18 Audit Logs
-
-```sql
-audit_logs (
-  id uuid primary key,
-  actor_type text not null,
-  actor_id text,
-  action text not null,
-  target_type text,
-  target_id text,
-  result text not null,
-  policy_decision jsonb,
-  metadata jsonb not null default '{}',
-  correlation_id text,
-  created_at timestamptz not null
-)
-```
-
-## 30.19 Secrets
-
-```sql
-secrets (
-  id uuid primary key,
-  name text not null,
-  scope text not null,
-  provider text not null,
-  reference text not null,
-  metadata jsonb not null default '{}',
-  created_by uuid references users(id),
-  created_at timestamptz not null,
-  updated_at timestamptz not null
-)
-```
-
----
-
-# 31. Backend API
-
-## 31.1 Workflows
-
-```http
-GET /api/workflows
-POST /api/workflows
-GET /api/workflows/{workflow_id}
-PATCH /api/workflows/{workflow_id}
-DELETE /api/workflows/{workflow_id}
-POST /api/workflows/{workflow_id}/enable
-POST /api/workflows/{workflow_id}/disable
-POST /api/workflows/{workflow_id}/versions
-GET /api/workflows/{workflow_id}/versions
-POST /api/workflows/{workflow_id}/run
-POST /api/workflows/{workflow_id}/validate
-```
-
-## 31.2 Workflow Runs
-
-```http
-GET /api/runs
-GET /api/runs/{run_id}
-POST /api/runs/{run_id}/cancel
-POST /api/runs/{run_id}/pause
-POST /api/runs/{run_id}/resume
-POST /api/runs/{run_id}/retry
-POST /api/runs/{run_id}/retry-stage/{stage_run_id}
-GET /api/runs/{run_id}/events
-GET /api/runs/{run_id}/logs
-GET /api/runs/{run_id}/artifacts
-GET /api/runs/{run_id}/stream
-```
-
-## 31.3 Agents
-
-```http
-GET /api/agents
-POST /api/agents
-GET /api/agents/{agent_id}
-PATCH /api/agents/{agent_id}
-DELETE /api/agents/{agent_id}
-POST /api/agents/{agent_id}/test
-GET /api/agents/{agent_id}/runs
-```
-
-## 31.4 Agent Teams
-
-```http
-GET /api/agent-teams
-POST /api/agent-teams
-GET /api/agent-teams/{team_id}
-PATCH /api/agent-teams/{team_id}
-DELETE /api/agent-teams/{team_id}
-POST /api/agent-teams/{team_id}/test
-```
-
-## 31.5 Models
-
-```http
-GET /api/models
-POST /api/models
-GET /api/models/{model_id}
-PATCH /api/models/{model_id}
-DELETE /api/models/{model_id}
-POST /api/models/{model_id}/test
-```
-
-## 31.6 Connectors
-
-```http
-GET /api/connectors
-POST /api/connectors
-GET /api/connectors/{connector_id}
-PATCH /api/connectors/{connector_id}
-DELETE /api/connectors/{connector_id}
-POST /api/connectors/{connector_id}/test
-GET /api/connectors/{connector_id}/events
-GET /api/connectors/{connector_id}/resources
-```
-
-## 31.7 Triggers
-
-```http
-GET /api/triggers
-POST /api/triggers
-GET /api/triggers/{trigger_id}
-PATCH /api/triggers/{trigger_id}
-DELETE /api/triggers/{trigger_id}
-POST /api/triggers/{trigger_id}/enable
-POST /api/triggers/{trigger_id}/disable
-```
-
-## 31.8 Monitors
-
-```http
-GET /api/monitors
-POST /api/monitors
-GET /api/monitors/{monitor_id}
-PATCH /api/monitors/{monitor_id}
-DELETE /api/monitors/{monitor_id}
-POST /api/monitors/{monitor_id}/enable
-POST /api/monitors/{monitor_id}/disable
-POST /api/monitors/{monitor_id}/run-now
-```
-
-## 31.9 Approvals
-
-```http
-GET /api/approvals
-GET /api/approvals/{approval_id}
-POST /api/approvals/{approval_id}/approve
-POST /api/approvals/{approval_id}/reject
-POST /api/approvals/{approval_id}/request-changes
-```
-
-## 31.10 Artifacts
-
-```http
-GET /api/artifacts
-GET /api/artifacts/{artifact_id}
-GET /api/artifacts/{artifact_id}/download
-GET /api/artifacts/{artifact_id}/preview
-```
-
-## 31.11 Webhooks
-
-```http
-POST /api/webhooks/{connector_type}/{connector_id}
-POST /api/webhooks/generic/{trigger_id}
-```
-
-## 31.12 Policies
-
-```http
-GET /api/policies
-POST /api/policies
-GET /api/policies/{policy_id}
-PATCH /api/policies/{policy_id}
-DELETE /api/policies/{policy_id}
-POST /api/policies/evaluate
-```
-
----
-
-# 32. Git Issue-to-PR Reference Workflow
-
-## 32.1 Purpose
-
-This workflow proves AgentHub can orchestrate a real, useful, multi-stage agent process against an external system.
-
-## 32.2 Managed Git Repository
-
-A Git repository is represented as a connector resource.
-
-Repository config:
-
-```yaml
-repository:
-  provider: github
-  connector: github-main
-  full_name: org/repo
-  default_branch: main
-
-automation:
-  enabled: true
-  trigger_labels:
-    - agent-ready
-  trigger_mentions:
-    - "@agenthub"
-
-branching:
-  branch_prefix: agent/
-  branch_template: "agent/issue-{issue_number}-{slug}"
-
-pull_requests:
-  create_draft: true
-  labels:
-    - agent-generated
-  reviewers: []
-
-specs:
-  enabled: true
-  require_approval: true
-  path_template: ".agenthub/specs/issue-{issue_number}/"
-
-implementation:
-  agent: mini-swe-implementation-agent
-  sandbox: default-docker-sandbox
-  test_command: auto
-
-merge:
-  allow_agent_merge: false
-  require_human_approval: true
-  require_ci_success: true
-```
-
-## 32.3 Spec Bundle
-
-The Git workflow should create a spec bundle.
-
-```text
-.agenthub/specs/issue-123/
-  metadata.yaml
-  conversation.md
-  spec.md
-  plan.md
-  tasks.md
-  test-plan.md
-  decisions.md
-  implementation-log.md
-```
-
-## 32.4 Workflow Stages
-
-```text
-load_issue_context
-triage_issue
-generate_spec
-approve_spec
-prepare_workspace
-run_implementation_agent
-collect_diff
-run_tests
-push_branch
-open_draft_pr
-wait_for_ci
-review_pr
-await_human_review
-revise_if_needed
-complete
-```
-
-## 32.5 Revision Loop
-
-When a PR comment or review requests changes:
-
-```text
-PR comment received
-  ↓
-event normalized
-  ↓
-workflow run resumed or new revision run created
-  ↓
-comments summarized
-  ↓
-implementation agent updates branch
-  ↓
-tests run
-  ↓
-PR updated
-  ↓
-status comment posted
-```
-
-## 32.6 Implementation Agent
-
-The first implementation agent should use mini-SWE-agent.
-
-Responsibilities:
-
-* Clone repository
-* Check out branch
-* Read spec bundle
-* Read issue context
-* Modify files
-* Run tests
-* Commit changes
-* Push branch
-* Return summary
-
-## 32.7 Review Agent
-
-The first review agent can be either:
-
-* simple LLM prompt adapter
-* CrewAI review team
-* PR-Agent adapter
-
-Review dimensions:
-
-* spec alignment
-* test coverage
-* code quality
-* security concerns
-* migration risk
-* CI result interpretation
-
----
-
-# 33. Prompt and Template System
-
-## 33.1 Template Types
-
-```text
-trigger_summary
-triage
-spec_generation
-implementation
-review
-revision
-failure_summary
-approval_request
-external_comment
-notification
-```
-
-## 33.2 Template Variables
-
-```text
-{{workflow}}
-{{workflow_run}}
-{{stage}}
-{{input}}
-{{previous_outputs}}
-{{event}}
-{{connector_resource}}
-{{issue}}
-{{comments}}
-{{pull_request}}
-{{ci_result}}
-{{spec_bundle}}
-{{policy_context}}
-{{human_feedback}}
-```
-
-## 33.3 Template Versioning
-
-Prompt templates should be versioned.
-
-Agent runs should record:
-
-* template ID
-* template version
-* rendered prompt hash
-* model used
-* runtime used
-
-Do not store full prompts if the instance is configured to avoid sensitive storage. Store hashes and redacted versions.
-
----
-
-# 34. Security Model
-
-## 34.1 Threats
-
-AgentHub must assume:
-
-* external input may contain prompt injection
-* repository content may contain malicious instructions
-* issue comments may try to exfiltrate secrets
-* agents may make incorrect decisions
-* tools may be misused
-* model output may be unsafe
-* external APIs may fail or behave unexpectedly
-
-## 34.2 Security Principles
-
-1. Deny dangerous permissions by default.
-2. Make all external writes explicit.
-3. Require approval for high-risk actions.
-4. Isolate code execution.
-5. Never expose secrets unnecessarily.
-6. Log all sensitive actions.
-7. Treat model output as untrusted until validated.
-8. Keep platform orchestration deterministic.
-9. Keep agent runtime permissions scoped.
-10. Allow repository or connector-specific policy overrides.
-
-## 34.3 Prompt Injection Mitigations
-
-* Separate system instructions from untrusted content.
-* Label untrusted content clearly.
-* Apply policy after model output.
-* Block tool calls not granted to agent.
-* Require approvals for sensitive actions.
-* Protect secrets from model-visible context.
-* Redact logs.
-* Use output schemas for high-impact decisions.
-* Avoid letting agents modify their own policies.
-
----
-
-# 35. MVP Definition
-
-## 35.1 MVP Goal
-
-Build the smallest useful AgentHub that proves:
-
-1. Workflows can be defined.
-2. External events can trigger workflows.
-3. Agents can run through runtime adapters.
-4. The UI can monitor workflow runs.
-5. A real Git issue can become a draft PR.
-
-## 35.2 MVP Features
-
-Required:
-
-* Local admin login
-* Connector registry
-* GitHub connector
-* Generic webhook connector
-* Workflow definition via YAML
-* Workflow run engine
-* Stage execution
-* Job queue
-* Agent registry
-* Model registry
-* Simple LLM prompt adapter
-* CrewAI adapter, basic
-* mini-SWE-agent adapter, basic
-* Docker sandbox runner
-* Artifact store
-* Event log
-* Audit log
-* Approval gate
-* Live run logs
-* Git issue-to-PR reference workflow
-* No automatic merge
-
-## 35.3 MVP Exclusions
-
-Not required for MVP:
-
-* Visual workflow builder
-* Full RBAC
-* Multi-tenant organizations
-* GitLab connector
-* Slack connector
-* Marketplace
-* Long-term memory
-* Vector search
-* Production deployment automation
-* Automatic merge
-* Kubernetes runner
-* Firecracker sandbox
-* Advanced cost analytics
-
----
-
-# 36. Development Milestones
-
-## Milestone 1: Platform Skeleton
-
-Deliverables:
-
-* Monorepo
-* Docker Compose
-* PostgreSQL
-* Redis
-* MinIO or local artifact storage
-* Backend API shell
-* Frontend shell
-* Local admin auth
-* Basic dashboard
-
-## Milestone 2: Core Data Model
-
-Deliverables:
-
-* Database migrations
-* CRUD for workflows
-* CRUD for agents
-* CRUD for models
-* CRUD for connectors
-* CRUD for triggers
-* CRUD for approvals
-* Event log
-* Audit log
-
-## Milestone 3: Workflow Engine v1
-
-Deliverables:
-
-* YAML workflow parser
-* Workflow validation
-* Workflow run creation
-* Stage execution
-* Sequential stage support
-* Condition stage support
-* Approval stage support
-* Retry support
-* Failure handling
-* Run timeline UI
-
-## Milestone 4: Runtime Adapter Framework
-
-Deliverables:
-
-* Runtime adapter interface
-* Simple LLM prompt adapter
-* Script adapter
-* Docker adapter
-* Runtime logs
-* Runtime artifacts
-* Cancellation support
-
-## Milestone 5: Connector Framework
-
-Deliverables:
-
-* Connector interface
-* Generic webhook connector
-* GitHub connector
-* Webhook verification
-* Event normalization
-* Trigger filtering
-* Connector action execution
-
-## Milestone 6: GitHub Reference Workflow Part 1
-
-Deliverables:
-
-* GitHub App setup
-* Repository registration
-* Issue event ingestion
-* Issue context loading
-* Label and mention trigger
-* Triage agent
-* Spec generation stage
-* Spec artifact viewer
-* Spec approval gate
-
-## Milestone 7: mini-SWE-agent Adapter
-
-Deliverables:
-
-* Workspace preparation
-* Repository clone
-* Branch creation
-* Prompt/context bundle creation
-* mini-SWE-agent invocation
-* Log streaming
-* Diff collection
-* Test command execution
-* Commit creation
-* Branch push
-
-## Milestone 8: Pull Request Flow
-
-Deliverables:
-
-* Draft PR creation
-* PR status tracking
-* CI monitor
-* PR review agent
-* Human review gate
-* Revision trigger from PR comments
-* PR update loop
-
-## Milestone 9: CrewAI Adapter
-
-Deliverables:
-
-* CrewAI runtime configuration
-* Hierarchical team support
-* Sequential team support
-* Structured output collection
-* Crew logs and artifacts
-* Use CrewAI for spec team or review team
-
-## Milestone 10: Policy and Security Hardening
-
-Deliverables:
-
-* Policy engine v1
-* Protected path checks
-* Tool permission checks
-* Secret scoping
-* Log redaction
-* Sandbox limits
-* Cost limits
-* Audit log coverage
-
----
-
-# 37. Suggested Monorepo Structure
+Monorepo: Turbo + pnpm
+Frontend: Next.js + TypeScript
+Backend: FastAPI
+ORM: SQLAlchemy
+Migrations: Alembic
+Worker: Celery
+Queue broker: Redis
+Database: PostgreSQL
+Vector database: pgvector
+Artifact storage: MinIO
+Sandbox: Docker per run
+Authentication: Authentik OIDC first
+First model provider: Kimi
+Second model provider: OpenAI
+License: Apache-2.0
+```
+
+## 6.2 Recommended App Structure
 
 ```text
 agenthub/
@@ -3526,139 +298,715 @@ agenthub/
 
   packages/
     shared/
-    workflow-engine/
-    policy-engine/
-    connector-sdk/
-    runtime-sdk/
-    model-gateway/
-    artifact-store/
-    sandbox-manager/
+    workflow-schema/
+    ui/
+    client-sdk/
+
+  python/
+    agenthub_core/
+      workflow/
+      policy/
+      connectors/
+      runtimes/
+      models/
+      artifacts/
+      memory/
+      sandbox/
+      events/
+      auth/
 
   connectors/
-    github/
-    generic-webhook/
+    gitea/
+    generic_webhook/
     http/
+    future_gitlab/
+    future_github/
 
   runtimes/
-    llm-prompt/
+    llm_prompt/
     script/
-    docker/
+    mini_swe_agent/
     crewai/
-    mini-swe-agent/
-    pr-agent/
 
   workflows/
     examples/
-      github-issue-to-pr.yaml
-      webhook-summarizer.yaml
+      manual-prompt-artifact-approval.yaml
+      generic-webhook-summarizer.yaml
+      gitea-issue-to-pr.yaml
 
   agents/
     examples/
-      git-triage-agent.yaml
-      git-spec-team.yaml
+      summarizer-agent.yaml
+      gitea-triage-agent.yaml
+      gitea-spec-team.yaml
       mini-swe-implementation-agent.yaml
       pr-review-team.yaml
 
+  policies/
+    examples/
+      default-secure-policy.yaml
+      gitea-merge-policy.yaml
+
   infra/
     docker-compose.yml
+    docker/
     k8s/
-    helm/
 
   docs/
-    product-spec.md
     architecture.md
+    development.md
     security.md
     workflow-format.md
     connector-sdk.md
     runtime-sdk.md
-    github-reference-workflow.md
-
-  tests/
-    integration/
-    fixtures/
+    model-gateway.md
+    gitea-reference-workflow.md
 ```
 
 ---
 
-# 38. First Vertical Slice
+# 7. Deployment Model
 
-The first vertical slice should avoid overbuilding.
+## 7.1 MVP Docker Compose Deployment
 
-Goal:
+AgentHub must run locally and on a small server with Docker Compose.
+
+Required services:
 
 ```text
-manual workflow run
-  ↓
-simple prompt agent
-  ↓
-approval gate
-  ↓
-GitHub issue context
-  ↓
-spec artifact
+agenthub-web
+agenthub-api
+agenthub-worker
+postgres
+redis
+minio
 ```
 
-Then expand to:
+Recommended optional local services:
 
 ```text
-GitHub label trigger
+authentik
+ollama
+gitea
+local OpenAI-compatible model endpoint
+```
+
+## 7.2 Future Deployment
+
+Future deployment should support Kubernetes.
+
+The architecture should avoid assumptions that prevent later migration to:
+
+```text
+Kubernetes jobs
+Temporal
+Hatchet
+Windmill
+external secret managers
+external object storage
+external vector databases
+external model gateways
+```
+
+---
+
+# 8. Authentication and Authorization
+
+## 8.1 Authentication
+
+MVP authentication uses:
+
+```text
+Authentik OIDC
+```
+
+Local password login is not required for MVP unless needed as an emergency development fallback.
+
+## 8.2 Workspace Model
+
+AgentHub supports multi-user operation with teams and projects from the start.
+
+A workspace is the top-level collaboration boundary.
+
+```text
+workspace
+  ├─ users
+  ├─ teams
+  ├─ projects
+  ├─ connectors
+  ├─ workflows
+  ├─ agents
+  ├─ models
+  ├─ policies
+  └─ secrets
+```
+
+## 8.3 Projects
+
+Projects group workflows, connectors, agents, artifacts, and memory around a domain.
+
+Examples:
+
+```text
+Platform Engineering
+Backend Services
+Internal Tools
+Customer Support Automation
+Release Automation
+```
+
+A project can be owned by one user or one or more teams.
+
+## 8.4 MVP Roles
+
+```text
+admin
+operator
+maintainer
+developer
+viewer
+```
+
+### admin
+
+Can manage the instance, workspaces, users, teams, secrets, models, and global policies.
+
+### operator
+
+Can manage workflows, agents, connectors, monitors, and runs.
+
+### maintainer
+
+Can approve high-risk workflow stages, Git specs, PR readiness, and merge actions where configured.
+
+### developer
+
+Can trigger allowed workflows, inspect runs, comment, and provide input.
+
+### viewer
+
+Can view allowed projects, runs, artifacts, and logs.
+
+---
+
+# 9. Architecture Overview
+
+```text
+Web UI
   ↓
-spec generation
+Backend API
   ↓
+Workflow Engine
+  ↓
+Postgres-backed durable state machine
+  ↓
+Redis / Celery queue
+  ↓
+Worker pool
+  ↓
+Runtime adapters
+    ├─ LLM prompt adapter
+    ├─ script adapter
+    ├─ mini-SWE-agent adapter
+    └─ CrewAI adapter
+
+Platform services
+  ├─ connector registry
+  ├─ trigger engine
+  ├─ monitor engine
+  ├─ model gateway
+  ├─ policy engine
+  ├─ tool registry
+  ├─ sandbox manager
+  ├─ secret store
+  ├─ vector memory
+  ├─ artifact store
+  ├─ event log
+  └─ audit log
+```
+
+---
+
+# 10. Persistence and Event Model
+
+AgentHub uses a pragmatic hybrid model:
+
+```text
+Postgres is the source of truth.
+Redis is only a queue.
+Workflow, stage, and agent run rows store current state.
+Every meaningful transition appends an event.
+Audit-relevant actions also append audit log entries.
+```
+
+This is not full event sourcing in the MVP, but it keeps a future path open.
+
+## 10.1 Required Tables for Current State
+
+```text
+workspaces
+projects
+teams
+users
+memberships
+connectors
+triggers
+monitors
+workflows
+workflow_versions
+workflow_runs
+stage_runs
+agents
+agent_teams
+agent_runs
+models
+tools
+policies
+approvals
+artifacts
+secrets
+memory_collections
+memory_items
+events
+audit_logs
+```
+
+## 10.2 Required Event Discipline
+
+Every transition should follow this pattern:
+
+```text
+validate input
+  ↓
+evaluate policy
+  ↓
+append event
+  ↓
+update current-state row
+  ↓
+enqueue next job if needed
+  ↓
+append audit log if security-relevant
+```
+
+Examples of internal events:
+
+```text
+workflow_run.created
+workflow_run.started
+stage_run.queued
+stage_run.started
+agent_run.started
+artifact.created
+approval.requested
+approval.approved
+connector_action.executed
+stage_run.completed
+workflow_run.completed
+policy.denied
+```
+
+---
+
+# 11. Workflow System
+
+## 11.1 Workflow Engine
+
+The MVP uses a custom lightweight workflow engine.
+
+It must be designed so it can later be replaced by or integrated with:
+
+```text
+Temporal
+Hatchet
+Windmill
+LangGraph
+custom durable workflow engine
+```
+
+The AgentHub workflow definition format must remain independent from the execution backend.
+
+## 11.2 Workflow Authoring
+
+Workflows are YAML-first.
+
+The MVP UI must provide:
+
+```text
+YAML editor
+schema validation
+validation error display
+read-only graph preview
+run history
+stage timeline
+```
+
+A visual builder is not required for MVP.
+
+## 11.3 Workflow Storage
+
+Workflows are stored in PostgreSQL first.
+
+YAML import/export must be supported early.
+
+GitOps workflow storage is a future feature.
+
+## 11.4 Workflow Versioning
+
+Every workflow edit creates a new workflow version.
+
+Every workflow run stores an immutable snapshot of:
+
+```text
+workflow definition
+agent definitions
+agent team definitions
+model routing decisions
+policy versions
+prompt template versions
+runtime adapter versions where practical
+```
+
+Active runs are not affected by later workflow edits.
+
+## 11.5 Supported MVP Stage Types
+
+```text
+agent
+agent_team
+script
+connector_action
 approval
-  ↓
-mini-SWE-agent
-  ↓
-draft PR
+condition
+wait_for_condition
+notification
+terminal
 ```
 
-## 38.1 First Slice Acceptance Criteria
+Future stage types:
 
-The first prototype is done when:
+```text
+parallel
+subworkflow
+human_input
+wait_for_event
+manual_task
+deployment
+```
 
-1. A user can start the stack with Docker Compose.
-2. A user can log in locally.
-3. A user can create a model definition.
-4. A user can create an agent definition.
-5. A user can create a workflow YAML.
-6. A user can manually run the workflow.
-7. The workflow runs one agent stage.
-8. The agent produces a markdown artifact.
-9. The UI shows the run timeline.
-10. The UI shows logs.
-11. The UI shows the artifact.
-12. The workflow can pause for approval.
-13. The user can approve and complete the workflow.
+## 11.6 Agents Starting Sub-Workflows
 
-## 38.2 Second Slice Acceptance Criteria
+In the MVP, agents cannot directly start sub-workflows.
 
-The second prototype is done when:
-
-1. A GitHub connector can be configured.
-2. AgentHub receives GitHub webhooks.
-3. A label trigger starts a workflow.
-4. The workflow loads issue context.
-5. The spec team creates a spec artifact.
-6. A maintainer approves the spec.
-7. The mini-SWE-agent adapter runs in Docker.
-8. A branch is pushed.
-9. A draft PR is opened.
-10. Logs and artifacts are visible in the UI.
-
----
-
-# 39. Example Workflow: Generic Webhook Summarizer
-
-This example proves the platform is not Git-specific.
+Agents may recommend a workflow action:
 
 ```yaml
-id: webhook-summarizer
-name: Webhook Summarizer
+recommended_actions:
+  - type: start_workflow
+    workflow: security-review
+    reason: "Authentication code changed."
+```
+
+The platform or a human decides whether to start it.
+
+Future versions may allow policy-approved sub-workflows.
+
+---
+
+# 12. First Vertical Slice Workflow
+
+The first vertical slice validates the core platform before connector complexity.
+
+## 12.1 Goal
+
+A user can manually run a workflow that:
+
+```text
+manual trigger
+  ↓
+Kimi LLM prompt stage
+  ↓
+markdown artifact created in MinIO
+  ↓
+approval requested
+  ↓
+human approves or rejects
+  ↓
+workflow completes
+```
+
+## 12.2 Acceptance Criteria
+
+The first vertical slice is complete when:
+
+1. Authentik OIDC login works.
+2. A workspace exists.
+3. A project exists.
+4. A workflow can be authored in YAML.
+5. The workflow can be manually triggered.
+6. A workflow run snapshot is stored.
+7. Celery executes the stage.
+8. The model gateway calls Kimi.
+9. The LLM prompt runtime returns structured output.
+10. A markdown artifact is stored in MinIO.
+11. An approval gate is created.
+12. A user can approve or reject the gate.
+13. The workflow continues or terminates accordingly.
+14. The UI shows the run timeline.
+15. The UI shows logs, events, and artifacts.
+
+## 12.3 Example Workflow
+
+```yaml
+id: manual-prompt-artifact-approval
+name: Manual Prompt Artifact Approval
 version: 1
 enabled: true
 
 triggers:
-  - id: generic-webhook
+  - id: manual
+    type: manual
+
+stages:
+  - id: draft_summary
+    type: agent
+    agent: simple-summary-agent
+    input:
+      prompt: "{{ input.prompt }}"
+    outputs:
+      summary: result
+
+  - id: create_artifact
+    type: connector_action
+    connector: artifact-store
+    action: artifact.create_markdown
+    input:
+      name: summary.md
+      content: "{{ summary.outputs.markdown }}"
+    outputs:
+      artifact: result
+
+  - id: approve
+    type: approval
+    title: "Approve generated artifact"
+    required_roles:
+      - maintainer
+    input:
+      artifact: "{{ artifact }}"
+
+  - id: complete
+    type: terminal
+    status: success
+```
+
+---
+
+# 13. Trigger System
+
+Triggers start workflows from events.
+
+Supported MVP triggers:
+
+```text
+manual trigger
+generic webhook trigger
+Gitea issue label trigger
+Gitea comment mention trigger
+scheduled trigger
+```
+
+Future triggers:
+
+```text
+GitLab events
+GitHub events
+Slack/Matrix commands
+email events
+RSS events
+database events
+workflow events
+```
+
+## 13.1 Trigger Deduplication
+
+All external events must be deduplicated.
+
+Deduplication examples:
+
+```text
+connector_id + external_event_id
+repository + issue_number + label + workflow_id
+webhook_delivery_id
+```
+
+## 13.2 Trigger Authorization
+
+Before starting a workflow:
+
+```text
+connector is enabled
+workflow is enabled
+actor is authorized if applicable
+trigger filter matches
+policy permits run creation
+duplicate active run is not already present
+```
+
+---
+
+# 14. Monitor System
+
+Monitors watch external conditions and emit internal events.
+
+Supported MVP monitor:
+
+```text
+basic polling monitor
+```
+
+For the Git workflow, monitors are used to watch:
+
+```text
+pull request CI/check status
+unresolved review comments
+stale agent PRs
+```
+
+Future monitors:
+
+```text
+RSS/security advisory monitor
+HTTP health monitor
+queue backlog monitor
+scheduled stale issue monitor
+email inbox monitor
+deployment status monitor
+```
+
+---
+
+# 15. Connector System
+
+## 15.1 Connector Strategy
+
+The first complete Git connector is:
+
+```text
+Gitea
+```
+
+The connector abstraction must remain open for:
+
+```text
+GitLab
+GitHub
+Forgejo
+generic Git
+generic HTTP
+generic webhook
+```
+
+Gitea is required because self-hosting is core to the product.
+
+GitLab support is highly desirable after Gitea.
+
+GitHub support should be straightforward if the provider abstraction is clean.
+
+## 15.2 MVP Connectors
+
+```text
+Gitea connector
+generic webhook connector
+HTTP connector
+artifact-store connector
+```
+
+## 15.3 Future Connectors
+
+```text
+GitLab
+GitHub
+Forgejo
+Slack
+Matrix
+Jira
+Linear
+email
+RSS
+Kubernetes
+database
+S3-compatible storage
+```
+
+## 15.4 Git Provider Abstraction
+
+Git providers must expose common operations:
+
+```text
+read repository
+read issue
+list issue comments
+post issue comment
+add/remove label
+create branch
+push commits
+open pull request
+update pull request
+read pull request
+list PR comments
+read CI/check status
+merge pull request if configured and allowed
+```
+
+## 15.5 Git Auth Strategy
+
+MVP uses a hybrid strategy:
+
+```text
+API access: provider token
+Git clone/push: HTTPS token or SSH key
+```
+
+Future production strategies:
+
+```text
+GitHub App
+GitLab OAuth/application integration
+Gitea OAuth/application tokens where available
+short-lived credentials
+provider-specific app models
+```
+
+---
+
+# 16. Secondary Reference Workflow: Generic Webhook Summarizer
+
+This workflow proves AgentHub is not only a Git bot.
+
+## 16.1 Workflow
+
+```text
+external webhook received
+  ↓
+summarization agent runs
+  ↓
+approval gate
+  ↓
+HTTP callback posts result
+  ↓
+artifact and audit log recorded
+```
+
+## 16.2 Example Workflow
+
+```yaml
+id: generic-webhook-summarizer
+name: Generic Webhook Summarizer
+version: 1
+enabled: true
+
+triggers:
+  - id: incoming-webhook
     type: webhook_event
     connector: generic-webhook
     path: /incoming/summarize
@@ -3674,9 +1022,9 @@ stages:
 
   - id: approve
     type: approval
-    title: "Approve summary before posting"
+    title: "Approve summary before callback"
     required_roles:
-      - admin
+      - maintainer
     input:
       summary: "{{ summary }}"
 
@@ -3687,7 +1035,7 @@ stages:
     input:
       url: "{{ event.payload.callback_url }}"
       body:
-        summary: "{{ summary }}"
+        summary: "{{ summary.outputs.text }}"
 
   - id: complete
     type: terminal
@@ -3696,19 +1044,69 @@ stages:
 
 ---
 
-# 40. Example Workflow: Git Issue to PR
+# 17. Gitea Issue-to-PR Reference Workflow
+
+## 17.1 Provider Priority
+
+The first complete Git provider is:
+
+```text
+Gitea
+```
+
+The provider abstraction must keep room for:
+
+```text
+GitLab
+GitHub
+Forgejo
+```
+
+## 17.2 Default Workflow
+
+```text
+issue labeled "agent-ready"
+  ↓
+load issue context
+  ↓
+triage
+  ↓
+generate spec
+  ↓
+human spec approval
+  ↓
+run mini-SWE-agent implementation
+  ↓
+collect diff
+  ↓
+run tests
+  ↓
+push branch
+  ↓
+open draft pull request
+  ↓
+wait for CI
+  ↓
+review
+  ↓
+human review
+  ↓
+mark ready or merge if configured
+```
+
+## 17.3 Workflow YAML
 
 ```yaml
-id: github-issue-to-pr
-name: GitHub Issue to Pull Request
+id: gitea-issue-to-pr
+name: Gitea Issue to Pull Request
 version: 1
 enabled: true
 
 triggers:
-  - id: label-agent-ready
+  - id: issue-agent-ready
     type: connector_event
-    connector: github-main
-    event: github.issue.labeled
+    connector: gitea-main
+    event: gitea.issue.labeled
     filter:
       all:
         - path: "$.label.name"
@@ -3716,11 +1114,20 @@ triggers:
         - path: "$.issue.state"
           equals: "open"
 
+  - id: issue-mentioned
+    type: connector_event
+    connector: gitea-main
+    event: gitea.issue.commented
+    filter:
+      contains:
+        path: "$.comment.body"
+        value: "@agenthub"
+
 stages:
   - id: load_issue
     type: connector_action
-    connector: github-main
-    action: github.load_issue_context
+    connector: gitea-main
+    action: gitea.load_issue_context
     input:
       repository: "{{ event.payload.repository.full_name }}"
       issue_number: "{{ event.payload.issue.number }}"
@@ -3729,7 +1136,7 @@ stages:
 
   - id: triage
     type: agent
-    agent: git-triage-agent
+    agent: gitea-triage-agent
     input:
       issue_context: "{{ issue_context }}"
     outputs:
@@ -3737,18 +1144,18 @@ stages:
 
   - id: maybe_stop
     type: condition
-    expression: "{{ triage.suitable == true }}"
+    expression: "{{ triage.outputs.suitable == true }}"
     on_true: generate_spec
     on_false: comment_not_suitable
 
   - id: comment_not_suitable
     type: connector_action
-    connector: github-main
-    action: github.create_issue_comment
+    connector: gitea-main
+    action: gitea.create_issue_comment
     input:
       repository: "{{ issue_context.repository }}"
       issue_number: "{{ issue_context.number }}"
-      body: "AgentHub triaged this issue as not suitable for automation: {{ triage.reason }}"
+      body: "AgentHub triaged this issue as not suitable for automation: {{ triage.outputs.reason }}"
     next: complete_not_suitable
 
   - id: complete_not_suitable
@@ -3757,7 +1164,7 @@ stages:
 
   - id: generate_spec
     type: agent_team
-    team: git-spec-team
+    team: gitea-spec-team
     input:
       issue_context: "{{ issue_context }}"
       triage: "{{ triage }}"
@@ -3783,8 +1190,8 @@ stages:
 
   - id: open_pr
     type: connector_action
-    connector: github-main
-    action: github.open_draft_pr
+    connector: gitea-main
+    action: gitea.open_draft_pr
     input:
       repository: "{{ issue_context.repository }}"
       issue_number: "{{ issue_context.number }}"
@@ -3794,8 +1201,8 @@ stages:
 
   - id: wait_for_ci
     type: wait_for_condition
-    connector: github-main
-    condition: github.pr_checks_completed
+    connector: gitea-main
+    condition: gitea.pr_checks_completed
     timeout_minutes: 60
     input:
       repository: "{{ issue_context.repository }}"
@@ -3822,113 +1229,1977 @@ stages:
       pull_request: "{{ pull_request }}"
       review: "{{ review }}"
 
+  - id: maybe_merge
+    type: condition
+    expression: "{{ workflow.config.merge.mode == 'merge_after_approval' }}"
+    on_true: merge_pr
+    on_false: mark_ready
+
+  - id: mark_ready
+    type: connector_action
+    connector: gitea-main
+    action: gitea.create_pr_comment
+    input:
+      repository: "{{ issue_context.repository }}"
+      pull_request_number: "{{ pull_request.number }}"
+      body: "AgentHub marked this PR as ready for human merge."
+    next: complete
+
+  - id: merge_pr
+    type: connector_action
+    connector: gitea-main
+    action: gitea.merge_pr
+    input:
+      repository: "{{ issue_context.repository }}"
+      pull_request_number: "{{ pull_request.number }}"
+      strategy: squash
+    next: complete
+
   - id: complete
     type: terminal
     status: success
 ```
 
----
+## 17.4 Spec Storage
 
-# 41. Definition of Done for MVP
-
-The MVP is complete when:
-
-1. AgentHub runs locally through Docker Compose.
-2. A user can log in.
-3. A user can configure at least one model provider.
-4. A user can configure at least one GitHub connector.
-5. A user can define a workflow in YAML.
-6. A user can manually run a workflow.
-7. A GitHub webhook can trigger a workflow.
-8. A workflow can run a single-agent stage.
-9. A workflow can run a CrewAI team stage.
-10. A workflow can run a mini-SWE-agent implementation stage.
-11. A workflow can pause for human approval.
-12. A workflow can produce artifacts.
-13. The UI shows run state, logs, artifacts, and approvals.
-14. The Git workflow can turn a labeled issue into a draft PR.
-15. The system records audit events for external writes.
-16. The system does not merge PRs automatically.
-
----
-
-# 42. Open Questions
-
-1. Should the initial workflow engine be custom, or should the project start on Temporal/Hatchet immediately?
-2. Should workflow definitions be YAML-only initially, or should the UI generate YAML?
-3. Should CrewAI support be included in the first MVP or the second milestone?
-4. Should agent definitions live only in the database, or also as versioned files in Git?
-5. Should workflow definitions be importable from Git repositories?
-6. Should model routing be global first, or workflow-local first?
-7. Should local models be a first-class MVP requirement?
-8. Should secrets use an internal encrypted store or external secret managers only?
-9. Should each agent run get its own Docker image or share a base image?
-10. Should the GitHub connector use GitHub App authentication only, or also personal access tokens for local development?
-11. Should workflow runs be immutable once started?
-12. Should human comments be accepted from external systems or only from the AgentHub UI?
-13. Should agents be able to start sub-workflows?
-14. Should policies be written in YAML first, or use a policy engine like OPA later?
-15. Should long-term memory be delayed until after the Git reference workflow is stable?
-
----
-
-# 43. Recommended Initial Decisions
-
-For fastest progress:
+Default:
 
 ```yaml
-workflow_engine: custom_sequential_state_machine_first
-workflow_definition: yaml
-frontend: nextjs
-backend: fastapi
-database: postgres
-queue: redis_rq_or_celery
-artifact_storage: local_filesystem_then_minio
-sandbox: docker
-first_connector: github
-second_connector: generic_webhook
-first_runtime: llm_prompt
-second_runtime: mini_swe_agent
-third_runtime: crewai
-merge_policy: human_only
-auth: local_admin_first
+specs:
+  store_as_artifacts: true
+  commit_to_branch: true
+  commit_to_default_branch: false
+```
+
+Generated specs should be visible in AgentHub and optionally included in the PR branch.
+
+## 17.5 Spec Bundle Layout
+
+```text
+.agenthub/specs/issue-123/
+  metadata.yaml
+  conversation.md
+  spec.md
+  plan.md
+  tasks.md
+  test-plan.md
+  decisions.md
+  implementation-log.md
+```
+
+## 17.6 PR Revision Loop
+
+```text
+PR review/comment received
+  ↓
+authorized command or changes requested detected
+  ↓
+workflow revision stage starts
+  ↓
+comments summarized
+  ↓
+implementation agent updates branch
+  ↓
+tests run
+  ↓
+PR updated
+  ↓
+status comment posted
 ```
 
 ---
 
-# 44. Product Philosophy
+# 18. Agent System
 
-AgentHub should be built around these principles:
+## 18.1 Agent Definition
 
-1. The platform owns control.
-2. Agents own task execution.
-3. Humans own approval.
-4. Policies own boundaries.
-5. Workflows own process.
-6. Connectors own external integration.
-7. Runtimes are replaceable.
-8. Models are replaceable.
-9. Artifacts are first-class.
-10. Every important action is observable and auditable.
+Agents are configured units that perform tasks.
+
+Each agent has:
+
+```text
+name
+role
+runtime
+model routing policy
+prompt templates
+tool grants
+sandbox configuration
+output schema
+limits
+permissions
+```
+
+## 18.2 Agent Roles
+
+Common roles:
+
+```text
+triage
+planner
+spec_writer
+researcher
+coder
+reviewer
+tester
+security_reviewer
+documentation_writer
+operator
+manager
+judge
+router
+```
+
+## 18.3 Agent Teams and Hierarchy
+
+AgentHub has its own native team abstraction.
+
+Team patterns:
+
+```text
+sequential
+parallel
+hierarchical
+supervisor_worker
+debate_judge
+router_specialist
+review_board
+```
+
+These are mapped onto runtime-specific implementations.
+
+Example mappings:
+
+```text
+AgentHub hierarchical team → CrewAI hierarchical process
+AgentHub coding worker → mini-SWE-agent
+AgentHub review board → CrewAI or custom parallel runner
+Future AgentHub graph team → LangGraph
+```
+
+## 18.4 CrewAI Role
+
+CrewAI is an optional runtime adapter for agent teams.
+
+It is useful for:
+
+```text
+hierarchical spec generation
+planning
+research
+review boards
+risk analysis
+multi-perspective critique
+manager-worker execution
+```
+
+It is not the core platform orchestration engine.
 
 ---
 
-# 45. Immediate Next Development Steps
+# 19. Runtime Adapter System
 
-1. Create the monorepo.
-2. Add Docker Compose for web, api, worker, Postgres, Redis, and MinIO.
-3. Implement the database schema for workflows, workflow runs, stage runs, agents, models, connectors, artifacts, events, and approvals.
-4. Implement YAML workflow validation.
-5. Implement manual workflow execution.
-6. Implement the simple LLM prompt runtime.
-7. Implement run timeline and logs in the UI.
-8. Implement approval gates.
-9. Implement the generic webhook connector.
-10. Implement the GitHub connector.
-11. Implement the GitHub issue-to-spec workflow.
-12. Implement the mini-SWE-agent adapter.
-13. Implement draft PR creation.
-14. Add CrewAI as an agent team runtime.
-15. Harden policies and sandboxing before enabling broader workflows.
+## 19.1 Runtime Adapter Interface
+
+Every runtime adapter should expose:
+
+```text
+validate definition
+prepare run
+start run
+stream events/logs
+cancel run
+collect result
+cleanup
+```
+
+## 19.2 MVP Runtime Adapters
+
+```text
+llm_prompt
+script
+mini_swe_agent
+crewai
+```
+
+## 19.3 Runtime Result Contract
+
+All runtimes must return a normalized result:
+
+```yaml
+status: success | failed | cancelled | timed_out | needs_input | blocked
+summary: string
+outputs: object
+artifacts: []
+events: []
+cost:
+  input_tokens: number
+  output_tokens: number
+  estimated_cost: number
+errors: []
+recommended_actions: []
+```
+
+---
+
+# 20. Model Gateway and Model Registry
+
+## 20.1 Supported MVP Providers
+
+AgentHub must normalize model access across:
+
+```text
+Kimi
+OpenAI
+Anthropic
+Ollama
+OpenAI-compatible endpoints
+```
+
+Implementation order:
+
+```text
+1. Kimi
+2. OpenAI
+3. OpenAI-compatible generic endpoint
+4. Anthropic
+5. Ollama
+```
+
+Kimi should be supported as a first-class provider profile through the normalized model gateway, using OpenAI-compatible API behavior where possible.
+
+## 20.2 Model Routing
+
+AgentHub uses a global model registry with workflow, agent, and stage overrides.
+
+Resolution order:
+
+```text
+stage explicit model
+  ↓
+agent explicit model
+  ↓
+team member explicit model
+  ↓
+workflow model routing policy
+  ↓
+project model routing policy
+  ↓
+workspace/global model routing policy
+  ↓
+system default model
+```
+
+## 20.3 Model Gateway Requirement
+
+All model calls should route through AgentHub where technically possible.
+
+The model gateway enables:
+
+```text
+provider abstraction
+cost tracking
+token tracking
+fallbacks
+routing
+rate limiting
+redaction
+audit records
+model health checks
+```
+
+Some third-party runtimes may require direct model credentials. Those exceptions must be explicit.
+
+## 20.4 Model Provider Definition
+
+```yaml
+id: kimi-main
+type: kimi
+name: Kimi Main
+base_url: https://api.moonshot.ai/v1
+api_key_secret: kimi_api_key
+enabled: true
+
+models:
+  - id: kimi-default
+    model_name: kimi-k2
+    capabilities:
+      - chat
+      - structured_output
+      - tool_calling
+```
+
+---
+
+# 21. Tool Registry and Tool Grants
+
+Tools are explicitly granted per agent or per team.
+
+No agent receives all tools by default.
+
+Default grants:
+
+```text
+no shell
+no filesystem write
+no external write
+no secret access
+no merge
+```
+
+Tool categories:
+
+```text
+filesystem
+shell
+git
+http
+browser
+database
+connector_action
+vector_search
+code_search
+notification
+artifact
+human_input
+```
+
+Tool risk levels:
+
+```text
+low
+medium
+high
+critical
+```
+
+Examples:
+
+```text
+read issue: low
+post comment: medium
+write file: medium
+push branch: high
+merge pull request: critical
+access secret: critical
+deploy production: critical
+```
+
+---
+
+# 22. Policy Engine
+
+## 22.1 MVP Policy Engine
+
+AgentHub uses a native YAML policy engine in the MVP.
+
+It should later remain compatible with or replaceable by:
+
+```text
+OPA/Rego
+Cedar
+CEL
+custom policy DSL
+```
+
+## 22.2 Policy Decisions
+
+Policies return:
+
+```yaml
+decision: allow | deny | require_approval
+reason: string
+matched_rules: []
+risk_level: low | medium | high | critical
+required_approvals: []
+```
+
+## 22.3 Policy Evaluation Points
+
+Evaluate policies before:
+
+```text
+starting workflow
+starting stage
+invoking model
+granting tool
+accessing secret
+running shell command
+writing file
+calling connector action
+posting external comment
+opening pull request
+merging pull request
+sending notification
+indexing memory
+retrying with elevated permissions
+```
+
+## 22.4 Example Policy
+
+```yaml
+id: default-secure-policy
+name: Default Secure Policy
+enabled: true
+
+rules:
+  - id: deny-secret-file-read
+    effect: deny
+    action: filesystem.read
+    paths:
+      - ".env"
+      - "**/*.pem"
+      - "**/*.key"
+
+  - id: require-approval-for-network
+    effect: require_approval
+    action: sandbox.network.enable
+    required_roles:
+      - maintainer
+
+  - id: require-approval-for-pr-merge
+    effect: require_approval
+    action: git.pull_request.merge
+    required_roles:
+      - maintainer
+
+  - id: max-cost-per-run
+    effect: deny
+    action: model.invoke
+    condition:
+      estimated_cost_usd_gt: 10
+```
+
+---
+
+# 23. Secrets
+
+## 23.1 MVP Secret Store
+
+AgentHub uses an internal encrypted secret store in the MVP.
+
+Secrets must be:
+
+```text
+encrypted at rest
+scoped to workspace/project/connector/agent
+masked in logs
+not exposed to agents by default
+granted only when needed
+audited when accessed
+```
+
+## 23.2 Future Secret Providers
+
+```text
+HashiCorp Vault
+Kubernetes Secrets
+AWS Secrets Manager
+GCP Secret Manager
+Azure Key Vault
+1Password Connect
+Doppler
+```
+
+---
+
+# 24. Sandbox and Execution Security
+
+## 24.1 MVP Sandbox
+
+Each code-executing agent run uses a Docker sandbox.
+
+Default sandbox behavior:
+
+```text
+one container per run
+resource limits
+timeout
+non-privileged
+no host Docker socket
+network disabled by default
+controlled environment variables
+workspace mounted explicitly
+logs captured and redacted
+artifacts extracted safely
+```
+
+## 24.2 Network Access
+
+Network access is disabled by default.
+
+It may be enabled per workflow, stage, or agent after policy evaluation.
+
+## 24.3 Runner Images
+
+Use a shared default runner image:
+
+```text
+agenthub/runner:latest
+```
+
+Allow per-agent override:
+
+```yaml
+sandbox:
+  image: custom/image:tag
+```
+
+---
+
+# 25. Memory and Vector Indexing
+
+## 25.1 Vector Database
+
+AgentHub includes vector memory from day one using:
+
+```text
+PostgreSQL + pgvector
+```
+
+## 25.2 Memory Philosophy
+
+Memory is explicit, scoped, inspectable, and permission-controlled.
+
+AgentHub must not silently index everything.
+
+## 25.3 Indexing Policy
+
+Indexing is explicit.
+
+Users or workflows choose what to index.
+
+Supported memory scopes:
+
+```text
+workspace
+project
+team
+repository
+connector
+workflow
+run
+artifact
+```
+
+## 25.4 First Memory Sources
+
+Memory may store:
+
+```text
+workflow artifacts
+run summaries
+repository knowledge
+issue and PR context
+documentation snippets
+connector/resource knowledge
+human-approved notes
+```
+
+## 25.5 Memory Requirements
+
+Memory items should include:
+
+```text
+source reference
+scope
+created_at
+updated_at
+freshness metadata
+permissions
+embedding model
+content hash
+```
+
+---
+
+# 26. Artifact Storage
+
+AgentHub uses MinIO from day one.
+
+Artifacts include:
+
+```text
+markdown
+json
+yaml
+text
+patch
+diff
+log
+test_report
+html
+image
+screenshot
+pull_request_reference
+external_link
+decision_record
+model_trace
+```
+
+Artifacts must be:
+
+```text
+versioned where needed
+previewable in UI
+downloadable
+linked to runs and stages
+available in approvals
+referenced by later stages
+immutable once finalized
+```
+
+---
+
+# 27. Approval System
+
+## 27.1 Approval Types
+
+```text
+stage_approval
+action_approval
+policy_approval
+spec_approval
+merge_approval
+secret_access_approval
+cost_approval
+memory_indexing_approval
+```
+
+## 27.2 Git Workflow Defaults
+
+Spec approval is required by default.
+
+Merge approval is required if AgentHub is configured to merge.
+
+## 27.3 Merge Behavior
+
+Merge behavior is configurable per project, repository, or workflow.
+
+Default:
+
+```yaml
+merge:
+  mode: mark_ready_only
+  allow_agenthub_merge: false
+```
+
+Optional controlled merge:
+
+```yaml
+merge:
+  mode: merge_after_approval
+  allow_agenthub_merge: true
+  require_human_approval: true
+  require_ci_success: true
+  require_no_unresolved_threads: true
+  strategy: squash
+```
+
+Agents must never merge directly.
+
+Merge is a platform connector action gated by policy and approval.
+
+---
+
+# 28. Logging, Prompts, and Traces
+
+## 28.1 Default Storage
+
+AgentHub stores:
+
+```text
+redacted prompts
+model outputs
+tool calls
+runtime logs
+artifacts
+policy decisions
+approval decisions
+connector actions
+cost metadata
+```
+
+AgentHub does not store hidden model reasoning or private chain-of-thought.
+
+## 28.2 Configurable Trace Storage
+
+Future versions may allow per-workspace or per-workflow trace settings:
+
+```yaml
+trace_storage:
+  store_full_prompts: false
+  store_redacted_prompts: true
+  store_model_outputs: true
+  store_tool_calls: true
+  store_hidden_reasoning: false
+```
+
+---
+
+# 29. External Comments and Commands
+
+External comments may trigger commands if authorized.
+
+For the Gitea workflow, supported commands should include:
+
+```text
+@agenthub status
+@agenthub generate spec
+@agenthub approve spec
+@agenthub start implementation
+@agenthub revise
+@agenthub retry
+@agenthub cancel
+@agenthub merge
+```
+
+Before accepting a command:
+
+```text
+actor must be authorized
+workflow must allow external commands
+command must be valid for current state
+policy must allow the action
+approval may be required
+```
+
+External issue/PR content is always treated as untrusted context.
+
+---
+
+# 30. User Interface Requirements
+
+## 30.1 Main Navigation
+
+```text
+Dashboard
+Workspaces
+Projects
+Teams
+Workflows
+Runs
+Agents
+Agent Teams
+Models
+Connectors
+Triggers
+Monitors
+Tools
+Memory
+Approvals
+Artifacts
+Policies
+Secrets
+Audit Log
+Settings
+```
+
+## 30.2 Dashboard
+
+Show:
+
+```text
+active workflow runs
+waiting approvals
+failed runs
+recently completed runs
+agent runs by status
+connector health
+model usage
+token/cost estimates
+sandbox activity
+recent audit events
+```
+
+## 30.3 Run Detail Page
+
+Show:
+
+```text
+workflow version
+trigger source
+input payload
+current stage
+stage timeline
+agent runs
+logs
+artifacts
+approvals
+policy decisions
+events
+errors
+cost estimate
+```
+
+Actions:
+
+```text
+cancel
+retry failed stage
+approve
+reject
+request changes
+download artifacts
+copy run link
+```
+
+## 30.4 Workflow Detail Page
+
+Tabs:
+
+```text
+Overview
+YAML Definition
+Graph Preview
+Runs
+Triggers
+Monitors
+Policies
+Versions
+Settings
+```
+
+## 30.5 Agent Team Page
+
+Support:
+
+```text
+team type
+manager agent
+member agents
+model assignments
+runtime adapter
+tool grants
+recent runs
+test run
+```
+
+## 30.6 Memory Page
+
+Support:
+
+```text
+collections
+scopes
+indexed sources
+search
+delete memory item
+inspect source
+re-index
+permissions
+```
+
+---
+
+# 31. Data Model
+
+## 31.1 Workspaces
+
+```sql
+workspaces (
+  id uuid primary key,
+  name text not null,
+  slug text unique not null,
+  created_at timestamptz not null,
+  updated_at timestamptz not null
+)
+```
+
+## 31.2 Users
+
+```sql
+users (
+  id uuid primary key,
+  workspace_id uuid references workspaces(id),
+  email text not null,
+  name text,
+  external_subject text,
+  role text not null,
+  created_at timestamptz not null,
+  updated_at timestamptz not null,
+  unique(workspace_id, email)
+)
+```
+
+## 31.3 Projects
+
+```sql
+projects (
+  id uuid primary key,
+  workspace_id uuid references workspaces(id),
+  name text not null,
+  slug text not null,
+  description text,
+  created_at timestamptz not null,
+  updated_at timestamptz not null,
+  unique(workspace_id, slug)
+)
+```
+
+## 31.4 Teams
+
+```sql
+teams (
+  id uuid primary key,
+  workspace_id uuid references workspaces(id),
+  name text not null,
+  slug text not null,
+  created_at timestamptz not null,
+  updated_at timestamptz not null,
+  unique(workspace_id, slug)
+)
+```
+
+## 31.5 Team Memberships
+
+```sql
+team_memberships (
+  id uuid primary key,
+  team_id uuid references teams(id),
+  user_id uuid references users(id),
+  role text not null,
+  created_at timestamptz not null
+)
+```
+
+## 31.6 Project Memberships
+
+```sql
+project_memberships (
+  id uuid primary key,
+  project_id uuid references projects(id),
+  user_id uuid references users(id),
+  team_id uuid references teams(id),
+  role text not null,
+  created_at timestamptz not null,
+  check (
+    user_id is not null or team_id is not null
+  )
+)
+```
+
+## 31.7 Connectors
+
+```sql
+connectors (
+  id uuid primary key,
+  workspace_id uuid references workspaces(id),
+  project_id uuid references projects(id),
+  name text not null,
+  type text not null,
+  enabled boolean not null default true,
+  config jsonb not null,
+  secret_refs jsonb not null default '[]',
+  health_status text not null default 'unknown',
+  created_at timestamptz not null,
+  updated_at timestamptz not null
+)
+```
+
+## 31.8 Workflows
+
+```sql
+workflows (
+  id uuid primary key,
+  workspace_id uuid references workspaces(id),
+  project_id uuid references projects(id),
+  name text not null,
+  slug text not null,
+  enabled boolean not null default false,
+  current_version integer not null default 1,
+  description text,
+  created_by uuid references users(id),
+  created_at timestamptz not null,
+  updated_at timestamptz not null,
+  unique(project_id, slug)
+)
+```
+
+## 31.9 Workflow Versions
+
+```sql
+workflow_versions (
+  id uuid primary key,
+  workflow_id uuid references workflows(id),
+  version integer not null,
+  definition jsonb not null,
+  created_by uuid references users(id),
+  created_at timestamptz not null,
+  unique(workflow_id, version)
+)
+```
+
+## 31.10 Workflow Runs
+
+```sql
+workflow_runs (
+  id uuid primary key,
+  workspace_id uuid references workspaces(id),
+  project_id uuid references projects(id),
+  workflow_id uuid references workflows(id),
+  workflow_version_id uuid references workflow_versions(id),
+  status text not null,
+  trigger_event_id uuid,
+  input jsonb not null,
+  state jsonb not null default '{}',
+  definition_snapshot jsonb not null,
+  current_stage text,
+  correlation_id text not null,
+  started_by uuid references users(id),
+  started_at timestamptz,
+  completed_at timestamptz,
+  created_at timestamptz not null,
+  updated_at timestamptz not null
+)
+```
+
+## 31.11 Stage Runs
+
+```sql
+stage_runs (
+  id uuid primary key,
+  workflow_run_id uuid references workflow_runs(id),
+  stage_id text not null,
+  stage_type text not null,
+  status text not null,
+  input jsonb not null default '{}',
+  output jsonb,
+  error jsonb,
+  attempts integer not null default 0,
+  started_at timestamptz,
+  completed_at timestamptz,
+  created_at timestamptz not null,
+  updated_at timestamptz not null
+)
+```
+
+## 31.12 Agents
+
+```sql
+agents (
+  id uuid primary key,
+  workspace_id uuid references workspaces(id),
+  project_id uuid references projects(id),
+  name text not null,
+  slug text not null,
+  type text not null,
+  runtime text not null,
+  enabled boolean not null default true,
+  definition jsonb not null,
+  created_by uuid references users(id),
+  created_at timestamptz not null,
+  updated_at timestamptz not null,
+  unique(project_id, slug)
+)
+```
+
+## 31.13 Agent Teams
+
+```sql
+agent_teams (
+  id uuid primary key,
+  workspace_id uuid references workspaces(id),
+  project_id uuid references projects(id),
+  name text not null,
+  slug text not null,
+  type text not null,
+  runtime text,
+  enabled boolean not null default true,
+  definition jsonb not null,
+  created_by uuid references users(id),
+  created_at timestamptz not null,
+  updated_at timestamptz not null,
+  unique(project_id, slug)
+)
+```
+
+## 31.14 Agent Runs
+
+```sql
+agent_runs (
+  id uuid primary key,
+  workflow_run_id uuid references workflow_runs(id),
+  stage_run_id uuid references stage_runs(id),
+  agent_id uuid references agents(id),
+  agent_team_id uuid references agent_teams(id),
+  runtime text not null,
+  status text not null,
+  input jsonb not null,
+  output jsonb,
+  error jsonb,
+  cost jsonb,
+  started_at timestamptz,
+  completed_at timestamptz,
+  created_at timestamptz not null,
+  updated_at timestamptz not null
+)
+```
+
+## 31.15 Models
+
+```sql
+models (
+  id uuid primary key,
+  workspace_id uuid references workspaces(id),
+  name text not null,
+  provider text not null,
+  model_name text not null,
+  enabled boolean not null default true,
+  config jsonb not null,
+  limits jsonb not null default '{}',
+  capabilities jsonb not null default '[]',
+  created_at timestamptz not null,
+  updated_at timestamptz not null
+)
+```
+
+## 31.16 Tools
+
+```sql
+tools (
+  id uuid primary key,
+  workspace_id uuid references workspaces(id),
+  name text not null,
+  type text not null,
+  enabled boolean not null default true,
+  definition jsonb not null,
+  risk_level text not null default 'medium',
+  created_at timestamptz not null,
+  updated_at timestamptz not null
+)
+```
+
+## 31.17 Policies
+
+```sql
+policies (
+  id uuid primary key,
+  workspace_id uuid references workspaces(id),
+  project_id uuid references projects(id),
+  name text not null,
+  enabled boolean not null default true,
+  scope text not null,
+  definition jsonb not null,
+  created_by uuid references users(id),
+  created_at timestamptz not null,
+  updated_at timestamptz not null
+)
+```
+
+## 31.18 Approvals
+
+```sql
+approvals (
+  id uuid primary key,
+  workflow_run_id uuid references workflow_runs(id),
+  stage_run_id uuid references stage_runs(id),
+  type text not null,
+  status text not null,
+  title text not null,
+  description text,
+  requested_by uuid references users(id),
+  resolved_by uuid references users(id),
+  required_roles jsonb not null default '[]',
+  context jsonb not null default '{}',
+  resolved_comment text,
+  expires_at timestamptz,
+  created_at timestamptz not null,
+  resolved_at timestamptz
+)
+```
+
+## 31.19 Artifacts
+
+```sql
+artifacts (
+  id uuid primary key,
+  workspace_id uuid references workspaces(id),
+  project_id uuid references projects(id),
+  workflow_run_id uuid references workflow_runs(id),
+  stage_run_id uuid references stage_runs(id),
+  agent_run_id uuid references agent_runs(id),
+  type text not null,
+  name text not null,
+  uri text not null,
+  content_type text,
+  metadata jsonb not null default '{}',
+  hash text,
+  created_at timestamptz not null
+)
+```
+
+## 31.20 Memory Collections
+
+```sql
+memory_collections (
+  id uuid primary key,
+  workspace_id uuid references workspaces(id),
+  project_id uuid references projects(id),
+  name text not null,
+  scope text not null,
+  config jsonb not null default '{}',
+  created_at timestamptz not null,
+  updated_at timestamptz not null
+)
+```
+
+## 31.21 Memory Items
+
+```sql
+memory_items (
+  id uuid primary key,
+  collection_id uuid references memory_collections(id),
+  source_type text not null,
+  source_id text,
+  content text not null,
+  content_hash text not null,
+  metadata jsonb not null default '{}',
+  embedding vector,
+  created_at timestamptz not null,
+  updated_at timestamptz not null
+)
+```
+
+## 31.22 Events
+
+```sql
+events (
+  id uuid primary key,
+  workspace_id uuid references workspaces(id),
+  project_id uuid references projects(id),
+  type text not null,
+  source text not null,
+  connector_id uuid references connectors(id),
+  workflow_run_id uuid references workflow_runs(id),
+  correlation_id text,
+  external_id text,
+  actor jsonb,
+  resource jsonb,
+  payload jsonb not null,
+  created_at timestamptz not null
+)
+```
+
+## 31.23 Audit Logs
+
+```sql
+audit_logs (
+  id uuid primary key,
+  workspace_id uuid references workspaces(id),
+  project_id uuid references projects(id),
+  actor_type text not null,
+  actor_id text,
+  action text not null,
+  target_type text,
+  target_id text,
+  result text not null,
+  policy_decision jsonb,
+  metadata jsonb not null default '{}',
+  correlation_id text,
+  created_at timestamptz not null
+)
+```
+
+## 31.24 Secrets
+
+```sql
+secrets (
+  id uuid primary key,
+  workspace_id uuid references workspaces(id),
+  project_id uuid references projects(id),
+  name text not null,
+  scope text not null,
+  provider text not null,
+  reference text not null,
+  encrypted_value bytea,
+  metadata jsonb not null default '{}',
+  created_by uuid references users(id),
+  created_at timestamptz not null,
+  updated_at timestamptz not null
+)
+```
+
+---
+
+# 32. Backend API
+
+## 32.1 Workspaces, Projects, Teams
+
+```http
+GET /api/workspaces
+POST /api/workspaces
+GET /api/workspaces/{workspace_id}
+
+GET /api/projects
+POST /api/projects
+GET /api/projects/{project_id}
+PATCH /api/projects/{project_id}
+
+GET /api/teams
+POST /api/teams
+GET /api/teams/{team_id}
+PATCH /api/teams/{team_id}
+POST /api/teams/{team_id}/members
+DELETE /api/teams/{team_id}/members/{user_id}
+```
+
+## 32.2 Workflows
+
+```http
+GET /api/workflows
+POST /api/workflows
+GET /api/workflows/{workflow_id}
+PATCH /api/workflows/{workflow_id}
+DELETE /api/workflows/{workflow_id}
+POST /api/workflows/{workflow_id}/enable
+POST /api/workflows/{workflow_id}/disable
+POST /api/workflows/{workflow_id}/versions
+GET /api/workflows/{workflow_id}/versions
+POST /api/workflows/{workflow_id}/run
+POST /api/workflows/{workflow_id}/validate
+```
+
+## 32.3 Workflow Runs
+
+```http
+GET /api/runs
+GET /api/runs/{run_id}
+POST /api/runs/{run_id}/cancel
+POST /api/runs/{run_id}/pause
+POST /api/runs/{run_id}/resume
+POST /api/runs/{run_id}/retry
+POST /api/runs/{run_id}/retry-stage/{stage_run_id}
+GET /api/runs/{run_id}/events
+GET /api/runs/{run_id}/logs
+GET /api/runs/{run_id}/artifacts
+GET /api/runs/{run_id}/stream
+```
+
+## 32.4 Agents and Agent Teams
+
+```http
+GET /api/agents
+POST /api/agents
+GET /api/agents/{agent_id}
+PATCH /api/agents/{agent_id}
+DELETE /api/agents/{agent_id}
+POST /api/agents/{agent_id}/test
+GET /api/agents/{agent_id}/runs
+
+GET /api/agent-teams
+POST /api/agent-teams
+GET /api/agent-teams/{team_id}
+PATCH /api/agent-teams/{team_id}
+DELETE /api/agent-teams/{team_id}
+POST /api/agent-teams/{team_id}/test
+```
+
+## 32.5 Models
+
+```http
+GET /api/models
+POST /api/models
+GET /api/models/{model_id}
+PATCH /api/models/{model_id}
+DELETE /api/models/{model_id}
+POST /api/models/{model_id}/test
+```
+
+## 32.6 Connectors
+
+```http
+GET /api/connectors
+POST /api/connectors
+GET /api/connectors/{connector_id}
+PATCH /api/connectors/{connector_id}
+DELETE /api/connectors/{connector_id}
+POST /api/connectors/{connector_id}/test
+GET /api/connectors/{connector_id}/events
+GET /api/connectors/{connector_id}/resources
+```
+
+## 32.7 Triggers and Monitors
+
+```http
+GET /api/triggers
+POST /api/triggers
+GET /api/triggers/{trigger_id}
+PATCH /api/triggers/{trigger_id}
+DELETE /api/triggers/{trigger_id}
+POST /api/triggers/{trigger_id}/enable
+POST /api/triggers/{trigger_id}/disable
+
+GET /api/monitors
+POST /api/monitors
+GET /api/monitors/{monitor_id}
+PATCH /api/monitors/{monitor_id}
+DELETE /api/monitors/{monitor_id}
+POST /api/monitors/{monitor_id}/enable
+POST /api/monitors/{monitor_id}/disable
+POST /api/monitors/{monitor_id}/run-now
+```
+
+## 32.8 Approvals
+
+```http
+GET /api/approvals
+GET /api/approvals/{approval_id}
+POST /api/approvals/{approval_id}/approve
+POST /api/approvals/{approval_id}/reject
+POST /api/approvals/{approval_id}/request-changes
+```
+
+## 32.9 Artifacts and Memory
+
+```http
+GET /api/artifacts
+GET /api/artifacts/{artifact_id}
+GET /api/artifacts/{artifact_id}/download
+GET /api/artifacts/{artifact_id}/preview
+
+GET /api/memory/collections
+POST /api/memory/collections
+GET /api/memory/collections/{collection_id}
+POST /api/memory/collections/{collection_id}/index
+POST /api/memory/search
+DELETE /api/memory/items/{memory_item_id}
+```
+
+## 32.10 Webhooks
+
+```http
+POST /api/webhooks/{connector_type}/{connector_id}
+POST /api/webhooks/generic/{trigger_id}
+```
+
+## 32.11 Policies
+
+```http
+GET /api/policies
+POST /api/policies
+GET /api/policies/{policy_id}
+PATCH /api/policies/{policy_id}
+DELETE /api/policies/{policy_id}
+POST /api/policies/evaluate
+```
+
+---
+
+# 33. MVP Scope
+
+## 33.1 MVP Must Prove
+
+The MVP must prove:
+
+1. AgentHub can run general workflows.
+2. AgentHub can run workflows from external triggers.
+3. AgentHub can orchestrate multiple runtimes.
+4. AgentHub can support multi-user teams and projects.
+5. AgentHub can use explicit vector memory.
+6. AgentHub can complete the Gitea issue-to-PR workflow.
+7. AgentHub can run a generic non-Git webhook workflow.
+
+## 33.2 MVP Required Features
+
+### Platform
+
+```text
+Docker Compose deployment
+Authentik OIDC login
+workspace support
+team support
+project support
+role model
+dashboard
+workflow registry
+YAML workflow editor
+workflow validator
+run timeline
+live logs
+artifact viewer
+approval inbox
+event log
+audit log
+```
+
+### Connectors
+
+```text
+Gitea connector
+generic webhook connector
+HTTP connector
+artifact-store connector
+```
+
+### Triggers and Monitors
+
+```text
+manual trigger
+webhook trigger
+Gitea label trigger
+Gitea mention trigger
+basic polling monitor
+```
+
+### Runtimes
+
+```text
+LLM prompt adapter
+script adapter
+mini-SWE-agent adapter
+CrewAI adapter
+```
+
+### Models
+
+```text
+Kimi
+OpenAI
+OpenAI-compatible
+Anthropic
+Ollama
+```
+
+### Security
+
+```text
+internal encrypted secret store
+native YAML policy engine
+explicit tool grants
+Docker sandbox
+network disabled by default
+redacted traces
+approval gates
+controlled merge only when configured
+```
+
+### Storage
+
+```text
+PostgreSQL
+pgvector
+Redis
+MinIO
+```
+
+---
+
+# 34. MVP Exclusions
+
+Not required for MVP:
+
+```text
+visual workflow builder
+GitOps configuration
+GitLab connector completeness
+GitHub connector completeness
+Kubernetes runners
+Firecracker/gVisor
+full event sourcing
+full OPA/Rego
+custom RBAC DSL
+silent automatic memory indexing
+automatic merge by default
+agent-launched sub-workflows
+SaaS multi-tenancy
+```
+
+---
+
+# 35. Development Milestones
+
+## Milestone 1: Platform Skeleton
+
+Deliverables:
+
+```text
+monorepo with Turbo + pnpm
+Docker Compose
+Postgres
+Redis
+MinIO
+FastAPI app
+Celery worker
+Next.js app
+Authentik OIDC login
+workspace/project/team schema
+basic dashboard
+Apache-2.0 license
+```
+
+## Milestone 2: Core Workflow Engine
+
+Deliverables:
+
+```text
+workflow YAML schema
+workflow validation
+workflow versioning
+manual workflow run
+stage run records
+event append discipline
+Redis/Celery-backed execution
+run timeline UI
+terminal stage
+condition stage
+approval stage
+```
+
+## Milestone 3: Kimi Model Gateway and Simple Agents
+
+Deliverables:
+
+```text
+model registry
+Kimi provider
+model gateway interface
+LLM prompt runtime
+agent registry
+agent run logs
+artifact creation
+first vertical slice workflow
+```
+
+## Milestone 4: Artifact and Approval Flow
+
+Deliverables:
+
+```text
+MinIO artifact store
+artifact viewer
+approval inbox
+approval actions
+approval events
+approval audit logs
+manual workflow → Kimi prompt → artifact → approval complete
+```
+
+## Milestone 5: Generic Webhook Workflow
+
+Deliverables:
+
+```text
+connector registry
+generic webhook connector
+HTTP connector
+webhook summarizer workflow
+approval gate
+HTTP callback action
+audit logging for external writes
+```
+
+## Milestone 6: Memory Foundation
+
+Deliverables:
+
+```text
+pgvector setup
+memory collections
+explicit indexing
+memory search
+memory permission scope
+memory source references
+```
+
+## Milestone 7: Gitea Connector
+
+Deliverables:
+
+```text
+Gitea token auth
+repository registration
+issue loading
+comment loading
+label trigger
+mention trigger
+post comment
+branch creation support
+pull request creation
+CI/check status monitor where supported
+```
+
+## Milestone 8: Runtime Adapters
+
+Deliverables:
+
+```text
+script adapter
+Docker sandbox manager
+mini-SWE-agent adapter
+basic CrewAI adapter
+runtime logs
+runtime cancellation
+runtime artifacts
+```
+
+## Milestone 9: Gitea Issue-to-PR Workflow
+
+Deliverables:
+
+```text
+issue trigger
+triage agent
+spec generation team
+spec approval
+mini-SWE-agent implementation
+branch push
+draft pull request
+CI wait
+review stage
+revision loop
+controlled merge or mark-ready behavior
+```
+
+## Milestone 10: Policy and Security Hardening
+
+Deliverables:
+
+```text
+YAML policy engine
+tool grants
+protected actions
+protected file paths
+network controls
+secret scoping
+log redaction
+merge policy
+cost limits
+runtime limits
+audit coverage
+```
+
+## Milestone 11: Packaging and Documentation
+
+Deliverables:
+
+```text
+sample workflows
+sample agents
+sample policies
+setup docs
+Gitea demo project
+generic webhook demo
+development docs
+operator docs
+security notes
+model provider docs
+runtime adapter docs
+connector SDK docs
+```
+
+---
+
+# 36. Definition of Done for MVP
+
+The MVP is done when:
+
+1. AgentHub runs with Docker Compose.
+2. Authentik OIDC login works.
+3. Multiple users can exist.
+4. Users can belong to teams.
+5. Projects can be created and owned by users or teams.
+6. A workflow can be authored in YAML.
+7. A workflow run stores an immutable definition snapshot.
+8. A workflow can be manually triggered.
+9. A generic webhook can trigger a workflow.
+10. A Gitea issue label can trigger a workflow.
+11. A Gitea comment mention can trigger a workflow command.
+12. A workflow can pause for approval.
+13. A workflow can run a Kimi-backed LLM prompt agent.
+14. A workflow can run a CrewAI team.
+15. A workflow can run mini-SWE-agent in Docker.
+16. A workflow can store artifacts in MinIO.
+17. AgentHub can explicitly index selected data into pgvector.
+18. The UI shows run timeline, logs, artifacts, approvals, and events.
+19. AgentHub can generate a spec from a Gitea issue.
+20. A maintainer can approve the spec.
+21. AgentHub can run an implementation agent.
+22. AgentHub can push a branch.
+23. AgentHub can open a draft pull request.
+24. AgentHub can monitor CI/check status where supported.
+25. AgentHub can revise a PR based on authorized comments.
+26. AgentHub can mark a PR ready or merge it only if configured, approved, and CI passes.
+27. All external writes are audit logged.
+28. Secrets are encrypted and masked.
+29. Network access is disabled by default for agent sandboxes.
+30. Tools are explicitly granted to agents or teams.
+31. Hidden model reasoning is not stored.
+
+---
+
+# 37. Immediate Development Plan
+
+## 37.1 Step 1: Repository Foundation
+
+Create the monorepo:
+
+```text
+agenthub/
+  apps/web
+  apps/api
+  apps/worker
+  packages/shared
+  infra/docker-compose.yml
+```
+
+Add:
+
+```text
+Apache-2.0 license
+README.md
+CONTRIBUTING.md
+docs/development.md
+.env.example
+```
+
+## 37.2 Step 2: Docker Compose
+
+Add services:
+
+```text
+web
+api
+worker
+postgres
+redis
+minio
+```
+
+Optional development profile:
+
+```text
+authentik
+gitea
+ollama
+```
+
+## 37.3 Step 3: Backend Foundation
+
+Implement:
+
+```text
+FastAPI app
+SQLAlchemy setup
+Alembic setup
+health endpoint
+database session handling
+configuration loading
+structured logging
+```
+
+## 37.4 Step 4: Authentik OIDC
+
+Implement:
+
+```text
+OIDC login
+callback handling
+session/JWT handling
+user provisioning
+workspace bootstrap
+role assignment
+```
+
+## 37.5 Step 5: Workflow Foundation
+
+Implement:
+
+```text
+workflow schema
+workflow validation
+workflow versioning
+manual run creation
+workflow run snapshot
+stage run table
+event append function
+Celery stage execution
+```
+
+## 37.6 Step 6: Kimi Model Gateway
+
+Implement:
+
+```text
+model provider registry
+Kimi provider
+chat completion interface
+structured output helper
+token/cost metadata placeholder
+model invocation logs
+```
+
+## 37.7 Step 7: First Runtime
+
+Implement:
+
+```text
+llm_prompt runtime
+agent definition
+prompt rendering
+model gateway invocation
+normalized runtime result
+artifact creation
+```
+
+## 37.8 Step 8: First Vertical Slice
+
+Implement the workflow:
+
+```text
+manual trigger
+  ↓
+Kimi prompt agent
+  ↓
+markdown artifact in MinIO
+  ↓
+approval gate
+  ↓
+completion
+```
+
+This is the first meaningful product checkpoint.
+
+---
+
+# 38. Final Baseline Decisions
+
+```text
+1. General-purpose agent workflow platform.
+2. Built first for small engineering teams.
+3. Docker Compose first.
+4. Custom lightweight workflow engine, designed to be swappable.
+5. YAML-first workflows.
+6. Database-first configuration, GitOps later.
+7. Immutable workflow run snapshots.
+8. CrewAI as runtime adapter, not platform core.
+9. MVP runtimes: prompt, script, mini-SWE-agent, CrewAI.
+10. Agents can recommend sub-workflows now; policy-approved sub-workflows later.
+11. Native AgentHub hierarchy abstraction.
+12. Models: Kimi first, then OpenAI, OpenAI-compatible, Anthropic, Ollama.
+13. Global model registry with workflow/agent/stage overrides.
+14. Model calls route through AgentHub where possible.
+15. Internal encrypted secret store first.
+16. Native YAML policy engine first.
+17. Docker per run first.
+18. Network disabled by default.
+19. Explicit per-agent/team tool grants.
+20. Gitea first, GitLab/GitHub/Forgejo later.
+21. API token plus SSH/HTTPS Git hybrid auth.
+22. Spec approval required by default.
+23. Specs stored as artifacts and optionally committed to PR branch.
+24. Merge configurable with approval and passing CI.
+25. Authorized external comments can trigger commands.
+26. Redacted prompts/traces; no hidden reasoning.
+27. Vector DB from day one with explicit scoped indexing.
+28. MinIO from day one.
+29. Postgres-backed state machine plus append-only events; Redis only for queueing.
+30. Apache-2.0 permissive open-source direction.
+31. Monorepo uses Turbo + pnpm.
+32. Backend uses FastAPI + SQLAlchemy + Alembic.
+33. Worker uses Celery + Redis.
+34. Authentication uses Authentik OIDC first.
+35. First vertical slice is manual workflow → Kimi prompt → artifact → approval.
+```
 
 ---