Example walkthroughs

This page walks through Agentweaver from project creation to reviewed work. Collective gates depend on the selected workflow. For built-in software workflows:

children: Agent → Assemble-ready
combined output: RAI → Build & Test → Human review → Merge → Scribe

The shared canonical-default-workflow image is awaiting owner reconciliation of collective inputs, applicable Build & Test, and coordinator-driven revision. Until promotion, the textual pipeline and review guide describe current behavior. Children do not run their own RAI, human review, merge, or Scribe.

---

Scenario 1 — Create a project, cast a team, run the default workflow, review and merge

This is the define-outcome path with autopilot off for software delivery, not the direct-start or unattended-confirmation path.

1. Create a project

From the Project Gallery (/projects), choose a creation path:

• Create blank project — enter a name and a repository folder. Agentweaver initializes an empty git repository (POST /api/projects with origin: blank).
• Create from GitHub — enter a name, select a Repo App-authorized repository, and a folder. Agentweaver first reserves a trackable project, then clones it after consuming an opaque repository_selection_code (POST /api/projects with origin: github). A disconnected client does not cancel work after that reservation. Retrying the same still-valid selection code returns the same creating, active, or failed project instead of creating another workspace.

You land on the project Dashboard (/projects/{id}).

2. Cast a team

Open Team → Cast (the Casting Wizard at /projects/{id}/team/cast). The wizard offers three strategies:

Strategy (UI tab)	What it does	API
Formulate	Describe the goal in plain language; the wizard proposes a roster	POST /api/projects/{id}/casting/proposals (mode: free_text, goal)
Template	Pick a predefined team template (e.g. Quick Software Development)	GET /api/casting/templates, then POST .../casting/proposals (mode: scenario, template_id)
Analyze	The wizard reads the project files and suggests a best-fit team	POST .../casting/proposals (mode: analysis)

(A manual mode also exists, which takes an explicit role_ids list.)

Review the proposed members, amend if needed (PATCH .../casting/proposals/{proposalId}), then Confirm (POST .../casting/proposals/{proposalId}/confirm). The casting algorithm assigns named personas from a thematic universe (The Matrix, Star Wars, and others) to each role, and the team is recorded. See Agent Teams & Blueprints.

3. Start the orchestration

From the project Board (/projects/{id}/board), click Start orchestration and enter a goal:

"Add input validation to the signup form and cover it with unit tests."

This calls POST /api/projects/{id}/orchestrations and takes you to the coordinator run page (/projects/{id}/orchestrations/{runId}).

4. Confirm the OutcomeSpec

The coordinator drafts an OutcomeSpec — goal, desired outcome, scope, and assumptions — and emits a coordinator.outcome_spec event. No agent work starts until you confirm it.

• Confirm: POST /api/runs/{runId}/outcome-spec/confirm
• Revise with feedback: POST /api/runs/{runId}/outcome-spec/revise

5. Watch the WorkPlan and topology

On confirmation, the coordinator decomposes the spec into a WorkPlan (coordinator.work_plan) — a dependency graph of subtasks. It dispatches independent subtasks in parallel, each in its own isolated git worktree. The topology view streams live over SSE (GET /api/runs/{runId}/stream); you can also fetch the plan (GET /api/runs/{runId}/work-plan) and child runs (GET /api/runs/{runId}/children).

Each child emits subtask.dispatched → subtask.running → subtask.assemble_ready. While the orchestration is active you can steer it (POST /api/runs/{runId}/steer) — send a directive, redirect a child, or stop the run.

6. Review and merge the assembled diff

When children reach assemble-ready, the coordinator combines their output and runs the selected collective gates, including RAI and applicable Build & Test. When the run reaches Human Review, open the file panel:

• Changes lists modified files (GET /api/runs/{runId}/files); click any file for a diff (GET /api/runs/{runId}/files/{path}).
• Commit and Merge approves and merges to the originating branch: POST /api/runs/{runId}/review with approved: true (or POST /api/runs/{runId}/commit).
• Change requests a revision: POST /api/runs/{runId}/review with request_changes and feedback — the coordinator decides how to steer or dispatch the required work.
• Decline discards the work: POST /api/runs/{runId}/review with approved: false.

If the target branch has moved, the merge may report conflicting files (merge.conflicted); the worktree is preserved for manual resolution.

7. Scribe records what the team learned

After successful merge, Scribe records the session and promotes only low-risk learning, pattern, and update entries attributed to that completed run. architectural/scope entries remain for owner/coordinator review. Structured trust records are authoritative; files are inspectable mirrors. See Team Memory.

---

Scenario 2 — Pick up a backlog task with the board and heartbeat

Use the Kanban board to queue work and let the heartbeat dispatch it.

1. Capture a task in the Backlog column (POST /api/projects/{id}/backlog/tasks). Add a description for context — sharper descriptions produce sharper OutcomeSpecs.
2. Rank the backlog by dragging cards (POST .../backlog/tasks/{taskId}/reorder), and optionally pin a workflow per card (PUT .../backlog/tasks/{taskId}/workflow-override).
3. Move to Ready when the task is ready to run (POST .../backlog/tasks/{taskId}/ready), or send everything at once (POST .../backlog/ready-all).
4. The heartbeat claims Ready tasks up to the concurrency limit and starts a coordinator orchestration for each, moving the card to Active. Inspect status on the Heartbeat page (GET /api/diagnostics/heartbeat).
5. When approval is needed, open Human Review as in Scenario 1. Failed runs land in Problems; inspect diagnostics and use explicit retry/recovery controls. Dragging is supported only between Backlog and Ready, not Problems to Ready.

See Board and Backlog.

---

Scenario 3 — Decompose a specification into backlog tasks

Turn a PRD, design doc, or feature spec already in the repository into queued work.

1. Open the Workspace page (/projects/{id}/workspace) and browse the repository (GET /api/projects/{id}/workspace, GET /api/projects/{id}/workspace/files).
2. Select a Markdown spec file and choose Decompose into tasks (POST /api/projects/{id}/backlog/decompose with the file_path). The response lists proposed backlog items (and flags any that already exist).
3. Review the preview and explicitly confirm (confirm: true) to persist new items. Edit saved tasks, then move selected items to Ready for heartbeat pickup. See Decomposition.

---

Scenario 4 — Drive the full lifecycle from an MCP client (Copilot CLI)

Everything above is available programmatically through the MCP server. Any MCP-compatible client can run the complete lifecycle. The tool names below are exact.

1. Sign in and connect repository access if needed — complete MCP OAuth with Agentweaver's Entra-backed identity. When GitHub access is needed, use github_repo_app_connect, open its browser_url, and poll github_repo_app_authorization_status.
2. Choose or create a project — project_list / project_get, or project_create. GitHub-origin creation first uses github_repository_selections_list and github_repository_selection_issue for its opaque selection code. Once the project exists, a Project Owner can use project_copilot_app_connect and project_copilot_app_authorization_status when a project binding is needed. Check project_github_capability_status; an eligible platform provider can supply project work without a project Copilot binding.
3. Confirm a team — team_cast defaults to a proposal. Confirm via team_cast(confirm_proposal_id=...) or confirm=true; inspect with team_get.
4. Choose one launch path — queue via backlog_capture_task and backlog_move_to_ready for heartbeat pickup, or explicitly start a new run. Do not queue the task and then start it again with run_task.
5. For manual define-outcome control — use coordinator_start with start_mode="defineOutcome", autopilot=false, and optional workflow_id. Inspect coordinator_outcome_spec_get, then use coordinator_outcome_spec_confirm or coordinator_outcome_spec_revise. Alternatively, run_task defaults to direct mode and starts/polls a new run.
6. Observe and steer — coordinator_work_plan_get, coordinator_children_get, orchestration_topology, coordinator_steer; monitor child runs with run_status, run_watch (SSE), run_show_artifacts, run_get_file.
7. Review — list artifacts before run_get_file. run_review(approved=true|false) supports approve/decline only. Request-changes feedback is available through the web/REST review surface; coordinator_steer is a separate steering control.
8. Optionally curate/export knowledge — decision_inbox_submit, memory_record, memory_search, or memory_export. Export is not a mandatory final run stage.

See the MCP reference for full tool parameters and the API reference for the underlying endpoints.

Diagram details and constraints

Element	Contract
title	The board is a projection
subtitle	Columns reflect persisted task and run state—not a separate workflow engine.
group-title0	Before and during execution
group-title1	Review / terminal outcomes
Backlog	Backlog
Backlog	Captured task; not queued
Backlog	task: backlog
Ready	Ready
Ready	Queued task
Ready	task: ready
Active	Active
Active	Work is in progress
Active	default non-review bucket
Problems	Problems
Problems	Failed / declined / merge failed
Problems	or assembly blocked / failed
Human Review	Human Review
Human Review	AwaitingReview / InReview
Human Review	or assembly stage: Review
Done	Done
Done	Completed / Merged / AssembleReady
Done	or plan Complete / stage Done
e1	queue
e2	claim + start
e3	await review
e4	finish
e5	problem
assurance-title	DEFAULT BUCKETS · NOT A NEW STATE MACHINE
assurance-line1	Configured workflow stages may replace the default run columns. Arrows summarize typical changes, not every path.
assurance-line2	The board polls persisted state. Ready tasks with unmet dependencies stay Ready; blocked is a flag.
Backlog	Entity
Backlog	BacklogTask
Backlog	State
Backlog	Run
Backlog	Not required
Backlog	Action
Backlog	Move to Ready
Ready	Blocked
Ready	Dependency metadata
Ready	Pickup
Ready	Atomic claim
Active	Input
Active	Coordinator run
Active	Status
Active	Non-review default
Active	Plan
Active	Dispatch / assembly
Active	Approval
Active	Separate pending flag
Problems	Failed / Declined
Problems	Merge
Problems	MergeFailed
Problems	Assembly
Problems	Blocked / Failed
Problems	Also
Problems	AssemblyDeclined
Human Review	AwaitingReview
Human Review	InReview
Human Review	Review stage
Human Review	Approve
Human Review	Resumes execution
Done	Completed / Merged
Done	AssembleReady
Done	Complete
Done	Done stage
backlog	No run is required yet; Move to Ready to queue work
ready	Unresolved dependencies stay here; Blocked is a flag, not a column
progress	Claimed tasks link to their run; Pending approval is a separate flag
failed	Blocked assembly is recoverable; Not every problem is terminal
review	Approval resumes the workflow; Approval alone is not Done
done	Persisted-state mapping; Not merely a clicked approval
notes	DEFAULT BUCKETS · NOT A NEW STATE MACHINE; Configured workflow stages may replace the default run columns. Arrows summarize typical changes, not every path.; The board polls persisted state. Ready tasks with unmet dependencies stay Ready; blocked is a flag.
groups	Before and during execution; Review and terminal outcomes

Diagram details and constraints

Element	Contract
title	MCP lifecycle: choose one launch path
takeaway	Queue pickup and explicit starts are alternatives; inspection and approvals remain explicit.
m-prep-title	PREPARE AUTHORITY AND A CONFIRMED TEAM
m-launch-title	CHOOSE ONE • DO NOT QUEUE AND EXPLICITLY START THE SAME TASK
m-observe-title	OBSERVE, INSPECT AND DECIDE • NOT AUTOMATIC SUCCESS
Authorize	Authorize
Authorize	MCP OAuth / Entra identity
Authorize	Repo capability is separate
Choose project	Choose project
Choose project	project_list / project_create
Choose project	Check provider + repo readiness
Confirm team	Confirm team
Confirm team	team_cast: proposal first
Confirm team	confirm_proposal_id or confirm
Define outcome	Define outcome
Define outcome	coordinator_start
Define outcome	defineOutcome; autopilot=false
Start and poll	Start and poll
Start and poll	run_task
Start and poll	Default direct; creates NEW run
Queue for heartbeat	Queue for heartbeat
Queue for heartbeat	backlog_capture_task
Queue for heartbeat	then backlog_move_to_ready
Observe / steer	Observe / steer
Observe / steer	coordinator_work_plan_get
Observe / steer	coordinator_children_get
Inspect files	Inspect files
Inspect files	run_show_artifacts
Inspect files	then run_get_file
Review when gated	Review when gated
Review when gated	run_review(approved: bool)
Review when gated	true approves; false declines
m1	authorize
m2	prepare
m3	confirm
m4	new run
m5	reserved run
m6	list
m7	inspect
m-confirm-heading	MANUAL GATE
m-confirm-body	coordinator_outcome_spec_get → coordinator_outcome_spec_confirm (or coordinator_outcome_spec_revise).
m-pickup-heading	HEARTBEAT
m-pickup-body	Atomically claims Ready item. Pickup autopilot controls confirmation, not tool or merge approval.
m-direct-heading	BOUNDED WAIT
m-direct-body	Returns artifacts, a gate, a next action, a timeout, or a failure. Never assume completion.
m-outcomes-heading	REVIEW PARITY
m-outcomes-body	Request changes: web/REST review, not run_review. coordinator_steer is separate. memory_export is optional.
m-gates-heading	COLLECTIVE GATES
m-gates-body	Children: Agent → Assemble-ready. Selected workflow gates apply to combined output, not per child.
notes	[object Object]; [object Object]; [object Object]; [object Object]; [object Object]
groups	[object Object]; [object Object]; [object Object]