PDD: GitHub Issue-Driven Spec Workflow

[jamesrxian]

Rough Idea

Create a workflow that creates an issue on GitHub, drive the issue with a freefsm PDD workflow. The user can develop an idea with the agent and go through PDD, then the issue becomes a spec.

Status

🟡 Requirements gathering in progress

Plan

• Implement create-issue state — use gh issue create, store issue number in context
• Add comment posting to each state — on state entry, post phase content as issue comment
• Add body update on transitions — update issue body status section at each phase change
• Implement finalize state — update issue body with complete spec summary, close or label the issue
• Write tests — validate FSM transitions and comment formatting

[jamesrxian]

📋 requirements.md

Q1: At what point should the GitHub issue be created?

A1: Very start. The issue is created at the beginning of the workflow so the PDD conversation is tracked in the issue from the start.

Q2: Should the issue body be updated as the PDD progresses, or should artifacts only live in local specs/ directory?

A2: Not sure yet — prototyping to discover.

[jamesrxian]

📐 design.md

Architecture

The workflow creates a GitHub issue at the start, then uses it as a living mirror of the PDD process.

flowchart LR
    A[User idea] --> B[Create Issue]
    B --> C[Requirements Q&A]
    C --> D[Research]
    D --> E[Design]
    E --> F[Plan]
    F --> G[Issue = Final Spec]

Loading

Components

• Issue body: Status tracker + final spec summary (updated at each phase transition)
• Issue comments: Incremental PDD artifacts (requirements Q&A, research findings)
• Local specs/: Canonical source of truth

Data Model

• run context tracks: issue_number, repo, slug
• Each FSM state posts a comment and updates the issue body status

[jamesrxian]

📝 plan.md

Implementation Steps

1. Create FSM workflow YAML — define states: create-issue, requirements, research, design, plan, finalize
2. Implement create-issue state — use gh issue create, store issue number in context
3. Add comment posting to each state — on state entry, post phase content as issue comment
4. Add body update on transitions — update issue body status section at each phase change
5. Implement finalize state — update issue body with complete spec summary, close or label the issue
6. Write tests — validate FSM transitions and comment formatting

[jamesrxian]

🔬 research/github-issue-as-spec-carrier.md

Summary

Prototyped using GitHub Issues to track PDD workflow progress. Created issue #1 and posted requirements as a comment. This research explores how GitHub Issues can serve as the living document for a PDD workflow.

Key Findings

1. Issue creation works well via gh issue create — title, body, and labels can be set at creation time
2. Comments can carry structured content — posting requirements.md content as a comment works. Each PDD phase could be a separate comment
3. No native file attachment for .md files — content must be inline in the issue body or comments
4. Three viable approaches emerged:
   • A: Body only — update body at each phase. Clean but loses edit history
   • B: Comments only — each phase = new comment. Full history but scattered
   • C: Hybrid — body = status + plan checklist; comments = incremental artifacts. Best of both

Trade-offs

Approach	Readability	History	Simplicity
A: Body only	✅ High	❌ Lost on edit	✅ Simple
B: Comments only	❌ Scattered	✅ Full	✅ Simple
C: Hybrid	✅ High	✅ Full	⚠️ Moderate

Recommendations

Use Approach C (hybrid): issue body = status + plan checklist (updated at each phase), comments = incremental PDD artifacts. Local specs/ remains canonical; the issue mirrors it.

References

• Prototype issue: PDD: GitHub Issue-Driven Spec Workflow #1
• gh issue create/comment/edit CLI docs