Skip to content
Merged
Show file tree
Hide file tree
Changes from 9 commits
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
298 changes: 298 additions & 0 deletions .egg-state/contracts/262.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,298 @@
{
"schemaVersion": "1.0",
"issue": {
"number": 262,
"title": "Refine the SDLC human plan review workflow",
"url": "https://github.com/jwbron/egg/issues/262"
},
"current_phase": "implement",
"acceptance_criteria": [
{
"id": "ac-1",
"description": "[TASK-1-1] CLI outputs properly formatted markdown block with HITL markers",
"verified": false
},
{
"id": "ac-2",
"description": "[TASK-1-2] Any add-decision with --options includes \"Other\" as last option",
"verified": false
},
{
"id": "ac-3",
"description": "[TASK-1-3] Tests cover markdown output, auto-appended Other, and edge cases",
"verified": false
},
{
"id": "ac-4",
"description": "[TASK-2-1] Template has guidance on formal HITL decisions, no informal checkboxes",
"verified": false
},
{
"id": "ac-5",
"description": "[TASK-2-2] Template includes approval checkbox with correct HTML marker",
"verified": false
},
{
"id": "ac-6",
"description": "[TASK-2-3] Template mentions approval should use phase-completion format",
"verified": false
},
{
"id": "ac-7",
"description": "[TASK-3-1] Prompt instructs agent to include decision markdown and approval section",
"verified": false
},
{
"id": "ac-8",
"description": "[TASK-3-2] Prompt includes approval section instructions",
"verified": false
},
{
"id": "ac-9",
"description": "[TASK-3-3] Consistent approval format across all prompts",
"verified": false
},
{
"id": "ac-10",
"description": "[TASK-4-1] Test verifies workflow regex patterns match CLI output format",
"verified": false
},
{
"id": "ac-11",
"description": "[TASK-4-2] Documentation explains informal vs formal decisions and approval flow",
"verified": false
}
],
"phases": [
{
"id": "phase-1",
"name": "Enhance Contract CLI Decision Output",
"status": "pending",
"tasks": [
{
"id": "task-1-1",
"description": "Add --format markdown flag to add-decision command",
"status": "pending",
"acceptance_criteria": "CLI outputs properly formatted markdown block with HITL markers",
"files_affected": [
"sandbox/egg_lib/contract_cli.py"
],
"commit": null,
"review_cycles": 0,
"max_cycles": 3,
"escalated": false,
"notes": ""
},
{
"id": "task-1-2",
"description": "Auto-append \"Other (explain in reply)\" option",
"status": "pending",
"acceptance_criteria": "Any add-decision with --options includes \"Other\" as last option",
"files_affected": [
"sandbox/egg_lib/contract_cli.py"
],
"commit": null,
"review_cycles": 0,
"max_cycles": 3,
"escalated": false,
"notes": ""
},
{
"id": "task-1-3",
"description": "Add unit tests for new add-decision output format",
"status": "pending",
"acceptance_criteria": "Tests cover markdown output, auto-appended Other, and edge cases",
"files_affected": [
"tests/sandbox/test_contract_cli.py"
],
"commit": null,
"review_cycles": 0,
"max_cycles": 3,
"escalated": false,
"notes": ""
}
],
"review_cycles": 0,
"max_cycles": 3,
"escalated": false,
"escalation_reason": null,
"review_feedback": []
},
{
"id": "phase-2",
"name": "Update Templates with Approval Section",
"status": "pending",
"tasks": [
{
"id": "task-2-1",
"description": "Update analysis.md template",
"status": "pending",
"acceptance_criteria": "Template has guidance on formal HITL decisions, no informal checkboxes",
"files_affected": [
"docs/templates/analysis.md"
],
"commit": null,
"review_cycles": 0,
"max_cycles": 3,
"escalated": false,
"notes": ""
},
{
"id": "task-2-2",
"description": "Create phase-completion.md template with approval marker",
"status": "pending",
"acceptance_criteria": "Template includes approval checkbox with correct HTML marker",
"files_affected": [
"docs/templates/phase-completion.md"
],
"commit": null,
"review_cycles": 0,
"max_cycles": 3,
"escalated": false,
"notes": ""
},
{
"id": "task-2-3",
"description": "Update plan.md to reference phase completion format",
"status": "pending",
"acceptance_criteria": "Template mentions approval should use phase-completion format",
"files_affected": [
"docs/templates/plan.md"
],
"commit": null,
"review_cycles": 0,
"max_cycles": 3,
"escalated": false,
"notes": ""
}
],
"review_cycles": 0,
"max_cycles": 3,
"escalated": false,
"escalation_reason": null,
"review_feedback": []
},
{
"id": "phase-3",
"name": "Update Phase Prompts",
"status": "pending",
"tasks": [
{
"id": "task-3-1",
"description": "Update build_refine_prompt() with decision and approval instructions",
"status": "pending",
"acceptance_criteria": "Prompt instructs agent to include decision markdown and approval section",
"files_affected": [
"action/build-sdlc-prompt.sh"
],
"commit": null,
"review_cycles": 0,
"max_cycles": 3,
"escalated": false,
"notes": ""
},
{
"id": "task-3-2",
"description": "Update build_plan_prompt() with approval instructions",
"status": "pending",
"acceptance_criteria": "Prompt includes approval section instructions",
"files_affected": [
"action/build-sdlc-prompt.sh"
],
"commit": null,
"review_cycles": 0,
"max_cycles": 3,
"escalated": false,
"notes": ""
},
{
"id": "task-3-3",
"description": "Add helper text for consistent approval format",
"status": "pending",
"acceptance_criteria": "Consistent approval format across all prompts",
"files_affected": [
"action/build-sdlc-prompt.sh"
],
"commit": null,
"review_cycles": 0,
"max_cycles": 3,
"escalated": false,
"notes": ""
}
],
"review_cycles": 0,
"max_cycles": 3,
"escalated": false,
"escalation_reason": null,
"review_feedback": []
},
{
"id": "phase-4",
"name": "Documentation and Testing",
"status": "pending",
"tasks": [
{
"id": "task-4-1",
"description": "Add integration test for decision markdown parsing",
"status": "pending",
"acceptance_criteria": "Test verifies workflow regex patterns match CLI output format",
"files_affected": [
"tests/workflows/test_hitl_integration.py"
],
"commit": null,
"review_cycles": 0,
"max_cycles": 3,
"escalated": false,
"notes": ""
},
{
"id": "task-4-2",
"description": "Document HITL decision workflow",
"status": "pending",
"acceptance_criteria": "Documentation explains informal vs formal decisions and approval flow",
"files_affected": [
"docs/hitl-decisions.md"
],
"commit": null,
"review_cycles": 0,
"max_cycles": 3,
"escalated": false,
"notes": ""
}
],
"review_cycles": 0,
"max_cycles": 3,
"escalated": false,
"escalation_reason": null,
"review_feedback": []
}
],
"decisions": [],
"circuit_breaker": {
"total_cycles": 0,
"max_total_cycles": 10,
"status": "closed"
},
"audit_log": [
{
"timestamp": "2026-02-08T07:28:18Z",
"actor": "jwbron",
"role": "human",
"action": "transition",
"field_path": "current_phase",
"old_value": "refine",
"new_value": "plan",
"reason": "Phase approved by human"
},
{
"timestamp": "2026-02-08T07:33:06Z",
"actor": "jwbron",
"role": "human",
"action": "transition",
"field_path": "current_phase",
"old_value": "plan",
"new_value": "implement",
"reason": "Phase approved by human"
}
]
}
74 changes: 67 additions & 7 deletions action/build-sdlc-prompt.sh
Original file line number Diff line number Diff line change
Expand Up @@ -160,15 +160,47 @@ In the refine phase:
- You CANNOT push code (git push)
- You CANNOT create PRs (gh pr create)

## HITL Decisions

For questions that require human input before proceeding:

**Multiple-choice questions** (use formal HITL decisions):
\`\`\`bash
egg-contract add-decision --question "Which approach should we use?" \\
--options "Option A" "Option B" "Option C" --format markdown
\`\`\`
Copy the markdown output into your analysis comment. The human can check a checkbox
to select an option. An "Other (explain in reply)" option is auto-appended.

**Open-ended questions** (no predefined options):
List these as plain text in your analysis. The human will respond via comment.

## Phase Completion

When your analysis is complete, post a completion comment with an approval section:

\`\`\`markdown
## Refine Phase Complete

[Summary of analysis and recommendation]

### Ready for Review

<!-- egg-phase-approval -->
- [ ] Approve and advance to plan phase

---

*Authored-by: egg*
\`\`\`

## Next Steps

When your analysis is complete:
1. Write the analysis document to a file: \`/tmp/analysis.md\`
2. Post via file to avoid shell escaping issues: \`gh issue comment ${issue_number} --body-file /tmp/analysis.md\`
3. If you have open questions, use \`egg-contract add-decision --question "..."\`
4. Wait for human approval to advance to the plan phase
3. Wait for human approval (they check the approval checkbox)

**IMPORTANT**: Always use \`--body-file\` instead of \`--body\` when posting analysis.
**IMPORTANT**: Always use \`--body-file\` instead of \`--body\` when posting.
Content containing \`\${{ }}\` expressions or other shell metacharacters will corrupt
the comment if passed inline via \`--body\`.
EOF
Expand Down Expand Up @@ -268,13 +300,41 @@ In the plan phase:
- You CANNOT push code (git push)
- You CANNOT create PRs (gh pr create)

## HITL Decisions

For questions that require human input before proceeding:

**Multiple-choice questions** (use formal HITL decisions):
\`\`\`bash
egg-contract add-decision --question "Which architecture pattern?" \\
--options "Microservices" "Monolith" "Hybrid" --format markdown
\`\`\`
Copy the markdown output into your plan comment. The human can check a checkbox
to select an option. An "Other (explain in reply)" option is auto-appended.

**Open-ended questions** (no predefined options):
List these as plain text. The human will respond via comment.

## Phase Completion

When your plan is complete, include an approval section at the end:

\`\`\`markdown
### Ready for Review

<!-- egg-phase-approval -->
- [ ] Approve and advance to implement phase

---

*Authored-by: egg*
\`\`\`

## Next Steps

When your plan is complete:
1. Write the plan document to a file: \`/tmp/plan.md\`
2. Post via file to avoid shell escaping issues: \`gh issue comment ${issue_number} --body-file /tmp/plan.md\`
3. If you have open questions, use \`egg-contract add-decision --question "..."\`
4. Wait for human approval to advance to the implement phase
3. Wait for human approval (they check the approval checkbox)

**IMPORTANT**: Always use \`--body-file\` instead of \`--body\` when posting the plan.
Content containing \`\${{ }}\` expressions or other shell metacharacters will corrupt
Expand Down
Loading
Loading