alex/AgentHub

Fork 0

Files

T

alex 723f74e150 Add git_agent_hub_spec.md

2026-05-29 15:22:52 +02:00

47 KiB

Raw Blame History

Spec Definition: Self-Hosted Repository Agent Orchestration Platform

1. Working Name

RepoPilot

Alternative names:

SpecPilot
ForgeAgent
IssueForge
RepoOps Agent
SDD Agent Hub

This specification will use RepoPilot as the placeholder name.

2. Product Summary

RepoPilot is a self-hosted web platform for managing AI coding agents across multiple Git repositories. It allows users to connect repositories, monitor issues and pull requests, assign agents to work items, generate and maintain structured specifications, run autonomous implementation loops, open pull requests, process review comments, and coordinate approval-controlled merges.

The platform is designed for teams that want a configurable, auditable, self-hosted alternative to SaaS coding agents.

RepoPilot does not replace human review. It provides a managed execution layer around coding agents, with visibility, control, repeatability, policy enforcement, and repository-specific configuration.

3. Core Problem

Modern coding agents can inspect repositories, modify files, run tests, and open pull requests. However, most available systems are either:

SaaS-first,
difficult to customize,
hard to monitor,
not designed around issue conversations,
not spec-driven,
lacking strong orchestration controls,
not suitable for self-hosted or regulated environments.

RepoPilot solves this by providing a self-hosted control plane for coding agents.

4. Goals

4.1 Product Goals

RepoPilot should allow a user to:

Add and manage Git repositories.
Monitor issues, pull requests, labels, comments, and CI status.
Configure repository-specific agent behavior.
Assign agents to issues manually or automatically.
Let users talk to agents through issue comments, PR comments, or the RepoPilot UI.
Generate structured specs from issue descriptions and conversations.
Execute implementation tasks using configurable coding agents.
Open draft pull requests.
Process review comments and update pull requests.
Track all agent actions in a web interface.
Manage multiple agents, models, tools, sandboxes, and orchestration policies.
Enforce approval gates before merging.
Provide full audit logs for all agent activity.
Run entirely self-hosted.

4.2 Engineering Goals

The system should be:

Modular.
Agent-framework agnostic.
Git provider agnostic where feasible.
Model-provider agnostic.
Secure by default.
Observable.
Horizontally scalable.
Suitable for local, single-server, and Kubernetes deployment.
Extensible through plugins and webhooks.

5. Non-Goals

Initial versions should not attempt to:

Replace human code review.
Guarantee correct code generation.
Automatically merge code without explicit policy permission.
Support every Git provider from day one.
Build a custom LLM or fine-tuning system.
Provide a full project-management replacement.
Implement every possible agent framework.
Support untrusted public repositories without sandbox hardening.

6. Primary Users

6.1 Admin

Responsible for system configuration, user management, global model settings, security policies, and integrations.

6.2 Repository Owner

Adds repositories, configures repo-specific automation rules, reviews agent behavior, approves merges, and manages repository-level policies.

6.3 Developer / Reviewer

Interacts with the agent through the UI, Git provider comments, issue threads, and PR reviews. Reviews generated specs and code.

6.4 Agent Operator

Monitors agent runs, diagnoses failures, tunes prompts, adjusts orchestration rules, and reviews execution traces.

7. Key Concepts

7.1 Managed Repository

A Git repository registered in RepoPilot. It has provider credentials, webhook configuration, agent policies, workflow settings, and repository-specific instructions.

7.2 Work Item

A unit of work that an agent may process.

Examples:

GitHub issue
GitLab issue
Gitea issue
Linear ticket, future
Manual task created in RepoPilot

7.3 Agent

A configured autonomous or semi-autonomous worker that can read context, reason about tasks, run tools, edit code, execute commands, and propose changes.

Examples:

mini-SWE-agent based coding agent
OpenHands runner
Custom spec generator
PR review agent
Test-fixing agent
Documentation agent

7.4 Agent Run

A single execution instance of an agent against a work item, pull request, repository, or manually supplied task.

7.5 Orchestration

The process that coordinates phases, agents, state transitions, policies, retries, approvals, and external events.

7.6 Spec-Driven Development Document Set

For each issue, RepoPilot may create and maintain a structured spec document set.

Recommended layout:

.specs/
  issue-123/
    metadata.yaml
    conversation.md
    spec.md
    plan.md
    tasks.md
    acceptance.md
    decisions.md
    test-plan.md
    implementation-log.md

7.7 Policy

A rule that controls what agents are allowed to do.

Examples:

Which repositories can be modified.
Which files can be edited.
Whether network access is allowed.
Whether PRs can be opened automatically.
Whether merging is allowed.
Whether human approval is required after spec generation.
Which model may be used for a repository.

8. High-Level Workflow

8.1 Standard Issue-to-PR Workflow

Issue created or labeled
  ↓
RepoPilot receives webhook
  ↓
Issue is classified
  ↓
Policy decides whether agent may engage
  ↓
Spec agent summarizes issue and conversation
  ↓
Spec documents are created or updated
  ↓
Optional human approval gate
  ↓
Implementation agent starts
  ↓
Agent clones repo in sandbox
  ↓
Agent creates branch
  ↓
Agent edits code
  ↓
Agent runs tests/checks
  ↓
Agent commits changes
  ↓
Agent opens draft PR
  ↓
CI runs
  ↓
PR review agent may review PR
  ↓
Human comments or requests changes
  ↓
Agent processes feedback
  ↓
Agent updates PR
  ↓
Human approves
  ↓
Merge occurs manually or through policy-controlled merge

9. System Architecture

9.1 Major Components

Web UI
  ↓
Backend API
  ↓
Orchestration Engine
  ↓
Job Queue
  ↓
Agent Runner Workers
  ↓
Sandbox Runtime
  ↓
Git Provider Integrations
  ↓
Database / Object Storage / Logs

9.2 Recommended Services

Web Frontend

Responsibilities:

Repository dashboard
Issue and PR monitoring
Agent run timeline
Live logs
Spec viewer/editor
Agent configuration
Orchestration workflow builder
Approval screens
Audit logs
User and access management

Recommended technology:

Next.js
React
TypeScript
Tailwind
shadcn/ui
TanStack Query
Monaco editor for specs/logs/configs

Backend API

Responsibilities:

Auth
User management
Repository management
Agent management
Work item management
Run management
Webhook ingestion
Integration APIs
Policy enforcement
Audit logging

Recommended technology:

FastAPI, NestJS, Django, or Go
REST API initially
WebSocket or Server-Sent Events for live updates

Orchestration Engine

Responsibilities:

Owns workflow state machines
Decides next phase
Applies policy gates
Schedules jobs
Handles retries
Handles cancellation
Handles feedback loops
Coordinates multiple agents

Recommended approach:

Start with a custom state machine.
Later support Temporal, Hatchet, Windmill, Prefect, or LangGraph-style orchestration.

Job Queue

Responsibilities:

Run async jobs
Dispatch agent jobs
Retry failed jobs
Rate-limit by repository, model, or runner
Track job status

Recommended options:

Redis + BullMQ
Celery + Redis
RabbitMQ
Temporal
Postgres-backed queue for MVP

Agent Runner

Responsibilities:

Execute agent task
Prepare workspace
Clone repository
Inject context
Invoke agent framework
Stream logs
Collect patches
Commit changes
Return result to orchestrator

Initial supported runner:

mini-SWE-agent runner

Future supported runners:

OpenHands
Claude Code wrapper
Aider
OpenAI Codex CLI
Custom shell-based agent
PR-Agent

Sandbox Runtime

Responsibilities:

Isolate code execution
Limit file system access
Limit network access
Enforce timeout
Enforce memory and CPU limits
Store artifacts
Prevent credential exfiltration

Recommended MVP:

Docker containers per run

Recommended production:

Firecracker microVMs
Kubernetes isolated jobs
gVisor
rootless Docker
network egress policies

Database

Responsibilities:

Store users, repos, issues, PRs, specs, runs, logs, policies, approvals, and events.

Recommended:

PostgreSQL

Object Storage

Responsibilities:

Store large logs
Agent traces
workspace snapshots
generated patches
artifacts
test reports

Recommended:

S3-compatible storage
MinIO for self-hosted

10. Deployment Model

10.1 MVP Deployment

Single Docker Compose stack:

repo-pilot-web
repo-pilot-api
repo-pilot-worker
postgres
redis
minio

10.2 Production Deployment

Kubernetes:

frontend deployment
api deployment
worker deployment
runner job pods
postgres managed or self-hosted
redis
object storage
ingress
secret manager
observability stack

10.3 Air-Gapped Mode

RepoPilot should eventually support restricted environments:

No outbound model APIs unless configured.
Local model endpoint support.
Mirrored dependencies.
Internal Git provider.
Offline documentation cache.
Strict network egress control.

11. Repository Management

11.1 Add Repository

The user should be able to add a repository through the UI.

Required fields:

provider: github | gitlab | gitea | bitbucket | generic-git
name: string
clone_url: string
default_branch: string
auth_method: app | oauth | token | ssh_key
visibility: private | internal | public
enabled: boolean

11.2 Repository Settings

Each managed repository should support:

automation:
  enabled: true
  trigger_mode: manual | label | mention | auto
  trigger_labels:
    - agent-ready
    - fix-me
  trigger_mentions:
    - "@repopilot"
  allowed_issue_states:
    - open

branching:
  branch_prefix: agent/
  branch_name_template: "agent/issue-{issue_number}-{slug}"

pull_requests:
  create_as_draft: true
  assign_author: true
  request_reviewers: []
  add_labels:
    - agent-generated

specs:
  enabled: true
  require_spec_before_implementation: true
  require_human_approval_after_spec: false
  spec_directory: ".specs"
  commit_specs_to_branch: true

execution:
  default_agent: mini-swe-agent
  max_runtime_minutes: 60
  max_retries: 2
  allow_network: false
  allow_dependency_install: true
  test_command: "auto"
  lint_command: "auto"

merge:
  allow_agent_merge: false
  require_human_approval: true
  require_ci_success: true
  squash_merge: true

security:
  protected_paths:
    - ".github/workflows"
    - "infra/"
    - "secrets/"
  allowed_paths: []
  blocked_paths:
    - ".env"
    - "**/*.pem"
    - "**/*.key"

12. Work Item Lifecycle

12.1 Work Item States

discovered
triaged
awaiting_spec
spec_in_progress
spec_ready
awaiting_spec_approval
implementation_queued
implementation_in_progress
pr_opened
awaiting_ci
awaiting_review
changes_requested
revision_queued
revision_in_progress
ready_to_merge
merged
closed
failed
cancelled

12.2 Work Item Events

Events that may affect state:

issue.opened
issue.edited
issue.labeled
issue.unlabeled
issue.commented
issue.assigned
issue.closed
pull_request.opened
pull_request.synchronize
pull_request.review_submitted
pull_request.commented
pull_request.closed
pull_request.merged
check_suite.completed
agent.run_started
agent.run_completed
agent.run_failed
approval.granted
approval.rejected
policy.blocked

13. Agent Types

13.1 Spec Agent

Purpose:

Read issue, comments, linked docs, code context, and repository instructions.
Produce structured SDD documents.
Identify ambiguity.
Create acceptance criteria.
Create implementation plan.
Create task list.
Create test plan.

Inputs:

repository
issue
comments
labels
linked_pull_requests
repository_instructions
existing_specs
relevant_files

Outputs:

spec.md
plan.md
tasks.md
acceptance.md
test-plan.md
decisions.md

13.2 Implementation Agent

Purpose:

Implement tasks from the approved or generated spec.
Modify code.
Run tests.
Commit changes.
Open or update PR.

Initial implementation:

mini-SWE-agent adapter

13.3 Review Agent

Purpose:

Review generated PR.
Identify bugs, missing tests, risky changes, and spec mismatches.
Comment on PR or create internal review report.

Possible implementation:

PR-Agent
custom LLM review agent

13.4 Test Agent

Purpose:

Focus only on failing tests, missing tests, flaky tests, or test coverage.

13.5 Documentation Agent

Purpose:

Update docs, changelogs, README files, migration notes, and examples.

13.6 Triage Agent

Purpose:

Classify issues.
Detect duplicates.
Estimate complexity.
Recommend whether an agent should work on the issue.

14. Agent Configuration

14.1 Agent Definition

id: mini-swe-default
name: Mini SWE Default
type: implementation
runner: mini-swe-agent
enabled: true

model:
  provider: openai | anthropic | local | openrouter | ollama | vllm | custom
  model_name: string
  temperature: 0.2
  max_tokens: 8192

execution:
  timeout_minutes: 60
  max_iterations: 100
  max_cost_usd: 5.00
  allow_network: false
  allow_shell: true
  allow_git_push: true

sandbox:
  image: "repopilot/runner-python-node:latest"
  cpu_limit: "4"
  memory_limit: "8Gi"
  disk_limit: "20Gi"

permissions:
  can_read_issues: true
  can_comment_issues: true
  can_create_branches: true
  can_push_commits: true
  can_open_prs: true
  can_merge_prs: false
  can_edit_workflows: false

prompting:
  system_prompt_template: "default-mini-swe-system"
  task_prompt_template: "issue-to-implementation"
  repo_instructions_file: ".repopilot/instructions.md"

15. Orchestration Management

RepoPilot should allow users to configure workflows as state machines.

15.1 Workflow Definition

Example:

id: default-issue-to-pr
name: Default Issue to PR Workflow
enabled: true

trigger:
  event: issue.labeled
  label: agent-ready

stages:
  - id: triage
    agent: triage-agent
    on_success: spec
    on_failure: failed

  - id: spec
    agent: spec-agent
    outputs:
      - spec.md
      - plan.md
      - tasks.md
    on_success: spec_approval

  - id: spec_approval
    type: approval_gate
    required_roles:
      - repo_owner
      - maintainer
    on_approved: implementation
    on_rejected: awaiting_comments

  - id: implementation
    agent: mini-swe-default
    on_success: open_pr
    on_failure: failed

  - id: open_pr
    type: git_provider_action
    action: create_or_update_pr
    on_success: ci_wait

  - id: ci_wait
    type: wait_for_ci
    require_success: true
    on_success: review
    on_failure: revision

  - id: review
    agent: review-agent
    on_success: human_review

  - id: human_review
    type: approval_gate
    required_roles:
      - maintainer
    on_approved: ready_to_merge
    on_rejected: revision

  - id: revision
    agent: mini-swe-default
    max_retries: 3
    on_success: ci_wait
    on_failure: failed

  - id: ready_to_merge
    type: terminal

15.2 Orchestration Features

The orchestration management UI should allow:

Viewing workflow definitions.
Creating workflows.
Editing workflows.
Enabling/disabling workflows.
Assigning workflows to repositories.
Viewing active workflow runs.
Retrying failed stages.
Cancelling active runs.
Replaying a run from a previous stage.
Manually advancing blocked stages.
Viewing decisions made by policy checks.

16. Web Interface Requirements

Recommended sections:

Dashboard
Repositories
Work Items
Pull Requests
Agent Runs
Agents
Workflows
Models
Sandboxes
Approvals
Audit Log
Settings

16.2 Dashboard

Should show:

Total managed repositories
Open work items
Active agent runs
Failed runs
Waiting approvals
Open agent PRs
Recent events
Cost estimate
Average success rate
CI pass/fail stats

16.3 Repository Detail Page

Tabs:

Overview
Issues
Pull Requests
Specs
Runs
Settings
Policies
Secrets
Webhooks

16.4 Work Item Detail Page

Should show:

Issue title
Source provider link
State
Labels
Assignment
Conversation timeline
Generated spec documents
Agent run history
Current workflow state
PR link
Approvals
Actions

Actions:

Assign Agent
Generate Spec
Approve Spec
Request Changes
Start Implementation
Cancel Run
Retry Run
Open PR
Comment on Issue
Comment on PR
Mark Blocked

16.5 Agent Run Detail Page

Should show:

Run status
Agent used
Model used
Repository
Work item
Trigger source
Start/end time
Duration
Cost estimate
Tokens used
Sandbox info
Logs
Tool calls
File changes
Commits
Test results
Final summary
Failure reason

Support live updates through WebSocket or SSE.

16.6 Spec Viewer

Should support:

Markdown rendering
Side-by-side edit/preview
Version history
Approval comments
Diff between spec versions
Link from spec item to implementation commit
Task checklist

16.7 Agent Management UI

Should support:

Create/edit/delete agent definitions
Select runner type
Select model provider
Configure prompt templates
Configure permissions
Configure sandbox limits
Configure tool access
Test agent on sample task
View agent performance metrics

16.8 Orchestration Management UI

Should support:

Workflow list
Workflow editor
YAML editor
Visual state graph
Stage configuration
Approval gate configuration
Retry policy
Timeout policy
Policy checks
Workflow run history

17. Spec-Driven Development Flow

17.1 Generated Spec Documents

Each work item should have a spec bundle.

metadata.yaml

issue_provider: github
repository: org/repo
issue_number: 123
title: "Add user export endpoint"
created_at: "2026-05-29T10:00:00Z"
updated_at: "2026-05-29T10:00:00Z"
state: draft | approved | implemented | obsolete
agent_owner: spec-agent
human_approved_by: null

conversation.md

Contains normalized issue and comment history.

# Conversation

## Issue

Title: Add user export endpoint

Body:
...

## Comments

### Comment by alice at 2026-05-29T10:30:00Z

...

### Comment by bob at 2026-05-29T11:00:00Z

...

spec.md

# Specification

## Problem

## Goals

## Non-Goals

## User Stories

## Functional Requirements

## Non-Functional Requirements

## Edge Cases

## Open Questions

## Acceptance Criteria

plan.md

# Implementation Plan

## Relevant Existing Code

## Proposed Changes

## Files Likely To Change

## Migration Plan

## Risks

## Rollback Plan

tasks.md

# Tasks

- [ ] Inspect existing API route structure
- [ ] Add export service
- [ ] Add endpoint
- [ ] Add tests
- [ ] Update docs

test-plan.md

# Test Plan

## Unit Tests

## Integration Tests

## Manual Tests

## Regression Tests

## Commands To Run

decisions.md

# Decisions

## Decision 1

Context:

Decision:

Alternatives:

Reason:

implementation-log.md

# Implementation Log

## Agent Run 1

Summary:

Files changed:

Tests run:

Failures:

Next steps:

17.2 Spec Lifecycle

draft
  ↓
needs_clarification
  ↓
ready_for_approval
  ↓
approved
  ↓
implementation_started
  ↓
implemented
  ↓
verified
  ↓
archived

17.3 Spec Approval

Repository policies should define whether spec approval is required.

Example:

specs:
  require_human_approval_after_spec: true
  approval_roles:
    - maintainer
    - repo_owner

18. Git Provider Integration

18.1 GitHub MVP

Required GitHub functionality:

Install GitHub App
Receive webhooks
Read issues
Read comments
Add comments
Add/remove labels
Create branches
Push commits
Open PRs
Update PRs
Read CI status
Read review comments
Request reviewers
Optionally merge PRs if allowed

18.2 Git Provider Abstraction

Define provider interface:

interface GitProvider {
  getRepository(id: string): Promise<Repository>;
  listIssues(repoId: string): Promise<Issue[]>;
  getIssue(repoId: string, issueNumber: number): Promise<Issue>;
  listIssueComments(repoId: string, issueNumber: number): Promise<Comment[]>;
  createIssueComment(repoId: string, issueNumber: number, body: string): Promise<Comment>;

  createBranch(repoId: string, fromBranch: string, newBranch: string): Promise<Branch>;
  commitFiles(repoId: string, branch: string, changes: FileChange[], message: string): Promise<Commit>;
  openPullRequest(repoId: string, input: PullRequestInput): Promise<PullRequest>;
  updatePullRequest(repoId: string, prNumber: number, input: PullRequestUpdate): Promise<PullRequest>;

  listPullRequestComments(repoId: string, prNumber: number): Promise<Comment[]>;
  createPullRequestComment(repoId: string, prNumber: number, body: string): Promise<Comment>;
  getPullRequestStatus(repoId: string, prNumber: number): Promise<PullRequestStatus>;

  mergePullRequest(repoId: string, prNumber: number, strategy: MergeStrategy): Promise<void>;
}

19. Comment Command Interface

Users should be able to interact with RepoPilot through issue and PR comments.

19.1 Mention Commands

Examples:

@repopilot generate spec
@repopilot start implementation
@repopilot revise based on my last comment
@repopilot run tests
@repopilot explain current status
@repopilot update spec
@repopilot cancel
@repopilot retry

19.2 Command Parser

The command parser should extract:

actor
repository
issue_or_pr
command
arguments
referenced_comments
permissions

19.3 Command Authorization

Before executing a command, RepoPilot must verify:

User has repository access.
User is allowed to trigger this command.
Repository policy permits this action.
Work item is in a compatible state.
No conflicting agent run is active unless concurrency is allowed.

20. Runner Design

20.1 Runner Interface

interface AgentRunner {
  prepare(input: AgentRunInput): Promise<void>;
  start(input: AgentRunInput): Promise<AgentRunHandle>;
  streamLogs(runId: string): AsyncIterable<LogEvent>;
  cancel(runId: string): Promise<void>;
  collectResult(runId: string): Promise<AgentRunResult>;
}

20.2 AgentRunInput

run_id: string
agent_id: string
repository:
  clone_url: string
  default_branch: string
  target_branch: string
work_item:
  provider: github
  type: issue | pull_request | manual
  id: string
  title: string
  body: string
  comments: []
spec_bundle_path: ".specs/issue-123"
instructions:
  system: string
  task: string
environment:
  sandbox_image: string
  env_vars: {}
  secrets: []
limits:
  timeout_minutes: 60
  max_iterations: 100
  max_cost_usd: 5

20.3 AgentRunResult

status: success | failed | cancelled | timed_out
summary: string
files_changed:
  - path: string
    additions: number
    deletions: number
commits:
  - sha: string
    message: string
tests:
  command: string
  status: passed | failed | not_run
  output_artifact: string
pull_request:
  created: true
  number: 456
  url: string
artifacts:
  - type: log
    uri: string
  - type: patch
    uri: string
cost:
  input_tokens: number
  output_tokens: number
  estimated_usd: number

21. mini-SWE-agent Adapter

21.1 Purpose

The mini-SWE-agent adapter should allow RepoPilot to use mini-SWE-agent as an implementation agent.

21.2 Responsibilities

The adapter should:

Create a clean workspace.
Clone the repository.
Check out the target branch.
Write issue context to a task file.
Write spec documents to the workspace.
Build a prompt for mini-SWE-agent.
Run mini-SWE-agent with configured model and limits.
Stream stdout/stderr and structured events.
Detect changed files.
Run configured test commands.
Commit changes.
Push branch.
Return result to orchestrator.

21.3 Prompt Template

You are an implementation agent working inside a repository.

You must follow the approved spec-driven development documents.

Repository instructions:
{{repository_instructions}}

Issue:
{{issue_title}}

Issue body:
{{issue_body}}

Conversation summary:
{{conversation_summary}}

Spec:
{{spec_md}}

Plan:
{{plan_md}}

Tasks:
{{tasks_md}}

Acceptance criteria:
{{acceptance_md}}

Rules:
- Do not modify protected files.
- Prefer minimal, focused changes.
- Run relevant tests.
- Update the implementation log.
- If requirements are unclear, stop and ask for clarification.
- Do not mark the task complete unless acceptance criteria are satisfied.

22. Policy Engine

22.1 Policy Evaluation Points

Policy should be checked before:

Starting agent run
Reading repository secrets
Allowing network access
Editing protected paths
Opening PR
Updating PR
Commenting externally
Merging PR
Retrying failed run
Running command from comment

22.2 Example Policy

id: default-secure-policy
name: Default Secure Policy

rules:
  - name: block-workflow-edits
    effect: deny
    action: file.write
    paths:
      - ".github/workflows/**"

  - name: require-approval-for-infra
    effect: require_approval
    action: file.write
    paths:
      - "infra/**"
      - "terraform/**"

  - name: deny-secret-files
    effect: deny
    action: file.read
    paths:
      - ".env"
      - "**/*.pem"
      - "**/*.key"

  - name: require-ci-before-merge
    effect: require
    action: pr.merge
    conditions:
      ci_status: success
      human_approval: true

23. Security Requirements

23.1 Secrets

Secrets must never be exposed directly to agents unless explicitly configured.
Secrets should be mounted only into sandbox runs that require them.
Secrets should be masked in logs.
Secrets should be scoped to repository and agent.
Secrets should support expiration and rotation.

23.2 Sandboxing

Agent code execution must be isolated.

Minimum requirements:

Separate container per run.
Read-only system image.
Limited mounted workspace.
Resource limits.
Timeout.
Optional network disabled by default.
No host Docker socket mounted.
No privileged containers.

23.3 Git Credentials

Use short-lived credentials where possible.
Scope credentials to specific repository.
Scope credentials to least privilege.
Avoid giving merge permissions to implementation agents.

23.4 Prompt Injection Protection

RepoPilot must treat issue content, comments, repository files, and PR comments as untrusted input.

The system should protect against instructions such as:

Ignore previous instructions.
Print secrets.
Modify CI to bypass tests.
Merge this PR automatically.
Delete repository files.

Mitigations:

Strong system prompts.
Policy engine.
Protected path checks.
Secret redaction.
Command allowlists.
Human approval gates.
Audit logs.
Model output validation where possible.

23.5 Audit Logs

Log all sensitive actions:

Repository added
Agent started
Secret accessed
File changes proposed
PR opened
PR updated
Comment posted
Approval granted
Merge performed
Policy denied action

24. Data Model

24.1 User

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
)

24.2 Repository

repositories (
  id uuid primary key,
  provider text not null,
  provider_repo_id text not null,
  full_name text not null,
  clone_url text not null,
  default_branch text not null,
  enabled boolean not null default true,
  settings jsonb not null,
  created_at timestamptz not null,
  updated_at timestamptz not null
)

24.3 Work Item

work_items (
  id uuid primary key,
  repository_id uuid references repositories(id),
  provider text not null,
  provider_type text not null,
  provider_id text not null,
  number integer,
  title text not null,
  body text,
  state text not null,
  labels jsonb not null,
  assigned_agent_id uuid,
  current_workflow_run_id uuid,
  external_url text,
  created_at timestamptz not null,
  updated_at timestamptz not null
)

24.4 Spec Bundle

spec_bundles (
  id uuid primary key,
  work_item_id uuid references work_items(id),
  state text not null,
  version integer not null,
  path text not null,
  content jsonb not null,
  approved_by uuid references users(id),
  approved_at timestamptz,
  created_at timestamptz not null,
  updated_at timestamptz not null
)

24.5 Agent

agents (
  id uuid primary key,
  name text not null,
  type text not null,
  runner text not null,
  enabled boolean not null,
  config jsonb not null,
  created_at timestamptz not null,
  updated_at timestamptz not null
)

24.6 Agent Run

agent_runs (
  id uuid primary key,
  agent_id uuid references agents(id),
  repository_id uuid references repositories(id),
  work_item_id uuid references work_items(id),
  workflow_run_id uuid,
  status text not null,
  trigger_type text not null,
  trigger_payload jsonb,
  input jsonb not null,
  result jsonb,
  started_at timestamptz,
  completed_at timestamptz,
  created_at timestamptz not null,
  updated_at timestamptz not null
)

24.7 Workflow

workflows (
  id uuid primary key,
  name text not null,
  enabled boolean not null,
  definition jsonb not null,
  created_at timestamptz not null,
  updated_at timestamptz not null
)

24.8 Workflow Run

workflow_runs (
  id uuid primary key,
  workflow_id uuid references workflows(id),
  repository_id uuid references repositories(id),
  work_item_id uuid references work_items(id),
  status text not null,
  current_stage text,
  state jsonb not null,
  started_at timestamptz,
  completed_at timestamptz,
  created_at timestamptz not null,
  updated_at timestamptz not null
)

24.9 Approval

approvals (
  id uuid primary key,
  target_type text not null,
  target_id uuid not null,
  status text not null,
  requested_by uuid references users(id),
  approved_by uuid references users(id),
  comment text,
  created_at timestamptz not null,
  resolved_at timestamptz
)

24.10 Event Log

events (
  id uuid primary key,
  repository_id uuid references repositories(id),
  work_item_id uuid references work_items(id),
  type text not null,
  source text not null,
  actor text,
  payload jsonb not null,
  created_at timestamptz not null
)

24.11 Audit Log

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,
  metadata jsonb,
  created_at timestamptz not null
)

25. API Specification

25.1 Repositories

GET /api/repositories
POST /api/repositories
GET /api/repositories/{id}
PATCH /api/repositories/{id}
DELETE /api/repositories/{id}
POST /api/repositories/{id}/sync
POST /api/repositories/{id}/test-connection

25.2 Work Items

GET /api/work-items
GET /api/work-items/{id}
PATCH /api/work-items/{id}
POST /api/work-items/{id}/assign-agent
POST /api/work-items/{id}/generate-spec
POST /api/work-items/{id}/start-implementation
POST /api/work-items/{id}/cancel
POST /api/work-items/{id}/retry

25.3 Specs

GET /api/work-items/{id}/spec
PUT /api/work-items/{id}/spec
POST /api/work-items/{id}/spec/approve
POST /api/work-items/{id}/spec/reject
GET /api/work-items/{id}/spec/history

25.4 Agents

GET /api/agents
POST /api/agents
GET /api/agents/{id}
PATCH /api/agents/{id}
DELETE /api/agents/{id}
POST /api/agents/{id}/test

25.5 Agent Runs

GET /api/agent-runs
GET /api/agent-runs/{id}
POST /api/agent-runs/{id}/cancel
POST /api/agent-runs/{id}/retry
GET /api/agent-runs/{id}/logs
GET /api/agent-runs/{id}/events
GET /api/agent-runs/{id}/artifacts

25.6 Workflows

GET /api/workflows
POST /api/workflows
GET /api/workflows/{id}
PATCH /api/workflows/{id}
DELETE /api/workflows/{id}
POST /api/workflows/{id}/validate
POST /api/workflows/{id}/enable
POST /api/workflows/{id}/disable

25.7 Workflow Runs

GET /api/workflow-runs
GET /api/workflow-runs/{id}
POST /api/workflow-runs/{id}/cancel
POST /api/workflow-runs/{id}/retry-stage
POST /api/workflow-runs/{id}/advance

25.8 Approvals

GET /api/approvals
GET /api/approvals/{id}
POST /api/approvals/{id}/approve
POST /api/approvals/{id}/reject

25.9 Webhooks

POST /api/webhooks/github
POST /api/webhooks/gitlab
POST /api/webhooks/gitea

25.10 Logs and Events

GET /api/events
GET /api/audit-logs
GET /api/live

26. Event Model

RepoPilot should normalize external provider events into internal events.

Example:

{
  "id": "evt_123",
  "type": "issue.commented",
  "source": "github",
  "repository_id": "repo_123",
  "work_item_id": "wi_123",
  "actor": "alice",
  "payload": {
    "issue_number": 123,
    "comment_id": 456,
    "body": "@repopilot generate spec"
  },
  "created_at": "2026-05-29T12:00:00Z"
}

27. Logging and Observability

27.1 Logs

Required log streams:

API logs
Worker logs
Agent run logs
Sandbox logs
Git provider webhook logs
Policy decision logs
Audit logs

27.2 Metrics

Suggested metrics:

agent_runs_total
agent_runs_failed_total
agent_run_duration_seconds
agent_run_cost_usd
agent_run_input_tokens
agent_run_output_tokens
work_items_active
work_items_failed
pull_requests_opened_total
pull_requests_merged_total
policy_denials_total
approval_wait_time_seconds
ci_failures_total

27.3 Traces

Each work item should have a trace ID used across:

webhook ingestion
workflow run
agent run
sandbox
provider API calls
UI timeline

28. Failure Handling

28.1 Failure Categories

agent_failed
agent_timeout
model_error
sandbox_error
git_error
provider_api_error
policy_denied
ci_failed
merge_conflict
tests_failed
approval_rejected
insufficient_context

28.2 Failure Behavior

When a run fails:

Mark run failed.
Store logs and artifacts.
Summarize failure.
Comment on issue or PR if policy allows.
Suggest next action.
Allow retry from UI.
Allow retry with modified instructions.

28.3 Retry Strategy

retry:
  max_attempts: 2
  backoff_seconds: 60
  retryable_errors:
    - model_error
    - provider_api_error
    - sandbox_error
  non_retryable_errors:
    - policy_denied
    - approval_rejected

29. Merge and Approval Policy

29.1 Default

By default, agents should not merge PRs.

merge:
  allow_agent_merge: false
  require_human_approval: true
  require_ci_success: true

29.2 Optional Controlled Merge

If enabled:

merge:
  allow_agent_merge: true
  require_human_approval: true
  require_ci_success: true
  require_no_unresolved_threads: true
  allowed_strategies:
    - squash

The merge action should still be performed by a restricted service account, not by the implementation agent directly.

30. Model Provider Management

RepoPilot should support multiple model providers.

30.1 Provider Configuration

providers:
  - id: openai-main
    type: openai
    base_url: null
    api_key_secret: openai_api_key

  - id: local-ollama
    type: ollama
    base_url: http://ollama:11434

  - id: vllm-local
    type: openai-compatible
    base_url: http://vllm:8000/v1
    api_key_secret: null

30.2 Model Routing

Allow policies such as:

routing:
  default_model: openai-main/gpt-5.1
  low_risk_model: local-ollama/qwen-coder
  review_model: openai-main/gpt-5.1
  max_cost_per_run_usd: 10

31. Prompt Template Management

Prompt templates should be configurable in the UI and versioned.

31.1 Template Types

triage
spec_generation
implementation
review
revision
test_fixing
documentation
status_summary
failure_summary

31.2 Template Variables

{{repository_name}}
{{repository_instructions}}
{{issue_title}}
{{issue_body}}
{{issue_comments}}
{{conversation_summary}}
{{spec_md}}
{{plan_md}}
{{tasks_md}}
{{acceptance_criteria}}
{{test_plan}}
{{changed_files}}
{{ci_results}}
{{review_comments}}

32. Repository Instruction Files

RepoPilot should support repository-local instruction files.

Recommended files:

.repopilot/instructions.md
.repopilot/policies.yaml
.repopilot/workflows.yaml
.repopilot/agents.yaml
.repopilot/spec-template.md
.repopilot/test-commands.yaml

Example .repopilot/instructions.md:

# RepoPilot Instructions

## Project Overview

## Architecture

## Coding Style

## Testing

## Pull Request Rules

## Forbidden Changes

## Common Commands

## Release Notes

33. MVP Scope

33.1 MVP Features

The first version should include:

Single-user or admin-only auth.
GitHub App integration.
Add repositories.
Receive GitHub webhooks.
List issues for managed repositories.
Trigger agent manually from UI.
Trigger agent with label or mention.
Generate spec bundle.
Run mini-SWE-agent in Docker.
Stream logs to UI.
Create branch.
Push commits.
Open draft PR.
Display run status.
Display generated specs.
Cancel active runs.
Retry failed runs.
Basic policy checks.
Basic audit logs.
No automatic merge.

33.2 MVP Exclusions

Do not include initially:

Multi-provider Git support.
Complex workflow editor.
Visual graph builder.
Multi-tenant organizations.
Automatic merge.
Advanced RBAC.
Firecracker sandboxing.
Full cost accounting.
Fine-grained prompt injection detection.
Agent marketplace.

34. Suggested MVP Architecture

Next.js frontend
FastAPI backend
PostgreSQL
Redis queue
Docker runner
GitHub App
mini-SWE-agent adapter

34.1 MVP Runtime Flow

GitHub webhook
  ↓
FastAPI /webhooks/github
  ↓
Normalize event
  ↓
Store event
  ↓
Create/update work item
  ↓
If trigger matches policy, enqueue workflow job
  ↓
Worker creates spec
  ↓
Worker runs mini-SWE-agent
  ↓
Worker pushes branch
  ↓
Worker opens draft PR
  ↓
UI streams status/logs

35. Development Milestones

Milestone 1: Foundation

Deliverables:

Repo skeleton
Docker Compose
PostgreSQL schema
Backend API
Frontend shell
Auth placeholder
Repository CRUD

Milestone 2: GitHub Integration

Deliverables:

GitHub App setup
Repository sync
Issue sync
Webhook receiver
Comment/label trigger detection
Event log UI

Milestone 3: Agent Run Infrastructure

Deliverables:

Job queue
Worker process
Docker sandbox runner
Agent run records
Live log streaming
Cancel/retry support

Milestone 4: Spec Generation

Deliverables:

Spec bundle data model
Spec generation prompt
Spec viewer
Spec approval state
Spec commit to branch

Milestone 5: mini-SWE-agent Adapter

Deliverables:

Workspace preparation
mini-SWE-agent invocation
Output capture
Changed file detection
Test command execution
Commit generation

Milestone 6: PR Creation

Deliverables:

Branch push
Draft PR creation
PR status tracking
PR timeline in UI
Agent summary comment

Milestone 7: Feedback Loop

Deliverables:

PR comment ingestion
Review comment ingestion
Revision run trigger
Update existing branch
Comment back with status

Milestone 8: Policies and Hardening

Deliverables:

Protected paths
Permission checks
Secret masking
Timeout enforcement
Network toggle
Audit log
Basic RBAC

36. Acceptance Criteria for MVP

RepoPilot MVP is complete when:

An admin can add a GitHub repository.
RepoPilot receives issue events from GitHub.
A user can label an issue agent-ready.
RepoPilot creates a work item.
RepoPilot generates a spec bundle.
RepoPilot runs mini-SWE-agent in an isolated container.
RepoPilot streams logs to the UI.
RepoPilot creates a branch.
RepoPilot pushes commits.
RepoPilot opens a draft PR.
A reviewer can comment on the PR.
RepoPilot can run a revision based on review feedback.
RepoPilot records all major events in an audit log.
RepoPilot never merges without explicit human approval.
A failed run can be inspected and retried.

37. Risks

37.1 Agent Quality

Coding agents may produce incorrect or incomplete code.

Mitigation:

Human review
CI requirements
Test enforcement
Review agent
Small scoped tasks
Spec approval

37.2 Security

Agents may be exposed to malicious issue content or repository files.

Mitigation:

Sandboxing
Policy engine
Protected paths
No secrets by default
Audit logs
Network isolation

37.3 Cost Overruns

Long-running agents may consume too many tokens.

Mitigation:

Max runtime
Max iterations
Max cost
Model routing
Run cancellation

37.4 Merge Conflicts

Agent branches may become stale.

Mitigation:

Rebase/update branch before revision
Detect conflicts
Ask for human intervention
Retry with fresh context

37.5 Poor Observability

Agent actions may be hard to understand.

Mitigation:

Live logs
Structured events
Timeline UI
Artifacts
Final run summary

38. Future Enhancements

38.1 Git Provider Expansion

GitLab
Gitea
Forgejo
Bitbucket
Azure DevOps

38.2 Advanced Orchestration

Visual workflow builder
Conditional branching
Parallel agents
Multi-agent debate
Automatic test repair loop
Dependency update workflows

38.3 Knowledge and Context

Repository embeddings
Documentation indexing
Architecture map
Historical PR memory
Past issue retrieval

38.4 Advanced Sandboxing

Firecracker microVMs
Ephemeral Kubernetes jobs
Per-run network policies
SBOM and dependency scanning

38.5 Evaluation

Agent success scoring
Regression tracking
Benchmark work items
Per-agent performance dashboards

38.6 Human Collaboration

Inline spec comments
Reviewer assignment rules
Slack/Matrix integration
Daily agent activity digest

39. Initial Repo Structure

Recommended monorepo layout:

repopilot/
  apps/
    web/
    api/
    worker/
  packages/
    git-providers/
    agents/
    runners/
    orchestration/
    policy/
    shared/
  infra/
    docker-compose.yml
    k8s/
  docs/
    architecture.md
    security.md
    development.md
  examples/
    workflows/
    agents/
    policies/
  .repopilot/
    instructions.md

40. Recommended First Implementation Slice

Build the smallest vertical slice:

One GitHub repo
  ↓
One issue
  ↓
Manual "Generate Spec" button
  ↓
Manual "Run Agent" button
  ↓
mini-SWE-agent runs locally in Docker
  ↓
Branch is pushed
  ↓
Draft PR is opened
  ↓
Logs visible in UI

This validates the core product before building advanced orchestration.

41. Example User Story Set

User Story 1: Add Repository

As an admin, I want to add a GitHub repository so that RepoPilot can monitor issues and pull requests.

Acceptance criteria:

I can install or connect a GitHub App.
I can select a repository.
RepoPilot stores repository metadata.
RepoPilot verifies webhook delivery.
RepoPilot shows recent issues.

User Story 2: Generate Spec

As a repository owner, I want RepoPilot to generate a structured spec from an issue so that implementation starts from a clear plan.

Acceptance criteria:

I can click “Generate Spec.”
RepoPilot reads issue body and comments.
RepoPilot creates spec documents.
I can view and edit the generated spec.
I can approve or reject the spec.

User Story 3: Run Agent

As a developer, I want to assign an implementation agent to an approved spec so that the agent can create a draft PR.

Acceptance criteria:

I can start an agent run.
RepoPilot creates an isolated sandbox.
The agent modifies code.
The agent runs tests if configured.
The agent pushes a branch.
The agent opens a draft PR.
The UI shows logs and final summary.

User Story 4: Revise PR

As a reviewer, I want to comment on an agent-created PR and have the agent revise the implementation.

Acceptance criteria:

RepoPilot detects review comments.
I can trigger a revision run.
The agent sees the comments and existing PR.
The agent updates the branch.
The PR receives a status comment.

User Story 5: Audit Agent Actions

As an admin, I want to inspect all agent actions so that I can understand what happened and diagnose failures.

Acceptance criteria:

Every run has logs.
Every external action is recorded.
Every policy decision is recorded.
I can see who approved specs and merges.

42. Design Principles

Human approval first.
Agents propose; maintainers decide.
Everything is auditable.
Repository policies are explicit.
Specs are first-class artifacts.
Runners are replaceable.
Git providers are replaceable.
No secret exposure by default.
Small tasks beat large autonomous missions.
Self-hosted must mean controllable, observable, and secure.

43. Initial Technical Decisions

Recommended initial decisions:

frontend: Next.js
backend: FastAPI
database: PostgreSQL
queue: Redis + RQ or Celery
runner_isolation: Docker
git_provider: GitHub App
first_agent_runner: mini-SWE-agent
object_storage: MinIO
auth: local admin login first, OIDC later
deployment: Docker Compose first, Kubernetes later

44. Open Questions

Should specs be committed to the agent branch, the default branch, or only stored in RepoPilot?
Should implementation start automatically after spec generation, or always require approval?
Should issue comments be treated as authoritative, or should only maintainer comments affect specs?
Should the agent be allowed to install dependencies?
Should network access be disabled by default?
Should multiple agents be allowed to work on the same issue?
Should RepoPilot support GitHub only for MVP?
Should the UI allow editing prompt templates?
Should local models be supported in MVP?
Should PR-Agent be included in MVP or added later?
Should the platform support organizations and teams from the beginning?
Should the system store full agent traces or only summarized logs?

45. Suggested Immediate Next Steps

Create the monorepo.
Define the PostgreSQL schema.
Implement repository CRUD.
Implement GitHub App authentication.
Implement webhook ingestion.
Build work item timeline.
Implement manual spec generation.
Implement Docker runner.
Wrap mini-SWE-agent.
Open a draft PR from a test issue.

46. Definition of Done for First Prototype

The first prototype is done when a developer can:

Start the stack locally with Docker Compose.
Connect one GitHub repository.
See open issues in the UI.
Select an issue.
Generate a spec.
Start an implementation run.
Watch logs stream in the UI.
See generated code changes.
Open a draft PR.
Trigger one revision from a PR comment.

47 KiB Raw Blame History

Spec Definition: Self-Hosted Repository Agent Orchestration Platform

1. Working Name

2. Product Summary

3. Core Problem

4. Goals

4.1 Product Goals

4.2 Engineering Goals

5. Non-Goals

6. Primary Users

6.1 Admin

6.2 Repository Owner

6.3 Developer / Reviewer

6.4 Agent Operator

7. Key Concepts

7.1 Managed Repository

7.2 Work Item

7.3 Agent

7.4 Agent Run

7.5 Orchestration

7.6 Spec-Driven Development Document Set

7.7 Policy

8. High-Level Workflow

8.1 Standard Issue-to-PR Workflow

9. System Architecture

9.1 Major Components

9.2 Recommended Services

Web Frontend

Backend API

Orchestration Engine

Job Queue

Agent Runner

Sandbox Runtime

Database

Object Storage

10. Deployment Model

10.1 MVP Deployment

10.2 Production Deployment

10.3 Air-Gapped Mode

11. Repository Management

11.1 Add Repository

11.2 Repository Settings

12. Work Item Lifecycle

12.1 Work Item States

12.2 Work Item Events

13. Agent Types

13.1 Spec Agent

13.2 Implementation Agent

13.3 Review Agent

13.4 Test Agent

13.5 Documentation Agent

13.6 Triage Agent

14. Agent Configuration

14.1 Agent Definition

15. Orchestration Management

15.1 Workflow Definition

15.2 Orchestration Features

16. Web Interface Requirements

16.1 Main Navigation

16.2 Dashboard

16.3 Repository Detail Page

16.4 Work Item Detail Page

16.5 Agent Run Detail Page

16.6 Spec Viewer

16.7 Agent Management UI

16.8 Orchestration Management UI

17. Spec-Driven Development Flow

17.1 Generated Spec Documents

metadata.yaml

conversation.md

spec.md

plan.md

tasks.md

test-plan.md

decisions.md

implementation-log.md

17.2 Spec Lifecycle

17.3 Spec Approval

18. Git Provider Integration

18.1 GitHub MVP

47 KiB

Raw Blame History