Generate structured spec artifacts (proposal, tech-stack, spec, design) through interactive collaboration, using research.md as structured input.
Phase: 1: Research & Spec Agent type: Main agent (interactive with user) Status: Implemented
Generate 4 planning artifacts from research findings through interactive collaboration with the user. Each artifact is presented for approval before proceeding to the next.
Duration estimate: ~15-30 minutes (depends on iteration rounds with user)
docs/specs/<feature>/research.md (from research phase — 16 sections)docs/specs/<feature>/proposal.mddocs/specs/<feature>/tech-stack.mddocs/specs/<feature>/spec.mddocs/specs/<feature>/design.mdproposal.md (root — generate first)
|
+--- tech-stack.md (requires: proposal)
|
+--- spec.md (requires: proposal)
|
+--- design.md (requires: proposal, tech-stack, spec)
Before generating any artifact, read the full research.md and use this mapping to pull structured data:
| Research Section | Feeds Into | How to Use |
|---|---|---|
| Executive Summary | proposal.md → Why | Extract motivation and build/buy/skip verdict |
| Problem Statement | proposal.md → Why | Use as problem context |
| Target Users + Core Workflows | proposal.md → What Changes; spec.md → User stories | Each workflow becomes 1+ scenario; each persona validates requirements |
| Domain Entities + Business Rules | spec.md → Requirements; design.md → Data Model | Entities → data model; rules → MUST requirements |
| Competitive Landscape + Feature Comparison | proposal.md → Impact | Reference competitors to justify feature decisions |
| Gap Analysis + Differentiation Strategy | proposal.md → Capabilities (New) | Gaps → new capabilities; differentiation → scope priorities |
| Initial MVP Scope | proposal.md → Scope (In/Out) | Must features → In Scope; later features → Out of Scope |
| Technical Approaches | tech-stack.md → Technology Choices | Each approach → tech-stack option with pros/cons |
| Contrarian View + Risks | design.md → Risks/Trade-offs | Import directly; ensure mitigations address contrarian concerns |
| Recommendations | proposal.md → Success Criteria | Recommendations → measurable success criteria |
CRITICAL: Do NOT just "read research.md for context." Extract specific data from specific sections. The mapping above tells you exactly what to pull and where to put it.
Read docs/specs/<feature>/research.md. Parse all 16 sections. Note especially:
If research.md is missing sections or quality is low, note concerns but proceed with available data. Do NOT re-do research.
Before generating any artifact, pause and collaborate with the user to define the spec direction. Research gives us data — this step turns data into a clear vision.
Ask the user 3-5 targeted questions based on what you found in research.md. Focus on decisions that will fundamentally shape the spec:
| Category | Example Questions |
|---|---|
| Scope priority | "Research tìm thấy 8 features cho MVP. Bạn muốn focus vào core workflow nào trước?" |
| User focus | "Research xác định 3 personas. Bạn muốn optimize cho persona nào là chính?" |
| Technical direction | "Research đề xuất 3 approach. Bạn có preference về [monolith vs microservice, self-hosted vs SaaS]?" |
| Differentiation | "Gap analysis cho thấy [X] là cơ hội lớn nhất. Bạn đồng ý đây là điểm khác biệt chính?" |
| Constraints | "Có constraint nào chưa được đề cập trong research? (timeline, budget, team size, existing infra)" |
| Integration | "Feature này cần integrate với hệ thống nào hiện tại?" |
| Risk appetite | "Contrarian view nêu [risk X]. Bạn đánh giá mức độ nghiêm trọng thế nào?" |
Rules:
research.md when askingBased on the user's answers, propose 2-3 possible spec directions. Each direction represents a different strategy for the same feature:
## Direction A: [Name] — [1-line summary]
- **Focus**: [Primary capability/user segment]
- **MVP Scope**: [3-5 key features]
- **Tech approach**: [From research]
- **Timeline estimate**: [Relative: small/medium/large]
- **Trade-off**: [What you gain vs what you sacrifice]
## Direction B: [Name] — [1-line summary]
...
## Direction C (optional): [Name] — [1-line summary]
...
Direction types to consider (pick the most relevant contrasts):
| Contrast | Direction A | Direction B |
|---|---|---|
| Scope | MVP tối giản (3-4 features) | Feature-rich v1 (8-10 features) |
| Audience | B2C consumer-first | B2B enterprise-first |
| Architecture | Monolith (ship fast) | Modular (scale later) |
| Build vs Integrate | Build from scratch | Integrate existing tools |
| Market entry | Compete head-on | Target underserved niche |
Rules:
After the user chooses (or mixes), summarize the agreed direction in 3-5 bullet points:
## Agreed Direction
- **Focus**: [chosen focus]
- **Primary persona**: [chosen persona]
- **MVP features**: [list]
- **Tech approach**: [chosen approach]
- **Key constraint**: [timeline/budget/etc.]
This becomes the guiding frame for all 4 artifacts. Reference this agreed direction in every subsequent step.
Using the template from references/spec-templates/proposal-template.md:
Draft the proposal using the Research → Spec mapping above, filtered through the agreed direction:
Present the draft section by section to the user (e.g., Why → What Changes → Capabilities → Scope → Success Criteria → Impact). Ask for feedback after each section before moving on.
Iterate on each section based on feedback until the user approves
Write the approved version to docs/specs/<feature>/proposal.md
Quality check before presenting:
Using the template from references/tech-stack-template.md:
docs/specs/<feature>/tech-stack.mdQuality check before presenting:
Using the template from references/spec-templates/spec-template.md:
Extract requirements from research + proposal:
Write each requirement with:
Example scenario:
### Requirement: Budget Creation
Users can create budgets with categories and spending limits.
**Priority**: MUST
#### Scenario: Create a new monthly budget
- **GIVEN** a logged-in user on the budget page
- **WHEN** the user enters category "Food", limit "3,000,000 VND", period "monthly", and clicks Save
- **THEN** the budget is created and appears in the budget list with remaining amount = limit
Use delta operations:
ADDED — new behavior (most items for greenfield)MODIFIED — changed behavior (for existing features)REMOVED — deleted behaviorPresent requirements one at a time (or in small groups of 2-3 related ones):
Write to docs/specs/<feature>/spec.md
Quality check before presenting:
Using the template from references/design-template.md:
Build the design from all previous artifacts:
Present the design section by section (e.g., Architecture → Components → Data Model → API → Error Handling → Risks → Testing). Ask for feedback after each section.
Iterate on each section until approved
Write to docs/specs/<feature>/design.md
Quality check before presenting:
All four artifacts are written. Report back to the orchestrator that SPEC is complete.
Before reporting, run the final quality gate:
Cross-artifact consistency checks:
spec.mddesign.md decisionsdesign.md risksdesign.md match Domain Entities from research.mdspec.md (every req traces to a proposal capability)If any check fails, fix the artifact before reporting completion.
| Situation | What to Do |
|---|---|
| User rejects all directions (Step 2.2) | Ask which specific aspect doesn't work: scope too large/small? Wrong audience? Wrong architecture? Then re-propose 2 directions that specifically address the complaint. If rejected again, ask the user to describe their preferred direction in their own words — use that as the agreed direction instead of proposing further. |
| User rejects direction partially | Acknowledge what they want to keep, what to drop. Restate as a new blended direction for confirmation before proceeding. "So your direction is: [X from A] + [Y from B] — is that right?" |
| User rejects artifact 3+ times | Ask: "Would you like to adjust the proposal scope? The current requirements may be misaligned with your vision." Offer to go back to proposal |
research.md missing or incomplete | Note which sections are missing. Proceed with available data. Flag gaps in each artifact: "[Note: research.md lacked Competitive Landscape — this section is based on general knowledge]" |
| Artifact conflict (e.g., tech-stack doesn't support spec requirement) | Surface the conflict to user immediately: "The chosen tech [X] doesn't support requirement [Y]. Options: 1) Change tech stack, 2) Modify requirement, 3) Accept as tech debt" |
| User wants to skip an artifact | Explain dependency: "Skipping [X] means [Y] cannot reference it. Generate a minimal version instead?" Generate minimal version if user agrees |
| User adds scope during spec generation | Check against proposal Scope: "This wasn't in the proposal scope. Options: 1) Add to proposal and continue, 2) Note as future work, 3) Replace an existing scope item" |