docs(workflows): update runtime-setup, agent-workflow, code-review, troubleshooting EN+RU
This commit is contained in:
777genius
parent
1490da10f9
commit
75c7455ed9
2 changed files with 52 additions and 96 deletions
|
|
@ -2,84 +2,55 @@
|
|||
|
||||
Agent Teams makes agent work visible as task state, messages, logs, and reviewable code changes.
|
||||
|
||||
## Modes
|
||||
## Lifecycle
|
||||
|
||||
| Mode | Description |
|
||||
| --- | --- |
|
||||
| Solo | One teammate with self-managed tasks |
|
||||
| Team | Many teammates working in parallel, reviewing each other |
|
||||
|
||||
Both modes share the same kanban, task logs, and code review surfaces.
|
||||
|
||||
## Task lifecycle
|
||||
|
||||
| Stage | What happens | Owner |
|
||||
| --- | --- | --- |
|
||||
| Provisioning | The app starts the runtime, confirms the process is alive, and waits for bootstrap confirmation | App |
|
||||
| Planning | The lead creates tasks, optionally assigns teammates, and sets dependencies | Lead or user |
|
||||
| In progress | Agents work in parallel and update task state via board MCP tools | Teammates |
|
||||
| Review | Changes are reviewed by agents or by you before final acceptance | Team lead or user |
|
||||
| Done | Accepted work stays linked to its task history and can still be inspected later | User |
|
||||
|
||||
### Planning → In progress
|
||||
|
||||
When a teammate starts a task, the board status becomes `in_progress`. The agent creates a task comment with its plan and continues working. All native tool actions (read, bash, edit, write) are streamed into a task log.
|
||||
|
||||
### In progress → Review
|
||||
|
||||
When the teammate finishes work, it posts a result comment and marks the task `completed`. The lead can then decide whether to accept it immediately or move it into review.
|
||||
|
||||
### Review → Done
|
||||
|
||||
If the review surface shows acceptable changes, approve the review. The task is finalized and linked to its diff.
|
||||
|
||||
::: warning Fix-first review
|
||||
If a teammate is asked for changes during review, it should post a follow-up comment with the fixes, then the lead can approve.
|
||||
:::
|
||||
| Stage | What happens |
|
||||
|-------|--------------|
|
||||
| Provisioning | The app starts the team and confirms runtime readiness |
|
||||
| Planning | The lead creates tasks and may assign teammates |
|
||||
| In progress | Agents work in parallel and update task state |
|
||||
| Review | Changes are reviewed by agents or by you |
|
||||
| Done | Accepted work stays linked to its task history |
|
||||
|
||||
## Kanban board
|
||||
|
||||
The board is the primary operating surface. It lets you:
|
||||
|
||||
- Scan open, blocked, and in-review work
|
||||
- Open task detail and inspect runtime logs
|
||||
- Review changes without reading raw session files
|
||||
- Assign or reassign owners
|
||||
|
||||
::: tip
|
||||
Use quick action buttons on cards to start, complete, or request review without opening the detail panel.
|
||||
:::
|
||||
The board is the primary operating surface. It lets you scan work, spot blocked tasks, open task detail, inspect logs, and review changes without reading raw session files.
|
||||
|
||||
## Messages and comments
|
||||
|
||||
| Channel | When to use |
|
||||
| --- | --- |
|
||||
| Direct message | Redirect an agent, ask a quick question |
|
||||
| Task comment | Notes that belong to a specific task |
|
||||
Use **direct messages** when you need to redirect an agent or ask a quick question. Use **task comments** when the note belongs to a specific piece of work. Comments preserve context for later review.
|
||||
|
||||
Comments preserve context for later review and appear in the task timeline.
|
||||
::: tip
|
||||
Task comments are the durable delivery channel. Agents should post findings, decisions, and blockers in comments so the whole team can see them on the board.
|
||||
:::
|
||||
|
||||
::: tip Prefer task comments
|
||||
If the remark is about a specific task, add it as a comment on that task rather than sending a direct message. It keeps the history linked to the work.
|
||||
## Work-sync protocol
|
||||
|
||||
Agents follow a strict status cycle:
|
||||
|
||||
1. **Start** — mark the task `in_progress` when beginning real work.
|
||||
2. **Comment** — post a short note before doing follow-up fixes.
|
||||
3. **Reopen** — move the task back to `in_progress` for additional work.
|
||||
4. **Result comment** — post a summary of changes.
|
||||
5. **Complete** — mark the task `completed`.
|
||||
|
||||
::: warning
|
||||
Never skip the comment-and-status cycle. The board depends on accurate state to show what is actually happening.
|
||||
:::
|
||||
|
||||
## Task logs
|
||||
|
||||
Task-specific logs isolate runtime output, actions, and messages for one assignment. Use them to answer:
|
||||
Task-specific logs isolate runtime output, actions, and messages for one assignment. Use them when you need to answer:
|
||||
|
||||
- What did this agent run?
|
||||
- Why did it change this file?
|
||||
- Did it ask another teammate for help?
|
||||
- Which task produced this diff?
|
||||
|
||||
## Parallel work patterns
|
||||
|
||||
Teammates can work on independent tasks at the same time. You can also create dependency links (`blocked-by`) so that one task waits until another is complete. Watch the board for blocked lanes and reassign owners if one teammate is idle while another is overloaded.
|
||||
|
||||
## Live processes
|
||||
|
||||
The live process section shows URLs and running processes when agents start local servers or tools. Open URLs directly from the app to inspect results. Processes remain registered until they are explicitly stopped or the runtime exits.
|
||||
The live process section shows URLs and running processes when agents start local servers or tools. Open URLs directly from the app to inspect results.
|
||||
|
||||
## Cross-team communication
|
||||
|
||||
Agents can send messages to other teams when teams are linked. Use this for handoffs, shared libraries, or status checks between squads.
|
||||
Teams can send messages to each other. Use this to share findings, request reviews, or coordinate work across team boundaries without leaving the board.
|
||||
|
|
|
|||
|
|
@ -4,60 +4,45 @@ Code review in Agent Teams is task-centered. You inspect what changed for a spec
|
|||
|
||||
## Review surface
|
||||
|
||||
For each completed task that touched files, the review UI lets you:
|
||||
Use the review UI to:
|
||||
|
||||
- Inspect changed files with before/after context
|
||||
- Inspect changed files
|
||||
- Accept or reject individual hunks
|
||||
- Leave inline comments
|
||||
- Connect the diff back to the task description and agent logs
|
||||
- Leave comments
|
||||
- Connect the diff back to the task and agent logs
|
||||
|
||||
## Review lifecycle
|
||||
|
||||
When a task is ready for review:
|
||||
|
||||
1. The author marks it `completed`.
|
||||
2. A reviewer calls `review_start` to move the task into the **REVIEW** column.
|
||||
3. The reviewer inspects hunks and logs.
|
||||
4. If accepted, the reviewer calls `review_approve` to move the task to **APPROVED**.
|
||||
5. If changes are needed, the reviewer calls `review_request_changes` with a comment describing what to fix.
|
||||
|
||||
::: tip
|
||||
Approve the **work task** itself (e.g. `#1234`), not a separate "review task". The task ends in APPROVED, not DONE.
|
||||
:::
|
||||
|
||||
## Hunk-level decisions
|
||||
|
||||
Accept small correct changes and reject isolated mistakes without throwing away the whole task. This is useful when an agent mostly solved the task but overreached in one file.
|
||||
|
||||
::: tip Accept incrementally
|
||||
If a diff is mostly correct, accept the good hunks first and request changes only for the parts that need fixing. This keeps the board moving.
|
||||
:::
|
||||
|
||||
## Initiating review
|
||||
|
||||
1. Open a completed task
|
||||
2. Look at the **Changes** tab
|
||||
3. If the diff looks reasonable, click **Request Review** to move the task into the review column
|
||||
|
||||
During review the task is not yet considered done, so other teammates or the lead can still comment on it.
|
||||
|
||||
## Review states
|
||||
|
||||
| State | Meaning |
|
||||
| --- | --- |
|
||||
| `none` | Task is new, in progress, or completed but not yet in review |
|
||||
| `review` | The task is actively under review |
|
||||
| `needsFix` | Changes were requested; the owner must update before re-approval |
|
||||
| `approved` | The review was accepted and the task is finalized |
|
||||
|
||||
## Agent review workflow
|
||||
|
||||
Teams can review each other's work before you make the final call. This catches obvious regressions and keeps the board honest, but you should still review risky areas yourself.
|
||||
|
||||
## Review participants
|
||||
|
||||
The team lead is the default reviewer. You can configure additional reviewers in the Kanban settings if you want peers to review each other's work.
|
||||
|
||||
## What to check manually
|
||||
|
||||
Prioritize these areas when reviewing:
|
||||
Prioritize:
|
||||
|
||||
- **Provider auth and runtime detection** — did the agent change runtime setup in a way that would break other paths?
|
||||
- **IPC, preload, and filesystem boundaries** — keep Electron responsibilities separated
|
||||
- **Git and worktree behavior** — verify branch naming, commits, and pushes
|
||||
- **Parsing and task lifecycle logic** — changes to task references, chunking, or filtering can break message delivery
|
||||
- **Persistence and code review flows** — changes to task storage or review state must stay consistent across IPC layers
|
||||
- Provider auth and runtime detection
|
||||
- IPC, preload, and filesystem boundaries
|
||||
- Git and worktree behavior
|
||||
- Parsing and task lifecycle logic
|
||||
- Persistence and code review flows
|
||||
|
||||
## Verification
|
||||
|
||||
Prefer focused verification commands. Broad formatting or lint-fix commands should not be used unless the task explicitly intends broad formatting churn.
|
||||
|
||||
::: warning Do not auto-format across the whole project
|
||||
Unless the task is specifically about formatting, avoid running `pnpm lint:fix` on unrelated files. It creates noise in the review surface.
|
||||
:::
|
||||
|
|
|
|||
Loading…
Reference in a new issue