Skip to content

docs: Update local-mode PR phase behavior [doc-updater] #693

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jwbron merged 3 commits into from
Feb 15, 2026
Merged

docs: Update local-mode PR phase behavior [doc-updater] #693

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3a0775e
Update docs for PR-phase access in local mode
jwbron Feb 15, 2026
a1d5792
Fix contradictory network mode docs and clarify gateway restrictions
egg-reviewer[bot] Feb 15, 2026
f3e8e63
Fix pr comment attribution and add add-decision to Refine row
egg-reviewer[bot] Feb 15, 2026
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
8 changes: 4 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,10 +99,10 @@ Each pipeline phase has a defined set of permitted operations:

| Phase | Allowed Operations | Exit Requires |
|-------|-------------------|---------------|
| **Refine** | `gh issue comment/edit` | Human approval |
| **Plan** | `gh issue comment/edit`, `egg-contract add-decision` | Human approval |
| **Implement** | `git push`, `egg-contract add-commit/update-notes` | All checks pass (CI + PR review) |
| **Merge** | `gh pr edit`, `git push` | Human merge |
| **Refine** | `gh issue comment/edit`, `git push` (state files), `egg-contract add-decision` | Human approval |
| **Plan** | `gh issue comment/edit`, `git push` (state files), `egg-contract add-decision` | Human approval |
| **Implement** | `git push` (code), `egg-contract add-commit/update-notes` | All checks pass (CI + PR review) |
| **PR** | `gh pr create/edit/comment`, `git push` | Human merge |

### How Isolation Works

Expand Down
4 changes: 2 additions & 2 deletions docs/architecture/orchestrator.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ Pipelines can specify an explicit network mode that controls internet access for

- **`public`**: Full internet access (default for issue-mode pipelines)
- **`private`**: Network lockdown - Anthropic API + private GitHub repos only (enforced by gateway proxy)
- **`None`** (auto): Falls back based on pipeline mode — `issue` → `public`, `local` → `local` for non-PR phases (switches to `public` for the PR phase to enable push access)
- **`None`** (auto): Falls back based on pipeline mode — `issue` → `public`, `local` → `local`

**Setting network mode:**

Expand All @@ -60,7 +60,7 @@ Pipelines can specify an explicit network mode that controls internet access for

**Special case: PR phase in local mode**

Local-mode pipelines normally use `local` gateway mode (isolated network without proxy/DNS lockdown), but the PR phase requires push access. If `network_mode="private"`, the pipeline stays in private mode even during the PR phase (no push allowed). Otherwise, the PR phase temporarily switches to `public` mode to enable `git push` and `gh pr create`.
Local-mode pipelines use `local` gateway mode throughout all phases, including the PR phase. During the PR phase, the gateway allows PR-specific operations (`gh pr create`, `gh pr edit`) based on phase permissions (`.egg/phase-permissions.json`), while continuing to block other GitHub operations. If `network_mode="private"`, the pipeline stays in private mode even during the PR phase (no push allowed).

## Per-Pipeline Worktrees

Expand Down
16 changes: 5 additions & 11 deletions docs/guides/local-quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,24 +87,18 @@ With no arguments, this starts a **local pipeline**. The agent will:
1. Ask what you want to build
2. Ask 1-2 clarifying questions
3. Create a local pipeline in the orchestrator
4. Run through refine → plan → implement phases entirely locally
4. Run through refine → plan → implement → PR phases entirely locally

No code is pushed, no PR is created, and no GitHub issues are touched. The gateway enforces this — `git push` and `gh` commands return 403 in local mode.

When the pipeline completes, push and create a PR manually:

```bash
git push origin egg/my-feature
gh pr create --title "Add feature" --body "..."
```
During refine and plan phases, the gateway restricts pushes to state files and blocks PR operations. During the PR phase, the gateway allows PR creation and editing so the agent can create a draft PR for your review.

**Local pipeline phases:**

| Phase | What happens |
|-------|-------------|
| **Refine** | Agent analyzes requirements from your prompt |
| **Plan** | Agent creates an implementation plan |
| **Implement** | Agent writes code locally (terminal phase) |
| **Implement** | Agent writes code locally |
| **PR** | Agent creates a draft PR (terminal phase) |

### Option B: Issue pipeline (GitHub-driven)

Expand Down Expand Up @@ -161,7 +155,7 @@ Here's what the issue pipeline creates and when:

**Nothing is merged automatically.** The gateway enforces merge blocking — only humans can merge PRs via the GitHub UI.

Local pipelines do not interact with GitHub at all — the gateway blocks push and gh operations in local mode.
Local pipelines create PRs during the PR phase but do not interact with GitHub issues. The gateway blocks most gh operations in local mode, but allows PR operations during the PR phase based on phase permissions.

The pipeline stores its internal state in `.egg-state/` on the feature branch (not on main). This includes the contract JSON, draft documents, and review verdicts.

Expand Down