zopu-code/docs/agent-context.md

Zopu Work OS — Agent Context

Purpose: compact bootstrap context for Codex/OMP/OpenCode/FLUE workers contributing to Zopu.
Usage: read this first, then load only task-relevant documents and repository files.

1. Mission

Build Zopu: a Work OS that turns conversation and external Signals into durable, verified outcomes.

Signal → Work → Definition → Design → Vertical Slices
→ Resolver → Attempts → Verification → Delivery → Result → Learning

The product is not chat threads, an issue tracker, a harness UI, or an autonomous PR factory.

2. Source-of-truth order

1. current accepted Work/Question/Decision
2. approved Work Definition
3. approved Design Packet + current Slice
4. repository tests/types/code
5. product.md
6. tech.md
7. design.md
8. dev-loop.md
9. slices.md
10. dev-plan.md
11. glossary.md
12. evaluation.md

When sources conflict, report the conflict. Do not silently choose a convenient interpretation.

3. Current product target

Initial user:

technical founder / small engineering team
one project + one Git repository
web chat + Work cards
manual merge

Initial complete loop:

message
→ Signal
→ approved Work
→ approved Design Packet
→ one bounded coding slice
→ independent verification
→ exact verified commit
→ real PR
→ human intervention/resume

4. Non-negotiable invariants

1. Work is a durable outcome, not a chat/session/issue/PR.
2. Exact Signal provenance is preserved.
3. State transitions are explicit commands/events.
4. FLUE/model output is validated proposal data, not authority.
5. Rivet actors own serialized lifecycle/recovery.
6. Harnesses and runtimes are replaceable adapters.
7. One mutating Attempt owns one isolated worktree.
8. Every Attempt is bounded and terminally classified.
9. Builder output remains candidate output until independent verification.
10. Evidence binds to exact revision and environment.
11. Published PR head equals verified integrated SHA.
12. Human questions/approvals are durable objects.
13. Retry/restart must not duplicate Work, commits, PRs, or deployments.
14. Merge/deploy remain human-gated initially.
15. Completion requires outcome evidence, not an agent’s “done.”

5. System ownership

Work OS       durable intent/state/evidence/policy
Rivet actors  identity, serialization, timers, recovery
FLUE          domain agents/workflows and typed proposals
Harness       bounded coding/tool loop
Sandbox       filesystem/process/network isolation
Git           source history
ArtifactStore durable output/evidence
UI/Buzz       interaction surfaces, not workflow truth

6. Initial actor shape

ProjectActor
├── project config + active Work index

WorkActor
├── definition/design/slices
├── resolver state
├── questions/approvals
├── artifacts/result

AttemptActor
├── runtime lease
├── harness session
├── normalized events
├── timeout/cancellation/outcome

Add Verification/Integration/Result actors only when their lifecycles justify separation.

7. Initial adapters

Preferred first implementation:

FLUE          definition/design/resolver support
Rivet         actors
CubeSandbox   full Linux runtime
OMP           first coding harness, replaceable
Git forge     branch/commit/PR
Convex        durable application data/projections where used
Effect        application ports/layers/errors/scopes/streams

Do not import provider-specific types into domain modules.

8. Working protocol for every code task

Before editing

1. Identify current vertical slice and acceptance criteria.
2. Read relevant docs and repository rules.
3. Inspect current architecture, tests, and existing abstractions.
4. State impacted modules and risks.
5. Produce/confirm a small implementation plan.
6. Ask a Question only when ambiguity changes behavior, security, data, or architecture.

During implementation

1. Stay within the current slice.
2. Preserve dependency direction.
3. Prefer existing patterns over parallel frameworks.
4. Add typed boundaries and tagged errors.
5. Make external effects idempotent.
6. Add cancellation/timeouts for long-running operations.
7. Record exact revisions/provider identifiers.
8. Add tests with the implementation.
9. Do not weaken unrelated tests or hide failures.
10. Explain intentional Design Packet deviations.

Before declaring candidate ready

Run task-relevant checks:

format/lint/typecheck
focused unit/integration tests
behavioral/live check
security/secret check where relevant
design-conformance review

Report:

files changed
behavior implemented
checks run + results
known risks/deviations
artifacts/revision
remaining blockers

Never claim verified unless the independent verification path ran.

9. Code organization rule

Use logical separation:

domain/       pure types/state/invariants
application/  use cases/commands
ports/        Effect services
adapters/     FLUE/Rivet/Cube/OMP/Git implementations

Keep the initial package count practical. A folder boundary is enough until independent reuse/lifecycle exists.

10. State modeling rule

Prefer explicit state machines over booleans.

Bad:

isRunning: boolean
isDone: boolean
hasError: boolean

Good:

type AttemptStatus =
  | "queued"
  | "running"
  | "succeeded"
  | "retryable_failure"
  | "needs_input"
  | "blocked"
  | "verification_failed"
  | "budget_exhausted"
  | "cancelled"
  | "permanent_failure"

Transitions must validate current version/state.

11. Model/agent output rule

Agents return schemas such as:

SignalProposal
WorkDefinitionProposal
DesignPacketProposal
ResolverDecisionProposal
VerificationAssessment
LearningProposal

Application code decodes, authorizes, and executes commands. Agents do not directly mutate arbitrary state.

12. Quality rule

For every behavior, identify:

acceptance criterion
implementation evidence
independent check
exact candidate revision
review requirement

Tests prove immediate behavior. Design review protects maintainability and future change cost. Both matter.

13. UI rule

Expose:

outcome
phase
latest meaningful update
next action/blocker
slice progress
evidence
delivery/result

Hide low-level harness noise by default. Preserve raw logs in diagnostics.

14. Scope control

Do not implement unless required by the current slice:

• dynamic Kit Builder;
• multiple harness providers;
• large fleets;
• autonomous merge/deploy;
• universal workflows;
• automatic canonical-memory mutation;
• sophisticated multi-tenancy.

Design replaceable boundaries, then ship one path.

15. Task completion template

## Implemented
- ...

## Behavior
- ...

## Verification run
- `command` — pass/fail
- ...

## Evidence
- candidate SHA/artifacts
- ...

## Design deviations
- none / ...

## Remaining risks or blockers
- none / ...

16. Required reading by task type

Task	Read
product/domain	product.md, glossary.md
UI	design.md, product.md
actors/state	tech.md, glossary.md
orchestration	dev-loop.md, tech.md
current sequencing	slices.md, dev-plan.md
verification/evals	evaluation.md, dev-loop.md
provider adapter	tech.md plus provider docs
broad feature	agent-context.md + all relevant sections

17. Stop and escalate when

• accepted definition/design is missing or contradictory;
• required permission is unavailable;
• worktree/revision identity is uncertain;
• a destructive action is outside policy;
• verification cannot bind to exact candidate;
• implementation requires expanding scope materially;
• a retry would repeat a non-transient failure;
• repository state suggests another active mutating owner.

Return a precise Question or blocker, not a guess.