Add PRD and epic planning stage to Yeti UI before GitHub execution

[bketelsen]

Background

Current workflow: issues land in GitHub, Yeti refines and executes them. The hard thinking — scope, acceptance criteria, task decomposition — is supposed to happen before issues exist, but there's no structured place for it.

CCPM (https://github.com/automazeio/ccpm) demonstrates the pattern clearly: a guided PRD and epic decomposition process produces structured artifacts before anything touches GitHub. By the time a task becomes an issue, the planning is already done and the issue is purely an execution artifact.

Proposal

Add a planning stage to Yeti's UI that covers:

1. PRD creation — agent-assisted or agent-led conversation that clarifies:

   • What problem is being solved?
   • Who are the users?
   • What does success look like?
   • What constraints exist?
   • What's explicitly out of scope?
     Produces a structured PRD document.

2. Epic decomposition — agent breaks PRD into epics with:

   • Architecture decisions
   • Technical approach
   • Task preview with dependency metadata (depends_on, parallel, conflicts_with)

3. GitHub handoff — once planning is approved by the human, Yeti creates the GitHub issues automatically. Issues are execution artifacts, not planning artifacts.

Acceptance Criteria

• Yeti UI has a planning mode distinct from the issue execution view
• Agent-led PRD conversation produces a structured document (stored in Yeti or the target repo)
• Epic decomposition produces tasks with explicit dependency metadata
• Human approval gate before any GitHub issues are created
• Created issues link back to the originating PRD/epic document
• Existing issue-refiner/issue-worker flow is unchanged for issues created outside this flow

References

• CCPM: https://github.com/automazeio/ccpm
• Harness research: Personal/Research/CCPM.md

[frostyardyeti]

— Automated by Yeti —

Implementation Plan

Clarifying Questions (blocking)

This issue proposes adding an interactive AI conversation layer and a planning workflow to a system that currently operates as a batch job runner with a server-rendered HTML dashboard. Several fundamental design decisions need answers before a reliable plan can be written:

1. Conversation UX model — what does "agent-led conversation" mean concretely?

The current Yeti UI is server-rendered HTML with no real-time bidirectional communication (the only streaming path is one-way SSE for toast notifications). An "agent-led PRD conversation" implies multiple interactive rounds of user input and AI response. Options:

• (A) Chat-style UI with streaming AI responses (requires WebSocket or SSE-based streaming, a fundamentally new UI paradigm for Yeti)
• (B) Multi-step form wizard where the user fills in structured fields and the AI critiques/refines them (fits the existing request/response model better)
• (C) Async model — user submits a description, Yeti generates a PRD draft offline (like issue-refiner does), user reviews and provides feedback in another round

These have very different implementation sizes. (A) is a large new subsystem; (B) and (C) fit more naturally into the existing architecture.

2. Where are PRD documents stored?

The issue says "stored in Yeti or the target repo." This is a fundamental architectural fork:

• (A) SQLite — new DB tables, PRDs are dashboard-native artifacts, but not version-controlled and not visible outside Yeti
• (B) Target repo — PRDs committed as files (e.g., docs/prds/PRD-001.md), version-controlled and accessible via GitHub, but requires worktree/commit infrastructure for non-code artifacts
• (C) GitHub issues/discussions — PRD stored as a GitHub issue body or discussion, linking is natural, but formatting/structure is constrained

This choice determines the storage layer, the linking mechanism (acceptance criterion: "created issues link back to the originating PRD"), and whether the feature works when Yeti is restarted mid-planning.

3. How does the AI interact with the target codebase during planning?

The issue mentions "Architecture decisions" and "Technical approach" in epic decomposition. Does the AI need to:

• (A) Read the target repo's actual codebase (like issue-refiner does — clone repo, create worktree, run Claude with file access) to ground architecture decisions in real code
• (B) Work purely from the PRD text without codebase access

(A) makes the output much higher quality but means each planning session needs worktree infrastructure and Claude CLI invocation. (B) is simpler but the output may not match the actual codebase.

4. What is the dependency metadata format on created GitHub issues?

The issue specifies tasks should have depends_on, parallel, conflicts_with metadata. GitHub issues have no native dependency system. Options:

• (A) Structured metadata in issue body (e.g., a YAML/markdown section at the top of each issue listing dependency issue numbers)
• (B) Labels (doesn't scale well for per-issue relationships)
• (C) Task list in the epic/parent issue with ordering and annotations

This affects how issue-worker and issue-refiner interpret these relationships (acceptance criterion: "existing flow unchanged"), and whether Yeti needs to understand dependency ordering during execution.

5. Does the "human approval gate" need a distinct UI state, or is it just a button?

The issue says "once planning is approved by the human, Yeti creates the GitHub issues." Is this:

• (A) An explicit review page where the human sees the full PRD + all planned issues before approving (with the ability to edit individual issues before creation)
• (B) A simple "Create Issues" button on the planning result page

(A) is significantly more UI work but much more useful. (B) is simpler but means the human can only approve/reject the entire batch.

---

Please respond to these questions as a comment on the GitHub issue so the next refinement cycle can incorporate the answers and produce a concrete implementation plan.