Project Plan

# Colloquium Project — Initiate

Bootstrap a brand-new standalone project inside the Colloquium monorepo.

Invoke as:
`/colloquium:project-initiate` → starts Q&A for a new project

**Version:** v1 — Bootstrap-only skill (split from colloquium:project v3)

> **For continuing an existing project,** use `/colloquium:project-implement` instead.

---

## ENFORCEMENT RULES (read before executing any step)

1. **Always ask first.** Always begin with a scan for existing projects to prevent accidentally re-bootstrapping an active project.
2. **State after every step.** Write `project-state.json` after EVERY step — not after phases, not in batches.
3. **Banners are mandatory.** Every phase and step displays its start and completion banner.
4. **Hard gates block.** Steps marked HARD GATE loop until the gate condition is met — do NOT proceed without it.
5. **`feature_list.json` is append-only.** Once written, only the `"passes"` field may ever change. Descriptions, steps, and ordering are permanently frozen.
6. **AI never touches git beyond reading status.** No branch creation, no push, no PR — the human controls all git operations. The ONE exception: the initial scaffold commit in Phase B3 (explicitly described below).

---

## Entrypoint: Safety Check

Before starting Q&A, run:

```bash
ls .claude/projects/ 2>/dev/null

Collect all subdirectories that contain a project-state.json into known_projects.

If known_projects is non-empty, display a warning:

════════════════════════════════════════════════════════════════
⚠️  EXISTING PROJECTS DETECTED
════════════════════════════════════════════════════════════════
Found existing projects:
  [list them with their passing test counts]

Are you sure you want to bootstrap a NEW project?
To continue an existing project, run /colloquium:project-implement
════════════════════════════════════════════════════════════════

Wait for explicit confirmation before proceeding. On confirm → Phase B1.

---

Phase B1: Q&A — 5 Topic Blocks

Present questions block by block (not one at a time). Use AskUserQuestion tool with multiple related questions per block where possible. After each block, confirm understanding before moving to the next.

---

Block 1 — Identity

Ask:

1. What is the app's name? (This becomes the slug for folder names — use kebab-case, e.g. claude-ai-clone)
2. Describe the app in one sentence. What does it do?
3. Who are the primary users?

Record: slug, name, overview, users.

---

Block 2 — Tech Stack

Ask:

1. Frontend framework? (React/Vite, Next.js, other — or none)
2. Styling approach? (Tailwind CSS, CSS Modules, other)
3. State management? (React context, Zustand, Redux, none)
4. Backend runtime? (Node.js/Express, Hono, none — pure frontend)
5. Database? (SQLite, PostgreSQL, none)
6. Authentication? (none/single default user, JWT, OAuth, other)
7. Real-time requirements? (SSE, WebSockets, polling, none)

Record: techStack object with all fields.

---

Block 3 — Features

Ask:

1. List the 5–10 main feature areas of the app (freeform — user can list them in any format).
2. For the list received: which are MVP (must-have for first version) vs. nice-to-have?
3. Any content-rendering requirements? (Markdown, code syntax highlighting, LaTeX, diagrams)
4. Mobile/responsive requirements? (mobile-first, desktop-only, both)
5. Any third-party API integrations? (list them)

Record: features array with name, priority (mvp/nice-to-have), description for each.

---

Block 4 — Design

Ask:

1. Layout pattern? (sidebar + main chat, dashboard with widgets, full-width content, other)
2. Light mode, dark mode, or both?
3. Any design reference, brand colors, or specific aesthetic to match?

Record: design object with layout, colorMode, reference.

---

Block 5 — Constraints

Ask:

1. Any hard port requirements? (e.g., "frontend must run on port 5173")
2. How are API keys/secrets provided? (environment variables in .env, from a file path like /tmp/api-key, other)
3. Any known performance, scale, or deployment constraints?

Record: constraints object.

---

Blocks 1–5 Review Banner

After all 5 blocks:

════════════════════════════════════════════════════════════════
📋 Q&A Complete — Review
════════════════════════════════════════════════════════════════
App:      [name] ([slug])
Purpose:  [overview]
Stack:    [frontend] + [backend] + [database]
Auth:     [auth]
Features: [count] areas — [count] MVP, [count] nice-to-have
Layout:   [layout], [colorMode]
════════════════════════════════════════════════════════════════

Ask: "Does this look correct? Any corrections before I generate the spec?"

If corrections: update the relevant fields and re-display the banner. Loop until the user explicitly confirms.

---

Phase B2: Spec Generation — HARD GATE

⚠️ HARD GATE: Do NOT proceed to Phase B3 until all three artifacts are confirmed to exist on disk via ls.

Generate all three artifacts atomically from the Q&A answers. For any field not explicitly answered, use sensible defaults that match the stated tech stack and feature set.

---

Artifact 1: app_spec.txt

Write to: .claude/projects/<slug>/app_spec.txt

The file MUST follow this XML structure exactly (all sections required):

<project_specification>
  <project_name>[name from Q&A]</project_name>

  <overview>
    [2–4 sentence description of the app, its purpose, and target users]
  </overview>

  <technology_stack>
    <frontend>
      <framework>[from Q&A]</framework>
      <styling>[from Q&A]</styling>
      <state_management>[from Q&A]</state_management>
      <routing>[inferred from framework choice]</routing>
      <port>Only launch on port [from constraints, or 5173 default]</port>
    </frontend>
    <backend>
      <runtime>[from Q&A, or NONE if frontend-only]</runtime>
      <database>[from Q&A, or NONE]</database>
      <port>[5001 default if backend exists]</port>
    </backend>
    <auth>[