Video summary

Up & Running with GitHub Spec Kit #3 - The /specify Command

Main summary

Key takeaways

Technology

Technological concepts / product workflow covered

GitHub Spec Kit setup flow

  • The video explains using the /specify command to generate a new high-level spec for a feature or application segment.
  • This comes after a prior step where you update a “constitution” file, which contains governing principles for future specs.

Recommendation on spec granularity

  • The speaker advises that it’s usually better to spec contained features, rather than trying to “one-shot” an entire app with a single spec.
  • If a feature is too small, Spec Kit may feel overkill.
  • Aim for a “happy medium”:
    • features are substantial enough to be meaningful
    • but still manageable

How /specify works (command behavior)

When you run:

  • /specify <feature description>

Spec Kit:

  1. Creates a new feature branch (without changing the main branch).
  2. Creates a folder structure for the spec:
    • a branch-named folder under specs/
    • inside it, a spec file named for the feature
  3. Loads a spec template from the templates/ directory to determine the spec structure.
  4. Writes the new spec into the generated spec file.
  5. Prints terminal output (such as branch name, spec file location, and feature number) that a coding agent can use.

Branch naming detail

  • The branch name is based on a feature number plus the first three words of the feature description.
  • The speaker recommends choosing the first three words intentionally, since they’ll appear in the branch name.

Example spec created in the walkthrough

Feature being specified

  • “Initial page setup” for a goal-tracking web app called “Do it”

High-level UI/UX requirements described

  • Two-column layout
    • Left: current goals + days left
    • Right: completed goals
  • Current goals
    • Each goal has a checkbox to move it to completed
    • Goals can also be deleted permanently
  • Adding goals
    • A button opens a modal with title and end date fields
  • Goal highlighting
    • Goals with an end date within 3 days are highlighted
  • Visual style
    • Modern light theme with fun pastel colors

Structure of the generated spec file (what gets included)

Metadata section

  • Includes:
    • branch name
    • creation date
    • status (draft)
    • the initial user input

Execution flow instructions

  • Tells the coding agent to:
    • extract key concepts from the input
    • add “needs clarification” markers where requirements are unclear

User story

  • A non-technical summary of what the user wants and why, such as:
    • tracking goals and deadlines
    • staying motivated and organized
    • seeing active goals at a glance

Acceptance scenarios

  • Example scenario:
    • viewing the main page shows two distinct columns (active vs completed)

Edge cases

  • Reserved for unanswered questions
  • May later be addressed with a clarify command

Functional requirements (FR)

  • Numbered requirements, such as:
    • system must display two columns
    • current goals must show title, remaining days calculation, checkbox, etc.

Key entities / data model concepts

  • Includes entities like:
    • Goal (title, end date, completion status)
    • User session

Quality / completeness checklists

  • Emphasizes that the spec is:
    • high-level (avoid implementation/architecture details)
    • focused on what/why, not how
    • suitable for non-technical stakeholders
    • written so requirements are testable
  • Includes checks like:
    • “mandatory sections completed”
    • “no needs clarification markers” (in this example)

Review / tutorial emphasis

This is primarily a tutorial walkthrough of:

  • how to write an appropriate high-level prompt for /specify
  • what files/branches it creates
  • how to read key sections of the resulting spec
  • how it sets up a later step using clarify to fill in underspecified areas

Main speakers / sources

  • Speaker: The unnamed presenter (“my friends…”) guiding through GitHub Spec Kit commands.
  • Primary source content: The GitHub Spec Kit /specify prompt/template and its supporting scripts (e.g., the “create new feature” script referenced in the walkthrough).

Original video