Spec Kit Workflow Commands
Operational guide for using /specify, /plan, and /tasks with GitHub Copilot in NexisChat.
This guide explains how to drive the Spec-Driven Development flow inside this repository using GitHub Copilot chat commands and the supporting prompt + template assets.
Command Summary
| Command | Purpose | Primary Output | Stored In |
|---|---|---|---|
/specify | Generate or refine a product/feature specification (problem, users, scope, outcomes, constraints) | Spec Markdown | specs/ (convention – create if absent) |
/plan | Produce a technical implementation plan (architecture, data, integration surfaces, sequencing, risks) | Plan Markdown | plans/ |
/tasks | Break spec+plan into atomic, verifiable tasks with acceptance criteria | Task List | tasks/ |
(Directories may not yet exist; create them per feature or domain.)
Prerequisites
- Added Spec Kit assets (see Integration doc)
- Constitution reviewed & adapted in
memory/constitution.md - Clear feature intent (avoid starting with vague "improve UX" asks)
Phase 1: /specify
Provide a concise but rich intent prompt:
/specify Implement team-based workspace sharing: users can create shared workspaces, invite members with roles (viewer, editor, admin), and audit membership changes.Copilot uses .github/prompts/specify.prompt.md + templates/spec-template.md to shape output. Review for:
- User types & journeys captured?
- Out-of-scope clearly stated?
- Edge cases (failure, abuse, scale) surfaced?
- Success metrics or validation signals present?
If gaps exist, reply with clarifications and re-run or ask: "Revise the specification to incorporate: ...". Store the approved version under specs/<feature-slug>.md.
Phase 2: /plan
When the spec is stable:
/plan Use existing Postgres via Drizzle ORM, re-use auth module, enforce role checks at API & UI, prefer optimistic updates, include background job for membership audit log compaction.The plan prompt (.github/prompts/plan.prompt.md) encourages structure across:
- Architecture & module boundaries
- Data model & migrations
- API surface (endpoints, payload contracts)
- UI components / state considerations
- Cross-cutting concerns (observability, security, performance)
- Risks, trade-offs, open questions
Iterate until constraints match reality (e.g., monorepo tooling, existing packages). Save to plans/<feature-slug>.md.
Phase 3: /tasks
Generate granular tasks only after plan approval:
/tasks Break down the team workspace sharing feature spec + plan into tasks. Include: migration, models, service layer, API handlers, UI screens, role enforcement tests, audit log retention job, documentation updates.The task prompt (.github/prompts/tasks.prompt.md) + templates/tasks-template.md shape output to include:
- Small scope (≤ ~200 LOC diff target when possible)
- Acceptance criteria & validation ideas
- Dependencies / ordering hints
- Testing guidance
Refine until tasks are:
- Independently reviewable
- Cover all plan sections (no orphaned architectural pieces)
- Mapped to success criteria
Store as tasks/<feature-slug>.md or split across directories if very large.
Implementation Loop
For each task:
- Open task file; copy objective into Copilot chat.
- Provide local context (paths, existing modules) if not already open.
- Ask for an implementation plan or direct changes.
- Generate patch; review diff for alignment to spec/plan.
- Add/adjust tests (unit/integration/e2e) before merging.
- Mark task complete in the task list (checkboxes if included).
If a task exposes a spec gap → update upstream spec/plan, regenerate downstream artifacts if needed.
Supporting Scripts
| Script | Function |
|---|---|
packages/scripts/src/spec-kit/create-new-feature.sh | Scaffolds feature directories & initial spec/plan/task placeholders (if adapted) |
packages/scripts/src/spec-kit/get-feature-paths.sh | Utility to resolve canonical paths for artifacts |
packages/scripts/src/spec-kit/setup-plan.sh | Orchestrates plan environment/context (e.g., collecting existing files for agent) |
packages/scripts/src/spec-kit/update-agent-context.sh | Refreshes derived context (e.g., summarizations) before generation |
packages/scripts/src/spec-kit/check-task-prerequisites.sh | Ensures environment + dependencies ready before implementing a task |
packages/scripts/src/spec-kit/common.sh | Shared helper functions (logging, path resolution, validation) |
(See Integration & Customization docs for enhancement ideas.)
Quality Gates per Phase
| Phase | Exit Checklist |
|---|---|
| Specify | Clear problem, personas, scope boundaries, success indicators |
| Plan | Architecture cohesive, data/API defined, risks logged, feasibility validated |
| Tasks | No large ambiguous tasks, coverage of spec/plan, explicit validation per task |
| Implement | Tests added/updated, diff scoped, no drift from upstream artifacts |
Tips
- Re-request alternative plan versions ("Provide a lean alternative focusing on minimal dependencies") before settling.
- Use diff-based review discipline: reject code that implements unapproved scope.
- Update constitution when recurring principles emerge (security posture, performance SLOs, design system rules).
- Keep tasks small; split if multiple concerns appear in one.
Anti-Patterns to Avoid
| Smell | Consequence | Fix |
|---|---|---|
| Skipping spec | Hidden assumptions propagate | Write minimal spec first |
| Giant plan | Hard to validate; slows iteration | Ask for concise + variant plans |
| Tasks too coarse | Review fatigue; regressions | Enforce atomic scope |
| Silent spec drift | Misaligned implementation | Amend spec + regenerate plan/tasks |
| Copy-paste prompts | Context loss | Tailor each phase with current constraints |
When to Regenerate
- New compliance or security constraints
- Architectural pivot (e.g., queue introduction)
- Significant performance or scale insights
- Feature scope expansion / contraction
Document rationale for regeneration at the top of the updated artifact (changelog section) to preserve historical intent.
Proceed to the Integration document for details on how the toolkit was embedded here.