Repository navigation
docs: list context workflows - #514
Conversation
A living list of the ways we expect people to move context into and out of Moca: what sandbox and storage each workflow uses, and where it stands. Centralizes the workflows table that lived in the delegate skill in rossoctl#455. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Jeremy Cohn <Jeremy.Cohn@ibm.com>
ingpaolodettori-dev
left a comment
ingpaolodettori-dev
left a comment
There was a problem hiding this comment.
Useful list, and the statuses check out against main: #482 and #494 are merged, #476, #358 and #495 are open, and contextctl ctx backup exists in rossoctl/context-service. No blockers. The inline comments are about where the page lives, a few places where it could be more precise about what phase 1 actually gives you, and some wording.
Author: moonlight16 (MEMBER — maintainer)
Areas reviewed: Docs (checked against docs/CONTRIBUTING-DOCS.md, docs/context-service.md, the #494 description, and rossoctl/context-service README/docs)
Agent/IDE config (.claude/.vscode): none
Commits: 1 commit, all signed-off: yes
CI status: passing (incl. docs / check-links)
| data that the task works from. This page lists the ways we expect people to move context into and | ||
| out of Moca, and what each one needs. It is a living list; propose changes in a PR. | ||
|
|
||
| A **workload** is an environment for delegated tasks: where they run and the context they work from |
There was a problem hiding this comment.
suggestion: docs/CONTRIBUTING-DOCS.md ("Where things go") has no home at the root of docs/, and nothing links to this page. docs/index.md doesn't list it either, so it starts out as one of the orphans that REORG-PLAN is cleaning up. Consider moving it to docs/concepts/, or to docs/notes/ if it's meant as a living working list, and adding a row to docs/index.md. A maturity line would also help (e.g. that it's a planning list rather than a description of shipped behavior), since CONTRIBUTING-DOCS asks every page for one.
|
|
||
| A **workload** is an environment for delegated tasks: where they run and the context they work from | ||
| ([docs/context-service.md](context-service.md)). Today a workload belongs to the user who created | ||
| it. Context is stored by [Context Service](https://github.com/rossoctl/context-service). |
There was a problem hiding this comment.
nit: CONTRIBUTING-DOCS.md (Terminology) says the product name is MOCA. This page uses "Moca" throughout. context-service.md does too, so this is optional, but new pages should use the documented spelling.
|
|
||
| ### Keep context in Moca | ||
|
|
||
| | # | Workflow | Flow | When to use it | Sandbox | Storage | Status | |
There was a problem hiding this comment.
suggestion: "Server done" is true, but phase 1 has limits a reader planning on workflows 1 and 2 will want to know about (from #494 and docs/context-service.md): workload runs are synchronous only (async /runs with a workloadId returns 501), they need a logged-in user, and /workloads returns 501 workloads_unavailable unless MOCA_CONTEXT_WORKLOADS_ENABLED=1 and CONTEXT_SERVICE_URL are set. A short footnote in the Status section, or a link to the context-service.md limits, would cover it.
| ## Sandbox and storage types | ||
|
|
||
| Sandboxes: | ||
|
|
There was a problem hiding this comment.
nit: The rossoctl/context-service README already lists "Automatic capture and restore of native agent-harness state" for Claude Code, Codex, OpenCode and Pi, and it has docs/context-portability.md. If the missing part is cross-harness translation (Claude Code → Codex), say that and link the existing capture/restore docs. As written, "No design yet" undersells what's there.
|
|
||
| Sandboxes: | ||
|
|
||
| - **Shared:** the operator's shared, statically provisioned sandboxes. Tasks from many workloads |
There was a problem hiding this comment.
| - **Either:** the workflow works with both. | ||
|
|
||
| Storage: | ||
|
|
There was a problem hiding this comment.
suggestion: Please add that shared sandboxes are not a security boundary between users. #494 says so explicitly: tasks from different users can run on the same sandbox, as the same Linux user, one after another, and read-only is enforced only by file permissions. Row 3 implies this already ("without seeing each other" needs per-workload sandboxes), but stating it here keeps readers from assuming workflows 1 and 2 isolate users.
| tasks build up, such as cloned repositories. | ||
| - **Existing Context PVC:** a Context that already exists, used instead of a new upload, and | ||
| authorized by Context Service's per-user permissions rather than a PVC name. | ||
|
|
There was a problem hiding this comment.
nit: "Delegated tasks always mount it rather than copying from it" reads as if it contradicts rows 1 and 2, where delegated tasks get a copy. Maybe: "In per-workload sandboxes (#476), delegated tasks mount it rather than copying from it."
| **5. Reuse a remote dataset.** Upload the context once and keep it. Later workloads, in other | ||
| batches or days later, point at the same Context instead of uploading again. Unlike #2, the | ||
| Context outlives the workload that first used it. | ||
|
|
There was a problem hiding this comment.
nit: "The BugStone pipeline project" isn't defined anywhere a reader of this page would find it (only in passing in two specs). Either gloss it in a few words or drop the sentence.
Move the context workflows list to docs/concepts/ with a Preview line and index entries, use the MOCA spelling, state phase 1 limits and that shared sandboxes are not a security boundary, link Context Service's capture/restore for workflow 9, and say "workflow N" for cross-references. Also correct that under SH_REQUIRE_AUTH an unauthenticated workload run is 401 token_required first (missed #516). Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Jeremy Cohn <Jeremy.Cohn@ibm.com>
docs: address #514 review; workload runs need a token first
3 participants
Part of the work split out of #455 (the original context-delegation PR), which kept a workflows table inside the delegate skill.
Adds
docs/context-workflows.md: a living list of the ways we expect people to move context into and out of Moca. Ten workflows in three groups (delegate work from a laptop, keep context in Moca, move context between places), each with a short flow sketch, the sandbox and storage it uses, and its status, linked to #482, #494, #476 (phase 2: per-workload sandboxes and storage), #358 (per-user PVC authorization) and #495 (one CLI for delegating subagent tasks).The descriptions will keep improving; this gets the list into the repo so we can point at it and refine it in follow-up PRs.
🤖 Generated with Claude Code