Facilitator Setup Guide

Complete step-by-step instructions for setting up the hackathon platform before the event.

Time estimate: 30-45 minutes
Prerequisites: GitHub org admin access, Copilot Enterprise trial (or paid access)

---

Pre-Workshop Checklist (1 Week Before)

• Invite facilitator co-leads to planning session
• Reserve Copilot Enterprise trial account(s) if participants need them
• Recruit 2-3 early testers to run through ATTENDEE-ONBOARDING.md
• Decide number of solution repositories (frontend, backend, infra, etc.)
• Collect team assignments (who will be on which team)

---

Step 1: Create GitHub Organization (5 minutes)

1.1 Create Org

1. Go to github.com
2. Click avatar → Settings → Organizations
3. Click New organization
4. Fill in:
   • Organization name: TanureLabOrg (or your name)
   • Email: Your email
   • Organization account: Free tier is fine
5. Click Create organization

1.2 Verify Setup

gh org list           # Verify org appears
gh auth status        # Confirm you're logged in as org admin

---

Step 2: Provision Central Repository (10 minutes)

2.1 Create Central Repo from Template

gh repo create TanureLabOrg/solution-central \
  --template TanureLabOrg/hackathon-central-template \
  --public

2.2 Clone & Update

cd ~/projects
git clone https://github.com/TanureLabOrg/solution-central.git
cd solution-central

2.3 Edit solution.yml

Update the file with your organization details:

solution:
  name: "Hackathon 2026"
  tagline: "Spec-driven, issues-first workshop"
  owner_org: "TanureLabOrg"
  owner_email: "you@example.com"

governance:
  workflow_mode_default: "issues-first"
  required_labels:
    - "type:*"
    - "phase:*"
    - "status:*"

copilot_space:
  name: "Hackathon 2026 Workspace"
  id: "TODO-FILL-AFTER-SPACE-CREATED"
  context_file_path: ".context/solution-context.md"

repositories:
  - name: "frontend"
    purpose: "Web UI"
    owner_team: "frontend-team"
  - name: "backend"
    purpose: "API & Services"
    owner_team: "backend-team"
  - name: "infra"
    purpose: "DevOps & Infrastructure"
    owner_team: "infra-team"

project:
  name: "Hackathon 2026 Board"
  id: "TODO-FILL-AFTER-PROJECT-CREATED"
  description: "Cross-repo project board"

2.4 Commit & Push

git add solution.yml
git commit -m "docs: update solution metadata"
git push origin main

---

Step 3: Create GitHub Project (10 minutes)

3.1 Create Project

1. Go to TanureLabOrg org on GitHub
2. Click Projects tab
3. Click New project
4. Select Table template
5. Fill:
   • Name: Hackathon 2026 Board
   • Description: Cross-repository tracking for all teams
6. Click Create project

3.2 Copy Project ID

1. Project URL should look like: github.com/orgs/TanureLabOrg/projects/3
2. The number 3 is your project ID
3. Update solution.yml → project.id: 3

3.3 Add Custom Fields

Follow detailed steps in GITHUB-PROJECT-SETUP.md.

Quick summary:

1. Type (single-select): Epic, Feature, Task, Architecture, Bug
2. Phase (single-select): Discovery, Specification, Planning, Implementation, Verification
3. Status (single-select): Triage, Ready, In Progress, Blocked, Review, Done
4. Repository (single-select): Frontend, Backend, Infra, Shared
5. Priority (single-select): P0, P1, P2, P3

3.4 Create Views

1. View 1: By Status
   • Group by Status field

   • Shows columns: Triage

     Ready

     In Progress

     Blocked

     Review

     Done

2. View 2: By Repository
   • Group by Repository field
   • Shows columns per team
3. View 3: Architecture Radar
   • Filter: Type = Architecture
   • Shows all cross-cutting decisions

---

Step 4: Create Copilot Space (10 minutes)

4.1 Create Space

1. Go to github.com/orgs/TanureLabOrg → Copilot tab
2. Click Create a new Copilot Space
3. Fill:
   • Space name: Hackathon 2026 Workspace
   • Description: Shared context for all teams
4. Click Create

4.2 Copy Space ID

1. Space URL should look like: github.com/orgs/TanureLabOrg/copilot/space/cu_XXXXX...
2. The ID is the part after /space/
3. Update solution.yml → copilot_space.id: cu_XXXXX...

4.3 Create Solution Context File

See detailed instructions in GITHUB-SPACES-SETUP.md to create .context/solution-context.md in the Space.

Minimal content (for reference, template in hackathon-platform):

# Hackathon 2026 Solution Context

## Overview
This is the shared context for the Hackathon 2026 platform.

## Solution Objectives
- Build a spec-driven planning system using GitHub Issues
- Practice issues-first workflow with spec-kit
- Collaborate across frontend, backend, infra teams

## Teams & Contacts
- **Frontend**: Team Lead (Slack: @frontend-lead)
- **Backend**: Team Lead (Slack: @backend-lead)
- **Infra**: Team Lead (Slack: @infra-lead)

## Key Links
- [Central Repo](https://github.com/TanureLabOrg/solution-central)
- [Project Board](https://github.com/orgs/TanureLabOrg/projects/3)
- [Facilitator Guide](https://github.com/hacathon-platform/blob/main/docs/FACILITATOR-SETUP.md)

## Enterprise Trial Access (if applicable)
Copilot Enterprise trial account:
- Account: trial+hackathon@company.com
- Password: [Share securely via 1Password/LastPass]
- Valid until: [Date]

---

Step 5: Provision Solution Repositories (10 minutes)

5.1 Create Each Repo

For each solution component (frontend, backend, infra):

gh repo create TanureLabOrg/frontend \
  --template TanureLabOrg/hackathon-repo-template \
  --public

gh repo create TanureLabOrg/backend \
  --template TanureLabOrg/hackathon-repo-template \
  --public

gh repo create TanureLabOrg/infra \
  --template TanureLabOrg/hackathon-repo-template \
  --public

5.2 Setup Labels in Each Repo

For each repository you created:

cd ~/projects/frontend
pwd  # Confirm you're in the right repo

# Copy the labels setup script from central repo
cp ~/projects/solution-central/scripts/setup-labels.ps1 ./

# Run it
./scripts/setup-labels.ps1 -Repo TanureLabOrg/frontend

# Verify (should show 17 labels)
gh label list --repo TanureLabOrg/frontend

Repeat for backend and infra.

5.3 Link Repositories to Project

For each repository:

1. Go to repo settings
2. Click General → GitHub Projects
3. Click Link a project
4. Select your Hackathon 2026 Board project
5. Click Link

Repeat for all three repos.

---

Step 6: Create Teams & Invite Members (5 minutes)

6.1 Create Teams

gh api /orgs/TanureLabOrg/teams \
  -f name=frontend-team \
  -f description="Frontend team"

gh api /orgs/TanureLabOrg/teams \
  -f name=backend-team \
  -f description="Backend team"

gh api /orgs/TanureLabOrg/teams \
  -f name=infra-team \
  -f description="Infrastructure team"

6.2 Add Members to Teams

# Add person1, person2, person3 to frontend-team
gh api --method PUT /orgs/TanureLabOrg/teams/1/memberships/person1
gh api --method PUT /orgs/TanureLabOrg/teams/1/memberships/person1

# And for other teams...

Alternatively, do this manually via GitHub UI if simpler.

6.3 Grant Team Access to Repos

For each repo, give the team access:

gh api --method PUT /repos/TanureLabOrg/frontend/teams/frontend-team \
  -f permission=push

---

Step 7: Pre-Workshop Validation (1 Day Before)

7.1 Test Spec Creation

As facilitator, test the full flow:

# Clone your frontend repo
git clone https://github.com/TanureLabOrg/frontend.git

# Open in VS Code with Copilot Chat
code .

# In Copilot Chat, run:
# "speckit.spec"
# Describe: "Users need to log in with OAuth"
# Should create: Epic issue in your repo

7.2 Verify GitHub Project

1. Open project board
2. Check that the Epic issue appears in Triage column
3. Verify Type field = Epic
4. Verify Phase field = Discovery
5. Verify Status field = Triage

7.3 Verify Copilot Space

1. In VS Code, open Copilot Chat
2. Load Space context (should show solution metadata)
3. Verify context includes repo links, team info, project board link

7.4 Dry Run: Full Flow (10 minutes)

1. Create Epic with speckit.spec
2. Create Features with speckit.plan Epic#N
3. Create Tasks with speckit.tasks Feature#N
4. Check GitHub Project board — all issues should be visible and linked

Expected result: 1 Epic + 2-3 Features + 4-6 Tasks visible on board, all properly labeled.

---

Step 8: Prepare Participant Invitations (Day Before)

8.1 Create Invitations

Send participants:

1. Link to org invite
2. GitHub username (if not already on GitHub)
3. Assigned repo (frontend, backend, or infra)
4. Link to ATTENDEE-ONBOARDING.md

Template email:

Subject: Hackathon 2026 — Ready to Get Started

Hi [Name],

Welcome to Hackathon 2026! Here's what to do:

1. Accept the GitHub org invite: [link]
2. Accept the repo invite for [frontend/backend/infra]
3. Follow the participant quick-start: [link to ATTENDEE-ONBOARDING.md]

You'll be creating your first Issue with spec-kit within 10 minutes.

Questions? Reply to this email or check the FAQ: [link]

See you soon!
[Facilitator]

8.2 Verify All Invites Sent

gh api /orgs/TanureLabOrg/invitations --jq '[.[] | {login: .invitee.login, repo: .invitee_team_role}]'

---

Step 9: Workshop Day Checklist (1 Hour Before)

• All facilitators have access to org, central repo, project, space
• All participants have accepted org & repo invites
• GitHub Project board is accessible (share link: github.com/orgs/TanureLabOrg/projects/3)
• Copilot Space is created and context file is published
• All repos are linked to project
• All labels are synced in each repo
• Test Slack/chat channel is ready (if using for standups)
• Share ATTENDEE-ONBOARDING.md one more time in all-hands message

---

Troubleshooting

“I can’t find the Project ID”

• URL structure: github.com/orgs/[org]/projects/[ID]
• The number after /projects/ is your ID

“Spaces tab is missing from org”

• Copilot Enterprise trial or paid plan required
• Check org settings → Billing & plans

“setup-labels.ps1 failed to run”

• Check: gh auth status — must be logged in as org member
• Check: gh auth refresh -s admin:org_hook — refresh token with correct scopes
• Windows PowerShell must allow script execution: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

“Issues created but don’t appear on project board”

• Check repo settings → GitHub Projects → Is the project linked?
• Check: Are issue creation and project link happening in correct org?

“Copilot Space context won’t load in Copilot Chat”

• Verify Space was created successfully
• Verify Space ID is correct in solution.yml
• Try: Close and reopen Copilot Chat in VS Code
• Try: Restart VS Code

---

Quick Reference: Done in 5 Steps

1. Create org: TanureLabOrg
2. Create central repo from template, update solution.yml
3. Create GitHub Project with custom fields
4. Create Copilot Space with context file
5. Create 3 solution repos from template, link all to project, invite teams

Then: Share ATTENDEE-ONBOARDING.md with all participants.