idea-to-implementation-doc

从想法到实施文档的工作流

当用户想要将一个具体的想法笔记转化为技术实施文档时，使用此技能。

这不是顶层想法索引工作流。它处理的是单个想法文件，并产出一份单独的实施计划。

目标

针对一份具体的想法／设计文档，创建一份详细的实施文档，其中：

• 仔细审阅想法
• 调研类似产品或现有应用
• 找出与现有解决方案之间的缺口或重叠之处
• 提出具体的构建方案
• 概述系统设计、主要组件和开发阶段
• 将计划转化为可执行的任务和／或提示词，供 Hermes、Claude Code、Codex、OpenClaw 或其他编码 Agent 使用
• 包含测试、验证和验收标准，确保“完成”意味着程序可正常运行并可供使用
• 生成一个 Markdown 文件，作为交给 Agent 的构建事实依据

重要限制

• 聚焦于实施策略，而不只是产品构思。
• 仅在避免重复造显而易见的轮子所需的范围内调研现有应用。
• 不要让技术栈过度复杂。选择最简单可行的方案。
• 保持输出实用且可执行。
• 如果用户要求文档保持非技术性，内容就止步于产品级架构和规划。
• 如果用户需要代码级细节，请将其放在单独的章节中，不要与产品描述混在一起。

输入

主要输入：

• 一份具体的想法笔记，例如 ideas/my-app.md

可选输入：

• 单独存在的相关设计文档（如有）
• 用户对技术栈、托管或平台的限制
• 部署／数据位置偏好：仅限本地、可自托管、Cloudflare、AWS、其他云服务或尚未决定
• 平台目标：浏览器／仅 Web、Windows 桌面、Mac 桌面、跨平台桌面、移动 Web、iOS、Android，或明确不支持移动端
• 已接受的技术默认方案或覆盖项：数据库、后端／运行时、前端、身份验证、文件／对象存储、队列／作业、实时／同步、搜索、可观测性／日志记录、测试和部署／CI

工作流

1）阅读源笔记

审阅目标想法／设计文档，并提取：

• 核心问题
• 目标用户
• 必备行为
• 非目标
• 尚未解决的问题

2）调研类似产品

寻找目标或工作流相似的应用／产品。

确定：

• 可比较的产品
• 它们有哪些相似之处
• 用户的想法有哪些不同之处
• 这个想法应避免复制或重复实现哪些内容

将此视为轻量级产品调研，而非全面的市场分析。

3）转化为实施策略

将想法转化为实施计划，涵盖：

• 产品范围
• 主要用户流程
• 数据模型／数据库需求
• 推荐的数据库／存储默认方案，以及已接受／变更的决策
• 托管／部署目标和数据存放位置
• 前端结构
• 后端／服务需求
• 平台目标决策：仅 Web、桌面应用、移动应用、响应式 Web，以及哪些属于 MVP，哪些留待后续
• 前端、后端／运行时、身份验证、存储、队列／作业、实时／同步、搜索、可观测性／日志记录、测试和部署／CI 的推荐技术默认方案
• 集成点
• 文件／模块组织
• 开发阶段
• 可执行的任务拆分
• 可供 Agent 使用的提示词或交接说明
• 测试和验证策略
• 验收标准和“完成意味着什么”检查清单
• 风险和待解决问题

4) 编写实现规格说明和最终交接文档

在源说明附近保存实现相关文档；适用时采用分阶段的创意工作流目录结构：

• README.md — 完整创意文档包的状态／索引页面。
• 02-implementation-spec.md — 详细的实现策略。
• 03-agent-build-handoff.md — 提供给编码 Agent 或 Superpowers 的最终单文件交接文档。
• 04-spec-review.md — 执行前的准备情况审查。

对于轻量级创意，可以使用单个 <idea-name>.implementation.md 文件；但完整应用构建应采用分阶段目录结构。

建议的命名方式：

• 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

建议的输出结构

# <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

最终 Agent 交接文档格式

完成实现规格说明初稿后，按以下必需结构创建 03-agent-build-handoff.md：

# <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.

规格审查关卡

在说明交接文档已准备就绪之前，按以下裁定结构创建 04-spec-review.md：

# <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

只有当构建交接文档已准备好交给 Superpowers，且不需要重大澄清时，才使用 PASS。

Lite 与 Full 模式及阶段推进规则

如果此技能用于轻量级创意，单个 <idea-name>.implementation.md 文件可能就足够。除非用户要求达到构建就绪状态，否则不要强制要求准备完整交接文档包。

对于 Full 模式，请遵循以下规则：

• 如果尚未解决的产品问题会影响架构或 MVP 范围，就不要进入实现阶段。
• 在测试要求、验证检查、验收标准和完成定义明确之前，不要创建 03-agent-build-handoff.md。
• 如果重大产品或技术选择尚未明确，不要将 04-spec-review.md 标记为 PASS。

用户可以使用准确短语 GREENLIGHT NEXT STAGE 覆盖完整性关卡。收到该短语后，继续编写下一份文档，将未解决事项记录为假设／开放问题，然后继续推进。

调研指南

调研类似产品时，请回答：

• 现有哪些应用已经解决了这个问题？
• 哪些部分属于常见功能？
• 哪些部分具有独特性或差异化？
• 这个创意是否实际上属于某个广为人知的产品类别的变体？
• 用户选择这款产品而非现有工具的理由是什么？

如果这个创意与现有应用非常相似，请明确指出，并建议重新定位或缩小范围。

审查指南

审查创意文档时，请明确检查以下方面：

• 歧义
• 范围蔓延
• 缺失的用户流程
• 数据所有权不明确
• 未确定托管方式／数据存储位置
• 未确定 Web、桌面和移动端的平台目标
• 缺少数据库／存储方案建议
• 缺少技术默认方案或用户覆盖选项
• 成功标准含糊
• 隐含假设
• 与其他地方已有功能重复

实施规划指南

技术方案应做到以下几点：

• 明确列出可能涉及的组件。
• 优先采用简单架构。
• 说明是否需要数据库，以及原因。
• 先推荐默认技术栈，再允许用户接受或更改。不要让用户从零开始逐一选择所有技术组件。
• 视情况涵盖数据库／存储、后端／运行时、前端／UI、身份验证、文件／对象存储、队列／任务、实时功能／同步、搜索、可观测性／日志、测试以及部署／CI。
• 将已接受的默认方案记录为决策，将用户的更改记录为明确的覆盖项。
• 如果应用规模较小，请说明最小可行架构，而非完整的企业级技术栈。
• 如果应用需要身份验证、持久化、搜索、同步或实时功能，请明确指出。

停止条件

如果用户要求停止或只需要高层审查，请整理已有内容，并明确标记尚存的不确定事项。

调用时的行为

此技能旨在作为任务运行，或在创意文档已存在后根据明确请求运行。

典型的回复风格：

• 简要总结创意内容
• 找到的类似产品
• 实施策略
• 新实施文档的文件路径

质量标准

一份优秀的实施文档应让开发者或 AI 编码 Agent 立即了解：

• 要构建什么
• 为什么这种方法合理
• 系统主要由哪些部分构成
• 如何开始构建而无需猜测
• 要与哪些现有产品进行比较
• 按什么顺序完成哪些任务
• 要运行哪些测试
• 如何验证应用确实可用
• 在 Agent 能如实宣称“已完成”之前，必须满足哪些条件