sehoon787/gstack-sprint

<Purpose> gstack-sprint wraps the 3-Phase Sprint workflow (design→execute→review) as a structured skill to guarantee deterministic execution. Without this skill, the 3-Phase workflow exists only as prompt instructions in boss.md and may be forgotten during long sessions. This skill is the single entry point for end-to-end feature implementation — it coordinates design, execution, and review with user confirmation at each phase boundary. </Purpose>

<Use_When>

• End-to-end feature implementation ("build this feature for me", "design and implement this")
• Build or Mid-sized intent type with implementation phase included
• User says "sprint", "end-to-end", "e2e implementation" </Use_When>

<Do_Not_Use_When>

• Pure design/planning/idea review without implementation → use /office-hours or /plan-ceo-review directly
• Architecture intent type (design only, no build)
• "just design it", "just plan it", "review this idea" — these route to /office-hours or /plan-ceo-review
• Single-purpose requests: code review → /review, QA → /qa, deploy → /ship
• Trivial fixes, research, documentation </Do_Not_Use_When>

<Why_This_Exists> End-to-end feature work fails silently in three predictable ways:

1. Implementation starts before design is aligned — wrong thing built
2. Execution proceeds without structured iteration — partial implementations declared done
3. Review skips comparison against the design doc — drift goes unnoticed

gstack-sprint enforces the three-phase contract: user-confirmed design → automated execution via ralph → user-confirmed review against the design doc. Each phase boundary requires explicit user confirmation before the next phase begins. </Why_This_Exists>

<Steps>

Phase 1: Design (conversation/interaction — user decides)

1. Determine scale from the user's request:

   • Large (new feature, cross-system architecture, significant refactor) → invoke /plan-ceo-review first, then proceed to step 2
   • Medium (scoped feature, single-service change) → skip /plan-ceo-review, proceed directly to step 2

2. Invoke /plan-eng-review (mandatory for all scales) to produce a structured engineering design document

3. Surface all key decisions using AskUserQuestion for each ambiguity:

   • Technology choices with tradeoffs
   • API contract decisions
   • Data model decisions
   • Scope boundary decisions
   • Do not batch decisions silently — each decision that affects implementation requires explicit user input

4. Wait for user to confirm "design complete" before transitioning to Phase 2. Do not proceed to Phase 2 on your own judgment.

5. Skip condition: If the user's original message already confirms design is done ("design is already done, just build it", "design is done, just build it") → skip Phase 1 entirely and proceed to Phase 2 with the provided design context

6. Fallback (gstack not installed): Use the OMC planner agent (opus) to produce a structured plan. Present the plan to the user and wait for their confirmation before proceeding.

---

Phase 2: Execute (autonomous/automated — ralph)

Phase 2 runs as an independent skill invocation, not nested within gstack-sprint's prompt context. Boss invokes Skill(skill: "ralph") for this phase.

1. Invoke the ralph skill — ralph internally selects its execution strategy based on scale:

   • Parallel multi-agent (ultrawork) for large, multi-story work
   • Single executor for simple, well-scoped implementation

2. ralph Step 7a (inside ralph): attempts gstack /review for code review — non-blocking, skips silently if gstack is not installed or /review fails

3. ralph Step 7b (inside ralph): architect/critic verification — always runs regardless of Step 7a result

4. Agent teams for complex work (ralph delegates to executor + code-reviewer + test-engineer in parallel as needed)

5. Fallback (gstack not installed): ralph's existing verification flow runs unchanged — no behavior difference from ralph's perspective

6. Phase 2 completion: ralph signals completion via its standard cancel/completion flow. After ralph completes, gstack-sprint resumes Phase 3.

---

Phase 3: Review (conversation/improvement — user confirms)

1. Find design doc: Search ~/.gstack/projects/ for the most recent design file matching the current repo.

   REPO=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)")
   ORG=$(git remote get-url origin 2>/dev/null | sed 's|.*[:/]\([^/]*\)/.*|\1|' || echo "unknown")
   DESIGN_DOC=$(ls -t ~/.gstack/projects/${ORG}-${REPO}/*-design-*.md 2>/dev/null | head -1)
   

   If no design doc is found, fall back to comparing against the original user request and any notes captured during Phase 1.

2. Read the design doc in full, then read all files implemented during Phase 2

3. Compare implementation against design: For each item in the design doc, determine whether it was implemented, partially implemented, or skipped. Note any implementation that was added beyond the design scope.

4. Present a comparison table to the user:

   | Design Item | Status | Notes | |---|---|---| | Feature A | Implemented | | | Feature B | Partial | Missing edge case X | | Feature C | Not implemented | Descoped during Phase 2 | | Bonus: Feature D | Added (not in design) | Confirm or revert |

5. AskUserQuestion with the following options:

   • "approve" — implementation matches design intent, proceed to next step
   • "needs improvement" — significant gaps exist, re-enter Phase 2 with corrections
   • "partial fix" — minor gaps, specify what to fix before approving

6. If "needs improvement" or "partial fix": Re-enter Phase 2 with a targeted correction delta. Pass the specific gaps to ralph rather than re-running the full implementation. After correction, return to Phase 3 Step 1.

7. If "approve": Suggest next steps — /ship or manual commit. Do not proceed autonomously.

8. Optional follow-up chain (present as options, do not auto-invoke):

   • /land-and-deploy → /canary → /document-release → /retro

9. Fallback (gstack not installed): Read the implemented files directly, compare against the original user request and Phase 1 notes, and present the comparison to the user for their review.

</Steps>

<Escalation_And_Stop_Conditions>

• Stop and report when a fundamental blocker requires user input (missing credentials, unclear requirements, external service down)
• Stop when the user says "stop", "cancel", or "abort"
• Never auto-advance phase boundaries — each phase requires explicit user confirmation
• If Phase 1 design decisions cannot be resolved after three rounds of AskUserQuestion, escalate to the user with a clear statement of what is blocking progress
• If Phase 2 (ralph) fails after the maximum retry attempts, surface the blocker to the user rather than silently retrying or declaring completion
• If Phase 3 comparison reveals that more than 50% of design items are unimplemented, flag this as a significant implementation gap before asking for user decision </Escalation_And_Stop_Conditions>

<Examples> <Good> Phase 1 — surfacing decisions before implementation: ``` AskUserQuestion: "Two decisions are needed during design review: 1. API authentication: JWT token approach or session cookie approach? 2. Data storage: Add Redis cache for real-time queries, or start with direct DB queries? Once you decide, say 'design complete' and I'll begin implementation." ``` Why good: Decisions are explicit, user controls phase transition, implementation cannot start without confirmation. </Good> <Good> Phase 3 — comparison table against design doc: ``` Design doc: ~/.gstack/projects/sehoon787-my-claude/sehunkim-main-design-20260326-142559.md

| Design Item | Status | Notes | |---|---|---| | User auth via JWT | Implemented | | | Refresh token rotation | Implemented | | | Rate limiting (100 req/min) | Partial | Middleware added, limit not configurable | | Audit log for auth events | Not implemented | Descoped during execution | | OpenAPI schema update | Implemented | |

3 items fully implemented, 1 partially implemented, 1 not implemented. How would you like to proceed? (approve / needs improvement / partial fix)

Why good: Reads the actual design doc, presents concrete status per item, asks before proceeding.
</Good>

<Bad>
Skipping Phase 1 and jumping straight to implementation:

"Understood, I'll start implementing right away." [immediately starts writing code without design confirmation]

Why bad: Phase 1 exists to align on design before implementation. Skipping it risks building the wrong thing.
</Bad>

<Bad>
Claiming Phase 3 complete without reading the design doc:

"Implementation is complete. All features are working correctly."

Why bad: Did not read the design doc, did not produce a comparison table, did not ask the user for confirmation. This is completion theater.
</Bad>
</Examples>

<Final_Checklist>
- [ ] Phase 1: Design doc produced and user confirmed "design complete" (or Phase 1 explicitly skipped per user request)
- [ ] Phase 2: ralph invoked and completed with its own verification (7a + 7b)
- [ ] Phase 3: Design doc located (or fallback to original request)
- [ ] Phase 3: Comparison table presented to user
- [ ] Phase 3: User selected "approve", "needs improvement", or "partial fix"
- [ ] If "needs improvement": correction delta passed to ralph, Phase 3 re-run after correction
- [ ] If "approve": next steps suggested (/ship or manual commit), no autonomous action taken
</Final_Checklist>