# Workflows

> Task by task, the DevHub calls in order: answer a question, change code, investigate, work from a plan, record knowledge.

Each workflow lists the calls in order. Take every id from a result, never from memory.

## Answer how or why something works

1. `vault_list` if you have no `vaultId`. Choose the repository vault for a question about one repository.
2. `knowledge_search` with the question. Use `rag_context` instead when you need grounded context to reason from.
3. Read the best hit: `knowledge_get` for a hit, `vault_file_read` for a note path.
4. Empty result: `vault_overview` shows which folders feed the search, `vault_files_search` reads all folders, `knowledge_index_status` says whether the index is ready.
5. Open source only after the vault, and only for what the vault does not say. When the two disagree, the code is right; record the correction (see "Record knowledge").

## Change code

1. `context_pull`.
2. `workspace_list` for the `workspaceId`; `vault_list` for the vault.
3. `vault_overview` on the repository vault. Then `knowledge_search` for the rules of this repository.
4. `repo_index_status`; `repo_index_refresh` if stale.
5. `repo_symbol_search` to find the place, `repo_file` for its neighbours, `repo_impact` and `repo_callers` before you change a signature.
6. `file_read`, then `file_replace` or `file_edit`. Use `file_create` for a new file.
7. `npm_script_list`, then `npm_script_run` with the project's own check or test script.
8. `repo_index_refresh`, then `repo_changed` to see that your files reached the index.
9. Report what changed and the result of the checks.

## Look into something before building it

1. `investigation_list`. The ground may be covered already, and a rejected variant is worth knowing.
2. `investigation_create` with a title and the repositories.
3. After each finished piece of the looking, `investigation_add`. Use one document per way of doing the thing: an analysis (what is there), a variant (a way in), a plan (what to do), a finding (what was settled).
4. You cannot close an investigation. Say in your answer that it is ready to close.

## Work from a plan

1. `plan_ready`, with no `planId` to see every plan. Never assume a step is free because it looks next.
2. `plan_claim` with `planId`, `stepId`. Give `by` if your endpoint does not identify you. The answer carries the step, its resume and a working tree.
3. Read the step's assignment and `nextSteps`. Decisions the owner pushed there override the assignment.
4. Work only in the working tree the claim returned.
5. During a long step, `plan_renew`. A claim nobody renews lapses and the step goes to someone else.
6. Commit with the step trailer, then `plan_close` with the commit shas. It merges the working tree back and records what landed. Use `as: "withdrawn"` for a step that will not happen; nothing is merged.
7. `step_log` at the end of every stint, including one that failed: what you did and what comes next. `step_update` if the status or the next steps changed.

> **Caution:** The exact form of the step trailer in a commit message (a line that names the step id) and what
> counts as a commit "behind" a step are taken from the Plans screen and are not confirmed.

To open a plan yourself: `plan_create` once an investigation has settled what to do, then `step_add` for each piece. Size a step to land as one commit. Name the steps it waits on (gates) and the files it touches (scope).

## Record knowledge

1. `vault_overview` or `vault_files_search` to find where the note belongs and whether it exists. Take the path from the result.
2. `vault_file_replace` to correct a note, `vault_file_create` for a new one. The vault must allow writing over MCP.
3. `knowledge_index_refresh` if `knowledge_search` does not return your note yet.
4. Something went wrong and the reason is worth stating: `learning_note`, one note per lesson. A standing fact about the work or the user: `memory_note`.

## Ask another agent

1. `agent_list`. It shows each agent, which client runs it and whether it can run at all.
2. `agent_run` with `agentId` and the `task`. After 45 seconds it can answer `RUNNING <runId>`. That is not a failure.
3. `agent_run_status` with `wait`. Do not run the task again.

## Verify what you did

- `audit_summary` for "is anything broken now", `audit_list` for one failed call.
- `display_screenshot` after `display_list` to see the result on screen, when the user allows it.

## Related

- [Using the tools](/devhub/for-agents/mcp-tools/index.md)
- [Errors](/devhub/for-agents/errors/index.md)
- [Plans](/devhub/features/plans/index.md)