IDKMesh

IDKMesh Product Goals, Component Boundaries, and Development Slice Map

Date: 2026-09-22
Status: canonical execution decomposition for the connector-control-plane product track
Parent tracker: #570
Routing plan: Model-Tier Dispatcher and Connector Routing

1. North-star product goal

IDKMesh should become a GitHub-first coordination product for bounded human/AI software work.

A small team should be able to connect a normal GitHub repository, configure several interchangeable worker/model paths, turn backlog items into bounded WorkUnits, dispatch only when policy permits it, retain candidate/evidence provenance, verify independently, and make explicit human integration decisions.

The default product should work without requiring an always-on IDKMesh server.

The core lifecycle is:

human goal / backlog
 -> bounded WorkUnit
 -> capability + authority routing
 -> admitted connector
 -> bounded attempt
 -> untrusted candidate
 -> canonical ResultManifest
 -> independent VerificationResult
 -> evidence/report
 -> explicit human decision
 -> normal protected integration
 -> retained outcome / learning

IDKMesh succeeds when that lifecycle is easy to understand, safe to operate, reproducible, and reusable on a second repository without adding project-specific coordinator code.

2. What IDKMesh is not trying to become

The connector-control-plane track must not turn into:

Provider/model capability, execution, verification, and repository authority remain separate concepts.

3. Product success gates

Development should be organized around evidence-bearing gates rather than feature count.

G0 — Core contracts are stable enough to implement against

Done when:

G1 — One provider-neutral connector kernel works locally

Done when:

G2 — At least two materially different worker paths produce candidates

Done when:

G3 — GitHub can safely coordinate work without an always-on server

Done when:

G4 — Candidate evidence converges independently of provider

Done when:

G5 — A newcomer can operate the system without editing Python

Done when:

G6 — IDKMesh develops IDKMesh through its own interfaces

Done when:

G7 — A second repository reaches a reproducible release

Done when:

4. Component boundaries

Each component owns one primary responsibility.

Component Primary responsibility Must not own
C1 Connector kernel profiles, registry, probes, routing primitives live provider semantics
C2 Jules connector Jules Source/Session/Activity mapping routing policy, merge authority
C3 Model provider OpenAI-compatible inference contract coding-agent loop
C4 Local agent runner bounded local coding-agent execution project authority
C5 GitHub dispatch GitHub event -> admitted run provider-specific policy
C6 Candidate normalization provider output -> canonical result/evidence verification verdict
C7 CLI/API human/operator control surface duplicate business logic
C8 GitHub bootstrap initialize another repo safely hidden admin mutation
C9 Durable ledger restart-safe run/event/idempotency state canonical application code
C10 Identity/roles actor -> stage-specific capability model capability scoring
C11 Pilot prove no-server second-project lifecycle new core semantics
C12 Governance baseline GitHub rules/permissions/secret preflight silent repository admin
C13 Work intake UX structured issue/project planning execution authority
C14 GitHub evidence surfaces readable GitHub-native status/evidence/release views mutation authority
C15 OpenHands worker second heterogeneous bounded coding-agent path verification or merge authority
UI Control Tower (#572) human understanding/decision views canonical state or autonomous merge

5. Slice-sizing rule

A normal development slice should be small enough that one contributor or agent can understand, implement, test, and review it without needing to redesign adjacent components.

Preferred slice properties

A slice should normally:

Practical size target

This is guidance, not a rigid line-count gate:

A PR that simultaneously changes profile schema, provider HTTP, GitHub dispatch, persistence, and UI is too large.

6. Promotion rule: catalogued slice -> GitHub issue

Do not create every future micro-slice as an issue immediately.

Promote a slice to a GitHub issue only when:

  1. its upstream contract is merged or explicitly frozen;
  2. acceptance criteria are testable now;
  3. no active PR already implements the same outcome;
  4. it can be completed without speculative adjacent redesign;
  5. a contributor can start from the issue without needing a private explanation.

This keeps the backlog actionable instead of aspirational.

7. Component slice catalog

C1 — Connector kernel (#574)

Goal: provide the provider-neutral local product kernel every later connector uses.

Already completed

Ready next

C1-B — versioned profile loader and validator

Outcome:

Acceptance:

C1-C — connector registry and fake drivers

Outcome:

Acceptance:

C1-D — normalized probe contract

Outcome:

Acceptance:

C1-E — environment secret references and redaction

Outcome:

Acceptance:

C1-F — local metadata/idempotency store

Outcome:

Acceptance:

C1-G — CLI: connections validate/list

Outcome:

Acceptance:

C1-H — CLI: probe/doctor/route explain

Outcome:

Acceptance:

C1-I — adversarial routing fixture pack

Outcome:

Acceptance:

C1 exit gate: G1.

C2 — Jules REST connector (#575)

Goal: first real hosted-agent connector behind C1.

Slices

C2 exit gate: one reproducible hosted candidate with exact provenance.

C3 — OpenAI-compatible model provider (#576)

Goal: one model-provider interface for local/hosted compatible endpoints.

Slices

C3 exit gate: one local and one optional hosted-compatible model path without coordinator changes.

C4 — bounded local agent runner (#577)

Goal: run one local coding agent inside an allowlisted disposable execution boundary.

Slices

These remain reviewable foundations only: no real coding agent is executed by either slice.

C4 exit gate: same WorkUnit semantics as remote agent, different execution path.

C5 — GitHub issue/webhook dispatch bridge (#578)

Goal: explicit GitHub action creates exactly one admitted run.

Slices

C5 exit gate: replayed action cannot duplicate work.

C6 — candidate normalization (#579)

Goal: erase provider-specific differences after candidate creation.

Slices

C6 exit gate: G4 provider-neutral evidence.

C7 — CLI and optional HTTP API (#580)

Goal: operate control plane without editing Python.

Slices

C7 exit gate: one newcomer can configure/probe/dispatch/inspect without provider JSON.

C8 — GitHub-first bootstrap (#596)

Goal: adopt IDKMesh in a repository with one command and no server.

Slices

C8 exit gate: deterministic no-server project bootstrap.

C9 — durable GitHub-native run ledger (#597)

Goal: preserve run state across ephemeral Actions workers.

Slices

C9 exit gate: G3 restart-safe coordination.

C10 — GitHub identity, roles, claims, authority (#598)

Goal: use GitHub human identity while keeping stage-specific authority explicit.

Slices

C10 exit gate: unauthorized GitHub input cannot broaden authority.

C11 — second-project pilot (#599)

Goal: prove IDKMesh is a reusable product, not repository-specific automation.

Slices

C11 exit gate: G7.

C12 — GitHub governance and secret baseline (#607)

Goal: turn repository-security assumptions into checked preconditions.

Slices

C12 exit gate: requested operation cannot run when its required GitHub guard is missing.

C13 — structured WorkUnit intake/project planning (#608)

Goal: make bounded work understandable without raw JSON.

Slices

C13 exit gate: structured planning improves usability without becoming authority.

C14 — GitHub-native evidence/dashboard/release surfaces (#609)

Goal: understand runs from GitHub before requiring the full Control Tower.

Slices

C14 exit gate: one run is understandable from normal GitHub surfaces.

C15 — OpenHands heterogeneous coding worker (#641)

Goal: add a second materially different issue-to-candidate coding worker without giving it verification or integration authority.

Slices

Safety rules

C15 exit gate: one low-risk issue can follow issue -> OpenHands run -> candidate PR -> normal IDKMesh CI -> human decision with exact run/source provenance and no authority widening.

UI — Human Control Tower (#572)

Goal: make system state understandable to a human without creating a second source of truth.

Slices

UI exit gate: newcomer can explain goal, work, evidence, uncertainty, authority, and required human decision from one interface.

8. Dependency graph

The critical path is:

C1 kernel
 |
 +--> C2 Jules -----------+
 |                        |
 +--> C15 OpenHands ------+--> C6 normalization --> verification/evidence
 |                        |
 +--> C3 model --> C4 ----+
 |                        |
 +--> C5 GitHub dispatch -+
 |          |
 |          +--> C9 durable state
 |          +--> C10 authority
 |
 +--> C7 CLI/API
 |
 +--> C8 bootstrap --> C12 governance
 |                 --> C13 intake
 |
 +----------------------------------> C14 GitHub evidence
                                       |
                                       +--> UI Control Tower

C1/C2/C4/C5/C6/C7/C8/C9/C10/C12/C13/C14/C15
                              |
                              v
                          C11 pilot

Parallel work that is safe

After C1 profile/registry/probe contracts are stable:

Avoid parallel edits to the same central routing/profile contract until each version is merged.

9. Immediate executable wave

The repository should now focus on a small wave rather than opening every future slice.

Wave 1 — converge the C1 implementation stack

All C1 micro-slices now have implementation candidates. Do not create more C1 feature branches until this stack is reviewed, integrated in dependency order, retargeted to current main, and the exact-head gates are green.

The stacked review order is #624 -> #625 -> #626 -> #629 -> #656 -> #657, with #627/#628 converged from the C1-B base at the appropriate points. Queued CI is not passing evidence.

Wave 2 — can begin once C1-B/C/D contracts are merged

Parallel:

Wave 3 — live execution edges

Only after common contracts stabilize:

10. Definition of done for any slice

Use .github/ISSUE_TEMPLATE/05-development-slice.md when promoting a catalogued slice into a GitHub issue. The template mirrors the fields below so boundedness is enforced at issue creation time rather than discovered during review.

Every slice issue/PR should include:

If those fields cannot be written clearly, the slice is probably still too large or too speculative.

11. Project management rule

The umbrella tracker (#570) should show only:

Detailed implementation belongs in component issues and promoted micro-slice issues.

This keeps #570 readable for humans while still allowing many contributors/agents to work independently.

12. Current status at this checkpoint

As of this document:

This site is open source. Improve this page.