Skip to content

Commit 86e22e2

Browse files
BunsDevBunsDev
authored
feat: operationalize hosted MVP (#1)
Adds hosted MVP webhook routing, worker timeout hardening, familiar operating docs, and starter configuration examples.\n\nCo-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
1 parent 9d46802 commit 86e22e2

21 files changed

Lines changed: 1146 additions & 34 deletions

File tree

‎DESIGN.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# coven-github Design
2+
3+
`coven-github` is a thin GitHub ingress layer for trusted familiar work. It should not become a generic agent platform inside the GitHub App. The GitHub App accepts repository events, routes them to the right familiar, records task state, and keeps humans in control through Cave oversight.
4+
5+
## Design Goal
6+
7+
Assign GitHub work to a known familiar and get a draft PR back with visible context, evidence, and an oversight path.
8+
9+
The core design constraint is trust continuity:
10+
11+
- The same familiar can return to the same repository with memory and team context.
12+
- The team can see what the familiar used, changed, tested, and could not decide.
13+
- The service can fail transparently without losing task state.
14+
- The open-source adapter remains self-hostable so buyers can inspect the trust boundary.
15+
16+
## Task Flow
17+
18+
```text
19+
GitHub event
20+
-> webhook HMAC validation
21+
-> event parsing and familiar routing
22+
-> task record and queue
23+
-> worker starts isolated session
24+
-> coven-code --headless receives session brief
25+
-> familiar drafts changes and result envelope
26+
-> GitHub Check Run and PR are updated
27+
-> Cave Board and session link expose oversight
28+
```
29+
30+
## Routing Model
31+
32+
The initial self-hosted adapter uses TOML familiar config:
33+
34+
- `bot_username` routes issue assignment and mentions.
35+
- `trigger_labels` route issue labels such as `coven:fix`.
36+
- `skills` and `model` shape the familiar runtime.
37+
38+
Hosted routing should move this into installation-scoped configuration:
39+
40+
- installation id,
41+
- organization,
42+
- repository,
43+
- familiar id,
44+
- allowed trigger labels,
45+
- memory scope,
46+
- skill pack,
47+
- model route,
48+
- autonomy tier.
49+
50+
## Cave Oversight Gate
51+
52+
Cave oversight is the control plane. It should show:
53+
54+
- task status and terminal state,
55+
- familiar identity,
56+
- repository and issue/PR links,
57+
- Check Run link,
58+
- session link,
59+
- context and memory scope used,
60+
- evidence collected,
61+
- human decision points.
62+
63+
Draft PRs are the default. The team should promote more autonomy only after the familiar earns trust through repeated visible work.
64+
65+
## Operational Pattern
66+
67+
ClawSweeper is the reference pattern for conservative GitHub automation inside the OpenClaw ecosystem: narrow promises, durable state, marker-backed comments edited in place, explicit maintainer commands, and deterministic gates before repair or merge work.
68+
69+
`coven-github` should borrow the operating style without becoming the same product:
70+
71+
- Keep one visible status surface per task instead of noisy repeated comments.
72+
- Treat maintainer commands as clear steering inputs, not casual chat.
73+
- Store durable task records before worker execution starts.
74+
- Re-check live GitHub state immediately before every mutation.
75+
- Prefer proposal, draft PR, and Cave approval loops before any higher-autonomy behavior.
76+
- Make status, evidence, and next action obvious to reviewers who never open Cave.
77+
78+
The familiar layer adds the moat: a known teammate with repo and team context. The ClawSweeper pattern supplies the operational discipline that makes that familiar safe to trust.
79+
80+
## Trust Boundaries
81+
82+
| Boundary | Rule |
83+
|---|---|
84+
| Webhook ingress | Validate HMAC before parsing or routing. |
85+
| Tenant data | Scope task state by GitHub installation before hosted launch. |
86+
| Worker execution | Run each task with a timeout and isolated workspace. |
87+
| Git auth | Use installation tokens, not user credentials. |
88+
| Memory | Make familiar memory opt-in, inspectable, and revocable. |
89+
| Comments | Ignore familiar bot self-comments to avoid loops. |
90+
| Output | Prefer draft PRs and explicit failure states. |
91+
92+
## Hosted Reliability Requirements
93+
94+
Hosted `coven-github` needs these before paid beta:
95+
96+
1. Durable queue.
97+
2. Persistent task store.
98+
3. GitHub delivery idempotency.
99+
4. Tenant-scoped task API auth.
100+
5. Installation-scoped familiar routing.
101+
6. Worker isolation and timeout enforcement.
102+
7. Audit events for accepted, started, retried, timed out, failed, needs input, PR opened, and completed.
103+
104+
## Why This Design Monetizes
105+
106+
The paid product is not "an agent that can write code." The paid product is a managed trust pipeline:
107+
108+
- Teams keep familiar context instead of re-explaining their standards.
109+
- Managers get visibility instead of hidden automation.
110+
- Security reviewers get a self-host path and a clear credential boundary.
111+
- Engineers get PRs from a known actor with a history.
112+
113+
That is what generic GitHub bots and one-shot coding agents do not provide.

‎FAMILIAR-CONTRACT.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Familiar Contract for GitHub Work
2+
3+
`coven-github` is not valuable because it can call the GitHub API. The value is that a team can deploy a familiar: a known, persistent, context-aware operator that understands the repo, the team's standards, and when to stop for human judgment.
4+
5+
The GitHub App should make that trust visible.
6+
7+
## Promise
8+
9+
A GitHub familiar should:
10+
11+
- Carry persistent identity across issues, PRs, repositories, and review cycles.
12+
- Use the team's configured model, skills, memory, and operating rules.
13+
- Explain what it changed and why in the familiar's voice.
14+
- Prefer draft PRs and Cave oversight for non-trivial work.
15+
- Treat ambiguity as a reason to ask, not a reason to guess.
16+
- Preserve repo hygiene: small branches, tested changes, clear failure states.
17+
- Make recovery easy when the task cannot be completed.
18+
19+
## Behavioral Guarantees
20+
21+
| Guarantee | Product behavior |
22+
|---|---|
23+
| Context continuity | The familiar can use organization/repo memory and prior task history when enabled. |
24+
| Team fit | Routing and skills are configured per installation, repository, and familiar. |
25+
| Human control | Cave oversight links appear in Check Runs, comments, and task state. |
26+
| Failure transparency | Every task ends in a visible state: review, done, needs input, failed, or timed out. |
27+
| Minimal surprise | Familiars open draft PRs by default until the team explicitly promotes automation. |
28+
| No self-trigger loops | Bot-authored comments do not retrigger the same familiar. |
29+
| Bounded execution | Worker timeout, retry, and isolation rules are enforced. |
30+
31+
## Why This Beats Generic Agents
32+
33+
Generic coding agents optimize for a single task. Familiars optimize for an ongoing working relationship.
34+
35+
That matters most in PR clearing:
36+
37+
- A generic agent can satisfy a prompt; a familiar can remember the team's release posture.
38+
- A generic agent can run tests; a familiar can know which tests are trusted signal.
39+
- A generic agent can make edits; a familiar can know when the change needs a design note, a migration path, or a human decision.
40+
- A generic agent can produce output; a familiar can build trust over repeated work.
41+
42+
## Operational Requirements
43+
44+
To make the familiar promise real, hosted `coven-github` needs:
45+
46+
1. Tenant-scoped familiar routing.
47+
2. Durable task history and event idempotency.
48+
3. Cave oversight as the default review surface.
49+
4. Familiar memory boundaries that are opt-in, inspectable, and revocable.
50+
5. Audit logs for task acceptance, execution, retries, timeout, PR creation, and human intervention.
51+
6. Clear tier limits so teams know when a familiar is operating as a draft helper versus an autonomous maintainer.
52+
53+
## Launch Rule
54+
55+
Do not sell "autonomous code changes" first. Sell "a trusted familiar that drafts PRs under your team's control."
56+
57+
Autonomy can expand after the service proves reliability through visible oversight, repeatable failure handling, and team-specific context.

‎HOSTED.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Hosted OpenCoven for GitHub
2+
3+
Hosted OpenCoven is the managed version of `coven-github`: install the GitHub App, configure a familiar, assign an issue or label, and get a draft PR back with Cave oversight.
4+
5+
The hosted tier should monetize managed reliability and familiar continuity, while the open-source adapter remains self-hostable for trust and inspection.
6+
7+
## What Hosted Adds
8+
9+
| Capability | Self-hosted adapter | Hosted OpenCoven |
10+
|---|---|---|
11+
| GitHub App ingress | You run it | Managed |
12+
| Queue | In-process/dev path until configured | Durable queue |
13+
| Task state | Local/in-memory unless extended | Persistent history |
14+
| Worker isolation | Operator-managed | Managed worker pool |
15+
| Familiar routing | Static config | Installation/repo scoped |
16+
| Familiar memory | Local/operator-managed | Optional cloud memory |
17+
| Cave oversight | Local Cave | Hosted-ready oversight links and dashboard |
18+
| Usage limits | Operator-managed | Tiered limits and audit logs |
19+
| Support | Community | Priority by tier |
20+
21+
## Packaging
22+
23+
| Tier | Buyer | Initial shape |
24+
|---|---|---|
25+
| Open / Self-host | OSS maintainers, security reviewers, local-first users | Free adapter, BYOM, one familiar, community support. |
26+
| Hosted Starter | Small teams with backlog | Managed queue, one familiar, task caps, Cave oversight links. |
27+
| Hosted Team | Product/platform teams | Multi-familiar routing, audit log, usage controls, priority queue, team memory. |
28+
| Hosted Dedicated | Security-sensitive orgs | Dedicated workers, stronger retention controls, custom limits, SLA, onboarding support. |
29+
30+
Launch with flat monthly tiers and task caps. Avoid pure usage billing until task duration and model-cost distribution are known.
31+
32+
## Buyer Promise
33+
34+
> Your familiar on your GitHub: the one that already knows your code, your team, and how you ship.
35+
36+
The strongest buyer promise is trust continuity. A familiar should know the diff between "works" and "good enough for this repo." Hosted makes that reliable without making the customer operate workers, queues, or task history.
37+
38+
## Data Boundaries
39+
40+
Hosted should make these boundaries explicit before beta:
41+
42+
- GitHub installation tokens are scoped to the installed repositories.
43+
- User GitHub credentials are not used for worker pushes.
44+
- Familiar memory is opt-in and scoped by installation/repository policy.
45+
- Task history records metadata, status, evidence, links, and summaries.
46+
- Raw repository workspaces are temporary and destroyed after the task.
47+
- Secrets are redacted from logs and task output.
48+
49+
## Beta Gate
50+
51+
Hosted beta should wait for:
52+
53+
1. Persistent task store.
54+
2. Durable queue.
55+
3. Tenant-scoped task API authentication.
56+
4. Worker isolation with cleanup and timeouts.
57+
5. Usage metering by installation, repo, familiar, and task.
58+
6. Cave oversight dashboard for task history and human intervention.
59+
60+
## Landing Page Copy
61+
62+
Headline:
63+
64+
> Assign it like a teammate. Get a PR back.
65+
66+
Support copy:
67+
68+
> OpenCoven lets your team deploy a trusted familiar to GitHub. It knows your repo context, follows your skills and review norms, drafts PRs under Cave oversight, and gets better as it works with your team.
69+
70+
Primary CTA:
71+
72+
- Join hosted beta
73+
74+
Secondary CTA:
75+
76+
- Self-host the adapter

‎README.md‎

Lines changed: 22 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,10 @@ Every existing GitHub coding agent is a black box: GitHub's model, GitHub's cont
2222

2323
`coven-github` flips that. Your familiar is yours: your model, your skills, your memory, your voice in the PR body. The GitHub App is just the ingress layer.
2424

25+
That is the product wedge: assign it like a teammate, get a PR back, and keep Cave oversight in the loop. A familiar should know the difference between "technically works" and "good enough for this repo, this team, and this moment."
26+
27+
See [Design](DESIGN.md), [Hosted OpenCoven](HOSTED.md), [Familiar Contract](FAMILIAR-CONTRACT.md), [Roadmap](ROADMAP.md), and [Hosted vs self-hosted](docs/hosted-vs-self-hosted.md) for the operational plan.
28+
2529
---
2630

2731
## Architecture
@@ -72,7 +76,22 @@ CovenCave oversight UI ← watch session live, intervene, steer
7276

7377
## Status
7478

75-
🚧 **In development.** See [COVEN-GITHUB.md](COVEN-GITHUB.md) for the full product spec.
79+
🚧 **In development.** The repo has the first GitHub App adapter path wired, but hosted production readiness is still being built. See [COVEN-GITHUB.md](COVEN-GITHUB.md) for the roadmap-level product spec.
80+
81+
| Capability | Status | Notes |
82+
|---|---|---|
83+
| Webhook HMAC validation | Implemented | Rejects unsigned or invalid GitHub webhook payloads. |
84+
| Issue assignment trigger | Implemented | Routes matching bot assignees to configured familiars. |
85+
| Label trigger | Implemented | Routes configured `trigger_labels` such as `coven:fix`. |
86+
| Issue / PR mention trigger | Implemented | Ignores familiar bot self-comments to avoid loops. |
87+
| GitHub App installation tokens | Implemented | Mints installation access tokens from the App private key. |
88+
| Check Run creation and completion | Partial | Creates and updates Check Runs; branch/SHA resolution still needs production hardening. |
89+
| `coven-code --headless` execution | Partial | Worker spawns headless sessions and enforces task timeouts; result quality depends on the runtime. |
90+
| Pull request creation | Partial | Opens draft PRs from session results; base branch is still hardcoded to `main`. |
91+
| CovenCave task polling | Partial | In-memory task API exists for local oversight; hosted control-plane auth and persistence are planned. |
92+
| Durable queue / task store | Planned | Required for hosted reliability and restarts. |
93+
| Hosted tier | Planned | See [Hosted vs self-hosted](docs/hosted-vs-self-hosted.md). |
94+
| Familiar trust contract | Planned | See [Familiar Contract](FAMILIAR-CONTRACT.md). |
7695

7796
---
7897

@@ -91,15 +110,15 @@ cp config/example.toml config/local.toml\n# Set: github_app_id, private_key_path
91110
./target/release/coven-github serve --config config/local.toml
92111
```
93112

94-
See [docs/self-hosting.md](docs/self-hosting.md) for full setup including GitHub App registration.
113+
See [docs/self-hosting.md](docs/self-hosting.md) for full setup including GitHub App registration. For a minimal familiar route, start from [`examples/familiar-github-starter`](examples/familiar-github-starter/).
95114

96115
---
97116

98117
## Sponsor / Hosted Tier
99118

100119
`coven-github` is open source and self-hostable. OpenCoven offers a **hosted tier** for organizations that want managed infra, cloud familiar memory, and multi-familiar routing without running their own workers.
101120

102-
See [opencoven.ai/github](https://opencoven.ai/github) for hosted tier details.
121+
See [Hosted OpenCoven](HOSTED.md) and [Hosted vs self-hosted](docs/hosted-vs-self-hosted.md) for the service shape, security boundaries, and buyer packaging.
103122

104123
---
105124

‎ROADMAP.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# coven-github Roadmap
2+
3+
This roadmap operationalizes `coven-github` as a hosted service funded by teams that want trusted familiar-driven GitHub work.
4+
5+
## Strategic Thesis
6+
7+
The market already has generic coding agents. OpenCoven's advantage is the familiar:
8+
9+
- A known teammate, not a disposable bot.
10+
- Context-aware across repos, issues, reviews, and team norms.
11+
- Governed by skills, memory, and a visible trust contract.
12+
- Watched and steered through Cave instead of hidden in a black box.
13+
14+
The hosted product should monetize managed reliability and trust continuity: durable task infrastructure, worker isolation, auditability, familiar memory, and multi-familiar routing.
15+
16+
## Milestone 1: Honest Self-Hosted Adapter
17+
18+
Goal: a motivated user can run the adapter and understand exactly what works.
19+
20+
- Implement issue assignment, label, issue mention, and PR review comment triggers.
21+
- Enforce webhook HMAC validation and bot self-comment suppression.
22+
- Enforce worker timeout behavior.
23+
- Keep README status honest about implemented, partial, and planned capabilities.
24+
- Publish security, isolation, self-hosting, hosted-vs-self-hosted, and familiar contract docs.
25+
26+
## Milestone 2: Hosted Control Plane
27+
28+
Goal: support real hosted installations without losing task state or leaking tenant context.
29+
30+
- Persistent task store.
31+
- Durable queue.
32+
- GitHub delivery idempotency.
33+
- Installation-scoped familiar routing.
34+
- Tenant-scoped task API auth for Cave.
35+
- Task audit log and terminal states.
36+
- Marker-backed GitHub status comments that are edited in place per task.
37+
- Maintainer command router for status, stop, retry, explain, and approve.
38+
39+
## Milestone 3: GitHub Correctness
40+
41+
Goal: make the GitHub App reliable across normal repositories.
42+
43+
- Resolve repository default branch through the GitHub API.
44+
- Resolve Check Run head SHA instead of using placeholders.
45+
- Use the repo default branch for PR base and session brief.
46+
- Capture review-comment diff hunk context.
47+
- Add transient GitHub API retry classification.
48+
- Add webhook fixture tests for all supported triggers.
49+
50+
## Milestone 4: Hosted Worker Fleet
51+
52+
Goal: make familiar execution safe enough to charge for.
53+
54+
- Containerized worker backend.
55+
- CPU, memory, disk, network, and timeout limits.
56+
- Workspace cleanup guarantees.
57+
- Token redaction and secret handling tests.
58+
- Usage metering by installation, repo, familiar, and task runtime.
59+
- Tier limits and concurrency controls.
60+
61+
## Milestone 5: Monetization Surface
62+
63+
Goal: make the value legible and buyable.
64+
65+
- `opencoven.ai/github` landing page.
66+
- Hosted beta waitlist.
67+
- Pricing: Community, Hosted Starter, Hosted Team, Hosted Dedicated.
68+
- Cave dashboard for task history, familiar routing, usage, and audit events.
69+
- Demo assets: issue assignment to Check Run, draft PR back to issue, Cave oversight intervention.
70+
- A reference demo showing the ClawSweeper-style operating loop: one visible status, explicit steering commands, durable audit trail, and familiar-specific PR output.
71+
72+
## Current Focus
73+
74+
1. Land the hosted MVP hardening branch.
75+
2. Build persistent task state and idempotency.
76+
3. Move familiar routing from global TOML toward installation-scoped config.
77+
4. Make Cave oversight central in the public story and product loop.
78+
5. Borrow ClawSweeper's conservative GitHub bot ergonomics: edited status comments, maintainer steering commands, and live-state rechecks before mutation.

‎crates/config/src/lib.rs‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -45,8 +45,12 @@ pub struct WorkerConfig {
4545
pub max_retries: u32,
4646
}
4747

48-
fn default_timeout() -> u64 { 600 }
49-
fn default_retries() -> u32 { 2 }
48+
fn default_timeout() -> u64 {
49+
600
50+
}
51+
fn default_retries() -> u32 {
52+
2
53+
}
5054

5155
/// Per-familiar configuration for task routing.
5256
#[derive(Debug, Clone, Deserialize, Serialize)]

0 commit comments

Comments
 (0)