/spec — Specification Brainstorming & Finalization Command

Prerequisites

• Implementation will be handled by a separate Coding Agent
• Review will be handled by a separate Review Agent
• Specifications should be "minimal necessary" and "not expanded later"
• Respect the user's answers regarding timeline and scale (you may make provisional decisions if unspecified)

Workflow (Strictly Follow)

Step 1: Generate Confirmation Questions (Approx. 7 Questions)

• Goal (What will be achievable when successful?)
• Target Users
• Key Inputs and Outputs
• Minimum User Operation Flow
• Constraints (Technical, Permissions, Dependencies, Deadlines, etc.)
• Explicit "Out of Scope" Items
• Criteria for Determining Success/Failure
• Verification Strategy (How to verify the Agent's deliverables)

Rules

• If domain-specific items are required, create questions to clarify them
• Prioritize questions that can be answered with Yes/No
• If there are many ambiguous points, you may split the conversation into rounds
  • When splitting into rounds, indicate the round number first, e.g., [1/3]
  • Limit the number of questions per round to reduce the user's response burden

About Verification Strategy (Important)

• Review: Whether the code is ready for commit (quality check)
• Verification: Whether we are moving toward or have achieved the goal (direction check)

1. Progress Verification: How to confirm we are on the right track during implementation
2. Achievement Verification: How to determine if the goal has been finally achieved
3. Gap Detection: How to find implementation omissions or shortcuts

Step 2: Provisional Decision Rules

• Always mark provisional decisions with

  (Provisional)

• If in doubt, choose the option that is simpler to implement and easier to test
• If no timeline is specified, you may make provisional decisions based on the premise of "completing in a short period"

Step 3: Tech Stack Proposal & Approval

Proposal Content

• Language & Runtime (e.g., TypeScript, Python, Go)
• Framework (e.g., Next.js, FastAPI, Echo)
• Database (e.g., PostgreSQL, SQLite, None)
• Key Libraries (e.g., Prisma, React Query)
• Testing Framework (e.g., Vitest, pytest)
• Other Tools (e.g., Docker, CI/CD)

Proposal Format

## Proposed Tech Stack

I would like to proceed with the following tech stack:

| Category | Selection | Reason |
|---------|------|------|
| Language | TypeScript | Type safety, rich ecosystem |
| Framework | Next.js | SSR support, integrated API Routes |
| ... | ... | ... |

Is this configuration acceptable?
Please let me know if you would like to make any changes.

Actions Based on User's Response

• "Leave it to you" / "That's okay" etc. → Proceed as proposed
• "X would be better" etc. → Update the proposal and reconfirm
• Specific specifications provided → Follow the specifications to finalize

Step 4: Output Spec.md

Spec.md

# Spec.md

## 1. Goal
- Describe "what will be achievable with this deliverable" in 1-2 lines

## 2. Non-Goals
- Explicitly list items that are **out of scope for this project**

## 3. Target Users
- Target users and usage scenarios

## 4. Core User Flow
- List user operations **in chronological order**
- At a granularity that clarifies screens/operations/results

## 5. Inputs & Outputs
- Main inputs (user input / external data)
- Main outputs (display / storage / generated products)

## 6. Tech Stack
- Language & Runtime
- Framework
- Database (if required)
- Key Libraries
- Testing Framework

## 7. Rules & Constraints
- Behavioral rules
- Technical, operational, and security constraints
- Prerequisites that must not be violated

## 8. Open Questions (Only if necessary)
- Points that could not be finalized at this stage
- Items that need reconfirmation before implementation

## 9. Acceptance Criteria (Max 10)
- **Judgment must be possible with Yes / No**
- Written in a way that can be verified through testing
- Max 10 items

## 10. Verification Strategy
Methods to verify if the Agent's deliverables are moving in the right direction or have achieved the goal.

- **Progress Verification**: How to confirm we are on the right track during implementation
  - Example: Run a demo upon completion of each task, check via screenshots
- **Achievement Verification**: Criteria to determine if the goal has been achieved
  - Example: Verify all Acceptance Criteria using a checklist
- **Gap Detection**: How to find implementation omissions or shortcuts
  - Example: Check coverage, manually test edge cases

## 11. Test Plan
- Max 3 e2e scenarios
- In Given / When / Then format

Step 5: Register Tasks with TodoWrite

Task Registration Rules

• Split tasks into granularities of "half a day to 1 day"
• Include Definition of Done (DoD) in the content of each task
• Consider dependencies and register tasks in order
• Organize by phase (Setup / Core / Polish)

Example

TodoWrite([
  { content: "Setup: Initialize project (DoD: package.json created)", status: "pending" },
  { content: "Core: User authentication feature (DoD: Login/logout functionality confirmed)", status: "pending" },
  { content: "Core: Data storage feature (DoD: CRUD operation tests passed)", status: "pending" },
  { content: "Polish: Error handling (DoD: Appropriate messages displayed for all error cases)", status: "pending" }
])

Output Order

1. Confirmation Questions (AskUserQuestion)
2. Tech Stack Proposal → User Approval
3. Generate & Save Spec.md
4. Register Tasks with TodoWrite
5. Completion Report

Success Criteria

• The Coding Agent can start implementation without additional questions
• The Review Agent can conduct reviews based on the Acceptance Criteria
• Humans only need to check the Spec.md and progress (/todos)