🔍 Agent 1

Discovery Agent

The Discovery Agent transforms a rough project idea into an implementation-ready specification. It asks one structured question per message, advances through up to 15 discovery phases, and produces a feature-spec.md that the Technical Planner can act on directly.

Discovery Phases

1 Core Concept & Value Proposition

2 Target Users & Personas

3 Platform & Distribution

4 Core Feature Set (MVP)

5 Authentication & Authorization

6 Data Model & Persistence

7 Integrations & APIs

8 Monetization & Pricing

9 Non-Functional Requirements

10 Design & Branding

11 Compliance & Privacy

12 Content & Localization

13 Growth & Analytics

14 Launch & Deployment

15 Risks & Constraints

Fast-Track Mode

If the initial brief is over 500 words and covers most of the discovery phases, the agent activates fast-track mode: it skips phases already answered, focuses only on gaps, and may complete discovery in 3–5 exchanges instead of 15.

ℹ️

Use !braindump for long briefs

Issue !braindump to dump everything you know about the project at once. The Discovery Agent will process the dump, identify covered phases, and only ask follow-up questions for missing information.

Discovery Commands

Command	Behavior
!braindump	Enter context ingestion mode — dump everything you know at once. Discovery identifies covered phases and asks only for missing information.
!spec	Compile `feature-spec.md` and `HANDOFF.json v1`. Triggers the Spec Enhancement Loop automatically before showing the Discovery Complete banner.
!enhance	Trigger a Spec Enhancement round on demand — surfaces premium feature suggestions and updates the spec after selection.
!state	Show internal discovery state (which phases are complete, Spec State contents).
!plan	Human gate: advance from Discovery to Technical Planning. Only available after the Enhancement Loop exits.
!reset	Reset discovery state and restart from the beginning.
!platforms	Show locked platform scope.

Spec Enhancement Loop

After !spec compiles the initial specification and Concept Validation passes, Discovery automatically asks:

✨

Would you like suggestions on how to improve your project specification?

Answer yes to get a curated table of premium feature recommendations. Answer no to proceed to !plan.

How it works

You answer yes.
Discovery internally analyzes the spec to identify high-value capabilities that would make this a top-1% product in its category. This analysis is not shown to you — only the results are.
Recommendations are presented in a numbered table you can select from.
Selected features are fully woven into every relevant section of feature-spec.md — not appended as a list.
The question repeats. Continue adding features in rounds, or decline to proceed to !plan.

Recommendation table format

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✨ Spec Enhancement Suggestions — MyApp
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

 #  Feature                          Category          Value Added                             Complexity   Priority
 ─  ──────────────────────────────   ───────────────   ─────────────────────────────────────   ──────────   ────────
 1  AI-powered onboarding wizard     AI / Intelligence  Learns user goals; personalizes flow    Medium       🔴 High
 2  In-app referral engine           Monetization       Viral growth loop with reward tiers     Low          🔴 High
 3  Real-time collaboration cursors  UX / Onboarding    Multi-user live editing (Figma-style)   High         🟡 Medium
 4  Advanced usage analytics         Analytics          Heatmaps, funnel drop-off, cohort view  Medium       🟡 Medium
 5  Offline-first sync engine        Performance        Full functionality without network       High         🟡 Medium
 6  Accessibility audit dashboard    Accessibility      WCAG compliance score + auto-fixes       Low          🟢 Low

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Enter the numbers of features to add (e.g. 1, 3, 5) — or "all" — or "none" to skip.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

After selection

Each selected feature is integrated into all sections it affects — not appended at the bottom:

Feature type	Spec sections updated
Any feature	Core Features (§3), User Stories (§4), Definition of Done (§20)
Changes user journey	Core User Flow (§5)
Creates new data	Data & State Requirements (§6)
Requires new API	API / Business Logic (§10)
Adds UI surface	UX Requirements (§9)
Affects permissions	Roles & Permissions (§12)
Changes revenue model	Monetization (§14)
Has security implications	Authentication & Security (§11)
Requires observability	Observability & Release Strategy (§17)
Platform-specific	Platform Scope Matrix (§7), Native Capabilities (§8)

!enhance on demand

Type !enhance at any point after the spec has been compiled to trigger another enhancement round. Each round surfaces new recommendations — features already offered are never re-suggested. The loop terminates automatically when all meaningful recommendations have been offered.

Outputs

Artifact	Path	Contents
`feature-spec.md`	`artifacts/discovery/`	Full product specification: overview, users, features, data model, APIs, monetization, NFRs, risks, and open questions
`HANDOFF.json v1`	`artifacts/pipeline/`	Machine-readable summary: spec_hash, platforms[], complexity_tier, tech_stack{}, open_questions[]
`design-contract.md`	`artifacts/discovery/`	Web projects only. Design system contract: brand colors, fonts, component library, spacing rules.

CIA — Competitive Intelligence Analysis

During Phase 1 (Core Concept), Discovery can run an optional Competitive Intelligence Analysis using the APIs listed in available_apis.md. This surfaces named competitors, pricing anchors, and positioning gaps before the spec is written — so the product can be differentiated from the start.

ℹ️

CIA is optional but valuable

Request it with !cia during Phase 1. Results are embedded in feature-spec.md under the Competitive Landscape section.

Complexity Tier Assignment

At the end of discovery, the agent assigns a complexity tier that governs downstream behavior:

Tier	Criteria
Simple	Single platform, no auth, no payments, no external APIs, <10 features
Standard	Auth required, database, 1–2 platforms, standard API integrations, 10–25 features
Complex	Multi-platform, payments, multi-tenant, ML/AI components, >25 features, compliance requirements

Multi-Modal Image Analysis

Whenever an image is attached to any message during a Discovery session, the agent analyzes it immediately before responding to the user's text. No special command is required — Claude supports multimodal input natively.

Image type	Analysis output
UI screenshot	Extract UI components, layout patterns, and implied User Stories. Components are added to the design contract draft.
Competitor screenshot	For each visible feature: classify as MATCH (build equivalent), EXCEED (build better), or SKIP (not needed for MVP).
Architecture / flow diagram	Extract entities, relationships, and data flows. Add to the TDD outline and SCHEMA.md draft.
Text / whiteboard photo	Parse as a structured braindump. Extract requirements, user stories, and constraints as if typed text.

The analysis is emitted as an Image Analysis block at the top of the agent's response, before any reply to the user's text content.

ℹ️

Model-adaptive output

The Discovery agent adjusts its output format based on the active model family. Claude models use full artifact Markdown. Kimi and GPT-family models use a streamlined format. Ollama local models use plain-text output without Unicode callout blocks.