diff --git a/docs/architecture/orchestrator.md b/docs/architecture/orchestrator.md index 4e552a0cc5..e3cf73e4a2 100644 --- a/docs/architecture/orchestrator.md +++ b/docs/architecture/orchestrator.md @@ -88,9 +88,9 @@ See `orchestrator/health_checks/README.md` for the full framework reference, inc Pipelines can specify an explicit network mode that controls internet access for spawned containers: -- **`public`**: Full internet access (default for issue-mode pipelines) +- **`public`**: Full internet access (default) - **`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` +- **`None`** (auto): Defaults to `public` **Setting network mode:** @@ -125,7 +125,7 @@ The orchestrator reads pipeline artifacts (verdict files, draft documents, check - Worktree paths are resolved dynamically based on pipeline ID and repository **Key artifact files in worktrees:** -- `.egg-state/contracts/{identifier}.json` — Contract state (issue number for issue-mode, pipeline ID for local-mode) +- `.egg-state/contracts/{identifier}.json` — Contract state (issue number for issue-driven pipelines, pipeline ID for prompt-driven pipelines) - `.egg-state/drafts/{identifier}-analysis.md` — Draft for `refine` phase (special-cased to `analysis`) - `.egg-state/drafts/{identifier}-{phase}.md` — Draft for other phases (e.g., `plan`). No draft for `implement` phase. - `.egg-state/reviews/{identifier}-{phase}-{reviewer_type}-review.json` — Review verdict files diff --git a/docs/development/STRUCTURE.md b/docs/development/STRUCTURE.md index d56346bec5..e6bee17cce 100644 --- a/docs/development/STRUCTURE.md +++ b/docs/development/STRUCTURE.md @@ -15,6 +15,7 @@ egg/ ├── sandbox/ # Sandbox container (untrusted, runs the LLM agent) ├── scripts/ # Validation and lint scripts ├── shared/ # Shared Python libraries (used by gateway + sandbox) +├── skills/ # Claude Code skills (installed into sandbox at startup) ├── tests/ # Unit tests ├── dev # Development CLI (setup, lint, test, ci) └── README.md @@ -30,8 +31,9 @@ egg/ | `integration_tests/` | Integration tests requiring Docker and real containers | CI / local | | `orchestrator/` | SDLC pipeline orchestrator: state management, container lifecycle, HITL queue | Orchestrator container | | `sandbox/` | Agent environment: Claude Code, tools, entrypoint | Sandbox container | -| `shared/` | Shared libraries: logging, config, git utilities, centralized constants | All containers | | `scripts/` | CI/lint scripts (config validation, import checks, hardcoded port detection, reviewer job name enforcement, LLM API boundary enforcement, model alias enforcement) | CI / local | +| `shared/` | Shared libraries: logging, config, git utilities, centralized constants | All containers | +| `skills/` | Claude Code skills (each subdirectory is a skill with `SKILL.md`) | Sandbox container | | `tests/` | Test suite | CI / local | ## Gateway Structure @@ -254,8 +256,8 @@ integration_tests/ ├── deployment_validation/ # Deployment validation integration tests │ ├── __init__.py │ └── test_deployment_check_e2e.py # End-to-end devserver lifecycle tests -├── local_pipeline/ # Local orchestrator integration tests -│ ├── conftest.py # Local pipeline test fixtures +├── local_pipeline/ # Orchestrator pipeline integration tests +│ ├── conftest.py # Pipeline test fixtures │ ├── docker-compose.yml # Orchestrator test environment │ ├── helpers.py # Shared API helper functions for tests │ ├── mock-sandbox/ # Mock sandbox for testing @@ -265,7 +267,7 @@ integration_tests/ │ ├── test_hitl_edge_cases.py # HITL decision edge case tests │ ├── test_local_pipeline.py # Orchestrator pipeline tests │ ├── test_signals.py # Signal handling tests -│ ├── test_unified_pipeline_behavior.py # Unified local/issue mode behavior tests +│ ├── test_unified_pipeline_behavior.py # Unified pipeline behavior tests │ └── test_worktree_integration.py # Worktree lifecycle and pipeline isolation tests └── sdlc/ # SDLC pipeline integration tests ├── conftest.py # SDLC test fixtures diff --git a/docs/development/TEST_COVERAGE_PLAN.md b/docs/development/TEST_COVERAGE_PLAN.md index b615abacbc..673584a1e1 100644 --- a/docs/development/TEST_COVERAGE_PLAN.md +++ b/docs/development/TEST_COVERAGE_PLAN.md @@ -41,7 +41,7 @@ integration_tests/ # Docker-based integration tests (~16 files) ├── test_network_isolation.py ├── test_credential_security.py ├── test_policy_enforcement.py -├── local_pipeline/ # Local orchestrator integration tests +├── local_pipeline/ # Orchestrator pipeline integration tests │ └── ... # API validation, concurrency, error recovery, HITL, signals, worktree └── ... ``` @@ -350,7 +350,7 @@ tests/ gateway/tests/ # Gateway-specific tests (keep separate) orchestrator/tests/ # Orchestrator-specific tests (keep separate) integration_tests/ # Full E2E tests (existing) -├── local_pipeline/ # Local orchestrator integration tests +├── local_pipeline/ # Orchestrator pipeline integration tests │ ├── helpers.py # Shared API helpers │ ├── test_api_validation.py │ ├── test_concurrent_pipelines.py diff --git a/docs/guides/local-quickstart.md b/docs/guides/local-quickstart.md index 2ae396d375..17a8b28a8c 100644 --- a/docs/guides/local-quickstart.md +++ b/docs/guides/local-quickstart.md @@ -76,7 +76,7 @@ On subsequent runs, `egg` starts the gateway and orchestrator automatically. The ## 4. Using the SDLC pipeline -### Option A: Local pipeline (prompt-driven, no GitHub interaction) +### Option A: Prompt-driven pipeline (no GitHub interaction) Inside the sandbox, run: @@ -84,16 +84,16 @@ Inside the sandbox, run: /sdlc ``` -With no arguments, this starts a **local pipeline**. The agent will: +With no arguments, this starts a **prompt-driven 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 → PR phases entirely locally +3. Create a pipeline in the orchestrator +4. Run through refine → plan → implement → PR phases During refine and plan phases, the gateway restricts pushes to state files and blocks PR operations. During the PR phase, the orchestrator auto-creates the PR using metadata from the plan, commit log, and diff stats — no agent is spawned. -**Local pipeline phases:** +**Pipeline phases:** | Phase | What happens | |-------|-------------| @@ -157,7 +157,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 create PRs during the PR phase but do not interact with GitHub issues. The orchestrator auto-creates the PR via `GatewayClient.create_pr()` — no agent is spawned during the PR phase. +Prompt-driven pipelines create PRs during the PR phase but do not interact with GitHub issues. The orchestrator auto-creates the PR via `GatewayClient.create_pr()` — no agent is spawned during the PR phase. 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. diff --git a/docs/guides/sdlc-pipeline.md b/docs/guides/sdlc-pipeline.md index 424a801e22..13454e6ab3 100644 --- a/docs/guides/sdlc-pipeline.md +++ b/docs/guides/sdlc-pipeline.md @@ -28,7 +28,7 @@ Agents cannot be trusted to self-police via prompts alone. The pipeline enforces ### 2. Contract-as-Code -All pipeline state is stored in JSON contracts at `.egg-state/contracts/{identifier}.json` and committed to the feature branch (not main), where `{identifier}` is the issue number for issue-mode pipelines or the pipeline ID for local-mode pipelines. This provides: +All pipeline state is stored in JSON contracts at `.egg-state/contracts/{identifier}.json` and committed to the feature branch (not main), where `{identifier}` is the issue number for issue-driven pipelines or the pipeline ID for prompt-driven pipelines. This provides: - Auditable history of all state changes - Recovery from failures without losing progress @@ -48,7 +48,7 @@ Code reviews are performed by the existing PR review workflow (`reusable-review. ### 4. Human-in-the-Loop at Critical Points -The pipeline pauses for human approval at phase transitions (refine and plan). The orchestrator's decision queue handles approval in both issue and local modes, and supports requesting changes with a circuit breaker (`max_review_cycles`, default 3) to prevent unbounded revision loops. +The pipeline pauses for human approval at phase transitions (refine and plan). The orchestrator's decision queue handles approval and supports requesting changes with a circuit breaker (`max_review_cycles`, default 3) to prevent unbounded revision loops. ## Pipeline Architecture @@ -812,7 +812,7 @@ Pipeline decisions made during refine and plan phases are automatically synced t **How it works:** 1. Agents create decisions via `OrchClient.create_decision()` or by queueing HITL checkpoints -2. Human resolves the decision (via terminal in local mode, or checkbox in issue mode) +2. Human resolves the decision (via terminal in prompt-driven mode, or checkbox in issue-driven mode) 3. After the phase completes, `_sync_pipeline_decisions_to_contract()` converts resolved non-phase-gate `HITLDecision` objects to contract `Decision` format 4. Synced decisions appear in `.egg-state/contracts/{identifier}.json` under the `decisions` array 5. Implement-phase agents can read these decisions from the contract to understand context @@ -1197,16 +1197,16 @@ The `egg-sdlc` CLI provides an interactive terminal interface for driving SDLC p **Usage:** ```bash -# Issue mode: start/attach to pipeline for a GitHub issue +# Issue-driven: start/attach to pipeline for a GitHub issue egg-sdlc -r -i egg-sdlc -r # Short form (positional issue) egg-sdlc --private -r -i # Private mode (network lockdown) -# Local mode: prompt-driven pipeline (no GitHub) +# Prompt-driven: interactive pipeline (no GitHub issue) egg-sdlc ``` -**Note:** Issue mode requires the `-r/--repo` flag specifying the repository directory name under `~/repos/` (e.g., `egg`). The flag also accepts full `owner/repo` format for direct specification. Repo autodetection was removed in favor of explicit specification. +**Note:** Issue-driven pipelines require the `-r/--repo` flag specifying the repository directory name under `~/repos/` (e.g., `egg`). The flag also accepts full `owner/repo` format for direct specification. Repo autodetection was removed in favor of explicit specification. **Features:** - Real-time DAG visualization (reuses `egg-pipeline-watch` SSE patterns) @@ -1237,7 +1237,7 @@ The SDLC pipeline can also be triggered via the local orchestrator API: # Via orchestrator API curl -X POST http://localhost:9849/api/v1/pipelines \ -H "Content-Type: application/json" \ - -d '{"issue_number": 123, "mode": "issue"}' + -d '{"issue_number": 123, "repo": "owner/repo", "branch": "egg/issue-123"}' # Via egg-orch CLI egg-orch pipeline create --issue 123 @@ -1278,10 +1278,10 @@ collaborating via a polling-based message bus hosted by the orchestrator. Enable concurrent execution with the `--concurrent` CLI flag: ```bash -# Issue mode +# Issue-driven egg-sdlc -r egg -i 999 --concurrent -# Local/prompt mode +# Prompt-driven egg-sdlc -r egg -p "Add feature X" --concurrent # Via egg-orch directly diff --git a/docs/hitl-decisions.md b/docs/hitl-decisions.md index 6d183fb838..eaad4a4c53 100644 --- a/docs/hitl-decisions.md +++ b/docs/hitl-decisions.md @@ -13,7 +13,7 @@ Three mechanisms exist for gathering human input: 2. **Feedback comments** — Open-ended questions in an editable comment 3. **Phase approval** — Single checkbox to approve and advance to the next phase -In local mode, decisions carry a `decision_type` field (`phase_gate`, `choice`, or `feedback`) that drives type-specific terminal rendering. The orchestrator's decision queue supports a "request changes" option at phase gates, with a circuit breaker (`max_hitl_review_cycles`, default 3) to prevent unbounded revision loops. See [Local Mode: Type-Aware Terminal Rendering](#local-mode-type-aware-terminal-rendering) for details. +In prompt-driven mode, decisions carry a `decision_type` field (`phase_gate`, `choice`, or `feedback`) that drives type-specific terminal rendering. The orchestrator's decision queue supports a "request changes" option at phase gates, with a circuit breaker (`max_hitl_review_cycles`, default 3) to prevent unbounded revision loops. See [Prompt-Driven Mode: Type-Aware Terminal Rendering](#prompt-driven-mode-type-aware-terminal-rendering) for details. **Decision sync to contract**: Resolved decisions made during refine and plan phases are automatically synced to the contract (`.egg-state/contracts/{identifier}.json`) after each phase completes, so implement-phase agents can see substantive choices (database selection, API style, config handling, etc.) made earlier. Phase gate decisions (approve/reject) are excluded from sync as they are process control, not implementation-relevant context. See [SDLC Pipeline Guide § Decision Sync to Contract](sdlc-pipeline.md#decision-sync-to-contract) for details. @@ -152,7 +152,7 @@ Phase approval is a simpler mechanism for advancing the pipeline at HITL gates. 3. When the human checks the `[x] Approve` checkbox, the orchestrator detects the change 4. The contract phase is updated and the next pipeline phase is triggered -In **local mode**, the orchestrator handles phase approval via its decision queue with `decision_type="phase_gate"`. The terminal displays the full document in a pager (default: `less -R`) and offers view, edit, approve, and request-changes options. A circuit breaker (`max_hitl_review_cycles`, default 3) prevents unbounded revision loops. +In **prompt-driven mode**, the orchestrator handles phase approval via its decision queue with `decision_type="phase_gate"`. The terminal displays the full document in a pager (default: `less -R`) and offers view, edit, approve, and request-changes options. A circuit breaker (`max_hitl_review_cycles`, default 3) prevents unbounded revision loops. ### Key Differences from Decisions @@ -208,9 +208,9 @@ Check that: - The submit checkbox is checked: `- [x] Submit feedback` - Answers are in blockquote format: `> Answer text` -## Local Mode: Type-Aware Terminal Rendering +## Prompt-Driven Mode: Type-Aware Terminal Rendering -In local mode (`egg-sdlc`), the HITL checkpoint handler (`sandbox/egg_lib/sdlc_hitl.py`) dispatches to type-specific terminal UIs based on the `decision_type` field on `HITLDecision`. +In prompt-driven mode (`egg-sdlc`), the HITL checkpoint handler (`sandbox/egg_lib/sdlc_hitl.py`) dispatches to type-specific terminal UIs based on the `decision_type` field on `HITLDecision`. ### Decision Types @@ -222,7 +222,7 @@ In local mode (`egg-sdlc`), the HITL checkpoint handler (`sandbox/egg_lib/sdlc_h ### Contract Decision Bridge -Contract decisions created by agents via `egg-contract add-decision` are automatically bridged to the phase gate menu in local mode. When unanswered decisions exist in the contract JSON, the phase gate displays a `[q] Answer open questions` option that lets humans respond directly from the terminal. Approving a phase gate with unanswered questions triggers a warning prompt. +Contract decisions created by agents via `egg-contract add-decision` are automatically bridged to the phase gate menu in prompt-driven mode. When unanswered decisions exist in the contract JSON, the phase gate displays a `[q] Answer open questions` option that lets humans respond directly from the terminal. Approving a phase gate with unanswered questions triggers a warning prompt. ### Draft Document Display