SDD: Github Copilot + OpenSpec

Here’s a clear summary of what you learned and the workflow for using GitHub Copilot and OpenSpec for Spec-Driven Development (SDD) initiation:

┌───────────────────────────────────────────────────────────┐
│              Spec-Driven Development (SDD)                │
│            GitHub Copilot  +  OpenSpec                    │
└───────────────────────────────────────────────────────────┘

[Start SDD]
    │
    ├─► (Copilot) Scaffold project
    │        Vue + Tailwind + FastAPI + SQLite
    │
    ├─► (You) Run FE/BE smoke tests
    │
    ├─► (OpenSpec) openspec init
    │
    ├─► Prepare openspec/project.md (prompt to fill details)
    │
    ├─► Change Proposal: Graph Construction Canvas
    │        • New graph button → empty canvas
    │        • Add/edit/drag nodes
    │        • Connect nodes & name edges
    │        • Save/delete graphs (unique name)
    │        • Tailwind colorful styling
    │
    ├─► (OpenSpec) openspec validate
    │        Check proposal.md, design.md, tasks.md, specs
    │
    ├─► Manual review
    │        Ensure tasks.md checklist format (GraphEditor, Tailwind, canvas helpers, node behaviors)
    │
    ├─► [Gate] Review OK?
    │        ├── No: Refine design/specs → break into smaller proposals → re‑validate
    │        └── Yes: Implement per openspec-apply.prompt.md
    │
    ├─► [Gate] Adjustments needed?
    │        ├── Yes: Use Copilot to change code (do NOT edit OpenSpec files) → validate again
    │        └── No: Finalize – proposal achieved
    │
    └─► Lessons:
             1) Don’t use Copilot on OpenSpec files

Here’s a clear summary of what you learned and the workflow for using GitHub Copilot and OpenSpec for Spec-Driven Development (SDD) initiation:

---

✅ Workflow Recap

1. Start with GitHub Copilot

   • Create an almost empty project.
   • Specify the tech stack:
     Frontend: Vue + Tailwind CSS
     Backend: FastAPI
     Database: SQLite
   • Run both frontend and backend to ensure the skeleton works.

2. Initialize OpenSpec

   • Inside the project folder, run openspec init.
   • This sets up prompts and structure for OpenSpec.

3. Prepare project.md

   • Use the prompt:
     Please read openspec/project.md and help me fill it out with details about my project, tech stack, and conventions

4. Add Change Proposals

   • Example proposal:
     create a change proposal - replacing current main page with a graph construction canvas...
   • Include details like:
     • Add nodes, edit names, drag & drop.
     • Connect nodes with edges, edit edge names.
     • Save/delete graphs with unique names.
     • Use Tailwind CSS for colorful styling.

5. Validate Proposal

   • Run openspec validate.
   • Check proposal.md, design.md, tasks.md, and specs.md.
   • Ensure tasks.md includes structured tasks like:

            ### 1.1 Frontend (Vue)
            - [ ] Replace `App.vue` shell with `GraphEditor` as the main view
            - [ ] Add Tailwind CSS to `frontend` (deps, config, base styles)
            - [ ] Implement canvas rendering and interaction helpers
            - [ ] Implement node add/edit/drag behaviors

6. Implement

   • Follow openspec-apply.prompt.md instructions.
   • Implement the change.

7. Iterate

   • If adjustments are needed (look & feel, UX), use GitHub Copilot to modify code.
   • Avoid using Copilot to edit OpenSpec files (to preserve format).

8. Finalize

   • Achieve the change proposal and confirm everything works.

---

✅ Lessons Learned

1. Do NOT use Copilot to edit OpenSpec files (proposal.md, tasks.md, etc.) — it breaks the required format.
2. Propose changes incrementally with OpenSpec rather than one big jump — easier for review and adjustment.
3. Copilot is great for code changes, but OpenSpec should drive the design and task structure.

---