From dev-workflow
Use when starting a new project's development after design is approved, or the user says 'write dev guide', 'break down this project into phases', or '写开发指南'. Creates a phased, project-level development guide that serves as the cornerstone document for all subsequent /write-plan and /run-phase cycles. Not for single-feature plans (use write-plan) or design exploration (use brainstorm).
npx claudepluginhub n0rvyn/indie-toolkit --plugin dev-workflowThis skill uses the workspace's default tool permissions.
This skill writes a phased development guide directly in main context, benefiting from full conversation history and project discussion context.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Designs and optimizes AI agent action spaces, tool definitions, observation formats, error recovery, and context for higher task completion rates.
This skill writes a phased development guide directly in main context, benefiting from full conversation history and project discussion context.
dev-workflow:write-plan/write-plandev-workflow:brainstormCollect the following before writing:
docs/06-plans/*-design.mddocs/01-discovery/project-brief.mddocs/02-architecture/If no project-brief or design doc exists, inform the user and suggest running the corresponding workflow first. Do not proceed without these inputs.
Read all found documents to ground the dev-guide in actual project state.
Before writing, check if a dev-guide already exists:
docs/06-plans/*-dev-guide.mdexisting_dev_guidesWrite the dev-guide following the Dev-Guide Writing Reference below. Save to docs/06-plans/YYYY-MM-DD-<project>-dev-guide.md.
After writing the new dev-guide:
existing_dev_guides is empty: skip this stepexisting_dev_guides:
a. Read the file
b. Check if it starts with YAML frontmatter (first line is ---)
c. If frontmatter exists: find the current: field and change its value to false
d. If no frontmatter exists (older file without frontmatter): skip this file (do not add frontmatter to files that weren't written with it)
e. Write the updated file backcurrent: false: {paths}"After the dev-guide is written and old guides are superseded:
Dispatch the dev-workflow:dev-guide-verifier agent with:
Read the agent's compact summary.
If verdict is approved:
If verdict is must-revise:
a. V7 (Structural) issues: directly Edit the dev-guide file to fix (frontmatter fields, missing sections, section markers — mechanical fixes only)
b. V1-V6 issues: apply revision instructions directly in main context — re-read the relevant source docs and fix the flagged issues in the dev-guide file. Max 1 revision cycle.
c. After revision: re-run V7 check only (structural, in main context — verify frontmatter fields, required sections, section markers) to confirm mechanical fixes. Do NOT re-dispatch the verifier agent.
d. If V1-V6 issues persist after the single revision cycle: note the unresolved items and present them to the user in Step 3 alongside the Phase outline, so the user can decide whether to accept or manually adjust.
e. If the verifier produced Decisions (DP-xxx entries): carry them forward to Step 3, where they will be presented alongside the dev-guide's own decisions.
After writing (and Step 2.7 passes or revision is done):
| Phase | Goal | Dependencies |
|---|---|---|
| Phase 1 | {goal} | None |
| Phase 2 | {goal} | Phase 1 |
| ... | ... | ... |
Collect decisions from two sources:
a. Read the ## Decisions section from the dev-guide file
b. If Step 2.7 produced verifier Decisions, include those as well (prefix verifier DPs with [V] to distinguish source)
If both sources have None. content, skip to step 3. Otherwise, merge all ### [DP-xxx] entries. Present blocking decisions first (regardless of source), then recommended.
Process each ### [DP-xxx] entry:
Comparison table (all decisions): extract from the decision's **Options:** lines, keeping each option's {description} — {trade-off} as-is in one column:
Context: {from decision}
| 方案 | 描述与代价 |
|---|---|
| A | {description} — {trade-off} |
| B | {description} — {trade-off} |
Recommendation line: only for recommended decisions, append **推荐:** {option} — {reason} after the table. For blocking decisions, omit this line.
AskUserQuestion: for recommended decisions, mark the recommended option with "(推荐)" in the label. For blocking decisions, do not pre-select any option.
Record user choices: edit the dev-guide file, replace the **Recommendation:** or **Recommendation (unverified):** line with **Chosen:** {user's choice}
Display all Phase details in one block, then confirm once.
Phase {i}: {goal}
| 维度 | 内容 |
|---|---|
| 前置依赖 | {dependencies} |
| 范围项 | {scope items, bulleted} |
| 用户可见的变化 | {from dev-guide, or "无 — 纯基建阶段"} |
| 关键文件/组件 | {key files and components} |
| 待定架构决策 | {architecture decisions to resolve, or "无"} |
| 验收标准 | {acceptance criteria} |
After user confirms in Step 4, update the dev-guide file's YAML frontmatter:
--- markers)confirmed_at: field exists: update its value to current ISO timestampconfirmed_at: field: add confirmed_at: YYYY-MM-DDTHH:MM:SS after the current: fieldThis timestamp is consumed by run-phase Step 1.5 to avoid redundant scope confirmation.
After user confirms:
Development guide saved. Use
/run-phaseto start the Phase 1 development cycle (plan → execute → review).
docs/06-plans/current: false (Step 2.5)---
type: dev-guide
status: active
tags: [tag1, tag2]
refs: []
current: true
---
# [Project Name] Development Guide
**Project brief:** docs/01-discovery/project-brief.md
**Design doc:** docs/06-plans/YYYY-MM-DD-<topic>-design.md
**Architecture:** docs/02-architecture/README.md
## Global Constraints
- Tech stack: [from CLAUDE.md]
- Coding standards: [from CLAUDE.md]
- Project-specific constraints: [from CLAUDE.md]
---
<!-- section: phase-1 keywords: {scope-keyword-1}, {scope-keyword-2} -->
## Phase 1: [Name]
**Goal:** One sentence describing the state after this Phase completes.
**Depends on:** None / Phase N
**Scope:**
- Feature A
- Feature B
**用户可见的变化:**
- {plain-language description of what the user will see/interact with after this Phase}
- {describe by screen location and appearance, not code identifiers}
**Architecture decisions:** Key technical decisions this Phase needs to make (list decision points, don't pre-decide — leave to /write-plan stage).
**Acceptance criteria:**
- [ ] Specific verifiable condition 1
- [ ] Specific verifiable condition 2
- [ ] Tests pass for this Phase's scope (UT for logic, E2E for user journeys)
**Review checklist:**
- [ ] /execution-review
- [ ] /ui-review (if Phase has UI)
- [ ] /design-review (if Phase has new pages)
- [ ] /feature-review (if Phase completes a full user journey)
<!-- /section -->
---
<!-- section: phase-N keywords: submission, app-store, accessibility -->
## Phase N: Submission Prep
**Goal:** App Store submission ready.
**Scope:**
- Performance optimization
- Accessibility audit
- Privacy compliance
- ASC materials
**Review checklist:**
- [ ] /submission-preview
- [ ] /appstoreconnect-review
<!-- /section -->
## Phase N: block is wrapped in <!-- section: phase-N keywords: {kw1}, {kw2} --> ... <!-- /section -->. Keywords are derived from the Phase's scope items: use noun forms of the key features and technologies (e.g., scope items "Implement SwiftData persistence", "Add offline queue" → keywords: swiftdata, persistence, offline, queue). 3-5 keywords per section.type is always dev-guide. status is always active when first written. tags — derive 2-5 keywords from the project name and major feature areas in the Phases (e.g., [sync, offline, swiftdata]). refs — list paths to the design doc and project brief referenced in the header. current — always true; the write-dev-guide skill manages toggling this to false on the previously-current dev-guide.If any planning finding requires a user choice before the dev-guide can be finalized, output a ## Decisions section in the dev-guide document. If no decisions needed, output ## Decisions\nNone.
Format per decision:
### [DP-001] {title} ({blocking / recommended})
**Context:** {why this decision is needed, 1-2 sentences}
**Options:**
- A: {description} — {trade-off}
- B: {description} — {trade-off}
**Recommendation:** {option} — {reason, 1 sentence}
Recommendation quality rule:
Router.swift:42 shows routes are registered centrally, extending that pattern is lower-risk"**Recommendation (unverified):** instead of **Recommendation:**, and state why evidence is absentPriority levels:
blocking — must be resolved before dev-guide can be approvedrecommended — has a sensible default but user should confirmCommon decision triggers for dev-guide writing: