Skip to content

docs: Update docs for HITL workflow [doc-updater] #338

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 1 commit into from
Feb 8, 2026
Merged

docs: Update docs for HITL workflow [doc-updater] #338

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
14 changes: 13 additions & 1 deletion docs/adr/implemented/ADR-SDLC-Pipeline.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -205,6 +205,8 @@ This functionality has been replaced by the PR-based review workflow, which prov

## HITL (Human-in-the-Loop) Mechanism

For detailed HITL workflow documentation, see [HITL Decisions](../../hitl-decisions.md).

When escalation occurs, the system generates a decision block with checkboxes for human input.

### Checkbox Categories
Expand All @@ -220,6 +222,14 @@ A 30-second debounce prevents accidental clicks:
- Decision is processed only after debounce expires
- Comment is updated with countdown status

### Phase Approval

In addition to formal HITL decisions, a simpler phase approval mechanism exists for advancing between phases:
- Uses `<!-- egg-phase-approval -->` markers in comments
- Single checkbox: `- [ ] Approve and advance to next phase`
- Detected by the `handle-approval` job in `sdlc-hitl.yml`
- See [Phase Completion Template](../../templates/phase-completion.md) for the comment format

---

## Gateway Integration
Expand Down Expand Up @@ -338,7 +348,9 @@ Long-running jobs checkpoint state before timeout:
| CLI tools | `sandbox/egg_lib/contract_cli.py` |
| PR review workflow | `.github/workflows/reusable-review.yml` |
| Workflow files | `.github/workflows/sdlc-*.yml` |
| Templates | `docs/templates/analysis.md`, `docs/templates/plan.md` |
| Templates | `docs/templates/analysis.md`, `docs/templates/plan.md`, `docs/templates/phase-completion.md` |
| HITL documentation | `docs/hitl-decisions.md` |
| HITL integration tests | `tests/workflows/test_hitl_integration.py` |

---

Expand Down
2 changes: 1 addition & 1 deletion docs/architecture/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ Agents interact with contract state via the `egg-contract` CLI (`sandbox/egg_lib
| `egg-contract update-notes --task <id> --notes <text>` | Add implementation notes |
| `egg-contract mark-task --task <id> --status <status>` | Mark task status (deprecated as of PR #285) |
| `egg-contract mark-phase --phase <id> --passed <bool>` | Mark phase status (deprecated as of PR #285) |
| `egg-contract add-decision --question <text> [--options ...]` | Create HITL decision point, optionally with predefined choices |
| `egg-contract add-decision --question <text> [--options ...] [--format {json,markdown}]` | Create HITL decision point with optional predefined choices and markdown output format for GitHub comments |

### Plan Parser

Expand Down
12 changes: 12 additions & 0 deletions docs/development/STRUCTURE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -122,6 +122,18 @@ integration_tests/
└── test_role_enforcement.py # Role-based mutation enforcement
```

## Unit Tests Structure

```
tests/
├── sandbox/ # Sandbox component tests
│ ├── test_contract_cli.py # Contract CLI tests
│ └── ...
└── workflows/ # Workflow integration tests
├── __init__.py
└── test_hitl_integration.py # HITL decision format verification
```

## Action Directory

```
Expand Down
27 changes: 18 additions & 9 deletions docs/guides/sdlc-pipeline.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -205,24 +205,26 @@ This functionality has been replaced by the PR-based review workflow, which prov

## Human-in-the-Loop Decisions

For detailed documentation on HITL workflows, see [HITL Decisions](../hitl-decisions.md).

### Checkbox-Based Interface

HITL decisions render as checkboxes in bot comments:
HITL decisions render as checkboxes in bot comments. The `<!-- egg-hitl-decision id=... -->` marker identifies each decision:

```markdown
## Human Decision Required

### Option 1: Provide Guidance
<!-- HITL-DECISION: guidance -->
- [ ] I will provide additional context or requirements below
- [ ] The acceptance criteria should be adjusted
- [ ] Break this task into smaller sub-tasks
<!-- egg-hitl-decision id=decision-1 -->

### Option 2: Override
<!-- HITL-DECISION: override -->
**How should we proceed with this task?**

- [ ] Provide additional context or requirements below
- [ ] Adjust the acceptance criteria
- [ ] Break this task into smaller sub-tasks
- [ ] Mark current tasks as complete (override review)
- [ ] Skip remaining tasks in this phase
- [ ] Cancel the pipeline for this issue
- [ ] Other (explain in reply)
```

### Debounce Mechanism
Expand Down Expand Up @@ -304,6 +306,10 @@ Template sections:
- [TASK-1-2] Add role validation — Acceptance: Unauthorized mutations rejected
```

### Phase Completion Comments

When a phase is complete and ready for human approval, agents post a comment using the [Phase Completion Template](../templates/phase-completion.md). This format includes the `<!-- egg-phase-approval -->` marker which the HITL workflow uses to detect approval checkbox changes.

### Task Population

Tasks are automatically extracted from the plan document and populated into the contract during the plan phase, after the plan document is validated.
Expand Down Expand Up @@ -363,8 +369,11 @@ egg-contract add-commit --task task-1-1 --commit abc1234
# Add implementation notes (implementer)
egg-contract update-notes --task task-1-1 --notes "Completed validation"

# Create HITL decision point
# Create HITL decision point (plain text)
egg-contract add-decision --question "Should we proceed with approach X?"

# Create HITL decision point with markdown checkbox format (for GitHub comments)
egg-contract add-decision --question "Which approach?" --options "A" "B" --format markdown
```

**Note:** `mark-task` and `mark-phase` commands (previously used by the dedicated reviewer agent) are deprecated as of PR #285. Task validation now happens via PR-based code review.
Expand Down
7 changes: 7 additions & 0 deletions docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,13 @@ This index helps both humans and LLMs navigate the documentation efficiently.
|----------|-------------|
| [Analysis Template](templates/analysis.md) | Problem analysis template for the refine phase |
| [Plan Template](templates/plan.md) | Implementation plan template with task ID format for the plan phase |
| [Phase Completion Template](templates/phase-completion.md) | Phase completion comment format with approval checkbox |

### SDLC Workflow Documentation

| Document | Description |
|----------|-------------|
| [HITL Decisions](hitl-decisions.md) | Human-in-the-loop decision workflow with formal decisions and phase approvals |

## Component Documentation

Expand Down
Loading