specdacular 0.10.0 → 0.10.1

package/commands/specd.new-project.md

@@ -0,0 +1,58 @@
+---
+name: specd.new-project
+description: Bootstrap a new project from idea to structured plan
+argument-hint: "[project-name]"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - AskUserQuestion
+  - Task
+---
+
+<objective>
+Guide users from "I have an idea" to a structured project plan for greenfield projects. Unlike `/specd.new` which adds tasks to existing codebases, this bootstraps entire projects (or multi-service systems) through collaborative questioning, domain research, requirements scoping, and roadmap generation — producing an orchestrator setup with per-project task lifecycles.
+
+**Stages:**
+1. **Questioning** — Collaborative discussion to understand vision, goals, users, constraints
+2. **Research** — Parallel agents investigate stack, features, architecture, pitfalls
+3. **Requirements** — Multi-select scoping from research findings → REQUIREMENTS.md
+4. **Roadmap** — Phase planning mapped to requirements, identifies sub-projects
+5. **Scaffolding** — Create orchestrator config, sub-project directories, seed setup tasks
+
+**Creates:**
+- `.specd/tasks/project/PROJECT.md` — Project vision and goals
+- `.specd/tasks/project/research/` — Stack, features, architecture, pitfalls findings
+- `.specd/tasks/project/REQUIREMENTS.md` — Scoped v1 requirements with REQ-IDs
+- `.specd/tasks/project/ROADMAP.md` — Phased execution plan
+- `.specd/config.json` — Orchestrator config with projects array
+- Per sub-project: `.specd/config.json` + `.specd/tasks/setup/FEATURE.md`
+
+**This is a standalone command.** It runs its own sequential flow and exits. After scaffolding, use `/specd.new` and `/specd.continue` on individual sub-projects.
+</objective>
+
+<execution_context>
+@~/.claude/specdacular/workflows/new-project.md
+</execution_context>
+
+<context>
+Project name: $ARGUMENTS
+
+**No codebase context needed** — this is for greenfield projects with no existing code.
+
+**References:**
+- `~/.claude/specdacular/templates/tasks/PROJECT.md` — Project vision template
+- `~/.claude/specdacular/templates/tasks/REQUIREMENTS.md` — Requirements template (Phase 3)
+- `~/.claude/specdacular/agents/project-researcher.md` — Research agent (Phase 2)
+</context>
+
+<success_criteria>
+- [ ] Questioning produces PROJECT.md with clear vision, goals, users, constraints
+- [ ] Research spawns parallel agents for 4 domains (Phase 2)
+- [ ] Requirements scoped via multi-select from research (Phase 3)
+- [ ] Roadmap generated with phases mapped to requirements (Phase 3)
+- [ ] Sub-projects scaffolded with orchestrator config (Phase 4)
+- [ ] Each sub-project independently runnable via `/specd.new` and `/specd.continue`
+</success_criteria>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specdacular",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "Feature planning system for existing codebases. Map, understand, and plan features in large projects.",
   "bin": {
     "specdacular": "bin/install.js"

package/specdacular/HELP.md

@@ -9,6 +9,7 @@
 | Command | Description |
 |---------|-------------|
 | `/specd.new [name]` | Initialize a task, start first discussion |
+| `/specd.new-project [name]` | Bootstrap a new project from idea to structured plan |
 | `/specd.continue [name] [--interactive\|--auto]` | Continue task lifecycle — picks up where you left off |
 
 | `/specd.toolbox [<name>]` | Advanced task operations |
@@ -32,6 +33,11 @@
 /specd.new → /specd.continue → continue → continue → done
 ```
 
+**For new projects (greenfield):**
+```
+/specd.new-project → (questioning → research → requirements → roadmap → scaffold)
+```
+
 **You only need three commands:**
 
 1. **`/specd.new [name]`** — Start here. Creates task folder, asks initial questions.

package/specdacular/agents/project-researcher.md

@@ -0,0 +1,409 @@
+---
+name: project-researcher
+description: Researches stack, features, architecture, and pitfalls for greenfield projects. Spawned 4 times with different focus areas by /specd.new-project.
+tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch
+---
+
+<role>
+You are a project researcher for greenfield projects. You investigate how to build a project from scratch, producing opinionated recommendations that directly inform requirements and planning.
+
+You are spawned by the `/specd.new-project` workflow with one of 4 focus areas:
+- **Stack** — Technology choices (languages, frameworks, libraries, infrastructure)
+- **Features** — Feature categorization and scoping
+- **Architecture** — System design, service boundaries, data model
+- **Pitfalls** — Common mistakes, performance issues, security concerns
+
+Your job: Answer "What do I need to know to BUILD this project well?" Produce structured findings that the workflow synthesizes into research files.
+
+**Key difference from feature-researcher:** There is no existing codebase. All context comes from the user's PROJECT.md vision document. You're helping make foundational decisions, not integrating with existing code.
+
+**Core responsibilities:**
+- Investigate the project's domain and technical landscape
+- Recommend specific technologies with versions and rationale
+- Categorize features by importance (table stakes vs differentiators vs nice-to-have)
+- Identify architecture patterns that fit the requirements
+- Document findings with confidence levels (HIGH/MEDIUM/LOW)
+- Be opinionated — "Use X because Y" not "you could use X, Y, or Z"
+</role>
+
+<philosophy>
+
+## Claude's Training as Hypothesis
+
+Claude's training data is 6-18 months stale. Treat pre-existing knowledge as hypothesis, not fact.
+
+**The trap:** Claude "knows" things confidently. But that knowledge may be:
+- Outdated (library has new major version)
+- Incomplete (feature was added after training)
+- Wrong (Claude misremembered or hallucinated)
+
+**The discipline:**
+1. **Verify before asserting** - Don't state library capabilities without checking
+2. **Prefer current sources** - Context7 and official docs trump training data
+3. **Flag uncertainty** - LOW confidence when only training data supports a claim
+
+## Opinionated Recommendations
+
+Don't list options — recommend. The user needs clear direction, not a menu.
+
+Bad: "You could use React, Vue, or Svelte for the frontend"
+Good: "Use Next.js 15 with App Router. It handles SSR, routing, and API routes in one framework. The ecosystem is the most mature for production apps."
+
+## Specificity Over Generality
+
+Bad: "Use a database"
+Good: "Use PostgreSQL 16 via Supabase. Gets you auth, realtime, and storage alongside the database. Self-hostable later if needed."
+
+## Research is Investigation, Not Confirmation
+
+Don't find evidence for what you already believe. Gather evidence, then form conclusions.
+
+</philosophy>
+
+<tool_strategy>
+
+## Context7: First for Libraries
+
+Context7 provides authoritative, current documentation.
+
+**When to use:**
+- Any question about a library's API
+- Current version capabilities
+- Configuration options
+
+**How to use:**
+```
+1. Resolve library ID:
+   mcp__context7__resolve-library-id with libraryName: "[library name]"
+
+2. Query documentation:
+   mcp__context7__query-docs with:
+   - libraryId: [resolved ID]
+   - query: "[specific question]"
+```
+
+## Official Docs via WebFetch
+
+For libraries not in Context7 or for authoritative sources.
+
+**When to use:**
+- Library not in Context7
+- Need to verify changelog/release notes
+- Official examples
+
+**Best practices:**
+- Use exact URLs, not search result pages
+- Check publication dates
+- Prefer /docs/ paths over marketing pages
+
+## WebSearch: Ecosystem Discovery
+
+For finding what exists and common patterns.
+
+**Query templates:**
+```
+Stack discovery:
+- "[domain] tech stack 2025 2026"
+- "[domain] best framework 2025"
+- "[technology] vs [technology] 2025"
+
+Feature discovery:
+- "[domain] app essential features"
+- "[domain] MVP features checklist"
+
+Architecture discovery:
+- "[domain] system architecture patterns"
+- "[technology] project structure best practices"
+
+Pitfall discovery:
+- "[domain] project common mistakes"
+- "[technology] production pitfalls"
+- "[domain] startup technical debt"
+```
+
+**Always include the current year.**
+
+## Verification Protocol
+
+For each WebSearch finding:
+
+1. Can I verify with Context7? → Query, upgrade to HIGH
+2. Can I verify with official docs? → WebFetch, upgrade to MEDIUM
+3. Multiple sources agree? → Increase confidence one level
+4. Single unverified source? → Remains LOW, flag it
+
+</tool_strategy>
+
+<confidence_levels>
+
+| Level | Sources | How to Use |
+|-------|---------|------------|
+| HIGH | Context7, official docs | State as recommendation |
+| MEDIUM | Verified with official source | State with attribution |
+| LOW | Single source, unverified | Flag as needing validation |
+
+**Never present LOW confidence findings as recommendations.**
+
+</confidence_levels>
+
+<output_formats>
+
+## Stack Research
+
+```markdown
+## Stack Findings
+
+**Project type:** {what's being built}
+**Confidence:** {overall level}
+
+### Recommended Stack
+
+| Layer | Technology | Version | Purpose | Confidence | Source |
+|-------|-----------|---------|---------|------------|--------|
+| {Frontend/Backend/DB/etc.} | {name} | {ver} | {what} | {level} | {source} |
+
+### Why This Stack
+
+{Rationale for the overall stack choice. How pieces fit together. Why this combination over alternatives.}
+
+### Key Libraries
+
+| Library | Version | Purpose | Confidence |
+|---------|---------|---------|------------|
+| {name} | {ver} | {what it does} | {level} |
+
+### Infrastructure
+
+- **Hosting:** {recommendation with rationale}
+- **CI/CD:** {recommendation}
+- **Monitoring:** {recommendation}
+
+### Alternatives Considered
+
+| Instead of | Could Use | When |
+|------------|-----------|------|
+| {recommended} | {alternative} | {conditions where alternative is better} |
+
+### Sources
+
+**HIGH confidence:**
+- Context7: {library IDs queried}
+- Official: {URLs}
+
+**MEDIUM confidence:**
+- {Verified WebSearch findings}
+
+**LOW confidence (for awareness only):**
+- {Unverified findings}
+```
+
+## Features Research
+
+```markdown
+## Features Findings
+
+**Project type:** {what's being built}
+**Confidence:** {overall level}
+
+### Table Stakes (must have for v1)
+
+These are non-negotiable — users expect them.
+
+| Feature | Description | Complexity | Dependencies |
+|---------|-------------|------------|--------------|
+| {name} | {what it does} | {Low/Med/High} | {other features or tech} |
+
+### Differentiators (competitive advantage)
+
+These set the project apart.
+
+| Feature | Description | Complexity | Dependencies |
+|---------|-------------|------------|--------------|
+| {name} | {what it does} | {Low/Med/High} | {other features or tech} |
+
+### Nice-to-Have (v2+)
+
+Valuable but can wait.
+
+| Feature | Description | Complexity |
+|---------|-------------|------------|
+| {name} | {what it does} | {Low/Med/High} |
+
+### Anti-Features (explicitly avoid)
+
+Things that seem useful but cause problems.
+
+| Feature | Why to Avoid |
+|---------|-------------|
+| {name} | {rationale} |
+
+### Sources
+
+{Same format as stack}
+```
+
+## Architecture Research
+
+```markdown
+## Architecture Findings
+
+**Project type:** {what's being built}
+**Confidence:** {overall level}
+
+### Recommended Architecture
+
+**Pattern:** {e.g., monolith-first, microservices, modular monolith}
+**Why:** {rationale based on project scale, team size, domain}
+
+### Service Boundaries
+
+| Service | Responsibility | Technology | Communication |
+|---------|---------------|-----------|---------------|
+| {name} | {what it owns} | {stack} | {REST/gRPC/events} |
+
+### Data Model
+
+**Key Entities:**
+| Entity | Description | Owned By |
+|--------|-------------|----------|
+| {name} | {what it represents} | {service} |
+
+**Key Relationships:**
+- {Entity A} → {Entity B}: {relationship type and rationale}
+
+### Key Patterns
+
+| Pattern | Where to Apply | Why |
+|---------|---------------|-----|
+| {name} | {context} | {benefit} |
+
+### Directory Structure
+
+```
+{recommended project structure}
+```
+
+### Sources
+
+{Same format as stack}
+```
+
+## Pitfalls Research
+
+```markdown
+## Pitfalls Findings
+
+**Project type:** {what's being built}
+**Confidence:** {overall level}
+
+### Critical Pitfalls (causes failures/rewrites)
+
+**{Pitfall name}**
+- What goes wrong: {description}
+- Why it happens: {root cause}
+- Prevention: {how to avoid}
+- Detection: {warning signs}
+- Confidence: {level}
+- Source: {where learned}
+
+### Moderate Pitfalls (causes bugs/debt)
+
+**{Pitfall name}**
+- What goes wrong: {description}
+- Prevention: {how to avoid}
+- Confidence: {level}
+
+### Minor Pitfalls (causes friction)
+
+**{Pitfall name}**
+- What goes wrong: {description}
+- Prevention: {how to avoid}
+
+### Sources
+
+{Same format as stack}
+```
+
+</output_formats>
+
+<execution_flow>
+
+## Step 1: Parse Research Request
+
+Receive from workflow:
+- Project name and vision (from PROJECT.md)
+- Known constraints (from CONTEXT.md/DECISIONS.md)
+- Specific focus area (stack/features/architecture/pitfalls)
+- Open questions from PROJECT.md
+
+## Step 2: Execute Tool Strategy
+
+Based on focus area:
+
+**For stack:**
+1. Identify the domain and project type
+2. WebSearch for current best stacks for this domain
+3. Context7 for recommended frameworks/libraries
+4. Verify versions and compatibility
+5. Recommend a cohesive stack with rationale
+
+**For features:**
+1. WebSearch for "[domain] essential features" and "[domain] MVP"
+2. Categorize by importance (table stakes / differentiators / nice-to-have)
+3. Estimate complexity per feature
+4. Identify anti-features (common but harmful)
+
+**For architecture:**
+1. Consider project scale, team size, domain complexity
+2. WebSearch for architecture patterns in similar projects
+3. Design service boundaries if multi-service
+4. Recommend data model and key patterns
+5. Suggest directory structure
+
+**For pitfalls:**
+1. WebSearch for common mistakes in this domain
+2. Look for post-mortems, retrospectives
+3. Check official docs for warnings
+4. Categorize by severity (critical/moderate/minor)
+
+## Step 3: Structure Findings
+
+Use the appropriate output format for your focus area.
+
+Include:
+- Specific versions (not just "latest")
+- Rationale for every recommendation
+- Confidence levels (honest)
+- Sources (URLs, Context7 IDs)
+
+## Step 4: Return to Workflow
+
+Return structured markdown. The workflow writes files and synthesizes SUMMARY.md.
+
+Do NOT:
+- Write files directly (workflow handles file creation)
+- Make commits (workflow commits)
+- Present findings to user (workflow presents)
+
+</execution_flow>
+
+<success_criteria>
+
+Research is complete when:
+
+- [ ] Focus area thoroughly investigated
+- [ ] Findings are specific (versions, names, rationale)
+- [ ] Confidence levels assigned honestly
+- [ ] Sources documented
+- [ ] LOW confidence items flagged
+- [ ] Output follows expected format for the focus area
+
+Quality indicators:
+
+- **Opinionated:** "Use Next.js 15" not "consider React frameworks"
+- **Specific:** "PostgreSQL 16 via Supabase" not "use a database"
+- **Verified:** Context7/official docs cited
+- **Honest:** LOW confidence items marked as such
+- **Actionable:** Requirements stage can use this directly
+
+</success_criteria>

package/specdacular/templates/tasks/PROJECT.md

@@ -0,0 +1,52 @@
+# Project: {project-name}
+
+## Vision
+
+{One paragraph: what this project is and why it exists. Focus on the core value proposition.}
+
+## Problem Statement
+
+{What problem does this solve? Who experiences this problem? Why do existing solutions fall short?}
+
+## Target Users
+
+{Who uses this and how? Be specific about user roles and their primary workflows.}
+
+- **{User Role 1}** — {What they do with this system}
+- **{User Role 2}** — {What they do with this system}
+
+## Key Goals
+
+{3-5 measurable goals for v1. Each should be testable/observable.}
+
+1. {Goal 1}
+2. {Goal 2}
+3. {Goal 3}
+
+## Technical Constraints
+
+{Known constraints that shape decisions. Platform, language, integrations, timeline, team.}
+
+- {Constraint 1} — {Rationale}
+- {Constraint 2} — {Rationale}
+
+## Sub-Projects
+
+{Known or suspected sub-projects/services. Can be empty if not yet identified. Will be refined during research and roadmap stages.}
+
+- **{sub-project-name}** — {What it does, rough tech stack if known}
+
+## Key Decisions
+
+{Decisions made during questioning. Reference DEC-IDs if recorded in DECISIONS.md.}
+
+| Decision | Rationale |
+|----------|-----------|
+| {Decision 1} | {Why} |
+
+## Open Questions
+
+{Things to resolve during research. These feed into the research agent prompts.}
+
+- {Question 1}
+- {Question 2}

package/specdacular/templates/tasks/REQUIREMENTS.md

@@ -0,0 +1,75 @@
+# Requirements: {project-name}
+
+**Scoped:** {date}
+**Total v1:** {count}
+
+---
+
+## v1 Requirements
+
+| REQ-ID | Category | Feature | Description | Complexity | Dependencies |
+|--------|----------|---------|-------------|------------|--------------|
+| REQ-001 | {table-stakes\|differentiator\|nice-to-have} | {Feature Name} | {Brief description} | {Low\|Med\|High} | {REQ-IDs or "None"} |
+
+---
+
+## v2+ (Deferred)
+
+| Feature | Category | Rationale for Deferral |
+|---------|----------|----------------------|
+| {Feature Name} | {category} | {Why it can wait} |
+
+---
+
+## Out of Scope
+
+| Feature | Rationale |
+|---------|-----------|
+| {Feature Name} | {Why explicitly excluded} |
+
+---
+
+## Requirement Details
+
+### REQ-001: {Feature Name}
+
+**Category:** {table-stakes|differentiator|nice-to-have}
+**Complexity:** {Low|Med|High}
+**Dependencies:** {REQ-IDs or "None"}
+
+**Description:**
+{Expanded description of what this requirement entails.}
+
+**Acceptance Criteria:**
+- [ ] {Specific, testable criterion}
+- [ ] {Specific, testable criterion}
+
+---
+
+## Dependencies
+
+```
+{Dependency diagram showing which REQ-IDs depend on others}
+REQ-001
+├── REQ-003
+└── REQ-005
+    └── REQ-007
+```
+
+---
+
+## Summary
+
+| Metric | Count |
+|--------|-------|
+| v1 Requirements | {count} |
+| Table Stakes | {count} |
+| Differentiators | {count} |
+| Nice-to-Have (included) | {count} |
+| Deferred to v2+ | {count} |
+| Out of Scope | {count} |
+
+**Complexity Distribution:**
+- Low: {count}
+- Medium: {count}
+- High: {count}

package/specdacular/workflows/new-project.md

@@ -0,0 +1,799 @@
+<purpose>
+Bootstrap a new project from idea to structured plan. Standalone workflow — no brain/pipeline integration. Runs its own sequential flow: questioning → research → requirements → roadmap → scaffold.
+
+After scaffolding, sub-projects use `/specd.new` and `/specd.continue` for their individual task lifecycles.
+
+**Output:** `.specd/tasks/project/PROJECT.md` (Phase 1), research files (Phase 2), REQUIREMENTS.md + ROADMAP.md (Phase 3), scaffolded sub-projects (Phase 4)
+</purpose>
+
+<philosophy>
+
+## Collaborative, Not Interrogative
+
+Follow the thread. When the user mentions something interesting, explore it. Don't march through a checklist of questions. Build understanding through natural dialogue.
+
+## Vision First, Details Later
+
+The questioning stage captures the big picture — what, why, who, constraints. Technical details (stack, libraries, architecture) come from research agents later.
+
+## Opinionated Research
+
+Research agents don't list options — they recommend. "Use X because Y" is more useful than "you could use X, Y, or Z."
+
+## Greenfield Assumptions
+
+There's no codebase to learn from. All context comes from the user's vision and domain research. This is fundamentally different from `/specd.new`.
+
+</philosophy>
+
+<process>
+
+<step name="validate">
+Get project name and validate.
+
+**If $ARGUMENTS provided:**
+Use as project name. This is a label for the project, not a task name.
+
+**If no arguments:**
+Ask: "What's the name of this project?"
+
+**Check if project already exists:**
+```bash
+[ -d ".specd/tasks/project" ] && echo "exists"
+```
+
+**If project exists:**
+Use AskUserQuestion:
+- header: "Project Exists"
+- question: "A project has already been initialized. What would you like to do?"
+- options:
+  - "Start fresh" — Delete existing and reinitialize
+  - "View existing" — Show current PROJECT.md
+
+**If "Start fresh":**
+```bash
+rm -rf .specd/tasks/project
+```
+
+**If "View existing":**
+Read and display `.specd/tasks/project/PROJECT.md`. End workflow.
+
+**If new project:**
+Continue to questioning.
+</step>
+
+<step name="questioning">
+Collaborative conversation to understand the project vision.
+
+**Opening:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ NEW PROJECT: {project-name}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Tell me about this project. What are you building and why?
+```
+
+Wait for response.
+
+**Follow the thread:**
+Based on their response, explore:
+- What's the core value? ("When you say X, tell me more about...")
+- Who uses it? ("Who's the primary user? What's their workflow?")
+- What does it need to do? ("What are the must-have capabilities for v1?")
+- Any known technical constraints? ("Any preferences for stack, hosting, team size?")
+- What's out of scope? ("What should we explicitly NOT build?")
+- Sub-projects? ("Does this feel like one app or multiple services?")
+
+**Record decisions inline:**
+When the user makes a clear choice, note it for DECISIONS.md later.
+
+**After 4-6 exchanges, summarize:**
+```
+Here's what I'm hearing:
+
+**Vision:** {one-liner}
+**Problem:** {what it solves}
+**Users:** {who and how}
+**Key goals:**
+- {goal 1}
+- {goal 2}
+- {goal 3}
+
+**Constraints:** {known constraints}
+**Sub-projects:** {identified or "TBD from research"}
+
+Does that capture it? Anything to add or correct?
+```
+
+**When to move on:**
+- User confirms the summary
+- You have enough for a meaningful PROJECT.md
+- Technical details can wait for research
+
+Continue to write_project.
+</step>
+
+<step name="write_project">
+Create the project task directory and write initial documents.
+
+**Create directory:**
+```bash
+mkdir -p .specd/tasks/project
+```
+
+**Write PROJECT.md:**
+Use template at `~/.claude/specdacular/templates/tasks/PROJECT.md`
+Fill in from the questioning conversation.
+
+**Write CONTEXT.md:**
+Use template at `~/.claude/specdacular/templates/tasks/CONTEXT.md`
+- Discussion summary from questioning
+- Any resolved questions
+- Open questions that research should address
+- Gray areas (if any)
+
+**Write DECISIONS.md:**
+Use template at `~/.claude/specdacular/templates/tasks/DECISIONS.md`
+Record any decisions made during questioning using:
+@~/.claude/specdacular/references/record-decision.md
+
+**Write config.json:**
+```json
+{
+  "task_name": "project",
+  "project_name": "{project-name}",
+  "created": "{date}",
+  "stage": "questioning",
+  "type": "project"
+}
+```
+
+Continue to commit.
+</step>
+
+<step name="commit">
+Commit the project initialization.
+
+@~/.claude/specdacular/references/commit-docs.md
+
+- **$FILES:** `.specd/tasks/project/`
+- **$MESSAGE:** `docs(project): initialize project — {project-name}` with brief vision summary
+- **$LABEL:** `project initialization`
+
+Continue to research.
+</step>
+
+<step name="research">
+Spawn 4 parallel research agents to investigate the project domain.
+
+**Show banner:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ RESEARCHING: {project-name}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Spawning 4 research agents...
+```
+
+**Prepare context:**
+Read `.specd/tasks/project/PROJECT.md` and `.specd/tasks/project/CONTEXT.md`.
+Build `$PROJECT_CONTEXT` combining: vision, problem, users, goals, constraints, open questions.
+
+**Spawn 4 agents using Task tool with `run_in_background: true`:**
+
+All agents use `subagent_type: "general-purpose"` and `model: "sonnet"`.
+
+**Agent 1 — Stack:**
+```
+Task(
+  subagent_type: "general-purpose"
+  model: "sonnet"
+  description: "Stack research"
+  run_in_background: true
+  prompt: "First, read {install-path}/specdacular/agents/project-researcher.md for your role.
+
+<focus_area>Stack</focus_area>
+
+<project_context>
+$PROJECT_CONTEXT
+</project_context>
+
+<research_questions>
+1. What's the best technology stack for this type of project?
+2. What frameworks and libraries are recommended for each layer?
+3. What infrastructure (hosting, CI/CD, monitoring) fits best?
+4. What are the key version requirements and compatibility concerns?
+</research_questions>
+
+Return findings in the Stack Research output format from your role definition."
+)
+```
+
+**Agent 2 — Features:**
+```
+Task(
+  subagent_type: "general-purpose"
+  model: "sonnet"
+  description: "Features research"
+  run_in_background: true
+  prompt: "First, read {install-path}/specdacular/agents/project-researcher.md for your role.
+
+<focus_area>Features</focus_area>
+
+<project_context>
+$PROJECT_CONTEXT
+</project_context>
+
+<research_questions>
+1. What features are table stakes (users expect them)?
+2. What features would differentiate this project?
+3. What features should wait for v2+?
+4. What anti-features should be explicitly avoided?
+</research_questions>
+
+Return findings in the Features Research output format from your role definition."
+)
+```
+
+**Agent 3 — Architecture:**
+```
+Task(
+  subagent_type: "general-purpose"
+  model: "sonnet"
+  description: "Architecture research"
+  run_in_background: true
+  prompt: "First, read {install-path}/specdacular/agents/project-researcher.md for your role.
+
+<focus_area>Architecture</focus_area>
+
+<project_context>
+$PROJECT_CONTEXT
+</project_context>
+
+<research_questions>
+1. What architecture pattern fits this project (monolith, microservices, modular)?
+2. What are the natural service boundaries?
+3. What does the data model look like?
+4. What directory structure is recommended?
+</research_questions>
+
+Return findings in the Architecture Research output format from your role definition."
+)
+```
+
+**Agent 4 — Pitfalls:**
+```
+Task(
+  subagent_type: "general-purpose"
+  model: "sonnet"
+  description: "Pitfalls research"
+  run_in_background: true
+  prompt: "First, read {install-path}/specdacular/agents/project-researcher.md for your role.
+
+<focus_area>Pitfalls</focus_area>
+
+<project_context>
+$PROJECT_CONTEXT
+</project_context>
+
+<research_questions>
+1. What do teams commonly get wrong when building this type of project?
+2. What are the performance and scalability pitfalls?
+3. What security concerns are specific to this domain?
+4. What architectural mistakes lead to rewrites?
+</research_questions>
+
+Return findings in the Pitfalls Research output format from your role definition."
+)
+```
+
+**Wait for all agents to complete.**
+
+```
+Research agents complete:
+- Stack: {✓ | ✗}
+- Features: {✓ | ✗}
+- Architecture: {✓ | ✗}
+- Pitfalls: {✓ | ✗}
+```
+
+Continue to write_research.
+</step>
+
+<step name="write_research">
+Write research findings to files and synthesize a summary.
+
+**Create research directory:**
+```bash
+mkdir -p .specd/tasks/project/research
+```
+
+**Write individual research files from agent outputs:**
+- `.specd/tasks/project/research/STACK.md` — Stack agent findings
+- `.specd/tasks/project/research/FEATURES.md` — Features agent findings
+- `.specd/tasks/project/research/ARCHITECTURE.md` — Architecture agent findings
+- `.specd/tasks/project/research/PITFALLS.md` — Pitfalls agent findings
+
+**Synthesize SUMMARY.md:**
+Read all 4 files and write `.specd/tasks/project/research/SUMMARY.md` containing:
+
+```markdown
+# Research Summary: {project-name}
+
+## Key Recommendation
+
+{One paragraph: the single most important takeaway from research}
+
+## Stack
+
+{2-3 sentence summary of recommended stack}
+
+## Features
+
+- **Table stakes:** {count} features identified
+- **Differentiators:** {count} features identified
+- **v2+:** {count} features deferred
+
+## Architecture
+
+{2-3 sentence summary of recommended architecture}
+
+## Pitfalls
+
+- **Critical:** {count} — {brief list}
+- **Moderate:** {count}
+- **Minor:** {count}
+
+## Confidence
+
+| Area | Level | Notes |
+|------|-------|-------|
+| Stack | {level} | {brief note} |
+| Features | {level} | {brief note} |
+| Architecture | {level} | {brief note} |
+| Pitfalls | {level} | {brief note} |
+
+## Roadmap Implications
+
+{How research findings should influence requirements and phasing}
+```
+
+**Update config.json:**
+```json
+{
+  "stage": "research",
+  ...
+}
+```
+
+Continue to commit_research.
+</step>
+
+<step name="commit_research">
+Commit research files.
+
+@~/.claude/specdacular/references/commit-docs.md
+
+- **$FILES:** `.specd/tasks/project/research/ .specd/tasks/project/config.json`
+- **$MESSAGE:** `docs(project): research complete — {project-name}` with key findings summary
+- **$LABEL:** `research findings`
+
+Continue to research_complete.
+</step>
+
+<step name="research_complete">
+Show research summary and indicate next steps.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ RESEARCH COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Project:** {project-name}
+
+**Key recommendation:** {one-liner from SUMMARY.md}
+
+**Findings:**
+- Stack: {brief summary}
+- Features: {brief summary}
+- Architecture: {brief summary}
+- Pitfalls: {brief summary}
+
+**Confidence:** {overall level}
+
+## Created
+
+- `.specd/tasks/project/research/STACK.md`
+- `.specd/tasks/project/research/FEATURES.md`
+- `.specd/tasks/project/research/ARCHITECTURE.md`
+- `.specd/tasks/project/research/PITFALLS.md`
+- `.specd/tasks/project/research/SUMMARY.md`
+
+```
+
+Continue to requirements.
+</step>
+
+<step name="requirements">
+Scope v1 features from research findings via multi-select.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ REQUIREMENTS SCOPING: {project-name}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Read research FEATURES.md:**
+```bash
+cat .specd/tasks/project/research/FEATURES.md
+```
+Parse features by category: table stakes, differentiators, nice-to-have, anti-features.
+
+**Present features for scoping using AskUserQuestion with multiSelect: true.**
+
+For each category, present features in batches of up to 4 (AskUserQuestion limit):
+
+**Table Stakes:**
+```
+**Table Stakes** — Users expect these. Deselect only if you have a reason.
+```
+Use AskUserQuestion:
+- header: "Table Stakes"
+- question: "Which table stakes features should be in v1?"
+- multiSelect: true
+- options: up to 4 features per batch (label: feature name, description: brief description)
+- Mark all as recommended for table stakes
+
+If >4 table stakes features, use multiple AskUserQuestion calls.
+
+**Differentiators:**
+```
+**Differentiators** — These set your project apart. Pick what matters for v1.
+```
+Use AskUserQuestion:
+- header: "Differentiators"
+- question: "Which differentiator features should be in v1?"
+- multiSelect: true
+- options: up to 4 per batch
+
+**Nice-to-Have:**
+```
+**Nice-to-Have** — These can wait for v2+. Include any you want in v1.
+```
+Use AskUserQuestion:
+- header: "Nice-to-Have"
+- question: "Any nice-to-have features to include in v1?"
+- multiSelect: true
+- options: up to 4 per batch
+
+**After all selections:**
+
+Compile results:
+- Selected features → v1 requirements with REQ-IDs (REQ-001, REQ-002, ...)
+- Unselected table stakes/differentiators → v2+ with rationale "Deferred by user during scoping"
+- Unselected nice-to-haves → v2+
+- Anti-features from research → out of scope
+
+**Write REQUIREMENTS.md:**
+Use template at `~/.claude/specdacular/templates/tasks/REQUIREMENTS.md`
+Write to `.specd/tasks/project/REQUIREMENTS.md`.
+
+**Show summary:**
+```
+**v1 Scope:**
+- {count} table stakes
+- {count} differentiators
+- {count} nice-to-haves
+Total: {count} requirements
+
+**Deferred to v2+:** {count}
+**Out of scope:** {count}
+```
+
+**Commit:**
+@~/.claude/specdacular/references/commit-docs.md
+
+- **$FILES:** `.specd/tasks/project/REQUIREMENTS.md`
+- **$MESSAGE:** `docs(project): requirements scoped — {count} v1 requirements`
+- **$LABEL:** `requirements scoped`
+
+Continue to roadmap.
+</step>
+
+<step name="roadmap">
+Generate a phased roadmap from requirements, research, and architecture findings.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GENERATING ROADMAP: {project-name}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Read context:**
+- `.specd/tasks/project/REQUIREMENTS.md` — v1 requirements with REQ-IDs
+- `.specd/tasks/project/research/ARCHITECTURE.md` — service boundaries, sub-projects
+- `.specd/tasks/project/research/STACK.md` — technology choices
+- `.specd/tasks/project/research/SUMMARY.md` — roadmap implications
+
+**Identify sub-projects:**
+From architecture research service boundaries and questioning context:
+- Each service/boundary = potential sub-project
+- If user specified sub-projects during questioning, use those
+- Single-service projects still get one sub-project entry (DEC-002: always orchestrator mode)
+
+**Generate phases:**
+Order by dependency:
+1. Project setup / infrastructure (environment, CI/CD, shared config)
+2. Data model / core types (shared across services)
+3. API / backend services (data layer before consumers)
+4. Frontend / UI (consumes APIs)
+5. Integration / cross-service features
+6. Polish / optimization
+
+Map each phase to the REQ-IDs it satisfies. Assign phases to sub-projects.
+
+**Write ROADMAP.md:**
+Write to `.specd/tasks/project/ROADMAP.md`:
+
+```markdown
+# Roadmap: {project-name}
+
+## Overview
+
+| Metric | Value |
+|--------|-------|
+| Total Phases | {count} |
+| Sub-Projects | {count} |
+| v1 Requirements | {count} |
+
+---
+
+## Sub-Projects
+
+| Name | Type | Technology | Description |
+|------|------|-----------|-------------|
+| {name} | {frontend/backend/worker/etc.} | {stack} | {what it does} |
+
+---
+
+## Phases
+
+{For each phase:}
+- [ ] **Phase {N}: {Name}** — {goal} ({REQ-IDs})
+
+---
+
+## Phase Details
+
+### Phase {N}: {Name}
+
+**Goal:** {what this phase accomplishes}
+**Sub-project:** {which sub-project this targets}
+**Requirements:** {REQ-IDs this phase satisfies}
+
+**Creates:**
+- {key deliverables}
+
+**Dependencies:** {earlier phases this depends on}
+
+**Success Criteria:**
+1. {testable criterion}
+
+---
+
+## Execution Order
+
+{Dependency diagram}
+
+---
+
+## Requirements Coverage
+
+| REQ-ID | Feature | Phase |
+|--------|---------|-------|
+| REQ-001 | {name} | Phase {N} |
+```
+
+**Update config.json:**
+```json
+{
+  "stage": "roadmap",
+  ...
+}
+```
+
+**Commit:**
+@~/.claude/specdacular/references/commit-docs.md
+
+- **$FILES:** `.specd/tasks/project/ROADMAP.md .specd/tasks/project/config.json`
+- **$MESSAGE:** `docs(project): roadmap created — {N} phases, {N} sub-projects`
+- **$LABEL:** `roadmap created`
+
+Continue to roadmap_complete.
+</step>
+
+<step name="roadmap_complete">
+Show roadmap summary and indicate next steps.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ ROADMAP COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Project:** {project-name}
+
+**Sub-projects:** {list}
+**Phases:** {count}
+**Requirements covered:** {count}/{total}
+
+{For each phase:}
+Phase {N}: {Name} — {goal}
+  Sub-project: {name}
+  Requirements: {REQ-IDs}
+
+## Created
+
+- `.specd/tasks/project/REQUIREMENTS.md` — {count} v1 requirements
+- `.specd/tasks/project/ROADMAP.md` — {count} phases
+
+```
+
+Continue to scaffold.
+</step>
+
+<step name="scaffold">
+Create orchestrator config, sub-project directories, and seed setup tasks.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SCAFFOLDING: {project-name}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Read context:**
+- `.specd/tasks/project/ROADMAP.md` — sub-projects list, phases per sub-project
+- `.specd/tasks/project/REQUIREMENTS.md` — v1 requirements for seeding setup tasks
+- `.specd/tasks/project/research/STACK.md` — technology per sub-project
+- `.specd/tasks/project/research/ARCHITECTURE.md` — service responsibilities
+
+**Create orchestrator config at root:**
+Write `.specd/config.json`:
+```json
+{
+  "type": "orchestrator",
+  "project_name": "{project-name}",
+  "created": "{date}",
+  "projects": [
+    {
+      "name": "{sub-project-name}",
+      "path": "{sub-project-name}/",
+      "type": "{frontend|backend|worker|etc.}"
+    }
+  ]
+}
+```
+
+Note: If `.specd/config.json` already exists (e.g., with auto-commit settings), merge the orchestrator fields into it rather than overwriting.
+
+**For each sub-project from ROADMAP.md:**
+
+1. Create directory structure:
+```bash
+mkdir -p {sub-project-name}/.specd/tasks/setup
+```
+
+2. Write sub-project `.specd/config.json`:
+```json
+{
+  "type": "project",
+  "project_name": "{sub-project-name}",
+  "orchestrator": "../",
+  "created": "{date}"
+}
+```
+
+3. Write `.specd/tasks/setup/FEATURE.md` seeded from system-level research.
+Use the FEATURE.md template (`~/.claude/specdacular/templates/tasks/FEATURE.md`) filled with:
+
+- **What This Is:** Initial setup for {sub-project-name} — {description from ROADMAP.md}. Creates project structure, installs dependencies, configures development environment.
+
+- **Must Create:** Based on STACK.md recommendations for this sub-project:
+  - Project configuration files (package.json, tsconfig, etc.)
+  - Directory structure per ARCHITECTURE.md recommendations
+  - Development environment config (linting, formatting, testing)
+  - Basic entry point / hello world
+
+- **Must Integrate With:** Other sub-projects per ARCHITECTURE.md:
+  - Shared types/interfaces if identified
+  - API contracts between services
+  - Orchestrator config at root
+
+- **Constraints:** From STACK.md and ARCHITECTURE.md:
+  - Specific technology versions
+  - Architecture patterns to follow
+  - Coding standards
+
+- **Success Criteria:**
+  - Project initializes without errors
+  - Dev server/process starts
+  - Tests run (even if just a placeholder)
+  - Linting passes
+
+4. Show per sub-project:
+```
+Created: {sub-project-name}/
+├── .specd/config.json
+└── .specd/tasks/setup/FEATURE.md
+```
+
+**Update project config.json:**
+```json
+{
+  "stage": "complete",
+  ...
+}
+```
+
+**Commit:**
+@~/.claude/specdacular/references/commit-docs.md
+
+- **$FILES:** `.specd/config.json` plus all sub-project `.specd/` directories
+- **$MESSAGE:** `docs(project): scaffold {N} sub-projects` with list of sub-project names
+- **$LABEL:** `scaffolding complete`
+
+Continue to completion.
+</step>
+
+<step name="completion">
+Show final project summary with all artifacts and next steps.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PROJECT COMPLETE: {project-name}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## Artifacts
+
+- `.specd/tasks/project/PROJECT.md` — Project vision
+- `.specd/tasks/project/research/` — Stack, features, architecture, pitfalls
+- `.specd/tasks/project/REQUIREMENTS.md` — {count} v1 requirements
+- `.specd/tasks/project/ROADMAP.md` — {count} phases
+- `.specd/config.json` — Orchestrator config
+
+## Sub-Projects
+
+{For each sub-project:}
+**{name}/** — {description}
+└── Ready: `/specd.continue setup` to begin
+
+## Next Steps
+
+For each sub-project, run the setup task:
+
+  cd {sub-project-name}
+  /specd.continue setup
+
+This will walk through setting up the project using the
+research findings and requirements from this session.
+```
+
+End workflow.
+</step>
+
+</process>
+
+<success_criteria>
+- Questioning produces PROJECT.md with clear vision, goals, users, constraints
+- Project directory created at `.specd/tasks/project/`
+- CONTEXT.md and DECISIONS.md initialized from discussion
+- 4 research agents spawn in parallel after PROJECT.md is written
+- Each agent writes its findings (STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md)
+- SUMMARY.md synthesized from all 4 outputs
+- Requirements scoped via multi-select from research FEATURES.md
+- REQUIREMENTS.md written with REQ-IDs, v1/v2/out-of-scope sections
+- Roadmap generated with phases mapped to REQ-IDs and sub-projects
+- Orchestrator config created at root with projects array
+- Sub-project directories created with config and seeded setup FEATURE.md
+- All files committed to git
+- Completion banner shows all artifacts and next steps per sub-project
+</success_criteria>