Platform Usage Reference

Deep-dive documentation for understanding and using all components of the platform.

Component 1: hackathon-repo-template

What it is: A reusable GitHub repository template for each solution component (frontend, backend, infra).

Files & Folders

.github/ISSUE_TEMPLATE/

Five issue form templates, each with required fields:

epic.yml — Epic Issue Form

Fields:
  - Problem Statement (textarea) — What problem does this solve?
  - Users/Personas (textarea) — Who are the end users?
  - Business Outcomes (textarea) — What success looks like
  - Non-Functional Requirements (textarea) — Performance, scale, reliability
  - Out of Scope (textarea) — What's explicitly NOT included
  - Risks (textarea) — Technical or business risks
  - References (textarea) — Links to RFCs, designs, business docs

feature.yml — Feature Issue Form

Fields:
  - Feature Objective (textarea) — What does the user do?
  - Parent Epic (text) — Reference to Epic #N
  - User Scenarios (textarea) — Example workflows
  - Acceptance Criteria (textarea) — What must be true
  - Technical Notes (textarea) — Implementation hints
  - Dependencies (textarea) — Blockers or prerequisites
  - Test Strategy (textarea) — How it will be verified

task.yml — Task Issue Form

Fields:
  - Implementation Intent (textarea) — What code change(s)?
  - Parent Feature (text) — Reference to Feature #N
  - Definition of Done (textarea) — Checklist items (becomes checkboxes)
  - Acceptance Criteria (textarea) — Team's verification steps
  - Evidence Links (textarea) — PR links, test reports

architecture.yml — Architecture Decision Record

Fields:
  - Decision Context (textarea) — Why are we deciding this?
  - Options Considered (textarea) — Alternative approaches
  - Chosen Option (textarea) — Decision and rationale
  - Consequences & Tradeoffs (textarea) — What we gain/lose
  - Standards & Guardrails (textarea) — Guidelines for implementation
  - Rollback Strategy (textarea) — How to undo if needed
  - Linked Issues (textarea) — Epic/Feature/Task it affects

bug.yml — Bug Report

Fields:
  - Observed Behavior (textarea) — What happened?
  - Expected Behavior (textarea) — What should happen?
  - Reproduction Steps (textarea) — How to recreate
  - Severity (dropdown) — Critical, High, Medium, Low
  - Impacted Scope (textarea) — Which components/users?
  - Fix AC (textarea) — What verification confirms the fix?

.github/labels.yml

Declarative label definitions. 17 labels pre-defined:

type:epic           — High-level capability
type:feature        — Stakeholder-visible functionality
type:task           — Implementation work unit
type:architecture   — Cross-cutting decision
type:bug            — Unexpected behavior / defect

phase:discovery     — Research, exploration
phase:specification — Design, requirements
phase:planning      — Breaking into tasks, scheduling
phase:implementation — Active development
phase:verification  — Testing, review, release

status:triage       — New, not reviewed
status:ready        — Reviewed, ready to start
status:in-progress  — Active work
status:blocked      — Waiting on dependency
status:review       — Done, awaiting approval
status:done         — Complete, verified, closed

priority:p0         — Critical path
priority:p1         — High priority
priority:p2         — Normal priority
priority:p3         — Low priority

Use setup-labels.ps1 to sync all labels to the repository.

.vscode/mcp.json

MCP Server configuration for VS Code Copilot Chat.

{
  "mcpServers": {
    "github": {
      "command": "gh",
      "args": ["api", "mcp"],
      "env": {}
    },
    "github-copilot-spaces": {
      "command": "gh",
      "args": ["api", "mcp", "copilot_spaces"],
      "env": {}
    }
  }
}

This enables:

config/workflow-mode.yml

Selector for execution mode (default: issues-first).

mode: issues-first    # Options: issues-first, hybrid, markdown-first

behavior:
  create_issues: true
  create_markdown: false
  require_parent_links: true
  require_acceptance_criteria: true
  enforce_label_taxonomy: true

.github/instructions/

Copilot agent instructions that control AI behavior in this repo.

issues-first.instructions.md — Always-on rules

applyTo: "**"
---
Use issues-first workflow. Create GitHub Issues for all work.
Labels: type:epic, type:feature, type:task, type:architecture, type:bug
Phases: phase:discovery → specification → planning → implementation → verification

spec-kit.instructions.md — spec-kit setup and usage

applyTo: "**"
---
Use spec-kit CLI commands (speckit.*) to create issues.
All five commands documented.

mode-switch.instructions.md — Read workflow-mode config before planning

applyTo: "**"
---
Before creating work items, read config/workflow-mode.yml to understand repo behavior mode.

scripts/setup-labels.ps1

PowerShell script to sync all 17 labels to the repository.

.\scripts\setup-labels.ps1 -Repo "TanureLabOrg/frontend"

scripts/setup-speckit.ps1

PowerShell script to install spec-kit CLI and gh-issues extension.

.\scripts\setup-speckit.ps1

Component 2: hackathon-central-template

What it is: Reusable template for the central orchestration repository (one per organization).

Key Files

solution.yml

Single source of truth for solution topology and governance.

solution:
  name: "Hackathon 2026"
  description: "Spec-driven issues-first workshop"
  owner_org: "TanureLabOrg"
  owner_email: "facilitator@example.com"

governance:
  workflow_mode_default: "issues-first"
  required_labels:
    - "type:*"
    - "phase:*"
    - "status:*"
  label_enforcement: "strict"  # strict | advisory | none

copilot_space:
  name: "Hackathon 2026 Workspace"
  id: "cu_1A2B3C4D5E6F..."
  context_file_path: ".context/solution-context.md"

repositories:
  - name: "frontend"
    purpose: "Web UI & client"
    url: "https://github.com/TanureLabOrg/frontend"
    owner_team: "frontend-team"
    labels_prefix: "fe:"  # Optional

  - name: "backend"
    purpose: "API & services"
    url: "https://github.com/TanureLabOrg/backend"
    owner_team: "backend-team"
    labels_prefix: "be:"

  - name: "infra"
    purpose: "DevOps & infrastructure"
    url: "https://github.com/TanureLabOrg/infra"
    owner_team: "infra-team"
    labels_prefix: "infra:"

project:
  name: "Hackathon 2026 Board"
  id: "3"
  url: "https://github.com/orgs/TanureLabOrg/projects/3"
  description: "Cross-repo project dashboard"
  
  custom_fields:
    - name: "Type"
      type: "single_select"
      options: ["Epic", "Feature", "Task", "Architecture", "Bug"]
    
    - name: "Phase"
      type: "single_select"
      options: ["Discovery", "Specification", "Planning", "Implementation", "Verification"]
    
    - name: "Status"
      type: "single_select"
      options: ["Triage", "Ready", "In Progress", "Blocked", "Review", "Done"]
    
    - name: "Repository"
      type: "single_select"
      options: ["Frontend", "Backend", "Infra"]
    
    - name: "Priority"
      type: "single_select"
      options: ["P0", "P1", "P2", "P3"]

wiki-source/

Shared baseline documentation — NOT the final destination.

Features:

Content examples:

.github/instructions/

Agent instructions for central repository.

spec-kit-agents.instructions.md — Comprehensive spec-kit agent guide

applyTo: "**"
---
Covers: Installation, Copilot Spaces integration, issues-over-markdown, 
all 5 commands, GitHub Project mapping, label taxonomy, cross-repo planning.

governance.instructions.md — Governance enforcement

applyTo: "**"
---
Enforces: solution.yml as source of truth, issues-first planning, 
parent-child traceability, label consistency.

wiki-policy.instructions.md — Wiki source policy

applyTo: "wiki-source/**,scripts/**"
---
Clarifies: wiki-source/ is shared baseline, NOT final destination.
Each repo's wiki is final destination.

AGENTS.md

Central agent instructions focused on spec-kit and solution orchestration.

Component 3: spec-kit-gh-issues Extension

What it is: Spec-Kit CLI extension for issues-first planning.

The Five Commands

speckit.spec

Creates: Epic issue + optional Architecture issue
Use when: User describes a new capability or problem
Inputs:

Problem statement
Users/personas
Desired outcomes
Non-functional requirements
Scope boundaries
Risks

Outputs:

Example:

Input: "We need user authentication with OAuth"
Output: Epic #42: "User Authentication: OAuth Integration"

speckit.plan

Creates: Feature issues linked to parent Epic
Use when: Epic is refined and ready for breakdown
Inputs:

Epic issue number (e.g., Epic#42)
Feature list with descriptions

Outputs:

Example:

Input: Epic#42, Features: [OAuth Config, Login UI, Session Management]
Output: Feature #43, #44, #45 (all linked to Epic#42)

speckit.tasks

Creates: Task issues with DoD checklists
Use when: Feature is approved and ready for implementation
Inputs:

Feature issue number (e.g., Feature#43)
Task list with descriptions

Outputs:

Example:

Input: Feature#43 (OAuth Config), Tasks: [Research provider, Choose library, Implement config]
Output: Task #46, #47, #48 (all linked to Feature#43, with DoD checklists)

speckit.sync

Creates: Full spec → plan → tasks flow in one command
Use when: Kickoff with complete spec ready
Inputs:

Spec details (problem, users, outcomes, scope)
Feature list
Task breakdown per feature

Outputs:

Example:

Input: Full specification with features and tasks
Output: Complete issue hierarchy ready to execute
Time: 2-3 minutes vs. 10+ minutes with manual steps

speckit.wiki-sync

Creates: Wiki source payload
Use when: Implementation milestone reached, documentation needed
Inputs:

Repo context (which repos to include)
Issue filter (which issues to document)

Outputs:

Component 4: GitHub Project

What it is: Cross-repository project dashboard with five custom fields.

Field Definitions

Type Field

Phase Field

Status Field

Repository Field

Priority Field

Standard Views

View 1: By Status

Groups issues by Status field.
Columns: Triage | Ready | In Progress | Blocked | Review | Done
Purpose: See sprint progress at a glance
Use by: Facilitator for standup, team for planning

View 2: By Repository

Groups issues by Repository field.
Columns: Frontend | Backend | Infra | Shared
Purpose: See load distribution per team
Use by: Facilitator to balance work, team leads for planning

View 3: Architecture Radar

Filtered view showing only Type=Architecture.
Purpose: Track all cross-cutting decisions
Use by: Architect, tech leads for coordination

Component 5: Copilot Spaces

What it is: Shared context hub for solution metadata.

What Goes in Space Context

Create .context/solution-context.md with:

# Hackathon 2026 Solution Context

## Solution Overview
Name: Hackathon 2026
Goal: Build spec-driven system using GitHub Issues
Duration: 90 minutes (or day-long variant)

## Teams
- Frontend: [Team names, Slack handles]
- Backend: [Team names, Slack handles]
- Infrastructure: [Team names, Slack handles]

## Architecture Principles
- Issues-first planning (no scattered markdown)
- Spec-kit for deterministic issue creation
- Single GitHub Project for cross-team visibility
- Copilot Spaces for shared context

## Key Links
- [GitHub Organization](https://github.com/TanureLabOrg)
- [Central Repository](https://github.com/TanureLabOrg/solution-central)
- [GitHub Project Board](https://github.com/orgs/TanureLabOrg/projects/3)
- [Facilitator Guide](#)
- [Participant Guide](#)

## Enterprise Trial (if applicable)
Account: trial@company.com
Password: [Shared securely]
Valid until: [Date]
Access: All Copilot Chat features

## Getting Help
- Question? Post in #hackathon Slack channel
- Stuck? Tag @facilitator

How Agents Use Space Context

  1. Agent loads Space context automatically when Space ID is known
  2. Agent reads: Solution name, team info, key links, enterprise trial status
  3. Agent infers: Project board location, central repo location, preferred labels
  4. Agent adapts spec-kit commands based on context (e.g., includes team name in issue title)
  5. Fallback: If Space unavailable, agent fetches context from central repo’s solution.yml

Label Taxonomy — Complete Reference

How Labels Flow to Project Fields

Label Type Maps To Example
type:epic prefix Type field Epic
type:feature prefix Type field Feature
type:task prefix Type field Task
type:architecture prefix Type field Architecture
type:bug prefix Type field Bug
phase:discovery prefix Phase field Discovery
phase:specification prefix Phase field Specification
phase:planning prefix Phase field Planning
phase:implementation prefix Phase field Implementation
phase:verification prefix Phase field Verification
status:triage prefix Status field Triage
status:ready prefix Status field Ready
status:in-progress prefix Status field In Progress
status:blocked prefix Status field Blocked
status:review prefix Status field Review
status:done prefix Status field Done
priority:p0 prefix Priority field P0

Typical Workflows

Workflow 1: Fast Kickoff (90 minutes)

  1. Minute 0–10: Facilitator frames problem
  2. Minute 10–20: Teams use speckit.spec to create Epic (1–2 per team)
  3. Minute 20–40: Teams use speckit.plan to create Features (3–5 per Epic)
  4. Minute 40–60: Teams use speckit.tasks to create Tasks (5–10 per Feature)
  5. Minute 60–90: Teams execute tasks, move issues on board, facilitator watches progress
  6. Minute 90°: Retrospective using speckit.wiki-sync to document decisions

Workflow 2: Day-Long Workshop

Workflow 3: Post-Workshop Continuation