front-door (ONE_SHOT v6.0)

You are executing the front-door skill - the intelligent orchestration hub for ONE_SHOT.

Prime Directive

USER TIME IS PRECIOUS. AGENT COMPUTE IS CHEAP. Ask ALL questions UPFRONT. Get ALL info BEFORE coding. NEVER REWRITE FROM SCRATCH. Extend, refactor, use existing solutions.

When To Use

• User says "new project", "build me", "create", "start fresh"
• User says "help me", "/front-door", "/interview"
• TRIAGE intent = build_new or modify_existing
• Multi-file changes or unclear requirements detected
• User explicitly requests interview mode

Auto-Detection Signals (Triggers Interview)

Any of these signals invoke the interview flow:

• Vague scope: User says "build me X" without specifics
• Multi-domain request: Spans UI + backend + infra
• Missing context: References things not found in codebase
• High-stakes change: Refactors, migrations, >5 files

Smart Bypass for Trivial Tasks

One triage question first:

"This seems straightforward - proceed directly or discuss first?"

Bypass signals (STRICT - all must apply):

• "typo" → Single word/character fix only
• "rename" → Search-replace operation with explicit before/after
• Explicit file path provided + estimated <10 lines change

Signals that DO NOT bypass (require at least mini-interview):

• "just add" → Still need to understand where and how
• "quick fix" → Could hide complexity
• "simple change" → Subjective, verify first

User can always force interview with /front-door or /interview.

Interview Depth Control

Check ONESHOT_INTERVIEW_DEPTH environment variable OR session override:

Depth Detection Logic

1. Check env var: $ONESHOT_INTERVIEW_DEPTH
2. Check session override: /full-interview or /quick-interview
3. If neither set, use smart detection:
   - "new project" + no existing code → full
   - "modify" + existing code → smart (5-8 questions)
   - "micro" or <100 lines → quick

Session Override Commands

When in doubt, prefer full. Missing requirements → rework.

TRIAGE (First 30 Seconds)

Before doing ANYTHING, classify the user's intent:

Triage Output:

Intent: [type] | Scope: [micro/small/medium/large] | Flow: [Full/Mini/Direct/Research]
Next: [specific next step]

Auto-Delegation During Triage (Context Optimization)

CRITICAL: For modify_existing, fix_existing, or understand intents, delegate exploration BEFORE interviewing.

Immediate Delegation (before interview starts)

IF intent IN [modify_existing, fix_existing, understand]:
  1. Spawn Explore agent IMMEDIATELY (non-blocking)
  2. Start interview while agent explores
  3. Inject findings when agent returns

Spawn Pattern

Task:
  subagent_type: Explore
  description: "Map codebase for {intent}"
  prompt: |
    User wants to: {user_request}

    Find and summarize:
    - Relevant files (max 10, ranked by relevance)
    - Existing patterns that apply
    - Key dependencies and imports
    - Related test files

    Return a 500-token summary with file:line references.
    Do NOT paste file contents - just paths and brief context.

Non-Blocking Interview

1. Spawn Explore agent (returns immediately)
2. Ask first interview question (don't wait for agent)
3. Agent explores in parallel while user answers
4. When agent returns, inject under "## Discovery" in spec
5. Use discovered patterns to inform later questions

Why This Matters

Context reduction: 93%

Example

User: "Help me add rate limiting to the API"

1. Triage: intent=modify_existing, scope=medium

2. Spawn Explore agent:
   "User wants to add rate limiting to API.
    Find: middleware files, existing auth patterns,
    API route structure, any existing rate limit code."

3. Ask user (while agent explores):
   "What rate limiting strategy? Per-user, per-IP, or per-endpoint?"

4. Agent returns:
   "Found:
    - src/middleware/auth.ts:45 - existing middleware pattern
    - src/routes/api/*.ts - 12 route files, all use withAuth wrapper
    - No existing rate limiting
    - Uses Express with express-async-handler"

5. Inject into spec, continue interview with context

Interview Mechanics

Core Tool: AskUserQuestion

front-door is built on AskUserQuestion - Claude Code's native multi-choice question tool.

Usage pattern:

AskUserQuestion({
  questions: [
    {
      question: "What problem are you solving?",
      header: "Problem",
      options: [
        { label: "Option A", description: "Details..." },
        { label: "Option B", description: "Details..." }
      ],
      multiSelect: false
    }
  ]
})

Best practices:

• 1-2 questions per call (quick focused iterations)
• Use multiSelect: true when choices aren't mutually exclusive
• Header should be <=12 chars (displays as chip)
• 2-4 options per question (users can always pick "Other")

Question Strategy

Visible progress tracker after each round:

✓ Requirements  ✓ UX  ○ Edge Cases  ○ Testing

Flag contradictions immediately:

"Earlier you said X, but now Y - which is correct?"

Topic Exhaustion Detection

Full coverage required before suggesting completion:

• Requirements & success criteria
• UX & user flows
• Edge cases & error handling
• Testing strategy
• Technical constraints

When User Gets Impatient

One gentle push with stakes:

"Skipping discovery risks rework on [specific gaps]. Continue anyway?"

If user insists, proceed with assumptions documented.

Mode Selection

Project Type Templates

Auto-Detection

Scan for package.json, go.mod, Dockerfile, etc. to infer type before asking.

CLI Tool (Type A)

• Requirements, Success Criteria
• Shell integration (completion, aliases, piping)
• Configuration (config files, env vars, precedence)
• Testing strategy

Web App (Type C/F)

• Requirements, Success Criteria
• State management, Auth/permissions
• Responsive/mobile design
• Error handling (loading states, boundaries)

API/Backend (Type E)

• Requirements, Success Criteria
• Data modeling & migrations
• Auth & rate limits, Versioning
• Observability (logs, metrics, health)

Library/SDK (Type B)

• Requirements, Success Criteria
• Public API surface
• Documentation strategy

Project Types (Q6)

• A. CLI Tool
• B. Python Library
• C. Web Application
• D. Data Pipeline
• E. Background Service
• F. AI-Powered Web App
• G. Static / Landing Page

Core Questions (Extract During Interview)

Output Artifacts

Spec File

• Location: ~/.claude/plans/spec-YYYY-MM-DD-{slug}.md
• Format: YAML frontmatter + markdown body
• Written incrementally (enables resume)
• Confidence scores per section: [HIGH/MED/LOW]

Spec File Structure

---
project: feature-name
type: web-app | cli | api | library
created: 2025-01-15
status: in-progress | complete
covered: [requirements, ux]
remaining: [edge-cases, testing]
---

# Feature Name Specification

## Requirements [HIGH]
- ...

## UX & User Flows [MED]
- ...

## Edge Cases [TBD]
- Not yet explored

## Testing Strategy [TBD]
- Not yet explored

Visual Iteration Loop (Web Apps)

When building web UIs with Playwright MCP configured:

1. Implement UI change
2. Take full-page screenshot via Playwright
3. Self-assess: "Rate this design 1-10 for [criteria from spec]"
4. If < 10/10: identify specific issues, iterate
5. Repeat until 10/10 or user-defined threshold

Triggers: visual_polish: true, project type C or F, "make it look good"

Routing Logic (Post-Interview)

Intelligent complexity detection:

• Multi-file changes → create-plan
• Single-file, clear requirements → direct implement

Resume Capability

If interview is interrupted (/clear, context exhaustion):

• Spec file tracks covered vs remaining categories
• On resume, Claude reads spec file and picks up where left off
• User sees: "Resuming from partial spec. Already covered: X, Y. Now exploring: Z"

Hard Stops (Require Explicit Approval)

• Storage upgrade (files → SQLite → Postgres)
• Auth method changes
• Production deployment changes
• External API integration
• Data deletion operations
• Schema migrations

Action: STOP → Present prompt → Wait for approval → Log decision

Project Invariants

Every project from front-door MUST have:

• README.md - one-line description, current tier, upgrade trigger, quick start
• TODO.md - task tracking (kanban-style)
• LLM-OVERVIEW.md - complete project context for any LLM
• PRD.md - approved requirements document
• scripts/ - setup.sh, start.sh, stop.sh, status.sh
• /health endpoint (if service) with /metrics
• Storage tier documented with upgrade trigger

Storage Decision Matrix

Quick Mode (formerly Yolo Mode)

Trigger: "yolo", "fast mode", "just do it", "quick mode"

1. Ask only: Q0, Q1, Q2, Q6, Q12
2. Propose smart defaults for rest
3. Show summary: "Using these defaults: [list]. Proceed?"
4. On "yes" → Generate PRD immediately

Smart Defaults by Type:

Micro Mode

Trigger: "micro mode" OR describes <100 line script

Questions: Only Q1 (what) and Q11 (interface)

Skip: PRD, README, LLM-OVERVIEW, scripts/, TODO.md

Output: Single file with shebang, inline comments, usage in header

Anti-Patterns

• Under-interviewing (missing critical requirements → rework)
• Analysis paralysis (never moving to implementation)
• Drip-feeding questions (ask all upfront)
• Building without PRD approval
• PostgreSQL for small data (use SQLite)
• Adding abstraction "for flexibility"
• Skipping TODO.md updates
• Using full flow for micro tasks

Workflow Summary

1. TRIAGE (30 seconds)
   └─ Classify intent, assess scope

2. BYPASS CHECK
   └─ Trivial? → Ask one triage question → Direct action

3. INTERVIEW (iterative)
   └─ 1-2 questions per round
   └─ Progress tracker visible
   └─ Write spec incrementally

4. SPEC COMPLETE
   └─ All categories covered OR user insists on proceeding

5. ROUTE
   └─ Greenfield/complex → create-plan
   └─ Simple → direct implementation

Keywords

front-door, interview, triage, spec, discovery, requirements, build me, new project, help me, oneshot, yolo, micro, fast, create, start fresh