Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 21 additions & 18 deletions docs/code.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,23 +4,17 @@

Implementation specialist that reads triaged GitHub issues, implements fixes or features following repository conventions, runs tests and linters, and commits to a local feature branch.

## How the agent works

Triggered when the `ready-to-code` label is applied to an issue or via `/fs-code`.

The code agent follows a three-phase pipeline: pre-script, sandbox execution, post-script.

1. **Pre-script** validates inputs on the runner before sandbox creation. It also checks for open PRs linked to the issue.
2. **Sandbox** — the agent reads the issue, explores the codebase, writes code, runs tests and linters, and commits locally. It has no network access (enforced by OpenShell).
3. **Post-script** runs on the runner: it performs protected path checks, secret scanning, pre-commit checks, pushes the branch, creates the PR, and best-effort assigns the PR to a human owner (latest `/fs-code` invoker, else issue assignee, else issue author).

This separation ensures the agent never has direct write access to the repository.

## How it helps

- Triaged issues can go from "ready" to "PR open" without human involvement.
- Implementation follows repo conventions because the agent reads existing code, tests, and linter configs before writing.
- The sandboxed execution model means a misbehaving agent cannot push arbitrary code — the post-script gates everything.
- The agent cannot push arbitrary code — all changes are gated before reaching the repository.

## Triggers

The code agent runs automatically when the `ready-to-code` label is applied to an issue.
Comment thread
rh-hemartin marked this conversation as resolved.
Resolved

It can also be triggered manually with the `/fs-code` command.

## Commands

Expand All @@ -31,17 +25,16 @@ This separation ensures the agent never has direct write access to the repositor
Requires write-level repository permission (admin, maintain, or write).

The `/fs-code` command accepts an optional `--force` flag. It can only be used
on issues (not PRs). The code agent is also triggered automatically when the
`ready-to-code` label is applied to an issue.
on issues (not PRs).

## Control labels

| Label | Meaning |
|-------|---------|
| `ready-to-code` | Triggers the code agent. Applied by the [triage](triage.md) post-script for low-risk categories (bug, documentation, performance), or manually by a human for feature work after prioritization. |
| `ready-for-review` | Applied by the code agent's post-script after pushing a PR. In per-repo installs, triggers review when applied to a PR; also marks workflow state for humans and the retro agent. |
| `ready-to-code` | Triggers the code agent. Applied by the [triage](triage.md) agent for low-risk categories (bug, documentation, performance), or manually by a human for feature work after prioritization. |
| `ready-for-review` | Applied after a PR is pushed. In per-repo installs, triggers the [review agent](review.md) when applied to a PR. Also marks workflow state for humans and the [retro agent](retro.md). |

## Configuration and extension
## Configuration

See [Customizing with AGENTS.md](https://fullsend.sh/docs/guides/user/customizing-with-agents-md) and
[Customizing with Skills](https://fullsend.sh/docs/guides/user/customizing-with-skills).
Expand All @@ -50,6 +43,16 @@ See [Customizing with AGENTS.md](https://fullsend.sh/docs/guides/user/customizin

None.

## How the agent works

The code agent follows a three-phase pipeline: pre-script, sandbox execution, post-script.

1. **Pre-script** validates inputs on the runner before sandbox creation. It also checks for open PRs linked to the issue.
2. **Sandbox** — the agent reads the issue, explores the codebase, writes code, runs tests and linters, and commits locally. It has no network access (enforced by OpenShell).
3. **Post-script** runs on the runner: it performs protected path checks, secret scanning, pre-commit checks, pushes the branch, creates the PR, and best-effort assigns the PR to a human owner (latest `/fs-code` invoker, else issue assignee, else issue author).

This separation ensures the agent never has direct write access to the repository.

## Source

[`harness/code.yaml`](../harness/code.yaml)
150 changes: 78 additions & 72 deletions docs/fix.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,40 +4,49 @@

Review-feedback specialist that reads review comments on open PRs, implements targeted fixes, runs tests and linters, and commits the result.

## How the agent works
## How it helps

The fix agent is triggered when the [review agent](review.md) requests changes or when a human issues a `/fs-fix` command on a PR. It follows the same sandboxed pipeline as the [code agent](code.md).
- Review feedback is addressed quickly — often before the reviewer checks back.
- Fixes are scoped to exactly what the review requested, reducing churn.
- The iteration cap prevents the fix and [review](review.md) agents from looping indefinitely.

1. **Pre-script** validates inputs and checks the iteration cap (preventing infinite fix loops).
2. **Sandbox** — the agent reads each review finding, implements targeted fixes, and verifies them against tests and linters.
3. **Validation loop** — the output is checked against a schema, with up to 2 retry iterations if the output is malformed.
4. **Post-script** pushes the commit and posts a summary comment on the PR.
## Triggers

### What the agent reads
The fix agent runs automatically when the [review agent](review.md) submits a
"changes requested" review on a same-repo PR (fork PRs are blocked).

The fix agent has two operating modes with different primary inputs:
It can also be triggered manually with the `/fs-fix` command.

**Bot-triggered** (review agent requests changes):
## Commands

| Input | Source | How it gets there |
|-------|--------|-------------------|
| Review body | Latest `CHANGES_REQUESTED` review from the review bot | Pre-fetched on the runner before the sandbox starts, injected as `review-body.txt` |
| PR diff | `gh pr diff` inside the sandbox | Agent calls this to understand what code changed |
| Repository checkout | Full repo at PR HEAD | Checked out on the runner, mounted into the sandbox |
| Repo conventions | `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md` | Read from the checkout inside the sandbox |
| Command | Where | Effect |
|---------|-------|--------|
| `/fs-fix` | PR comment | Triggers the fix agent on the PR |
| `/fs-fix-stop` | PR comment | Disables the fix agent for this PR |

**Human-triggered** (`/fs-fix [instruction]`):
Requires write-level repository permission (admin, maintain, or write).

| Input | Source | How it gets there |
|-------|--------|-------------------|
| Human instruction | Free text after `/fs-fix` in the comment | Extracted by the workflow, passed as `HUMAN_INSTRUCTION` env var (up to 10,000 bytes) |
| PR diff | `gh pr diff` inside the sandbox | Same as bot-triggered |
| Repository checkout | Full repo at PR HEAD | Same as bot-triggered |
| Repo conventions | `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md` | Same as bot-triggered |
| Review body (if any) | Prior review bot `CHANGES_REQUESTED` review | Still injected as `review-body.txt`, but human instruction takes precedence |
The `/fs-fix` command accepts optional free-text instructions after the
command. The text gives you direct control over what to fix:

- `/fs-fix` — fix whatever the [review agent](review.md) flagged
- `/fs-fix you forgot to update the docs here`
- `/fs-fix the error handling in processItem needs to distinguish between retryable and fatal errors`
- `/fs-fix address the concern raised in #42` — same-repo references work
([details](#links-and-urls-in-instructions))

`/fs-fix-stop` adds the `fullsend-no-fix` label to the PR, preventing any
further automatic fix runs. Manual `/fs-fix` commands still work.
Remove the label or use `/fs-fix` to re-engage.

## What the agent acts on

**When triggered by a review:** the agent reads the review body, the PR diff,
and the full repository checkout.

When a human instruction is present, it supersedes the review body as the
primary directive.
**When triggered by `/fs-fix`:** the agent reads your instruction text, the PR
diff, the full repository checkout, and any prior review. When a human
instruction is present, it takes precedence over the review body.

### What the agent does not read

Expand All @@ -48,7 +57,7 @@ than you might expect:
not individual line-level comments. If you need the agent to act on a
specific inline comment, copy the relevant text into a `/fs-fix` instruction.
- **Other PR comments.** General discussion comments on the PR are not part of
the agent's context. Only the review body and the `/fs-fix` instruction are
the agent's input. Only the review body and the `/fs-fix` instruction are
read.
- **CI logs and check status.** The fix agent does not read GitHub Actions logs,
check run output, or merge readiness indicators. It addresses review
Expand All @@ -64,16 +73,15 @@ depends on where the URL points:

| URL type | Works? | Why |
|----------|--------|-----|
| Same-repo issue or PR (`#123` or full GitHub URL) | Yes | Agent resolves via `gh` CLI through the GitHub API |
| Same-repo file or commit | Yes | Same mechanism — GitHub API via minted token |
| Cross-repo GitHub URL | No | Minted token is scoped to the target repo only |
| GitHub Gist | No | `gist.github.com` is not routable through the sandbox proxy |
| External URL (docs, pastebins, etc.) | No | Sandbox proxy blocks all non-API HTTP egress (403 Forbidden) |
| Same-repo issue or PR (`#123` or full GitHub URL) | Yes | Resolved via the GitHub API |
| Same-repo file or commit | Yes | Same mechanism |
| Cross-repo GitHub URL | No | Access is scoped to the target repo only |
| GitHub Gist | No | Not accessible from the agent environment |
| External URL (docs, pastebins, etc.) | No | External HTTP access is blocked |

GitHub may auto-shorten same-repo URLs in rendered comments (e.g.,
`https://github.com/org/repo/issues/2` becomes `#2`), but the dispatch
pipeline reads the raw comment body, so the full URL is preserved in the
instruction text either way.
`https://github.com/org/repo/issues/2` becomes `#2`), but the full URL is
preserved either way.

**If you need the agent to act on external context**, paste the relevant
content directly into the `/fs-fix` comment rather than linking to it. The
Expand All @@ -83,61 +91,59 @@ instruction supports multi-line text (up to 10,000 bytes).

The fix agent enforces iteration caps to prevent infinite review-fix loops:

- **Bot-triggered:** up to 5 iterations per PR (configurable).
- **Human-triggered:** up to 10 total iterations per PR (configurable), shared
across bot and human triggers.
- When a bot-triggered run is approaching the bot cap, the agent applies the
- **Automatic:** up to 5 iterations per PR (configurable).
- **Manual (`/fs-fix`):** up to 10 total iterations per PR (configurable), shared
across automatic and manual triggers.
- When an automatic run is approaching its cap, the agent applies the
`needs-human` label.
- Each `/fs-fix` comment cancels any in-flight fix run for the same PR and
starts a new one.

## How it helps

- Review feedback is addressed quickly — often before the reviewer checks back.
- Fixes are scoped to exactly what the review requested, reducing churn.
- The iteration cap prevents the fix and [review](review.md) agents from looping indefinitely.
## Control labels

## Commands
| Label | Meaning |
|-------|---------|
| `fullsend-no-fix` | Prevents automatic fix runs on this PR. Applied by `/fs-fix-stop`. Manual `/fs-fix` commands are unaffected. |
| `needs-human` | The fix agent is approaching its iteration cap and needs human direction. Applied automatically when an automatic fix iteration reaches the warning threshold. |

| Command | Where | Effect |
|---------|-------|--------|
| `/fs-fix` | PR comment | Triggers the fix agent on the PR |
| `/fs-fix-stop` | PR comment | Disables the fix agent for this PR |
## Configuration

Requires write-level repository permission (admin, maintain, or write).
See [Customizing with AGENTS.md](https://fullsend.sh/docs/guides/user/customizing-with-agents-md) and
[Customizing with Skills](https://fullsend.sh/docs/guides/user/customizing-with-skills).

The `/fs-fix` command accepts optional free-text instructions after the
command. The text is passed to the agent as a human instruction, giving you
direct control over what to fix:
### Variables

- `/fs-fix` — fix whatever the [review agent](review.md) flagged
- `/fs-fix you forgot to update the docs here`
- `/fs-fix the error handling in processItem needs to distinguish between retryable and fatal errors`
- `/fs-fix address the concern raised in #42` — same-repo references work
([details](#links-and-urls-in-instructions))
None.

Comment thread
rh-hemartin marked this conversation as resolved.
Resolved
The fix agent also triggers automatically when the [review agent](review.md) submits a
"changes requested" review on a same-repo PR (fork PRs are blocked).
## How the agent works

`/fs-fix-stop` adds the `fullsend-no-fix` label to the PR, preventing any
further bot-triggered fix runs. Human-triggered `/fs-fix` commands still work.
Remove the label or use `/fs-fix` to re-engage.
The fix agent follows the same pipeline as the [code agent](code.md):

## Control labels
1. **Pre-script** validates inputs and checks the iteration cap (preventing infinite fix loops).
2. **Sandbox** — the agent reads each review finding, implements targeted fixes, and verifies them against tests and linters.
3. **Validation loop** — the output is checked against a schema, with up to 2 retry iterations if the output is malformed.
4. **Post-script** pushes the commit and posts a summary comment on the PR.

| Label | Meaning |
|-------|---------|
| `fullsend-no-fix` | Prevents bot-triggered fix runs on this PR. Applied by `/fs-fix-stop`. Human `/fs-fix` commands are unaffected. |
| `needs-human` | The fix agent is approaching its iteration cap and needs human direction. Applied automatically when a bot-triggered fix iteration reaches the warning threshold. |
### Input details

## Configuration and extension
**Bot-triggered** (review agent requests changes):

See [Customizing with AGENTS.md](https://fullsend.sh/docs/guides/user/customizing-with-agents-md) and
[Customizing with Skills](https://fullsend.sh/docs/guides/user/customizing-with-skills).
| Input | Source | How it gets there |
|-------|--------|-------------------|
| Review body | Latest `CHANGES_REQUESTED` review from the review bot | Pre-fetched on the runner before the sandbox starts, injected as `review-body.txt` |
| PR diff | `gh pr diff` inside the sandbox | Agent calls this to understand what code changed |
| Repository checkout | Full repo at PR HEAD | Checked out on the runner, mounted into the sandbox |
| Repo conventions | `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md` | Read from the checkout inside the sandbox |

### Variables
**Human-triggered** (`/fs-fix [instruction]`):

None.
| Input | Source | How it gets there |
|-------|--------|-------------------|
| Human instruction | Free text after `/fs-fix` in the comment | Extracted by the workflow, passed as `HUMAN_INSTRUCTION` env var (up to 10,000 bytes) |
| PR diff | `gh pr diff` inside the sandbox | Same as bot-triggered |
| Repository checkout | Full repo at PR HEAD | Same as bot-triggered |
| Repo conventions | `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md` | Same as bot-triggered |
| Review body (if any) | Prior review bot `CHANGES_REQUESTED` review | Still injected as `review-body.txt`, but human instruction takes precedence |

## Source

Expand Down
23 changes: 13 additions & 10 deletions docs/prioritize.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,20 +2,20 @@

![Prioritize agent icon](icons/prioritize.png)

Scores a GitHub issue using the RICE framework (Reach, Impact, Confidence, Effort) and produces structured scores with reasoning for project board ranking.

## How the agent works

Triggered on a schedule (the prioritize scheduler polls the project board for unscored or stale issues) or on-demand via `/fs-prioritize`.

The prioritize agent fetches the issue and all its context, then evaluates it across the four RICE dimensions. It can invoke customer-research skills to gather additional signal about reach and impact. The output is a structured JSON result with per-dimension scores and written reasoning, which the post-script uses to update the project board.
Scores a GitHub issue using the RICE framework (Reach, Impact, Confidence, Effort) and produces scores with reasoning for project board ranking.

## How it helps

- Issues are ranked consistently using the same framework, reducing bias from whoever happens to see them first.
- Scoring reasoning is transparent and auditable — anyone can read why an issue was ranked the way it was.
- Project boards stay sorted by value, so humans can focus on the highest-impact work first.

## Triggers

The prioritize agent runs on a schedule, polling the project board for unscored or stale issues.

It can also be triggered manually with the `/fs-prioritize` command.

## Commands

| Command | Where | Effect |
Expand All @@ -31,10 +31,9 @@ skill data.
## Control labels

The prioritize agent does not apply or consume control labels. It reads the
issue content and produces a structured score — the post-script updates the
project board directly.
issue content and produces a score — the project board is updated directly.

## Configuration and extension
## Configuration

### Skill: `customer-research`

Expand All @@ -61,6 +60,10 @@ about it" (Reach 2.0), instead of guessing from the issue text alone.

None.

## How the agent works

The prioritize agent fetches the issue and all its context, then evaluates it across the four RICE dimensions. It can invoke customer-research skills to gather additional signal about reach and impact. The output is a structured JSON result with per-dimension scores and written reasoning, which the post-script uses to update the project board.

## Source

[`harness/prioritize.yaml`](../harness/prioritize.yaml)
Loading