mirror of
https://github.com/rennf93/roboco.git
synced 2026-08-03 07:23:24 +02:00
docs: reflow hard-wrapped prose to one line per paragraph
Markdown and editors soft-wrap on their own, so the manual ~75-char line breaks across the docs added nothing but noise. Join wrapped prose, list items, and paragraphs into single lines across 67 docs — README, CLAUDE.md, deployment, usage, the RAG knowledge base, and the agent role prompts. Whitespace-only: code fences, tables, and blockquote alerts are byte-identical and the change is token-verified (no content altered). Applied with a deterministic reflow tool (committed separately). Also lands two doc edits that were awaiting commit: the measured under-load resource numbers in usage.md and the pr_reviewer additions to the org-structure RAG doc.
This commit is contained in:
Renn F
@@ -2,12 +2,9 @@
|
||||
|
||||
## Overview
|
||||
|
||||
Agents collaborate directly through two content tools on the `roboco-do`
|
||||
MCP server: `dm` for agent-to-agent messages and `say` for channel posts.
|
||||
Use `channels()` to discover the channels you can post to.
|
||||
Agents collaborate directly through two content tools on the `roboco-do` MCP server: `dm` for agent-to-agent messages and `say` for channel posts. Use `channels()` to discover the channels you can post to.
|
||||
|
||||
**Key:** A2A is about *existing* tasks, NOT task creation. Pass the
|
||||
`task_id` you're collaborating on so the message is linked to it.
|
||||
**Key:** A2A is about *existing* tasks, NOT task creation. Pass the `task_id` you're collaborating on so the message is linked to it.
|
||||
|
||||
## Flow
|
||||
|
||||
@@ -29,9 +26,7 @@ dm(
|
||||
)
|
||||
```
|
||||
|
||||
Cross-cell `dm` is **denied by policy**. If you need something from
|
||||
another cell, route it through your Cell PM via `escalate_up(task_id,
|
||||
reason)` — the PM coordinates across cells.
|
||||
Cross-cell `dm` is **denied by policy**. If you need something from another cell, route it through your Cell PM via `escalate_up(task_id, reason)` — the PM coordinates across cells.
|
||||
|
||||
## Channel Posts
|
||||
|
||||
@@ -44,13 +39,11 @@ say(
|
||||
)
|
||||
```
|
||||
|
||||
Call `channels()` first if you're unsure of the exact slug — it returns
|
||||
the channels you're allowed to post to, so you don't have to guess.
|
||||
Call `channels()` first if you're unsure of the exact slug — it returns the channels you're allowed to post to, so you don't have to guess.
|
||||
|
||||
## Task Creation Rules
|
||||
|
||||
**Only PMs create tasks** (via the `delegate` verb). Regular agents
|
||||
cannot create work from a `dm` or `say`.
|
||||
**Only PMs create tasks** (via the `delegate` verb). Regular agents cannot create work from a `dm` or `say`.
|
||||
|
||||
If a conversation surfaces work that needs a new task:
|
||||
1. Escalate to your Cell PM: `escalate_up(task_id, reason="Needs a subtask for X")`
|
||||
@@ -58,12 +51,8 @@ If a conversation surfaces work that needs a new task:
|
||||
|
||||
## Permissions
|
||||
|
||||
Most roles can `dm` (same-cell) and `say` to their channels, plus read
|
||||
their inbox with `notify_list` / `notify_get`.
|
||||
Most roles can `dm` (same-cell) and `say` to their channels, plus read their inbox with `notify_list` / `notify_get`.
|
||||
|
||||
The **Auditor** is a silent observer: it can read (`notify_list`,
|
||||
`notify_get`, `channels`) but has **no** `say`, `dm`, or `notify` — it
|
||||
never communicates outwardly.
|
||||
The **Auditor** is a silent observer: it can read (`notify_list`, `notify_get`, `channels`) but has **no** `say`, `dm`, or `notify` — it never communicates outwardly.
|
||||
|
||||
Only PMs and the Board can send ack-required `notify` signals; regular
|
||||
agents use `say` and `dm` only.
|
||||
Only PMs and the Board can send ack-required `notify` signals; regular agents use `say` and `dm` only.
|
||||
|
||||
@@ -14,14 +14,9 @@ Developer/QA/Documenter
|
||||
CEO
|
||||
```
|
||||
|
||||
`escalate_up` walks this chain **one rung at a time** — it auto-routes to
|
||||
your immediate escalation target; you cannot choose a higher level or skip
|
||||
a rung.
|
||||
`escalate_up` walks this chain **one rung at a time** — it auto-routes to your immediate escalation target; you cannot choose a higher level or skip a rung.
|
||||
|
||||
The one exception is `escalate_to_ceo`: it is a **separate** verb,
|
||||
available only to Main PM and the Board (Product Owner / Head of
|
||||
Marketing), that goes straight to the CEO for final approval of a major
|
||||
task. It is not part of the `escalate_up` chain.
|
||||
The one exception is `escalate_to_ceo`: it is a **separate** verb, available only to Main PM and the Board (Product Owner / Head of Marketing), that goes straight to the CEO for final approval of a major task. It is not part of the `escalate_up` chain.
|
||||
|
||||
## How to Escalate (up one rung)
|
||||
|
||||
@@ -51,9 +46,7 @@ Auto-routes to your escalation target (you cannot choose it).
|
||||
| **Escalate** | Need a decision / help from above | `escalate_up` |
|
||||
| **Block** | Can't proceed on an external dependency | `i_am_blocked` |
|
||||
|
||||
There is no agent-facing "pause" verb. If you need to step off a task you
|
||||
claimed but haven't progressed, use `unclaim(task_id)` to return it to
|
||||
the pool.
|
||||
There is no agent-facing "pause" verb. If you need to step off a task you claimed but haven't progressed, use `unclaim(task_id)` to return it to the pool.
|
||||
|
||||
## Blocking a Task
|
||||
|
||||
@@ -85,8 +78,7 @@ Requirements:
|
||||
- Only Main PM, Product Owner, or Head of Marketing can call it
|
||||
- **PARENT TASKS ONLY** — subtasks cannot be escalated to CEO
|
||||
|
||||
If you need to escalate a subtask, escalate the parent task instead. The
|
||||
CEO reviews the complete feature, not individual components.
|
||||
If you need to escalate a subtask, escalate the parent task instead. The CEO reviews the complete feature, not individual components.
|
||||
|
||||
## Good Escalation Format
|
||||
|
||||
@@ -105,5 +97,4 @@ Include:
|
||||
4. Communicate the decision (`say` / `dm` / `notify`)
|
||||
5. Unblock if needed: `unblock(task_id)`
|
||||
|
||||
CRITICAL: Verbal resolution is NOT enough. To clear a block you MUST call
|
||||
`unblock(task_id)`.
|
||||
CRITICAL: Verbal resolution is NOT enough. To clear a block you MUST call `unblock(task_id)`.
|
||||
|
||||
@@ -19,18 +19,13 @@ Links:
|
||||
- Journal: {api}/journals/{agent-slug}
|
||||
```
|
||||
|
||||
**Required:** the conventional `type` (feat, fix, chore, docs, refactor,
|
||||
test, style, perf, ci, build) at the start of the subject. The
|
||||
`commit_validator` rejects messages that don't start with one of these
|
||||
followed by `(scope)?:`.
|
||||
**Required:** the conventional `type` (feat, fix, chore, docs, refactor, test, style, perf, ci, build) at the start of the subject. The `commit_validator` rejects messages that don't start with one of these followed by `(scope)?:`.
|
||||
|
||||
**Optional:** `scope` (api, auth, db, ui), `body`, the `files` argument
|
||||
to scope the commit.
|
||||
**Optional:** `scope` (api, auth, db, ui), `body`, the `files` argument to scope the commit.
|
||||
|
||||
## How to commit
|
||||
|
||||
Use the **`commit`** verb on the roboco-do MCP — devs and documenters
|
||||
only. There is no `roboco_git_commit` tool.
|
||||
Use the **`commit`** verb on the roboco-do MCP — devs and documenters only. There is no `roboco_git_commit` tool.
|
||||
|
||||
```python
|
||||
commit(
|
||||
@@ -50,5 +45,4 @@ The choreographer:
|
||||
6. Pushes to the agent's branch on origin
|
||||
7. Records the commit on the task (`commits[]` field on `TaskTable`)
|
||||
|
||||
You don't need a separate `push` step. There is no `roboco_git_push`
|
||||
tool.
|
||||
You don't need a separate `push` step. There is no `roboco_git_push` tool.
|
||||
|
||||
@@ -10,17 +10,13 @@ All commits are automatically prefixed with the task ID by the choreographer:
|
||||
|
||||
Example: `[a1b2c3d4] Add rate limiting endpoint`
|
||||
|
||||
You write the message — the prefix is added for you. Don't include
|
||||
`[task-id]` yourself; it gets stripped and re-applied.
|
||||
You write the message — the prefix is added for you. Don't include `[task-id]` yourself; it gets stripped and re-applied.
|
||||
|
||||
## Who Can Commit
|
||||
|
||||
`commit` is in the **roboco-do** MCP and is mounted only for **developers**
|
||||
and **documenters**. PMs delegate code work and call `complete` to merge.
|
||||
`commit` is in the **roboco-do** MCP and is mounted only for **developers** and **documenters**. PMs delegate code work and call `complete` to merge.
|
||||
|
||||
There is **no** `roboco_git_commit / _push / _create_pr` MCP tool. The
|
||||
single `commit` verb covers commit + push + PR-trigger via the
|
||||
choreographer.
|
||||
There is **no** `roboco_git_commit / _push / _create_pr` MCP tool. The single `commit` verb covers commit + push + PR-trigger via the choreographer.
|
||||
|
||||
## Creating Commits
|
||||
|
||||
@@ -38,8 +34,7 @@ This automatically:
|
||||
3. Stages the listed files (or everything tracked + modified if omitted)
|
||||
4. Pushes to the agent's auto-created branch
|
||||
5. Records the commit on the task (`commits[]` field on `TaskTable`)
|
||||
6. Opens a PR through the choreographer when the task transitions out of
|
||||
`in_progress` (no separate `create_pr` call required)
|
||||
6. Opens a PR through the choreographer when the task transitions out of `in_progress` (no separate `create_pr` call required)
|
||||
|
||||
## Before Committing
|
||||
|
||||
@@ -50,13 +45,10 @@ This automatically:
|
||||
|
||||
## After Committing
|
||||
|
||||
You don't push or create a PR yourself. The choreographer pushed the
|
||||
commit during `commit()`, and the PR is opened/merged as part of the
|
||||
lifecycle transitions:
|
||||
You don't push or create a PR yourself. The choreographer pushed the commit during `commit()`, and the PR is opened/merged as part of the lifecycle transitions:
|
||||
|
||||
- `open_pr(task_id)` — opens the PR (devs)
|
||||
- `pass(task_id)` (QA) → `i_documented(task_id)` (doc) → `complete(task_id)`
|
||||
(cell PM merges the leaf PR; main PM opens the master PR)
|
||||
- `pass(task_id)` (QA) → `i_documented(task_id)` (doc) → `complete(task_id)` (cell PM merges the leaf PR; main PM opens the master PR)
|
||||
|
||||
## Viewing Commits and History
|
||||
|
||||
|
||||
@@ -7,29 +7,18 @@
|
||||
|
||||
## How PRs Are Created
|
||||
|
||||
There is **no** `roboco_git_create_pr` MCP tool. PRs are side-effects of
|
||||
lifecycle transitions, driven by the choreographer:
|
||||
There is **no** `roboco_git_create_pr` MCP tool. PRs are side-effects of lifecycle transitions, driven by the choreographer:
|
||||
|
||||
- **Leaf PR (cell-scoped, `is_root_pr=False`)**:
|
||||
Opened automatically when the assigned developer calls
|
||||
`open_pr(task_id)` after their `commit(...)` calls. Merged when
|
||||
the Cell PM calls `complete(task_id, notes)` after QA + docs sign off.
|
||||
- **Leaf PR (cell-scoped, `is_root_pr=False`)**: Opened automatically when the assigned developer calls `open_pr(task_id)` after their `commit(...)` calls. Merged when the Cell PM calls `complete(task_id, notes)` after QA + docs sign off.
|
||||
|
||||
- **Master PR (`is_root_pr=True`)**:
|
||||
Opened by the choreographer when the **Main PM** calls
|
||||
`complete(task_id, notes)` on the root parent task. Merged by the CEO
|
||||
via the dashboard once all cell-scoped PRs have been merged into it.
|
||||
- **Master PR (`is_root_pr=True`)**: Opened by the choreographer when the **Main PM** calls `complete(task_id, notes)` on the root parent task. Merged by the CEO via the dashboard once all cell-scoped PRs have been merged into it.
|
||||
|
||||
Title and body are generated from the task templates in
|
||||
`roboco/templates/git/pr_*.py`. Don't hand-write PR descriptions in the
|
||||
agent prompts — they'll be overridden.
|
||||
Title and body are generated from the task templates in `roboco/templates/git/pr_*.py`. Don't hand-write PR descriptions in the agent prompts — they'll be overridden.
|
||||
|
||||
## Auto-Checkout
|
||||
|
||||
Branches and checkout are handled automatically:
|
||||
|
||||
- `i_will_work_on(task_id)` (devs) creates the task's branch and checks it
|
||||
out in the agent's workspace.
|
||||
- `i_will_work_on(task_id)` (devs) creates the task's branch and checks it out in the agent's workspace.
|
||||
- `i_will_plan(task_id, plan)` (PMs) does the same for parent tasks.
|
||||
- Workspace dirty? The verb returns an error envelope; clean up first
|
||||
with `commit(...)` or escalate via `i_am_blocked(task_id, reason)`.
|
||||
- Workspace dirty? The verb returns an error envelope; clean up first with `commit(...)` or escalate via `i_am_blocked(task_id, reason)`.
|
||||
|
||||
@@ -9,9 +9,7 @@
|
||||
|
||||
## The Tool
|
||||
|
||||
Journaling is a single content tool: `note(text, scope, ...)` on the
|
||||
`roboco-do` MCP server. There is **no** separate `roboco_journal_*` tool —
|
||||
the `scope` argument selects the kind of entry.
|
||||
Journaling is a single content tool: `note(text, scope, ...)` on the `roboco-do` MCP server. There is **no** separate `roboco_journal_*` tool — the `scope` argument selects the kind of entry.
|
||||
|
||||
| `scope` | Use For |
|
||||
|---------|---------|
|
||||
@@ -55,9 +53,7 @@ note(
|
||||
)
|
||||
```
|
||||
|
||||
`options`, `consequences`, and `next_steps` accept either a list or a
|
||||
single value. For `decision` and `reflect` scopes the structured fields
|
||||
are recommended; the note is always recorded even if some are omitted.
|
||||
`options`, `consequences`, and `next_steps` accept either a list or a single value. For `decision` and `reflect` scopes the structured fields are recommended; the note is always recorded even if some are omitted.
|
||||
|
||||
## Required Reflections
|
||||
|
||||
@@ -77,8 +73,7 @@ note(
|
||||
|
||||
## Searching Journals
|
||||
|
||||
Journal entries are indexed into the knowledge base. Search them through
|
||||
the `roboco-optimal` RAG tools (there is no dedicated journal-search verb):
|
||||
Journal entries are indexed into the knowledge base. Search them through the `roboco-optimal` RAG tools (there is no dedicated journal-search verb):
|
||||
|
||||
```python
|
||||
# Semantic search across the KB, filtered to journal entries
|
||||
|
||||
@@ -2,15 +2,11 @@
|
||||
|
||||
## When PRs Are Created
|
||||
|
||||
PRs are opened **before** QA review, not during `awaiting_documentation`.
|
||||
The choreographer creates the PR as a side-effect of the developer's
|
||||
`open_pr(task_id)` transition (`verifying → awaiting_qa`).
|
||||
PRs are opened **before** QA review, not during `awaiting_documentation`. The choreographer creates the PR as a side-effect of the developer's `open_pr(task_id)` transition (`verifying → awaiting_qa`).
|
||||
|
||||
This is by design: QA reviews the real PR diff on GitHub, and the
|
||||
downstream PM/CEO approval chain operates on a PR that already exists.
|
||||
This is by design: QA reviews the real PR diff on GitHub, and the downstream PM/CEO approval chain operates on a PR that already exists.
|
||||
|
||||
You do **not** call any tool to create a PR. There is no
|
||||
`roboco_git_create_pr` MCP tool.
|
||||
You do **not** call any tool to create a PR. There is no `roboco_git_create_pr` MCP tool.
|
||||
|
||||
## How the dev triggers it
|
||||
|
||||
@@ -27,28 +23,22 @@ open_pr(task_id="<task>")
|
||||
|
||||
The transition enforces (`enforcement/task_lifecycle.py`):
|
||||
|
||||
- `self_verified=True` — set when you call `i_am_done()` or
|
||||
`verify(task_id)` first
|
||||
- `self_verified=True` — set when you call `i_am_done()` or `verify(task_id)` first
|
||||
- `commits` non-empty — at least one commit on the task
|
||||
- `progress_updates` non-empty — at least one note on what changed
|
||||
- `pr_number` is set automatically by the choreographer; you don't pass it
|
||||
|
||||
If any precondition is missing, the verb returns an envelope explaining
|
||||
what's missing and how to remediate.
|
||||
If any precondition is missing, the verb returns an envelope explaining what's missing and how to remediate.
|
||||
|
||||
## PR Title and Body
|
||||
|
||||
Generated from templates in `roboco/templates/git/pr_internal.py` and
|
||||
`roboco/templates/git/pr_root.py`. You don't write the body by hand —
|
||||
it's filled with task title, acceptance criteria, the dev's notes, and
|
||||
the standard traceability links.
|
||||
Generated from templates in `roboco/templates/git/pr_internal.py` and `roboco/templates/git/pr_root.py`. You don't write the body by hand — it's filled with task title, acceptance criteria, the dev's notes, and the standard traceability links.
|
||||
|
||||
Title format: `[TASK-{root-id:8}:{task-id:8}] {task-title}`.
|
||||
|
||||
## Parallel Documenter Phase
|
||||
|
||||
After QA passes, the task transitions to `awaiting_documentation` and
|
||||
runs documenter + dev in parallel:
|
||||
After QA passes, the task transitions to `awaiting_documentation` and runs documenter + dev in parallel:
|
||||
|
||||
| Agent | Action | Flag set |
|
||||
|-------|--------|----------|
|
||||
@@ -59,35 +49,25 @@ Task transitions to `awaiting_pm_review` when both are true.
|
||||
|
||||
## PM Merges via `complete`
|
||||
|
||||
After `awaiting_pm_review`, the Cell PM calls `complete(task_id, notes)`.
|
||||
The choreographer:
|
||||
After `awaiting_pm_review`, the Cell PM calls `complete(task_id, notes)`. The choreographer:
|
||||
|
||||
1. Verifies all subtasks are in a terminal state
|
||||
2. Verifies the PR is reviewable
|
||||
3. Merges the leaf PR into the parent branch (squash by default)
|
||||
4. Transitions the task to `completed`
|
||||
|
||||
For the root parent, **Main PM**'s `complete` opens the master PR and
|
||||
escalates to CEO via `escalate_to_ceo` semantics.
|
||||
For the root parent, **Main PM**'s `complete` opens the master PR and escalates to CEO via `escalate_to_ceo` semantics.
|
||||
|
||||
There is no `roboco_git_merge_pr` MCP tool.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **Git token:** the project must have an encrypted GitHub PAT set on
|
||||
`projects.git_token_encrypted`. Without it, the workspace clone — and
|
||||
therefore everything downstream — fails with `WorkspaceError`.
|
||||
- **Git token:** the project must have an encrypted GitHub PAT set on `projects.git_token_encrypted`. Without it, the workspace clone — and therefore everything downstream — fails with `WorkspaceError`.
|
||||
- **Token scope:** `repo` (for branch push, PR create, PR merge).
|
||||
- **Default branch:** `projects.default_branch` is the merge target for
|
||||
the master PR (typically `master`).
|
||||
- **Default branch:** `projects.default_branch` is the merge target for the master PR (typically `master`).
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- `NO_COMMITS` on `open_pr` → call `commit(...)` first; nothing to
|
||||
open a PR over.
|
||||
- `NO_PR` on `pass`/`fail` → the choreographer didn't open a PR; check
|
||||
the workspace state with `roboco_git_status` and re-call
|
||||
`open_pr` once the workspace is clean.
|
||||
- `FORCE_PUSH_FORBIDDEN` → only the CEO may force-push. If your branch
|
||||
diverged, `unclaim` and re-`claim` the task; the choreographer
|
||||
rebuilds the branch.
|
||||
- `NO_COMMITS` on `open_pr` → call `commit(...)` first; nothing to open a PR over.
|
||||
- `NO_PR` on `pass`/`fail` → the choreographer didn't open a PR; check the workspace state with `roboco_git_status` and re-call `open_pr` once the workspace is clean.
|
||||
- `FORCE_PUSH_FORBIDDEN` → only the CEO may force-push. If your branch diverged, `unclaim` and re-`claim` the task; the choreographer rebuilds the branch.
|
||||
|
||||
@@ -3,8 +3,7 @@
|
||||
## Preconditions
|
||||
|
||||
- Task is in `awaiting_qa` status
|
||||
- The developer's PR is open (the choreographer opened it during their
|
||||
`open_pr(task_id)` call)
|
||||
- The developer's PR is open (the choreographer opened it during their `open_pr(task_id)` call)
|
||||
- You are not the original developer of the task (self-review guard)
|
||||
|
||||
## Steps
|
||||
@@ -39,9 +38,7 @@ note(text="Verified AC #1 (429 on 101st req), #2 (TTL match), #3 "
|
||||
task_id="<task>")
|
||||
```
|
||||
|
||||
There is no `roboco_task_claim / _start / _qa_pass / _qa_fail` and no
|
||||
`roboco_git_checkout`. The verbs above (`claim_review`, `pass`, `fail`)
|
||||
are the actual surface; branch checkout is a side-effect of `claim_review`.
|
||||
There is no `roboco_task_claim / _start / _qa_pass / _qa_fail` and no `roboco_git_checkout`. The verbs above (`claim_review`, `pass`, `fail`) are the actual surface; branch checkout is a side-effect of `claim_review`.
|
||||
|
||||
## Review Checklist
|
||||
|
||||
@@ -72,8 +69,7 @@ Result:
|
||||
|
||||
- Task advances to `awaiting_documentation`
|
||||
- Documenter and the original dev work in parallel from here
|
||||
- The PR stays open; it will be merged later by the Cell PM via
|
||||
`complete(task_id, ...)`
|
||||
- The PR stays open; it will be merged later by the Cell PM via `complete(task_id, ...)`
|
||||
|
||||
## Failing QA
|
||||
|
||||
@@ -111,14 +107,10 @@ note(
|
||||
|
||||
## Self-Review Prevention
|
||||
|
||||
The system blocks QA from reviewing their own dev work. The original
|
||||
developer is recorded in `quick_context` at submit-for-qa time. If
|
||||
`qa_agent_id == original_developer_id`, **all** QA actions on the task
|
||||
return `not_authorized`:
|
||||
The system blocks QA from reviewing their own dev work. The original developer is recorded in `quick_context` at submit-for-qa time. If `qa_agent_id == original_developer_id`, **all** QA actions on the task return `not_authorized`:
|
||||
|
||||
- `claim_review` — FORBIDDEN
|
||||
- `pass` — FORBIDDEN (defence-in-depth even if claim somehow succeeded)
|
||||
- `fail` — FORBIDDEN (same)
|
||||
|
||||
Enforced at the gateway layer in
|
||||
`roboco/services/gateway/choreographer/_impl.py`.
|
||||
Enforced at the gateway layer in `roboco/services/gateway/choreographer/_impl.py`.
|
||||
|
||||
@@ -25,9 +25,7 @@ claim_doc_task(task_id) # Documenter
|
||||
# - assigned_to: your agent ID
|
||||
```
|
||||
|
||||
The claim verb both claims and starts the task — there is no separate
|
||||
`start` call. For developers, `i_will_work_on` also creates and checks
|
||||
out the `feature/{team}/{task-hierarchy}` branch.
|
||||
The claim verb both claims and starts the task — there is no separate `start` call. For developers, `i_will_work_on` also creates and checks out the `feature/{team}/{task-hierarchy}` branch.
|
||||
|
||||
## Before Claiming
|
||||
|
||||
@@ -62,9 +60,7 @@ unclaim(task_id)
|
||||
# - You can now claim new work
|
||||
```
|
||||
|
||||
`unclaim` takes only the `task_id` — it returns the task to the pool for
|
||||
re-pickup. To hand a specific task to a specific agent, escalate to your
|
||||
PM (`escalate_up`) and let the PM re-`delegate` or reassign it.
|
||||
`unclaim` takes only the `task_id` — it returns the task to the pool for re-pickup. To hand a specific task to a specific agent, escalate to your PM (`escalate_up`) and let the PM re-`delegate` or reassign it.
|
||||
|
||||
**When to use unclaim:**
|
||||
- Task is out of your team's scope
|
||||
|
||||
@@ -2,17 +2,13 @@
|
||||
|
||||
## Overview
|
||||
|
||||
Planning is a **PM activity**. When a PM (Cell PM or Main PM) picks up a
|
||||
coordination or parent task, they record a plan with `i_will_plan` and
|
||||
then fan the work out into subtasks with `delegate`.
|
||||
Planning is a **PM activity**. When a PM (Cell PM or Main PM) picks up a coordination or parent task, they record a plan with `i_will_plan` and then fan the work out into subtasks with `delegate`.
|
||||
|
||||
```
|
||||
triage / give_me_work → i_will_plan → delegate (one per subtask) → i_am_idle
|
||||
```
|
||||
|
||||
Developers do not have a separate planning verb — they pass a short
|
||||
`plan` argument directly to `i_will_work_on(task_id, plan="...")` when
|
||||
they claim a coding task.
|
||||
Developers do not have a separate planning verb — they pass a short `plan` argument directly to `i_will_work_on(task_id, plan="...")` when they claim a coding task.
|
||||
|
||||
## Submitting a Plan (PM)
|
||||
|
||||
@@ -32,8 +28,7 @@ i_will_plan(
|
||||
)
|
||||
```
|
||||
|
||||
After `i_will_plan`, the envelope's `next` field points you at
|
||||
`delegate` — create one subtask per unit of work:
|
||||
After `i_will_plan`, the envelope's `next` field points you at `delegate` — create one subtask per unit of work:
|
||||
|
||||
```python
|
||||
delegate(
|
||||
@@ -52,61 +47,37 @@ delegate(
|
||||
|
||||
## Acceptance-Criteria Coverage
|
||||
|
||||
When you decompose a parent task, declare which parent criteria each subtask is
|
||||
responsible for with **`covers_parent_criteria`** (a list of the parent's
|
||||
`acceptance_criteria_ids`). This is what lets the org prove a decomposition
|
||||
covers the parent's full intent — and it drives two gates and your coverage
|
||||
briefing.
|
||||
When you decompose a parent task, declare which parent criteria each subtask is responsible for with **`covers_parent_criteria`** (a list of the parent's `acceptance_criteria_ids`). This is what lets the org prove a decomposition covers the parent's full intent — and it drives two gates and your coverage briefing.
|
||||
|
||||
After `i_will_plan` and after each `delegate`, your envelope carries a coverage
|
||||
view of the parent so you can see what is still unmapped:
|
||||
After `i_will_plan` and after each `delegate`, your envelope carries a coverage view of the parent so you can see what is still unmapped:
|
||||
|
||||
- **`parent_ac_coverage`** — one entry per parent criterion: its `id`, `text`,
|
||||
whether a live subtask `claimed` it, and whether a completed subtask
|
||||
`verified` it.
|
||||
- **`unclaimed_parent_acs`** — the parent criterion ids that no live subtask
|
||||
covers yet. Keep delegating until this is empty.
|
||||
- **`parent_ac_coverage`** — one entry per parent criterion: its `id`, `text`, whether a live subtask `claimed` it, and whether a completed subtask `verified` it.
|
||||
- **`unclaimed_parent_acs`** — the parent criterion ids that no live subtask covers yet. Keep delegating until this is empty.
|
||||
|
||||
Two gates build on the coverage link:
|
||||
|
||||
- **Decomposition floor** — you cannot go `i_am_idle` on a parent while a
|
||||
criterion is still unclaimed. Delegate (or `reassign`) subtasks until every
|
||||
criterion is covered.
|
||||
- **Roll-up gate** — a parent cannot `complete`, `submit_up`, or
|
||||
`escalate_to_ceo` unless every criterion traces to a child that **passed QA**
|
||||
on it.
|
||||
- **Decomposition floor** — you cannot go `i_am_idle` on a parent while a criterion is still unclaimed. Delegate (or `reassign`) subtasks until every criterion is covered.
|
||||
- **Roll-up gate** — a parent cannot `complete`, `submit_up`, or `escalate_to_ceo` unless every criterion traces to a child that **passed QA** on it.
|
||||
|
||||
Both gates are **safe-by-construction**: they stay inert until you start
|
||||
declaring `covers_parent_criteria`, so a decomposition that never declares
|
||||
coverage is never blocked. Declaring coverage is how you opt your parent into
|
||||
the guarantee.
|
||||
Both gates are **safe-by-construction**: they stay inert until you start declaring `covers_parent_criteria`, so a decomposition that never declares coverage is never blocked. Declaring coverage is how you opt your parent into the guarantee.
|
||||
|
||||
## Delegating Code Work: Per-Dev Queues
|
||||
|
||||
For code subtasks, delegate each developer their **full queue up front** rather
|
||||
than one task at a time. Both of a cell's developers build in parallel, and each
|
||||
works its own queue one task at a time, in order:
|
||||
For code subtasks, delegate each developer their **full queue up front** rather than one task at a time. Both of a cell's developers build in parallel, and each works its own queue one task at a time, in order:
|
||||
|
||||
- A per-lane dispatch barrier holds a developer's later subtasks until their
|
||||
current one is in flight — so each dev's lane stays sequenced while the two
|
||||
devs run concurrently.
|
||||
- Leaf PRs are still merged into the shared cell branch **in sequence**, not
|
||||
in parallel.
|
||||
- A per-lane dispatch barrier holds a developer's later subtasks until their current one is in flight — so each dev's lane stays sequenced while the two devs run concurrently.
|
||||
- Leaf PRs are still merged into the shared cell branch **in sequence**, not in parallel.
|
||||
- Order the queue by dependency: the subtask others build on goes first.
|
||||
|
||||
Caps still apply: at most 12 subtasks per parent, and same-title duplicate
|
||||
subtasks are rejected.
|
||||
Caps still apply: at most 12 subtasks per parent, and same-title duplicate subtasks are rejected.
|
||||
|
||||
## Git Workflow
|
||||
|
||||
All code tasks follow the git workflow:
|
||||
- **Branches are auto-created when a developer claims the task** via
|
||||
`i_will_work_on` — no manual branch creation
|
||||
- **Branches are auto-created when a developer claims the task** via `i_will_work_on` — no manual branch creation
|
||||
- Root tasks: branch created from the default branch (main/master)
|
||||
- Subtasks: branch forked from the parent's branch
|
||||
|
||||
Coordination/parent tasks that only plan and delegate (no code) do not
|
||||
need a branch of their own.
|
||||
Coordination/parent tasks that only plan and delegate (no code) do not need a branch of their own.
|
||||
|
||||
Hierarchical branch naming uses `--` between task IDs to avoid git ref
|
||||
conflicts: `feature/{team}/{ROOT}--{SUB}--{SUBSUB}`.
|
||||
Hierarchical branch naming uses `--` between task IDs to avoid git ref conflicts: `feature/{team}/{ROOT}--{SUB}--{SUBSUB}`.
|
||||
|
||||
@@ -73,8 +73,4 @@ backlog → pending (a PM activates the task during `triage`)
|
||||
|
||||
## Checking State
|
||||
|
||||
You don't poll task state directly — every flow verb returns a
|
||||
standardized envelope whose `status` and `next` fields tell you the
|
||||
task's current state and what to call next. Trust the envelope rather
|
||||
than guessing. To pull the full task context (criteria, prior notes,
|
||||
handoff), call `evidence(task_id)`.
|
||||
You don't poll task state directly — every flow verb returns a standardized envelope whose `status` and `next` fields tell you the task's current state and what to call next. Trust the envelope rather than guessing. To pull the full task context (criteria, prior notes, handoff), call `evidence(task_id)`.
|
||||
|
||||
Reference in New Issue
Block a user