🎯 Quick Start: Your First Issue in 10 Minutes

Welcome! This guide gets you from zero to “first issue created” in under 10 minutes.

Prerequisites: Do You Have These?

Before starting, verify you have:

Don’t have Node.js? Download from nodejs.org (takes 2 minutes)

Check what you have:

node --version      # Should show v18+
npm --version       # Should show v9+
gh auth status      # Should show you're logged in

Step 1: Accept Invitations (1 minute)

Organization Invite

  1. Check your email for: “You’ve been invited to join [ORG-NAME] on GitHub”
  2. Click View invitation or go to https://github.com/
  3. Find and click Accept invitation

Repository Invite

  1. Check email for: “You’ve been invited to [your-repo] repository”
  2. Click Accept

✓ Check: Visit https://github.com/orgs/TanureLabOrg — you should see your repo listed.

Step 2: Install Spec-Kit Tools (3 minutes)

What is spec-kit? A command-line tool that automatically creates GitHub Issues with proper structure.

Quick Install (Easiest)

Navigate to your repository and run:

cd ~/your-repo-path
./scripts/setup-speckit.ps1

This will install:

Manual Install (If script fails)

# Install spec-kit CLI globally
npm install -g spec-kit-cli

# Install extension
specify extension add gh-issues --from https://github.com/TanureLabOrg/spec-kit-gh-issues/releases/latest

# Install preset
specify preset add hackathon-workshop --from https://github.com/TanureLabOrg/spec-kit-hackathon-preset/releases/latest

# Verify
specify --version        # Should print version
specify preset list      # Should show 'hackathon-workshop'

âś“ Check: Run specify --version and you should see output.

Step 3: Create Your First Epic (4 minutes)

An Epic is your main specification or architecture document.

Run the Command

cd ~/your-repo-name
speckit spec

Answer the Prompts

The command will ask you questions:

? What is the name of your specification?
» My Frontend Component Architecture

? Brief description?
» React-based component library with TypeScript support

? Acceptance criteria? (separate with semicolon)
» Passes tests; Type-safe; Documented; <2s load time

? Related Epic? (leave blank if this IS the epic)
» 

? Who is the owner?
» your-github-username

What Happens

Spec-kit will:

  1. Create an Epic issue with your info
  2. Create an Architecture guidance issue
  3. Add proper labels: type:epic, phase:specification
  4. Print the issue numbers to your terminal

Verify in GitHub

  1. Go to your repo on GitHub
  2. Click Issues
  3. You should see your new Epic issue
  4. Click it and verify:
    • âś… Correct title and description
    • âś… Has labels: type:epic, phase:specification
    • âś… Status: status:triage

âś“ Checkpoint: Your Epic appears in GitHub Issues.

Step 4: (Optional) Create a Feature Plan

Once your Epic is created, plan features:

speckit plan

Prompts:

? Epic to link? (e.g., Epic#42)
» Epic#[YOUR-NUMBER]

? Feature name?
» User Authentication Service

? Description?
» JWT-based auth with Google OAuth provider

? Repository?
» backend

This creates a Feature issue linked to your Epic.

What You’ve Accomplished! 🎉

âś… Installed spec-kit and hackathon preset
âś… Created your first Epic issue
âś… Linked Architecture guidance
âś… Learned the workflow

Next: See Platform Usage Guide for deeper workflows.

Troubleshooting

“Command not found: speckit”

Cause: spec-kit CLI not installed or Node.js not in PATH

Fix:

node --version           # Verify Node.js installed
npm list -g spec-kit-cli  # Check if spec-kit installed

# If not installed:
npm install -g spec-kit-cli

“Extension not found”

Cause: GitHub Issues extension not installed

Fix:

specify extension add gh-issues --from https://github.com/TanureLabOrg/spec-kit-gh-issues/releases/latest

“Preset not found when running speckit spec”

Cause: Hackathon preset not installed

Fix:

specify preset add hackathon-workshop --from https://github.com/TanureLabOrg/spec-kit-hackathon-preset/releases/latest

# Verify:
specify preset list

“GitHub authentication failed”

Cause: GitHub CLI not authenticated

Fix:

gh auth status          # Check status
gh auth login           # Re-authenticate
gh auth refresh         # Refresh token if expired

“Can’t access the repo”

Cause: Haven’t accepted the invitation OR permissions issue

Fix:

  1. Check email for invitation
  2. Accept it at https://github.com/TanureLabOrg
  3. Run: gh repo list TanureLabOrg to verify access

Next Steps

  1. Read Platform Usage Guide — full workflow details
  2. Learn Architecture Guidelines — how we do spec-first development
  3. Ask Questions if you’re stuck — open an issue in central repo
  4. Start Building — create your features and tasks!

⏱️ Time to first issue: 10 minutes
⏱️ Time to full setup: 1 hour

Ready? Let’s go! →