Status: practical adoption guide for the current alpha framework
Audience: project owners, maintainers, human contributors, AI-agent operators, and automation builders
This guide answers the practical question that is easy to miss in the rest of the repository:
How do I start a new application repository and use IDKMesh ideas and contracts so humans, AI agents, tools, and CI can collaborate without giving any one worker too much authority?
The short answer is:
Use Git/GitHub as the canonical project state, use bounded Work Units as the unit of delegation, let humans and agents produce candidate work, verify candidate work separately, and keep integration authority outside the worker and verifier.
Today, IDKMesh can support this as a GitHub-native operating model plus executable contracts and validation components. The full one-command Verified Swarm Runner that automatically discovers, dispatches, verifies, and integrates arbitrary external projects is not finished yet.
That distinction matters throughout this guide.
For a normal new software project, the recommended deployment is GitHub-first and server-optional.
You should not need to operate a permanent IDKMesh server just to use the collaboration model. The target repository holds project/policy state, GitHub Actions runs event-driven coordination, hosted agents run on their providers, and optional idkmesh-node workers run on contributor/project machines only when local models or special compute are needed.
See GitHub-First Deployment and Multi-User Operation for the exact deployment profiles, durable-state plan, multi-user role model, and criteria for when a separate control service becomes justified.
An ordinary development loop often looks like this:
issue -> developer or agent -> pull request -> tests -> merge
An IDKMesh-style loop makes the trust and evidence boundaries explicit:
goal
-> bounded issue / Work Unit
-> capability and risk routing
-> human or agent worker
-> candidate branch / artifacts
-> worker result + provenance
-> independent verifier
-> verification evidence
-> protected integration decision
-> measured outcome
-> next bounded work
The most important invariant is:
worker success != acceptance
verification recommendation != merge authority
CI success != independent human review
IDKMesh is therefore useful when the hard problem is not merely generating code, but coordinating multiple imperfect contributors and preserving enough evidence to decide what should become canonical.
This operating model is a good fit for:
It is probably unnecessary for a tiny throwaway project where one person is comfortable owning generation, review, and integration alone.
It is also not yet a finished turnkey solution if the requirement is:
Those are reference-product goals, not current production claims.
A clean adoption keeps three things distinct.
Your new project remains the canonical source of truth for:
IDKMesh does not need to replace GitHub.
These define how work is bounded and how evidence is interpreted:
See ProjectManifest and DomainPack interfaces and schema navigation.
Workers and verifiers can be:
The project contract should describe capabilities and authority, not hard-code one model vendor.
flowchart TD
A[Project goal or GitHub issue] --> B{Small and testable enough?}
B -- No --> C[Research or decompose]
C --> B
B -- Yes --> D[Create bounded Work Unit]
D --> E[Classify risk, permissions, dependencies, evidence]
E --> F[Route to lowest-cost capable worker]
F --> G[Human or agent works on isolated branch/worktree]
G --> H[Candidate artifacts + worker provenance]
H --> I[Independent verification on exact candidate revision]
I --> J{Required checks and evidence satisfied?}
J -- No --> K[Reject, revise, replan, or escalate]
K --> D
J -- Yes --> L[Protected PR / integration review]
L --> M{Human or governance decision}
M -- Reject --> K
M -- Accept --> N[Merge into canonical branch]
N --> O[Observe outcome and record evidence]
O --> A
The flow is intentionally a loop. A failed attempt is not an exceptional state; it is evidence that should improve the next Work Unit, routing decision, validator, or policy.
The following is the recommended conceptual sequence for a new application.
mkdir myapp
cd myapp
git init
Create the smallest runnable skeleton for the application, for example:
myapp/
README.md
src/
tests/
docs/
.github/
workflows/
Commit the baseline before inviting agents to work:
git add .
git commit -m "Initial project baseline"
Create the remote repository and push the baseline using the GitHub UI, GitHub CLI, or your normal Git workflow.
The important property is not the creation command. It is that the repository has one canonical default branch and all later candidate work can be traced to exact Git revisions.
Before connecting autonomous workers:
The application repository, not an agent prompt, is the authority boundary.
A practical project-side layout is:
myapp/
.idkmesh/
README.md
project.json
work-units/
results/
verification/
evidence/
This layout is a recommended adoption convention, not yet an official bootstrap generated by a stable idkmesh init command.
Use the current reference contracts as templates:
The current ProjectManifest validator in experiments/project_contracts.py resolves manifests and DomainPack paths inside the IDKMesh checkout. It is therefore useful as the contract reference and self-test today, but the repository does not yet provide a polished arbitrary-external-repository bootstrap/validation CLI. Do not mistake the reference contract for a completed external-project installer.
The project policy should answer these questions first:
Only after these are defined should the project choose models or agent products.
This prevents a provider integration from accidentally defining project governance.
Different participants can join the same flow without becoming the same kind of actor.
A human can:
A human worker follows the same scope contract as an automated worker.
A GitHub-native agent can be given:
It should normally not receive direct main-branch or merge authority.
The GitHub issue is the routing and coordination surface; the PR is the candidate artifact.
A local agent can work in:
Give it:
Credentials should be runtime-scoped and short-lived where possible. Do not store API keys or secrets inside Work Units or committed provenance files.
IDKMesh already contains protocol-neutral worker-adapter infrastructure and A2A/MCP mappings under interop.
Use these protocols as transport and tool-integration surfaces, while keeping IDKMesh semantics in:
A successful A2A or MCP call is transport success, not acceptance of the work.
Do not use an LLM when a deterministic tool is the better worker or verifier.
Examples:
A useful routing rule is: deterministic before probabilistic, smaller capable model before larger model, and stronger verification as risk rises.
The ideal Work Unit is not merely “an issue that sounds small.” It is a task with enough structure that a different worker and verifier can agree on what was asked.
A machine/agent-friendly Work Unit should make these fields explicit:
| Field | Question it answers |
|---|---|
| ID | Which task is this? |
| exact base revision | What repository state is the worker changing? |
| objective | What single result is wanted? |
| inputs | What may the worker rely on? |
| outputs | What artifacts must be produced? |
| allowed paths | Where may the worker write? |
| forbidden paths | What must remain untouched? |
| capabilities | What must the worker be able to do? |
| security/risk | How dangerous is the work? |
| permissions | Network, filesystem, secrets, process limits |
| dependencies | What must already exist? |
| validators | Which checks are required? |
| evidence | What proof must be retained? |
| budget | Time, compute, human attention, tokens, spend |
| failure semantics | Stop, retry, replan, or escalate |
| provenance | Who or what created the Work Unit? |
The current machine-readable definition is WorkUnit v0.2.
Prefer a Work Unit that has:
Split a task when it combines materially different questions, for example:
research -> architecture decision -> implementation -> migration -> deployment
Those are usually separate Work Units because each stage can invalidate the next one.
Also split:
A good test is:
Can a reviewer understand what changed, why, and how it was checked without reading the worker’s private conversation?
If not, the unit is probably too large or underspecified.
The core contract should remain vendor-neutral. Model names change quickly; capability classes are more stable.
A practical routing ladder is:
| Tier | Typical worker | Best for |
|---|---|---|
| T0 | deterministic tool/script | formatting, schema checks, tests, mechanical transformations |
| T1 | lightweight/fast model | issue classification, simple docs, narrow edits, boilerplate |
| T2 | strong general coding/reasoning model | normal features, bugs, refactors, multi-file reasoning |
| T3 | peak model or specialist human | high uncertainty, security-sensitive design, difficult debugging, architecture, failed lower-tier attempts |
This is a recommended routing policy, not a claim that the current repository already provides one universal live router across every vendor.
Use this decision order:
1. Is the task allowed by project policy?
no -> stop/escalate
2. Can a deterministic tool solve it?
yes -> T0
3. What capabilities are required?
select only workers that match them
4. What is the risk class?
higher risk -> stronger worker constraints + stronger verification
5. How much ambiguity, context, novelty, and cross-file reasoning is present?
low -> T1
normal -> T2
high or repeated failure -> T3
6. Can the result be independently verified?
no -> decompose or require human/specialist review
7. Route to the lowest tier that is capable of producing useful evidence.
Never use model size as an authority rule.
bigger model != permission to merge
higher benchmark score != permission to weaken verification
same model twice != automatically independent verification
Independence can be weakened by shared model families, prompts, tools, datasets, providers, or failure modes even when two separate agent processes are used.
For each assigned Work Unit, the worker should follow a bounded loop:
inspect exact base revision
-> confirm scope and permissions
-> make the smallest candidate change
-> run required local checks
-> record exact commands/results
-> record tool/model provenance when practical
-> identify remaining uncertainty
-> open/update candidate PR or result artifact
-> stop
The worker should not silently expand scope just because it notices another problem.
If a blocker appears, the correct outputs are often:
“Could not complete safely” is better evidence than an unbounded attempt.
A worker completion is a candidate, not an accepted result.
For software work, the candidate normally consists of:
The ResultManifest contract exists to record worker-produced artifacts and claims without granting acceptance authority.
In a lightweight GitHub-only adoption, a PR description can initially carry the same information even before every project automates the JSON contract.
Verification should target the exact candidate revision, not a moving branch.
A verifier should:
A good verifier attempts to falsify the candidate, not merely confirm the worker’s summary.
For model-based verification, diversity can help, but nominal reviewer count is not the same as independent evidence. If a project collects many reviewer verdicts, idkmesh gate-audit can diagnose correlated failures from observed verdict data.
The integrator or maintainer decides what becomes canonical.
Before merging, check:
The preferred default for software projects is:
automatic candidate generation: allowed within policy
automatic self-acceptance: forbidden
automatic merge: off unless an explicit future policy safely enables it
protected human/governance integration: on
The current reference software-engineering ProjectManifest follows this pattern.
A project can implement the workflow with GitHub labels, project fields, or an external queue. The exact label names are project-specific, but the state transitions should remain explicit.
| State | Entry requirement | Exit artifact |
|---|---|---|
| draft | idea exists | clarified issue or research question |
| ready | bounded objective and checks exist | Work Unit |
| claimed | eligible worker selected | worker identity + base revision |
| candidate | worker produced artifacts | branch/PR + result evidence |
| verifying | verifier owns evaluation | check/review evidence |
| revise/reject | required evidence failed | findings + next action |
| verified | required checks satisfied | verification result/recommendation |
| integration review | protected authority inspects evidence | accept/reject/escalate decision |
| integrated | canonical branch changed | merge commit/release artifact |
| observed | outcome measured | follow-up evidence or next Work Unit |
Agents should be able to parse these states without depending on private conversational context.
You can adopt the principles before the full runner exists.
Use:
This gives a real coordination improvement without waiting for every automation component.
Add:
Each new automation layer should remove manual friction without collapsing the authority boundaries.
Use one agent as builder and a different model/tool or deterministic test stack as verifier.
The human keeps merge authority.
Good first adoption because the workflow is simple while still preventing one coding agent from self-certifying.
Use GitHub issues as shared Work Units, route narrow work to cheaper/faster workers, difficult work to stronger workers, and keep verification independent from the producing agent where practical.
Collect verdict data if several automated reviewers are used and periodically audit whether they are actually independent.
Humans and agents use the same bounded issue/PR path.
Do not create a privileged “AI lane” that bypasses contributor rules. Instead expose:
This keeps the repository understandable to contributors who do not use the same agent tools.
Use read-only or proposal-only ProjectManifest policy, separate research Work Units from implementation Work Units, require artifact hashes and reproduction evidence, and keep the repository write boundary narrow.
The existing research-replication ProjectManifest demonstrates this pattern.
A long prompt can contain useful context, but it should not be the only place where scope, permissions, tests, and authority rules live.
Durable project state belongs in repository artifacts.
Route and verify against immutable SHAs when possible.
A verifier evaluating “whatever is currently on the branch” can accidentally inspect a different artifact from the one the worker produced.
Ask:
Which capabilities and trust level does this task require?
before asking:
Which vendor should receive it?
Run deterministic checks before expensive model review.
Do not spend frontier-model attention to discover a formatting error or failing unit test.
If candidates are accumulating faster than they can be reviewed, add review capacity or reduce generation.
More workers are harmful when verification debt grows without bound.
A worker saying “I am 95% confident” is provenance about the worker state. It is not substitute evidence.
Work Units may describe required permission scopes. Secret values belong in protected runtime stores.
A failed attempt should leave:
Avoid:
A new external application is ready for an IDKMesh-style development loop when all of the following are true:
[ ] repository exists and has a canonical default branch
[ ] main/default branch is protected
[ ] baseline CI is reproducible
[ ] project goals and contribution rules are in the repository
[ ] project policy defines allowed work and integration authority
[ ] ProjectManifest/DomainPack strategy is selected
[ ] worker roles/capabilities are defined
[ ] verifier role is separate where required
[ ] agents receive least-privilege credentials
[ ] tasks can be expressed as bounded Work Units
[ ] every automated task has explicit stop/failure semantics
[ ] candidate work is isolated on a branch/worktree/sandbox
[ ] required evidence is attached to the exact candidate revision
[ ] merge authority remains protected
[ ] outcomes feed back into future tasks/routing
For external-project adoption to become truly easy, IDKMesh should converge toward a bootstrap such as:
idkmesh init
-> create .idkmesh/
-> select DomainPack
-> generate ProjectManifest
-> inspect repository language/test commands
-> generate bounded default policies
-> install GitHub workflow templates
-> configure worker adapters
-> validate branch-protection assumptions
-> emit first Work Units
Then an operational loop can become:
GitHub event
-> classify/decompose
-> Work Unit
-> capability/risk routing
-> worker adapter
-> candidate + ResultManifest
-> verifier adapter
-> VerificationResult
-> protected integration queue
-> human/governance decision
This is the direction of the reference product. The current repository already has many underlying contracts and adapter concepts, but not yet this complete external-project bootstrap as one polished user flow.
If you want to use IDKMesh ideas on a new application today, do this:
That is the smallest useful “mesh.”
You do not need many agents to start. You need clear boundaries, evidence, and a repeatable loop.