Summary

When zerg init detects an empty project directory, it runs Inception Mode — a shallow requirements wizard that collects basic metadata (name, description, platform, architecture style) via Rich prompts, then immediately scaffolds files and selects a tech stack.

Meanwhile, /zerg:brainstorm exists specifically for deep requirements discovery: competitive research, multi-round Socratic questioning, trade-off exploration, design validation, YAGNI gates, and GitHub issue generation.

These two workflows are disconnected. An empty-project init should offer brainstorm-first as the primary path, since the tech stack decision should emerge from deliberate requirements discovery — not a quick prompt wizard.

Additionally, security rule fetching depends on stack detection (detect_project_stack() in zerg/security/rules.py:206), which scans for existing files. On an empty project, only generic OWASP rules get fetched — language/framework/infrastructure rules are missed entirely until the user manually re-runs zerg security-rules integrate after code exists.

Current Flow (Problem)

zerg init (empty directory)
  → is_empty_project() returns True                    # init.py:138
  → run_inception_mode()                               # inception.py:353
    → gather_requirements()                            # charter.py — Rich prompts
       Collects: name, description, purpose, platform, architecture, 
                 performance, security level, scalability, testing strategy
    → select_technology(charter)                       # tech_selector.py — recommendation engine
       Outputs: language, framework, package manager, test framework
    → scaffold_project(charter, stack)                 # inception.py:26 — template rendering
    → write_project_md(charter)
    → _init_git_repo()
  → detect_project_stack()                             # NOW files exist, stack detected
  → integrate_security_rules()                         # Fetches rules for scaffolded stack
  → "Next steps: zerg plan <feature>"

Problems

1. Shallow discovery — gather_requirements() uses Rich prompts (Prompt.ask()) for quick Q&A. No competitive research, no Socratic exploration, no trade-off analysis, no YAGNI filtering. The user gets asked "What problem does this solve?" but never "Who are your competitors? What are common pain points? What are the architectural trade-offs?"

2. Premature tech stack commitment — select_technology() runs immediately after basic prompts. The user chooses Python/FastAPI before deeply exploring whether their requirements actually need an API, a CLI, a library, or something else entirely.

3. Security rules miss the window — When init runs on an empty dir, detect_project_stack() finds nothing. Security rules are fetched after scaffolding, but only if scaffolding produces detectable files. If the user's actual stack diverges from the scaffold (common — scaffold is a starting point), the security rules will be wrong until manually re-run.

4. Brainstorm is orphaned — /zerg:brainstorm has deep discovery capabilities (research, Socratic dialogue, trade-offs, design validation, YAGNI gates, issue generation) that are never surfaced to greenfield users. The "Next steps" after init says "zerg plan <feature>" — brainstorm isn't mentioned.

Proposed Flow

zerg init (empty directory)
  → is_empty_project() returns True
  → AskUserQuestion: "Empty project. How would you like to start?"
    → Option A: "Deep discovery (Recommended)" 
        → Launch /zerg:brainstorm with project domain
        → Brainstorm output includes:
          - Requirements (validated-design.md)
          - Tech stack decision (from trade-off exploration)
          - Feature backlog (GitHub issues)
          - YAGNI-filtered scope
        → Return to init with brainstorm context
        → scaffold_project() using brainstorm's tech stack decision
        → fetch security rules for the DECIDED stack (not detected)
        → "Next steps: zerg plan <top-feature> --issue <N>"

    → Option B: "Quick setup"
        → Current Inception Mode (unchanged)
        → gather_requirements() + select_technology() + scaffold
        → fetch security rules after scaffold

    → Option C: "I already know my stack"
        → zerg init --stack python,fastapi,docker
        → Skip discovery, scaffold directly
        → fetch security rules for DECLARED stack

Key Design Decisions

1. Brainstorm Output Feeds Init

Brainstorm already saves structured outputs:

• .gsd/specs/{session-id}/validated-design.md — validated requirements
• .gsd/specs/{session-id}/tradeoffs.md — architectural decisions (including tech stack)
• .gsd/specs/{session-id}/research.md — competitive analysis
• .gsd/specs/{session-id}/brainstorm.md — session summary

Init should read these files to extract the tech stack decision instead of running its own select_technology() wizard.

2. Security Rules Use Declared Stack

Instead of relying solely on detect_project_stack() (file scanning), integrate_security_rules() should accept an explicit ProjectStack parameter:

# Current: always scans files
def integrate_security_rules(project_path, ...):
    stack = detect_project_stack(project_path)  # Finds nothing on empty project

# Proposed: accept pre-determined stack
def integrate_security_rules(project_path, stack=None, ...):
    if stack is None:
        stack = detect_project_stack(project_path)
    # Use provided stack OR detected stack

This allows init to pass the stack from brainstorm's trade-off decisions or from --stack flag, ensuring correct security rules from day one.

3. --stack Flag for Experienced Users

Users who know their stack shouldn't need brainstorm or inception:

zerg init --stack python,fastapi,docker,postgresql

This would:

1. Parse the stack declaration into a ProjectStack object
2. Skip gather_requirements() and select_technology()
3. Scaffold using the declared stack
4. Fetch security rules for the declared stack immediately

Files to Modify

Comparison: Inception Mode vs Brainstorm

Acceptance Criteria

• zerg init on empty directory presents 3 options: deep discovery, quick setup, explicit stack
• "Deep discovery" launches /zerg:brainstorm flow, then returns to init with context
• Brainstorm's trade-off output includes explicit tech stack decision
• Init reads brainstorm output to hydrate ProjectCharter and TechStack
• integrate_security_rules() accepts optional stack parameter
• --stack flag enables direct stack declaration without discovery
• Security rules fetched match the decided/declared stack (not just detected files)
• Quick setup path remains unchanged (backward compatible)
• Init's "Next steps" output adapts based on which path was taken
• Documentation updated: init command reference, brainstorm handoff

Edge Cases

Related Issues

• feat: worktree isolation for task mode workers #226 — Worktree isolation for task mode (post-init execution concern)
• epic: Claude Code Agent Teams integration — transform ZERG into a higher-level orchestration framework #177 — Agent Teams epic (brainstorm may eventually run as a teammate)