From cce987372566e391b1e1122bc6c40c409d327c64 Mon Sep 17 00:00:00 2001 From: zichun Date: Mon, 18 May 2026 10:14:26 +0800 Subject: [PATCH] push --- skills/internal/superpower-brainstorming/SKILL.md | 105 --------------------------------------------------------------------------------------------------------- skills/internal/superpower-writing-plans/SKILL.md | 131 ----------------------------------------------------------------------------------------------------------------------------------- 2 files changed, 0 insertions(+), 236 deletions(-) delete mode 100644 skills/internal/superpower-brainstorming/SKILL.md delete mode 100644 skills/internal/superpower-writing-plans/SKILL.md diff --git a/skills/internal/superpower-brainstorming/SKILL.md b/skills/internal/superpower-brainstorming/SKILL.md deleted file mode 100644 index dc3e4b9..0000000 --- a/skills/internal/superpower-brainstorming/SKILL.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -name: superpower-brainstorming -description: Internal fork of superpowers:brainstorming with approval gates stripped. Use when a parent skill needs structured Q&A + design + spec doc, without user "approve design / review spec" wait points. -user-invocable: false ---- - -# Brainstorming Ideas Into Designs (Internal, Gate-Free) - -Help turn ideas into fully formed designs and specs through natural collaborative dialogue. This is an **internal fork** of `superpowers:brainstorming`: ``, "approve design", "review spec", and Visual Companion have been removed so the flow can run without user-facing confirmation breaks. QA (AskUserQuestion) is still used freely for genuine ambiguity. - -**Caller contract:** the parent skill passes in (or this skill derives) a spec output path. Once the spec file is written and self-reviewed, control returns to the caller. This skill does NOT chain to any next skill itself. - -**No human-fill markers in output.** The spec you write is CC's internal reasoning artifact, not a user-review doc. Do NOT emit `【人工填写：...】` style placeholders — that convention belongs to A-phase docs (`docs/01~10`, `CLAUDE.md`, `.env.local`), not B-phase specs/plans. When a concrete value is needed: - -1. **Look up first** — check `.env.local`, `docs/07-环境配置.md`, `CLAUDE.md`, existing code. If the value is already resolved somewhere, cite that source in the spec (e.g., "JWT_SECRET 从 `.env.local` 读取，`application.yml` 用 `${JWT_SECRET}` 注入") -2. **Ask via `AskUserQuestion` second** — if no source exists, ask the user directly; record their answer in the spec -3. **Never leave a 【人工填写：】 placeholder** — if step 1 + 2 somehow can't resolve it, the spec must name the exact blocker (not a generic human-fill marker), and Q&A keeps going until it's resolved - -## Checklist - -Complete in order: - -1. **Explore project context** — check files, docs, recent commits relevant to the topic -2. **Ask clarifying questions** — one at a time, only for genuine ambiguity; understand purpose / constraints / success criteria -3. **Pick an approach** — if multiple viable approaches exist, briefly weigh trade-offs and pick the best; surface the choice only if the user's answer to a prior Q&A did not already decide it -4. **Write design doc** — save to the path provided by the caller (default `docs/superpowers/specs/YYYY-MM-DD--design.md` if none) -5. **Spec self-review** — inline check for placeholders, contradictions, ambiguity, scope; fix inline -6. **Return control to caller** — no further chaining - -## Process Flow - -```dot -digraph brainstorming { - "Explore project context" [shape=box]; - "Ask clarifying questions\n(one at a time)" [shape=box]; - "Pick approach\n(weigh trade-offs only if needed)" [shape=box]; - "Write design doc" [shape=box]; - "Spec self-review\n(fix inline)" [shape=box]; - "Return to caller" [shape=doublecircle]; - - "Explore project context" -> "Ask clarifying questions\n(one at a time)"; - "Ask clarifying questions\n(one at a time)" -> "Pick approach\n(weigh trade-offs only if needed)"; - "Pick approach\n(weigh trade-offs only if needed)" -> "Write design doc"; - "Write design doc" -> "Spec self-review\n(fix inline)"; - "Spec self-review\n(fix inline)" -> "Return to caller"; -} -``` - -## The Process - -**Understanding the idea:** - -- Check current project state first (files, docs, recent commits) -- Before asking detailed questions, assess scope: if the request describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"), surface this immediately. Don't spend questions refining details of a project that needs to be decomposed first. -- If the project is too large for a single spec, help decompose: what are the independent pieces, how do they relate, what order to build? Then brainstorm the first sub-project through the normal design flow. -- For appropriately-scoped projects, ask questions one at a time -- Prefer multiple choice questions when possible, but open-ended is fine too -- Only one question per message -- Focus on understanding: purpose, constraints, success criteria - -**Approach selection:** - -- If there is a single obvious approach driven by the Q&A answers, just use it -- If trade-offs remain, briefly state 2-3 approaches + your recommendation inline in the spec (not as a confirmation gate) - -**Design for isolation and clarity:** - -- Break the system into smaller units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently -- For each unit you should be able to answer: what does it do, how do you use it, what does it depend on -- Smaller, well-bounded units are easier to reason about and test; large files are a signal of doing too much - -**Working in existing codebases:** - -- Explore the current structure before proposing changes. Follow existing patterns. -- Where existing code has problems that affect the work (e.g., a file that's grown too large, unclear boundaries, tangled responsibilities), include targeted improvements as part of the design — the way a good developer improves code they're working in. -- Don't propose unrelated refactoring. Stay focused on what serves the current goal. - -## After Q&A - -**Write the design doc:** - -- Write the validated design (spec) to the caller-provided path (default `docs/superpowers/specs/YYYY-MM-DD--design.md`) -- Cover: goal, inputs/outputs, rules, constraints, schema/API refs, acceptance criteria — or match the template the caller expects - -**Spec self-review (no user wait):** - -1. **Placeholder scan:** any "TBD", "TODO", "【人工填写：...】", incomplete sections, vague requirements? Fix them — either resolve via file lookup, raise a `AskUserQuestion`, or rewrite the passage to be concrete. -2. **Internal consistency:** do any sections contradict? Does architecture match feature descriptions? -3. **Scope check:** focused enough for a single implementation plan, or needs decomposition? -4. **Ambiguity check:** could any requirement be interpreted two ways? Pick one, make it explicit. - -Fix inline. No re-review — just fix and move on. - -**Terminal state:** - -Return control to the caller. Do not invoke writing-plans, frontend-design, or any other skill from here. - -## Key Principles - -- **One question at a time** — don't overwhelm -- **Multiple choice preferred** — easier to answer -- **QA for ambiguity only** — don't fabricate confirmation questions -- **YAGNI ruthlessly** — remove unnecessary features from designs -- **Incremental understanding** — clarify when something doesn't make sense -- **No approval gates** — writing the spec is the commit; any disagreement surfaces as a concrete Q&A item diff --git a/skills/internal/superpower-writing-plans/SKILL.md b/skills/internal/superpower-writing-plans/SKILL.md deleted file mode 100644 index 3d2aa7c..0000000 --- a/skills/internal/superpower-writing-plans/SKILL.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -name: superpower-writing-plans -description: Internal fork of superpowers:writing-plans with the "Which execution approach?" handoff gate stripped. Use when a parent skill needs a bite-sized, TDD-ready implementation plan written to disk without user-facing confirmation breaks. -user-invocable: false ---- - -# Writing Plans (Internal, Gate-Free) - -Write task-level implementation plans that tell the TDD executor **what to do**, not **how to write the code**. The executor is `feature-tdd` (Claude itself with full context), not a mechanical copy-paster — so the plan captures file boundaries, test intent, API shapes and completion criteria, and lets the executor produce the actual code in the red-green cycle. DRY. YAGNI. TDD. Frequent commits. - -**Do NOT dump full file contents (pom.xml, entity classes, config files) into the plan.** The plan and the code end up as two sources of truth that drift; 2000+ line plans also waste context. Code is produced during TDD, not pre-written here. - -**Caller contract:** the parent skill passes in (or this skill derives) a plan output path and a spec file path. Once the plan is written and self-reviewed, control returns to the caller. This skill does NOT ask the user to choose an execution mode; the caller decides. - -**Save plans to:** the caller-provided path (default `docs/superpowers/plans/YYYY-MM-DD-.md`). - -## Scope Check - -If the spec covers multiple independent subsystems, it should have been broken into sub-project specs during brainstorming. If it wasn't, surface this to the caller — suggest breaking into separate plans, one per subsystem. Each plan should produce working, testable software on its own. - -## File Structure - -Before defining tasks, map out which files will be created or modified and what each one is responsible for. This is where decomposition decisions get locked in. - -- Design units with clear boundaries and well-defined interfaces. Each file should have one clear responsibility. -- Files that change together should live together. Split by responsibility, not by technical layer. -- In existing codebases, follow established patterns. Don't unilaterally restructure — but if a file you're modifying has grown unwieldy, including a split in the plan is reasonable. - -This structure informs the task decomposition. Each task should produce self-contained changes that make sense independently. - -## Bite-Sized Task Granularity - -**Each step is one action (2-5 minutes):** -- "Write the failing test" — step -- "Run it to make sure it fails" — step -- "Implement the minimal code to make the test pass" — step -- "Run the tests and make sure they pass" — step -- "Commit" — step - -## Plan Document Header - -**Every plan MUST start with this header:** - -```markdown -# [Feature Name] Implementation Plan - -> **Execution:** Parent skill `feature-tdd` executes this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** [One sentence describing what this builds] - -**Architecture:** [2-3 sentences about approach] - -**Tech Stack:** [Key technologies/libraries] - ---- -``` - -## Task Structure - -Each task is a unit of red-green-commit. Capture intent and boundaries — leave code to TDD. - -````markdown -### Task N: [Component Name] - -**Files:** -- Create: `exact/path/to/File.java` -- Modify: `exact/path/to/Existing.java:123-145` -- Test: `tests/exact/path/to/FileTest.java` - -**API shape (只写需要约束实现的签名；内部实现留给 TDD):** -- `LoginService#login(LoginRequest req) : LoginResponse` -- `throws AccountLockedException when iLoginFailCount ≥ 5 within tLockUntil window` - -- [ ] **Step 1: 写失败测试** - - 测试名: `LoginServiceTest#loginWithBadPassword_incrementsFailCount_returns40101` - - 意图: 错误密码 → `iLoginFailCount += 1`；第 5 次 → 设置 `tLockUntil = now + 15min`；返回码 40101 - - 子会话确认 FAIL（函数/类不存在） - -- [ ] **Step 2: 实现最小代码** - - 目标: 让 Step 1 测试通过；不多做 - - 涉及文件: `LoginService.java`, `SftLoginInfoMapper.java` - -- [ ] **Step 3: 子会话验证 PASS** - -- [ ] **Step 4: Commit** - - `git add <文件>` - - `git commit -m "feat(sys): 登录失败计数 + 锁定 REQ-SYS-001"` -```` - -**允许的代码块场景**（少数例外，需要写死而非让 TDD 自由发挥的内容）： - -- **DDL / migration 文件**：`V_n__*.sql` 的 ALTER/CREATE 语句——因为 schema 是事实源、不是 TDD 的"红绿"产物 -- **合同级常量**：API 错误码表、JWT claim 名、Redis key 模式——这些跨模块被消费，必须在 plan 锁定 -- **测试的断言形状**（可选）：如果一句话说不清"测什么"，给个 3-5 行断言 sketch 是 OK 的 - -除此之外一律用散文+签名描述，**不贴完整文件**。 - -## No Placeholders - -Every step must contain the actual content an engineer needs. These are **plan failures** — never write them: -- "TBD", "TODO", "implement later", "fill in details" -- **`【人工填写：...】`** — this marker is A-phase only (`docs/01~10`, `CLAUDE.md`, `.env.local`). It must NEVER appear in B-phase plans. If you need a concrete value: (a) look it up in `.env.local` / `docs/07` / `CLAUDE.md` / existing code and cite the source in the plan, or (b) ask the user via `AskUserQuestion` and record the answer. The plan is CC's executable artifact, not a user-review doc. -- "Add appropriate error handling" / "add validation" / "handle edge cases"（具体到哪些错误码 / 哪些字段） -- "Similar to Task N"（相似任务各自写清楚测试意图 + 完成判据，不互相链接） -- References to types, functions, or methods not defined in any task（类/方法首次出现的 task 要给出 API 签名） - -> 散文级"做什么"是 OK 的——执行器（feature-tdd）会在 TDD 循环里决定"怎么写"。plan 的义务是**约束范围**，不是**替 TDD 写代码**。 - -## Remember - -- Exact file paths always -- Exact commands with expected output (for test runs and git ops) -- API signatures / class names / error codes / contract values — 必须写死 -- Internal implementation code — 不写；留给 TDD 阶段 -- DRY, YAGNI, TDD, frequent commits - -## Self-Review - -After writing the complete plan, look at the spec with fresh eyes and check the plan against it. This is a checklist you run yourself — not a subagent dispatch, not a user approval gate. - -**1. Spec coverage:** Skim each section/requirement in the spec. Can you point to a task that implements it? List any gaps. - -**2. Placeholder scan:** Search your plan for red flags — any of the patterns from the "No Placeholders" section above (including `【人工填写：...】`). Fix them: resolve by file lookup, raise a `AskUserQuestion`, or rewrite the step to be concrete. - -**3. Type consistency:** Do the types, method signatures, and property names you used in later tasks match what you defined in earlier tasks? A function called `clearLayers()` in Task 3 but `clearFullLayers()` in Task 7 is a bug. - -If you find issues, fix them inline. No re-review — just fix and move on. If you find a spec requirement with no task, add the task. - -## Terminal State - -Once the plan file is written and self-reviewed, return control to the caller. Do NOT ask the user to pick an execution approach; the caller decides how to execute. -- libgit2 0.22.2