From 4a4a6ddae8ffb86756588db25e372352fc55c877 Mon Sep 17 00:00:00 2001 From: Bill Murdock Date: Thu, 19 Mar 2026 10:40:29 -0400 Subject: [PATCH 1/6] docs: add tutorial guide for the Bug Fix workflow User-facing tutorial covering how to start a bugfix session, choose a model, walk through each workflow phase, and use speedrun mode. Written for end users, not workflow developers. Made-with: Cursor --- docs/bugfix-tutorial.md | 253 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 253 insertions(+) create mode 100644 docs/bugfix-tutorial.md diff --git a/docs/bugfix-tutorial.md b/docs/bugfix-tutorial.md new file mode 100644 index 0000000..a1bc8bc --- /dev/null +++ b/docs/bugfix-tutorial.md @@ -0,0 +1,253 @@ +# Bug Fix Workflow Tutorial + +This tutorial walks you through using the Bug Fix workflow on the Ambient +Code Platform to diagnose and fix software bugs. By the end you will know how +to start a session, move through each phase of the workflow, and submit a pull +request with the fix. + +## Getting Started + +### Log in and create a session + +Open [red.ht/ambient](https://red.ht/ambient) and start a new session. Select +the **Bug Fix** workflow and the model you want to use. + +### Choosing a model + +At the time of writing, **Claude Opus** is the model we find works best for +fixing bugs. If your bug is straightforward (a clear error message pointing to +an obvious cause), a less powerful model may be fine and can be quicker and +cheaper. + +Keep in mind, though, that if the bug turns out to be more complex than you +expect, a less powerful model can end up being *slower* and *more expensive*. A +bug that a stronger model solves in one pass may take several rounds of +back-and-forth with a weaker model, consuming more time and tokens overall. When +in doubt, start with a capable model. + +### Adding repository context + +You can add the GitHub repository you want to work on by clicking the +**Add Context** tab in the Explorer panel before you begin. However, this is +not strictly necessary. If you give the workflow a link to the repository, or +to an issue in that repository, it will clone the repo into your session +automatically. + +## Starting the Workflow + +There are several ways to kick things off once your session is running. + +### Option 1: Paste a bug issue link + +Simply paste a link to a GitHub issue and the workflow will clone the repository +and begin walking you through the bug fix process interactively. For example: + +```text +https://github.com/llamastack/llama-stack/issues/5119 +``` + +The workflow will assess the issue, summarize its understanding, and ask for +your input before moving on to the next step. + +### Option 2: Speedrun a bug issue + +If you want the workflow to run through every phase without stopping for +input between steps, use the `/speedrun` command followed by the issue link: + +```text +/speedrun https://github.com/llamastack/llama-stack/issues/5119 +``` + +See [Speedrun mode](#speedrun-mode) below for details on what this does and +when to use it. + +### Option 3: Describe the bug yourself + +You do not need a GitHub issue at all. You can describe the bug in your own +words and provide a link to the repository: + +```text +The Milvus vector store integration rejects collection names that contain +hyphens. Repo: https://github.com/llamastack/llama-stack +``` + +The workflow will clone the repo and proceed from there. This works with or +without `/speedrun`. Prefix your description with `/speedrun` to run through +all phases automatically, or leave it off to step through interactively. + +## Workflow Phases + +The Bug Fix workflow is organized into a series of phases. In the default +interactive mode the workflow completes one phase at a time, presents you with +results and recommendations, and then waits for you to decide what to do next. +You can follow the suggested order, skip ahead, or go back to revisit an +earlier phase at any point. + +Most phases produce a **report**, a Markdown file you can view in the +**Files** section of the Explorer panel. These reports are internal to +your session (they are not published to GitHub or anywhere else) and serve +two purposes: + +1. **Visibility for you.** The reports give you a deeper view of what the + workflow found and decided at each step, so you can provide more informed + input and steer the process effectively. + +2. **Memory for the workflow.** The platform can only keep a finite amount of + context in memory at a time. By the time the workflow reaches the Test or + Review phase, for example, the details of the original assessment may no + longer be in its working context. The written reports let later phases refer + back to earlier analysis without losing important details. + +### Assess + +**Command:** `/assess` + +The first phase reads the bug report (or your description) and presents a +summary of its understanding: what the bug is, where it likely occurs, what +information is available, what is missing, and a proposed plan for +reproducing it. No code is changed or executed in this phase; it is purely +analysis and planning. + +This is your chance to correct any misunderstandings or fill in missing +details before work begins. + +**Report:** `artifacts/bugfix/reports/assessment.md` + +### Reproduce + +**Command:** `/reproduce` + +This phase attempts to reproduce the bug in a controlled environment. It +follows the plan from the Assess phase, documents the steps taken, and records +what happened. Even a failed reproduction attempt is documented, since +understanding *why* a bug is hard to reproduce is useful information for +diagnosis. + +**Report:** `artifacts/bugfix/reports/reproduction.md` + +### Diagnose + +**Command:** `/diagnose` + +Root cause analysis. The workflow traces through the code, examines git +history, forms hypotheses about what is going wrong, and tests them. The goal +is to understand *why* the bug happens, not just *what* happens. The diagnosis +also assesses how much of the codebase is affected and recommends an approach +for the fix. + +**Report:** `artifacts/bugfix/analysis/root-cause.md` + +### Fix + +**Command:** `/fix` + +Implements the bug fix. The workflow creates a feature branch, makes the +minimal code changes needed to resolve the root cause, runs linters and +formatters, and documents the implementation choices it made. + +**Report:** `artifacts/bugfix/fixes/implementation-notes.md` + +### Test + +**Command:** `/test` + +Verifies the fix. The workflow creates regression tests that fail without the +fix and pass with it, runs the project's full test suite to check for +unintended side effects, and performs manual verification of the original +reproduction steps. + +**Report:** `artifacts/bugfix/tests/verification.md` + +### Review + +**Command:** `/review` + +An optional but recommended self-review phase. The workflow steps back and +critically evaluates the fix and tests: Does the fix address the root cause or +just suppress a symptom? Do the tests actually prove the bug is resolved, or +could they be hiding problems? The review produces a verdict: + +- **Fix and tests are solid.** Ready to proceed to documentation and PR. +- **Fix is adequate but tests are incomplete.** Additional testing is + recommended before proceeding. +- **Fix is inadequate.** The fix needs more work. The workflow will suggest + going back to the Fix phase with specific guidance. + +### Document + +**Command:** `/document` + +Creates the supporting documentation for the fix: release notes, a changelog +entry, an issue update, and a draft pull request description. + +**Reports:** `artifacts/bugfix/docs/` (multiple files including +`release-notes.md`, `changelog-entry.md`, and `pr-description.md`) + +### PR + +**Command:** `/pr` + +The final phase. The workflow pushes the feature branch to a fork and creates a +draft pull request against the upstream repository. If automated PR creation +fails for any reason (e.g., missing permissions), it provides instructions for +creating the PR manually. + +## Speedrun Mode + +**Command:** `/speedrun` + +Speedrun mode runs through all remaining phases in sequence without pausing for +your input between steps. It is useful when you have a well-defined bug and +trust the workflow to handle the full lifecycle autonomously. + +Even in speedrun mode, the workflow will stop and ask you for guidance if it +hits a situation that needs human judgment, such as when the root cause is +unclear, if there are multiple valid fix approaches with different trade-offs, +or if a security concern arises. + +### Why speedrun is not the default + +The default interactive mode pauses after each phase so you can review the +results and steer the process. For many bugs, especially complex ones or bugs +where the report is incomplete or ambiguous, this deliberate pacing is +valuable. Reviewing the assessment before reproduction begins, or checking the +diagnosis before a fix is attempted, lets you catch mistakes early and provide +context that the workflow might not have. + +Speedrun is best suited for well-understood bugs where you are confident the +report contains enough information for the workflow to proceed on its own. + +### Speedrun examples + +Run from the beginning with a bug issue link: + +```text +/speedrun https://github.com/llamastack/llama-stack/issues/5119 +``` + +Continue from wherever you are in the flow (the workflow detects which phases are already complete): + +```text +/speedrun +``` + +Jump ahead to a specific phase: + +```text +/speedrun Jump ahead to /fix +``` + +## Viewing Reports and Artifacts + +As the workflow progresses, reports and other artifacts are written to the +`artifacts/bugfix/` directory. You can view these files at any time in the +**Files** section of the Explorer panel. The reports are Markdown files that +provide a detailed record of each phase's analysis, decisions, and outcomes. + +## A Note on Automation + +This tutorial has covered using the Bug Fix workflow through the interactive UI. +It is also possible to connect to the Ambient Code Platform remotely (for +example, via a GitHub Action or other automation) to trigger bug fix workflows +programmatically. The details of that setup are outside the scope of this +tutorial. From e608e1422e07974c20d2df824351abdb6a693a91 Mon Sep 17 00:00:00 2001 From: Bill Murdock Date: Thu, 19 Mar 2026 10:47:14 -0400 Subject: [PATCH 2/6] docs: replace automation placeholder with full guide Cover GitHub Action, acpctl CLI, MCP server, and SDKs with examples specific to the Bug Fix workflow. Made-with: Cursor --- docs/bugfix-tutorial.md | 143 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 137 insertions(+), 6 deletions(-) diff --git a/docs/bugfix-tutorial.md b/docs/bugfix-tutorial.md index a1bc8bc..8b9ce75 100644 --- a/docs/bugfix-tutorial.md +++ b/docs/bugfix-tutorial.md @@ -244,10 +244,141 @@ As the workflow progresses, reports and other artifacts are written to the **Files** section of the Explorer panel. The reports are Markdown files that provide a detailed record of each phase's analysis, decisions, and outcomes. -## A Note on Automation +## Automation + +Everything above describes using the Bug Fix workflow through the interactive +UI. The Ambient Code Platform also supports triggering sessions +programmatically, so you can incorporate bug fixing into CI/CD pipelines, +scheduled jobs, or custom tooling. + +### GitHub Action + +The [`ambient-action`](https://github.com/ambient-code/ambient-action) GitHub +Action (v0.0.2, beta) creates ACP sessions directly from GitHub workflows. You +can use it to automatically kick off a bug fix session when a new issue is +opened, when a label is applied, or on any other GitHub event. + +The action supports two modes: + +- **Fire-and-forget.** Create the session and let the workflow continue. The + agent runs in the background. +- **Wait-for-completion.** Block the GitHub workflow until the session finishes + (or times out), then use the session result in subsequent steps. + +Here is a minimal example that triggers a bug fix speedrun whenever an issue is +labeled `auto-fix`: + +```yaml +name: Auto Bug Fix +on: + issues: + types: [labeled] + +jobs: + fix: + if: github.event.label.name == 'auto-fix' + runs-on: ubuntu-latest + steps: + - uses: ambient-code/ambient-action@v0.0.2 + with: + api-url: ${{ secrets.ACP_URL }} + api-token: ${{ secrets.ACP_TOKEN }} + project: my-team + prompt: | + /speedrun https://github.com/${{ github.repository }}/issues/${{ github.event.issue.number }} + repos: | + [{"url": "https://github.com/${{ github.repository }}", "branch": "main", "autoPush": true}] + workflow: | + {"gitUrl": "https://github.com/ambient-code/workflows", "branch": "main", "path": "workflows/bugfix"} + wait: true + timeout: 30 +``` + +Key inputs: + +| Input | Required | Description | +| --- | --- | --- | +| `api-url` | Yes | ACP API URL | +| `api-token` | Yes | Bearer token (store as a GitHub secret) | +| `project` | Yes | Target workspace/project name | +| `prompt` | Yes | Task prompt for the agent | +| `repos` | No | JSON array of repos to clone into the session | +| `workflow` | No | JSON workflow object (repo URL, branch, path) | +| `model` | No | Model override (e.g., `claude-sonnet-4-20250514`) | +| `wait` | No | Wait for the session to complete (default: `false`) | +| `timeout` | No | Timeout in minutes (default: `30`) | + +When `wait` is `true`, the action outputs `session-name`, `session-uid`, +`session-phase`, and `session-result`, which you can use in subsequent workflow +steps. + +### CLI (`acpctl`) + +The `acpctl` command-line tool lets you create and manage sessions from your +terminal. Install it from the +[platform repository](https://github.com/ambient-code/platform) under +`components/ambient-cli/`. + +```bash +# Log in +acpctl login --token --url --project + +# Create a bug fix session +acpctl create session --name fix-issue-5119 \ + --prompt "/speedrun https://github.com/llamastack/llama-stack/issues/5119" \ + --repo-url https://github.com/llamastack/llama-stack \ + --model claude-sonnet-4 + +# Check session status +acpctl get session +``` + +Configuration can also be set through environment variables (`AMBIENT_TOKEN`, +`AMBIENT_PROJECT`, `AMBIENT_API_URL`). + +### MCP Server + +The [`mcp-acp`](https://github.com/ambient-code/mcp) MCP server lets you +manage ACP sessions from Claude Desktop, Claude Code, or any MCP-compatible +client. It supports creating sessions from predefined templates (including +bugfix), viewing logs and transcripts, and managing sessions across multiple +clusters. + +Install it and add it to your Claude Desktop configuration: + +```json +{ + "mcpServers": { + "acp": { + "command": "uvx", + "args": ["mcp-acp"] + } + } +} +``` + +Configure your cluster credentials in `~/.config/acp/clusters.yaml`. Once set +up, you can ask Claude to create bug fix sessions, check on running sessions, +and retrieve results, all from within your regular Claude conversation. + +### SDKs + +For deeper integration, the Ambient Platform SDK provides client libraries in +Go, Python, and TypeScript. These are generated from the platform's OpenAPI +specification and support the full session lifecycle. + +```python +from ambient_platform.client import AmbientClient + +client = AmbientClient.from_env() +session = client.sessions.create({ + "name": "fix-issue-5119", + "prompt": "/speedrun https://github.com/llamastack/llama-stack/issues/5119", + "workflow_id": "bugfix" +}) +``` -This tutorial has covered using the Bug Fix workflow through the interactive UI. -It is also possible to connect to the Ambient Code Platform remotely (for -example, via a GitHub Action or other automation) to trigger bug fix workflows -programmatically. The details of that setup are outside the scope of this -tutorial. +The SDKs are available in the +[platform repository](https://github.com/ambient-code/platform) under +`components/ambient-sdk/`. All three languages support the same environment +variables: `AMBIENT_TOKEN`, `AMBIENT_PROJECT`, and `AMBIENT_API_URL`. From 1f808f3271af863764ac132deb38802231895144 Mon Sep 17 00:00:00 2001 From: Bill Murdock Date: Thu, 19 Mar 2026 11:28:08 -0400 Subject: [PATCH 3/6] docs: rewrite automation section with verified REST API details Lead with the raw curl example showing the actual backend API call, explain each field (especially activeWorkflow which loads the workflow), keep GitHub Action as a convenience wrapper, and demote unverified tools to brief pointers. Made-with: Cursor --- docs/bugfix-tutorial.md | 166 ++++++++++++++++++---------------------- 1 file changed, 74 insertions(+), 92 deletions(-) diff --git a/docs/bugfix-tutorial.md b/docs/bugfix-tutorial.md index 8b9ce75..3366049 100644 --- a/docs/bugfix-tutorial.md +++ b/docs/bugfix-tutorial.md @@ -251,21 +251,65 @@ UI. The Ambient Code Platform also supports triggering sessions programmatically, so you can incorporate bug fixing into CI/CD pipelines, scheduled jobs, or custom tooling. +### How it works + +Under the hood, creating a session is a single HTTP POST to the platform's +backend API. The request body includes the prompt, the repositories to clone, +and an `activeWorkflow` object that tells the platform which workflow to load. +Anything that can make an authenticated HTTP request can create a bug fix +session. + +Here is the equivalent `curl` call: + +```bash +curl -X POST \ + "${ACP_API_URL}/projects/${ACP_PROJECT}/agentic-sessions" \ + -H "Authorization: Bearer ${ACP_TOKEN}" \ + -H "Content-Type: application/json" \ + -d '{ + "initialPrompt": "/speedrun https://github.com/llamastack/llama-stack/issues/5119", + "activeWorkflow": { + "gitUrl": "https://github.com/ambient-code/workflows", + "branch": "main", + "path": "workflows/bugfix" + }, + "repos": [ + {"url": "https://github.com/llamastack/llama-stack", "branch": "main", "autoPush": true} + ], + "llmSettings": {"model": "claude-sonnet-4-5"}, + "timeout": 1800 + }' +``` + +The key fields are: + +- **`initialPrompt`** is what the agent sees as its first instruction. This is + where you pass the bug description, issue link, or `/speedrun` command. +- **`activeWorkflow`** tells the platform which workflow to load. For the Bug + Fix workflow, point it at this repository with the path `workflows/bugfix`. + If you omit this field, the session starts with no workflow. +- **`repos`** is an array of repositories to clone into the session. Set + `autoPush` to `true` if you want the agent to push its fix automatically. +- **`llmSettings.model`** selects the model. +- **`timeout`** is the session timeout in seconds. + +Authentication uses a bearer token in the `Authorization` header. + ### GitHub Action The [`ambient-action`](https://github.com/ambient-code/ambient-action) GitHub -Action (v0.0.2, beta) creates ACP sessions directly from GitHub workflows. You -can use it to automatically kick off a bug fix session when a new issue is -opened, when a label is applied, or on any other GitHub event. +Action wraps this API call for use in GitHub workflows. You can use it to +automatically kick off a bug fix session when a new issue is opened, when a +label is applied, or on any other GitHub event. The action supports two modes: -- **Fire-and-forget.** Create the session and let the workflow continue. The - agent runs in the background. +- **Fire-and-forget.** Create the session and let the GitHub workflow continue. + The agent runs in the background. - **Wait-for-completion.** Block the GitHub workflow until the session finishes (or times out), then use the session result in subsequent steps. -Here is a minimal example that triggers a bug fix speedrun whenever an issue is +Here is an example that triggers a bug fix speedrun whenever an issue is labeled `auto-fix`: ```yaml @@ -294,91 +338,29 @@ jobs: timeout: 30 ``` -Key inputs: - -| Input | Required | Description | -| --- | --- | --- | -| `api-url` | Yes | ACP API URL | -| `api-token` | Yes | Bearer token (store as a GitHub secret) | -| `project` | Yes | Target workspace/project name | -| `prompt` | Yes | Task prompt for the agent | -| `repos` | No | JSON array of repos to clone into the session | -| `workflow` | No | JSON workflow object (repo URL, branch, path) | -| `model` | No | Model override (e.g., `claude-sonnet-4-20250514`) | -| `wait` | No | Wait for the session to complete (default: `false`) | -| `timeout` | No | Timeout in minutes (default: `30`) | - When `wait` is `true`, the action outputs `session-name`, `session-uid`, `session-phase`, and `session-result`, which you can use in subsequent workflow -steps. - -### CLI (`acpctl`) - -The `acpctl` command-line tool lets you create and manage sessions from your -terminal. Install it from the -[platform repository](https://github.com/ambient-code/platform) under -`components/ambient-cli/`. - -```bash -# Log in -acpctl login --token --url --project - -# Create a bug fix session -acpctl create session --name fix-issue-5119 \ - --prompt "/speedrun https://github.com/llamastack/llama-stack/issues/5119" \ - --repo-url https://github.com/llamastack/llama-stack \ - --model claude-sonnet-4 - -# Check session status -acpctl get session -``` - -Configuration can also be set through environment variables (`AMBIENT_TOKEN`, -`AMBIENT_PROJECT`, `AMBIENT_API_URL`). - -### MCP Server - -The [`mcp-acp`](https://github.com/ambient-code/mcp) MCP server lets you -manage ACP sessions from Claude Desktop, Claude Code, or any MCP-compatible -client. It supports creating sessions from predefined templates (including -bugfix), viewing logs and transcripts, and managing sessions across multiple -clusters. - -Install it and add it to your Claude Desktop configuration: - -```json -{ - "mcpServers": { - "acp": { - "command": "uvx", - "args": ["mcp-acp"] - } - } -} -``` - -Configure your cluster credentials in `~/.config/acp/clusters.yaml`. Once set -up, you can ask Claude to create bug fix sessions, check on running sessions, -and retrieve results, all from within your regular Claude conversation. - -### SDKs - -For deeper integration, the Ambient Platform SDK provides client libraries in -Go, Python, and TypeScript. These are generated from the platform's OpenAPI -specification and support the full session lifecycle. - -```python -from ambient_platform.client import AmbientClient - -client = AmbientClient.from_env() -session = client.sessions.create({ - "name": "fix-issue-5119", - "prompt": "/speedrun https://github.com/llamastack/llama-stack/issues/5119", - "workflow_id": "bugfix" -}) -``` - -The SDKs are available in the -[platform repository](https://github.com/ambient-code/platform) under -`components/ambient-sdk/`. All three languages support the same environment -variables: `AMBIENT_TOKEN`, `AMBIENT_PROJECT`, and `AMBIENT_API_URL`. +steps. See the +[action repository](https://github.com/ambient-code/ambient-action) for the +full list of inputs and outputs. + +### Other tools + +Several other tools can manage ACP sessions, though their support for +specifying a workflow varies: + +- **[`acpctl`](https://github.com/ambient-code/platform/tree/main/components/ambient-cli)** + is a command-line tool for the platform. It can create sessions and check + their status, but does not yet have a flag for specifying a workflow. +- **[`mcp-acp`](https://github.com/ambient-code/mcp)** is an MCP server that + lets you manage ACP sessions from Claude Desktop, Claude Code, or any + MCP-compatible client. It supports creating sessions from predefined + templates including bugfix. +- **[Ambient Platform SDKs](https://github.com/ambient-code/platform/tree/main/components/ambient-sdk)** + provide client libraries in Go, Python, and TypeScript for programmatic + session management. + +Since the underlying mechanism is a single REST call (as shown in the `curl` +example above), you can always fall back to a direct HTTP request from any +language or tool if the higher-level wrappers do not yet support the options you +need. From 9091c48b0f6230014176e9c84517c375f5bdcd6c Mon Sep 17 00:00:00 2001 From: Bill Murdock Date: Thu, 19 Mar 2026 11:56:27 -0400 Subject: [PATCH 4/6] docs: clarify automation tool limitations and REST API fallback Made-with: Cursor --- docs/bugfix-tutorial.md | 26 ++++++++++++++++---------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/docs/bugfix-tutorial.md b/docs/bugfix-tutorial.md index 3366049..208fcc4 100644 --- a/docs/bugfix-tutorial.md +++ b/docs/bugfix-tutorial.md @@ -344,23 +344,29 @@ steps. See the [action repository](https://github.com/ambient-code/ambient-action) for the full list of inputs and outputs. -### Other tools +### Tools that do NOT yet support workflows -Several other tools can manage ACP sessions, though their support for -specifying a workflow varies: +Several other tools can create and manage ACP sessions. At the time of writing, +none of them support setting `activeWorkflow`, which means they cannot load the +structured Bug Fix workflow described in this tutorial. They will create a +session, but it will not have the phases, commands, or reports that the workflow +provides. - **[`acpctl`](https://github.com/ambient-code/platform/tree/main/components/ambient-cli)** is a command-line tool for the platform. It can create sessions and check - their status, but does not yet have a flag for specifying a workflow. + their status, but does not have a flag for specifying a workflow. - **[`mcp-acp`](https://github.com/ambient-code/mcp)** is an MCP server that lets you manage ACP sessions from Claude Desktop, Claude Code, or any - MCP-compatible client. It supports creating sessions from predefined - templates including bugfix. + MCP-compatible client. It has a "bugfix" template, but that template only + sets a generic prompt and model. It does not load the Bug Fix workflow. - **[Ambient Platform SDKs](https://github.com/ambient-code/platform/tree/main/components/ambient-sdk)** provide client libraries in Go, Python, and TypeScript for programmatic session management. -Since the underlying mechanism is a single REST call (as shown in the `curl` -example above), you can always fall back to a direct HTTP request from any -language or tool if the higher-level wrappers do not yet support the options you -need. +If you want to automate bug fix sessions from a script, CI pipeline, or any +other environment, you do not need any of these tools. The platform's backend +API accepts a straightforward JSON POST request (as shown in the `curl` example +above). The `activeWorkflow` field in that request is what tells the platform to +load the Bug Fix workflow into the session. Any HTTP client in any language can +make that call. The GitHub Action is just a convenience wrapper that does the +same thing and adds polling for completion. From 9ae2107bb5249c5e87f7d4c5e29fe0deb8f0d19a Mon Sep 17 00:00:00 2001 From: Bill Murdock Date: Thu, 19 Mar 2026 15:39:35 -0400 Subject: [PATCH 5/6] docs: address review feedback on bugfix tutorial - Note that 8 phases include Review and PR beyond the 6-phase greeting - Add Review artifact path (artifacts/bugfix/review/verdict.md) - Explain how to interrupt speedrun and what causes it to stop - Mark Automation section as for advanced users Made-with: Cursor --- docs/bugfix-tutorial.md | 35 +++++++++++++++++++++++++++-------- 1 file changed, 27 insertions(+), 8 deletions(-) diff --git a/docs/bugfix-tutorial.md b/docs/bugfix-tutorial.md index 208fcc4..e5d390b 100644 --- a/docs/bugfix-tutorial.md +++ b/docs/bugfix-tutorial.md @@ -47,7 +47,13 @@ https://github.com/llamastack/llama-stack/issues/5119 ``` The workflow will assess the issue, summarize its understanding, and ask for -your input before moving on to the next step. +your input before moving on to the next step. Alternatively, you could start with: + +```text +/assess https://github.com/llamastack/llama-stack/issues/5119 +``` + +That makes it more explicit that you want to start at the beginning with the assessment. ### Option 2: Speedrun a bug issue @@ -77,11 +83,15 @@ all phases automatically, or leave it off to step through interactively. ## Workflow Phases -The Bug Fix workflow is organized into a series of phases. In the default -interactive mode the workflow completes one phase at a time, presents you with -results and recommendations, and then waits for you to decide what to do next. -You can follow the suggested order, skip ahead, or go back to revisit an -earlier phase at any point. +The Bug Fix workflow is organized into a series of phases. The in-product +greeting summarizes six core phases (Assess through Document), but in practice +the full workflow includes eight: the six core phases plus Review (an optional +quality check) and PR (to submit the fix). All eight are described below. + +In the default interactive mode the workflow completes one phase at a time, +presents you with results and recommendations, and then waits for you to decide +what to do next. You can follow the suggested order, skip ahead, or go back to +revisit an earlier phase at any point. Most phases produce a **report**, a Markdown file you can view in the **Files** section of the Explorer panel. These reports are internal to @@ -173,6 +183,8 @@ could they be hiding problems? The review produces a verdict: - **Fix is inadequate.** The fix needs more work. The workflow will suggest going back to the Fix phase with specific guidance. +**Report:** `artifacts/bugfix/review/verdict.md` + ### Document **Command:** `/document` @@ -203,7 +215,14 @@ trust the workflow to handle the full lifecycle autonomously. Even in speedrun mode, the workflow will stop and ask you for guidance if it hits a situation that needs human judgment, such as when the root cause is unclear, if there are multiple valid fix approaches with different trade-offs, -or if a security concern arises. +or if a security concern arises. It will also stop if it hits an obstacle it +cannot get past on its own, for example if you gave it a link to a repository +that does not exist. + +You can also interrupt a speedrun at any time by clicking the **stop** button +in the chat UI. Once stopped, you can interact with the session freely: review +what has been done so far, request changes, provide additional context, or tell +it to continue the speedrun from where it left off. ### Why speedrun is not the default @@ -244,7 +263,7 @@ As the workflow progresses, reports and other artifacts are written to the **Files** section of the Explorer panel. The reports are Markdown files that provide a detailed record of each phase's analysis, decisions, and outcomes. -## Automation +## Automation (for advanced users) Everything above describes using the Bug Fix workflow through the interactive UI. The Ambient Code Platform also supports triggering sessions From 2b9b6294fa0310712381348a166c5b08711f83fb Mon Sep 17 00:00:00 2001 From: Bill Murdock Date: Thu, 19 Mar 2026 15:49:48 -0400 Subject: [PATCH 6/6] docs: add Assess phase to README, align phases across docs - Add Phase 1: Assess to bugfix README (was missing) - Renumber all phases (now 1-8) - Fix Review output path in README (now artifacts/bugfix/review/verdict.md) - Update Quick Start to reference /assess instead of /reproduce - Minor copy fixes in tutorial Made-with: Cursor --- docs/bugfix-tutorial.md | 4 +++- workflows/bugfix/README.md | 33 ++++++++++++++++++++++++--------- 2 files changed, 27 insertions(+), 10 deletions(-) diff --git a/docs/bugfix-tutorial.md b/docs/bugfix-tutorial.md index e5d390b..5bb79ab 100644 --- a/docs/bugfix-tutorial.md +++ b/docs/bugfix-tutorial.md @@ -31,7 +31,9 @@ You can add the GitHub repository you want to work on by clicking the **Add Context** tab in the Explorer panel before you begin. However, this is not strictly necessary. If you give the workflow a link to the repository, or to an issue in that repository, it will clone the repo into your session -automatically. +automatically. Adding it in the Explorer panel can still be helpful for +simplifying the model's task by ensuring it has the repo you want available +before starting. ## Starting the Workflow diff --git a/workflows/bugfix/README.md b/workflows/bugfix/README.md index 522fd03..7cf1fde 100644 --- a/workflows/bugfix/README.md +++ b/workflows/bugfix/README.md @@ -49,7 +49,22 @@ This separation keeps commands simple and consistent while the skills contain th The Bug Fix Workflow follows this approach: -### Phase 1: Reproduce (`/reproduce`) +### Phase 1: Assess (`/assess`) + +**Purpose**: Understand the bug report and propose a plan before taking action. + +- Read the bug report, issue URL, or symptom description +- Clone the repository if not already available (read-only, no code executed) +- Summarize understanding of the bug, its location, and severity +- Identify what information is available and what is missing +- Propose a reproduction plan +- Let the user correct misunderstandings before work begins + +**Output**: `artifacts/bugfix/reports/assessment.md` + +**When to use**: Start here to build a shared understanding before investing effort. This is the default first phase when you provide a bug report. + +### Phase 2: Reproduce (`/reproduce`) **Purpose**: Systematically reproduce the bug and document observable behavior. @@ -63,7 +78,7 @@ The Bug Fix Workflow follows this approach: **When to use**: Start here if you have a bug report, issue URL, or symptom description. -### Phase 2: Diagnose (`/diagnose`) +### Phase 3: Diagnose (`/diagnose`) **Purpose**: Perform root cause analysis and assess impact. @@ -78,7 +93,7 @@ The Bug Fix Workflow follows this approach: **When to use**: After successful reproduction, or skip here if you know the symptoms. -### Phase 3: Fix (`/fix`) +### Phase 4: Fix (`/fix`) **Purpose**: Implement the bug fix following best practices. @@ -93,7 +108,7 @@ The Bug Fix Workflow follows this approach: **When to use**: After diagnosis phase, or jump here if you already know the root cause. -### Phase 4: Test (`/test`) +### Phase 5: Test (`/test`) **Purpose**: Verify the fix and create regression tests. @@ -108,7 +123,7 @@ The Bug Fix Workflow follows this approach: **When to use**: After implementing the fix. -### Phase 5: Review (`/review`) — Optional +### Phase 6: Review (`/review`) — Optional **Purpose**: Critically evaluate the fix and its tests before proceeding. @@ -123,11 +138,11 @@ The Bug Fix Workflow follows this approach: - **Fix is adequate, tests are incomplete** → Provide instructions for what additional testing is needed (including manual steps for the user) - **Fix and tests are solid** → Recommend proceeding to `/document` and `/pr` -**Output**: Review findings reported inline to the user (not a file). +**Output**: `artifacts/bugfix/review/verdict.md` **When to use**: After `/test`, especially for complex or high-risk fixes. -### Phase 6: Document (`/document`) +### Phase 7: Document (`/document`) **Purpose**: Create complete documentation for the fix. @@ -141,7 +156,7 @@ The Bug Fix Workflow follows this approach: **When to use**: After testing is complete. -### Phase 7: PR (`/pr`) +### Phase 8: PR (`/pr`) **Purpose**: Create a pull request to submit the bug fix. @@ -162,7 +177,7 @@ The Bug Fix Workflow follows this approach: 1. **Create an AgenticSession** in the Ambient Code Platform 2. **Select "Bug Fix Workflow"** from the workflows dropdown 3. **Provide context**: Bug report URL, issue number, or symptom description -4. **Start with `/reproduce`** to systematically document the bug +4. **Start with `/assess`** to analyze the bug report and build a plan 5. **Follow the phases** sequentially or jump to any phase based on your context ### Example Usage