AgentHub/agent_hub_spec.md

# AgentHub Specification v0.3

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, general-purpose agent workflow and orchestration platform for small engineering teams.

It provides a control plane for defining, managing, running, observing, and governing AI agents across external systems and workflows.

AgentHub is not a single coding agent, Git bot, CrewAI wrapper, or model frontend. It is a platform layer that coordinates:

```text
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
  ↓
label or comment trigger
  ↓
workflow starts
  ↓
spec generation
  ↓
human spec approval
  ↓
implementation agent
  ↓
branch pushed
  ↓
draft pull request opened
  ↓
CI monitored
  ↓
review/revision loop
  ↓
human-approved merge or merge-ready state
```

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 Identity

AgentHub is a:

```text
general-purpose self-hosted agent workflow platform
```

Its first strong use case is developer automation, but the core architecture must not be Git-specific.

## 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. Product Principles

## 3.1 Platform Orchestration vs Agent Orchestration

AgentHub owns deterministic platform orchestration.

Agent runtimes own task execution.

### AgentHub owns

```text
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
```

### Agent runtimes own

```text
reasoning loops
tool use within granted permissions
multi-agent collaboration
code editing
reviewing
summarizing
planning
runtime-specific execution
```

## 3.2 Runtime-Agnostic Architecture

AgentHub must support multiple runtime adapters.

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.

---

# 4. Goals

## 4.1 Product Goals

AgentHub should allow users to:

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:

* 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 for MVP

The MVP should not attempt to:

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. Implementation Stack

## 6.1 Final Implementation Decisions

```text
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/
  apps/
    web/
    api/
    worker/

  packages/
    shared/
    workflow-schema/
    ui/
    client-sdk/

  python/
    agenthub_core/
      workflow/
      policy/
      connectors/
      runtimes/
      models/
      artifacts/
      memory/
      sandbox/
      events/
      auth/

  connectors/
    gitea/
    generic_webhook/
    http/
    future_gitlab/
    future_github/

  runtimes/
    llm_prompt/
    script/
    mini_swe_agent/
    crewai/

  workflows/
    examples/
      manual-prompt-artifact-approval.yaml
      generic-webhook-summarizer.yaml
      gitea-issue-to-pr.yaml

  agents/
    examples/
      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/

  docs/
    architecture.md
    development.md
    security.md
    workflow-format.md
    connector-sdk.md
    runtime-sdk.md
    model-gateway.md
    gitea-reference-workflow.md
```

---

# 7. Deployment Model

## 7.1 MVP Docker Compose Deployment

AgentHub must run locally and on a small server with Docker Compose.

Required services:

```text
agenthub-web
agenthub-api
agenthub-worker
postgres
redis
minio
```

Recommended optional local services:

```text
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
  ↓
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
condition
wait_for_condition
notification
terminal
```

Future stage types:

```text
parallel
subworkflow
human_input
wait_for_event
manual_task
deployment
```

## 11.6 Agents Starting Sub-Workflows

In the MVP, agents cannot directly start sub-workflows.

Agents may recommend a workflow action:

```yaml
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: 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

stages:
  - id: summarize
    type: agent
    agent: summarizer-agent
    input:
      payload: "{{ event.payload }}"
    outputs:
      summary: result

  - id: approve
    type: approval
    title: "Approve summary before callback"
    required_roles:
      - maintainer
    input:
      summary: "{{ summary }}"

  - id: post_result
    type: connector_action
    connector: http
    action: http.post
    input:
      url: "{{ event.payload.callback_url }}"
      body:
        summary: "{{ summary.outputs.text }}"

  - id: complete
    type: terminal
    status: success
```

---

# 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: gitea-issue-to-pr
name: Gitea Issue to Pull Request
version: 1
enabled: true

triggers:
  - id: issue-agent-ready
    type: connector_event
    connector: gitea-main
    event: gitea.issue.labeled
    filter:
      all:
        - path: "$.label.name"
          equals: "agent-ready"
        - 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: gitea-main
    action: gitea.load_issue_context
    input:
      repository: "{{ event.payload.repository.full_name }}"
      issue_number: "{{ event.payload.issue.number }}"
    outputs:
      issue_context: result

  - id: triage
    type: agent
    agent: gitea-triage-agent
    input:
      issue_context: "{{ issue_context }}"
    outputs:
      triage: result

  - id: maybe_stop
    type: condition
    expression: "{{ triage.outputs.suitable == true }}"
    on_true: generate_spec
    on_false: comment_not_suitable

  - id: comment_not_suitable
    type: connector_action
    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.outputs.reason }}"
    next: complete_not_suitable

  - id: complete_not_suitable
    type: terminal
    status: success

  - id: generate_spec
    type: agent_team
    team: gitea-spec-team
    input:
      issue_context: "{{ issue_context }}"
      triage: "{{ triage }}"
    outputs:
      spec_bundle: result

  - id: approve_spec
    type: approval
    title: "Approve generated spec"
    required_roles:
      - maintainer
    input:
      spec_bundle: "{{ spec_bundle }}"

  - id: implement
    type: agent
    agent: mini-swe-implementation-agent
    input:
      issue_context: "{{ issue_context }}"
      spec_bundle: "{{ spec_bundle }}"
    outputs:
      implementation: result

  - id: open_pr
    type: connector_action
    connector: gitea-main
    action: gitea.open_draft_pr
    input:
      repository: "{{ issue_context.repository }}"
      issue_number: "{{ issue_context.number }}"
      implementation: "{{ implementation }}"
    outputs:
      pull_request: result

  - id: wait_for_ci
    type: wait_for_condition
    connector: gitea-main
    condition: gitea.pr_checks_completed
    timeout_minutes: 60
    input:
      repository: "{{ issue_context.repository }}"
      pull_request_number: "{{ pull_request.number }}"
    outputs:
      ci_result: result

  - id: review_pr
    type: agent_team
    team: pr-review-team
    input:
      pull_request: "{{ pull_request }}"
      spec_bundle: "{{ spec_bundle }}"
      ci_result: "{{ ci_result }}"
    outputs:
      review: result

  - id: human_review
    type: approval
    title: "Approve PR readiness"
    required_roles:
      - maintainer
    input:
      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

Default:

```yaml
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
```

---

# 18. Agent System

## 18.1 Agent Definition

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.

---

# 19. Runtime Adapter System

## 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.
```

---