Idea To Implementation Doc

Idea to Implementation Doc Workflow

Use this skill when the user wants to take one specific idea note and turn it into a technical implementation document.

This is not the top-level ideas index workflow. It works on a single idea file and produces a separate implementation plan.

Goal

Given a specific idea/design doc, create a detailed implementation document that:

• reviews the idea carefully
• researches similar products or existing apps
• identifies gaps or overlap with existing solutions
• proposes a concrete build approach
• outlines the system design, major components, and development phases
• converts the plan into an executable set of tasks and/or prompts for Hermes, Claude Code, Codex, OpenClaw, or another coding agent
• includes testing, verification, and acceptance criteria so “done” means the program works and is ready to use
• produces a single markdown file that can be handed to an agent as the build source of truth

Important constraints

• Focus on implementation strategy, not just product brainstorming.
• Research existing apps only to the extent needed to avoid reinventing something obvious.
• Do not over-engineer the stack. Choose the simplest viable approach.
• Keep the output practical and actionable.
• If the user asks for the doc to stay non-technical, stop at product-level architecture and planning.
• If the user wants code-level detail, include it in a separate section rather than mixing it into the product description.

Inputs

Primary input:

• one specific idea note, e.g. ideas/my-app.md

Optional input:

• associated design doc, if it exists separately
• user constraints about stack, hosting, or platform
• deployment/data-location preference: local-only, self-hosted, Cloudflare, AWS, another cloud, or undecided
• platform targets: browser/web-only, Windows desktop, Mac desktop, cross-platform desktop, mobile web, iOS, Android, or explicitly no mobile
• accepted technical defaults or overrides for database, backend/runtime, frontend, auth, file/object storage, queues/jobs, realtime/sync, search, observability/logging, tests, and deployment/CI

Workflow

1) Read the source note

Review the target idea/design doc and extract:

• the core problem
• intended user
• must-have behavior
• non-goals
• any unresolved questions

2) Research similar products

Look for apps/products with similar goals or workflows.

Identify:

• comparable products
• what they do similarly
• where the user’s idea differs
• what this idea should avoid copying or duplicating

Treat this as lightweight product reconnaissance, not exhaustive market analysis.

3) Convert to an implementation strategy

Translate the idea into an implementation plan covering:

• product scope
• main user flows
• data model / database needs
• recommended database/storage default and accepted/changed decision
• hosting/deployment target and where data should live
• front end structure
• backend/service needs
• platform target decisions: web-only, desktop apps, mobile apps, responsive web, and which are MVP vs later
• recommended technical defaults for frontend, backend/runtime, auth, storage, queues/jobs, realtime/sync, search, observability/logging, tests, and deployment/CI
• integration points
• file/module organization
• development phases
• executable task breakdown
• agent-ready prompts or handoff instructions
• testing and verification strategy
• acceptance criteria and “done means” checklist
• risks and open questions

4) Produce implementation spec and final handoff docs

Save the implementation work near the source note using the staged idea-workflow layout when appropriate:

• README.md — status/index page for the full idea package.
• 02-implementation-spec.md — the detailed implementation strategy.
• 03-agent-build-handoff.md — the final single-file handoff for a coding agent or Superpowers.
• 04-spec-review.md — readiness review before execution.

For lightweight ideas, a single <idea-name>.implementation.md file is acceptable, but full app builds should use the staged layout.

Suggested naming:

• ideas/<idea-slug>/README.md
• ideas/<idea-slug>/02-implementation-spec.md
• ideas/<idea-slug>/03-agent-build-handoff.md
• ideas/<idea-slug>/04-spec-review.md

Recommended output structure

# <Idea Title> Implementation Plan

## Summary

## Source Idea Review

## Similar Products / Market Check

## Product Scope

## System Overview

## Data Model

## Database / Storage Recommendation

## Hosting / Data Location / Deployment

## Technical Stack Recommendation

## Frontend Plan

## Platform Targets

## Backend / Services Plan

## Key Workflows

## Milestones / Phases

## Build Tasks

## Agent Build Prompt

## Testing and Verification Plan

## Acceptance Criteria / Done Means

## Risks and Tradeoffs

## Open Questions

## Next Build Prompt

Final agent handoff format

After the implementation spec is drafted, create 03-agent-build-handoff.md using this required structure:

# <Project Name> Agent Build Handoff

## Mission

## Product Vision

## User Experience Goals

## Non-Negotiable Requirements

## Out of Scope

## Technical Architecture

## Data Model

## Database / Storage Recommendation

State the recommended database/storage approach, why it fits the product, and whether the user accepted it or overrode it. Mention relevant alternatives considered when helpful.

## Hosting / Data Location / Deployment

Specify whether data stays local, is self-hosted, uses Cloudflare, AWS, another cloud, or remains undecided. If undecided, list the assumptions used for the MVP and what would change later.

## Platform Targets

Specify whether the MVP is browser/web-only, Windows desktop, Mac desktop, cross-platform desktop, mobile web, iOS, Android, or a combination. Explicitly separate MVP platforms from future platforms.

## Technical Stack Recommendation

List recommended defaults and user overrides for frontend, backend/runtime, auth, database, file/object storage, queues/jobs, realtime/sync, search, observability/logging, testing, and deployment/CI. The handoff should not require the build agent to guess these choices unless the spec explicitly marks them as flexible.

## Integrations

## Implementation Phases

## Build Tasks

## Testing Requirements

## Verification Commands / Checks

## Acceptance Criteria

## Done Means

## Known Risks

## Open Questions

## Prompt for Build Agent
Use a prompt that asks the build agent to inspect the project, preserve scope, create or follow an implementation plan, run tests, and verify evidence before claiming done. Do not duplicate Superpowers' detailed planning protocol; hand off to it.

## Superpowers Build Handoff
Use the `superpowers-gpt` workflow on this document.

Start with:
1. `superpowers-using-superpowers` to route the work.
2. `superpowers-writing-plans` to inspect the target repo and turn this handoff into exact implementation tasks, files, commands, tests, and expected results.
3. `superpowers-executing-plans` or `superpowers-subagent-driven-development` to implement the approved plan without scope drift.
4. `superpowers-requesting-code-review` to review the implementation.
5. `superpowers-verification-before-completion` to prove the work satisfies the acceptance criteria before claiming completion.

The goal is to convert this spec into an executable implementation plan, build it with tests, review the result, and verify before claiming completion.

Spec review gate

Before saying the handoff is ready, create 04-spec-review.md with this verdict structure:

# <Project Name> Spec Review

Verdict: PASS | PASS WITH CHANGES | FAIL

## Summary

## Readiness Checklist
- [ ] Product goal is clear
- [ ] Requirements are testable
- [ ] Product decisions are resolved or explicitly listed
- [ ] Technical decisions are resolved or explicitly listed
- [ ] Database/storage recommendation is present or explicitly unnecessary
- [ ] Recommended technical defaults are documented, with user overrides if any
- [ ] Acceptance criteria are concrete
- [ ] Done Means is specific
- [ ] A fresh agent could build from the handoff without obvious missing context
- [ ] Testing requirements are included
- [ ] Verification commands/checks are included
- [ ] Non-goals prevent likely scope creep

## Required Changes Before Build

## Optional Improvements

## Superpowers Handoff Recommendation

Only use PASS when the build handoff is ready to feed into Superpowers without major clarification.