project-long-task

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Project Long Task

长期项目任务

A structured workflow for long-running, milestone-based builds. This skill supports two modes:

Init mode — New project: collects requirements through an interactive interview, then generates a complete documentation scaffold that guides autonomous execution from planning through implementation.
Update mode — Existing project: collects requirements for a change through a focused interview, then updates the existing documentation to incorporate the change. Supports three update types:
- New Feature — Adding new functionality (3-8 interview rounds)
- Bug Fix — Fixing issues that may change behavior or architecture (1-3 interview rounds)
- Change — Requirement changes, refactors, tech migrations (2-5 interview rounds)

一种适用于长期、基于里程碑的构建任务的结构化工作流。此技能支持两种模式：

初始化模式 — 新项目：通过交互式访谈收集需求，然后生成完整的文档框架，指导从规划到实现的自主执行。
更新模式 — 现有项目：通过针对性访谈收集变更需求，然后更新现有文档以纳入该变更。支持三种更新类型：
- 新增功能 — 添加新功能（3-8轮访谈）
- Bug修复 — 修复可能改变行为或架构的问题（1-3轮访谈）
- 变更 — 需求变更、重构、技术迁移（2-5轮访谈）

Why this structure works

该结构的优势

Long-running tasks fail when context drifts or the executor loses track of what's done and what's next. This workflow prevents that by separating concerns into distinct documents that each serve a clear purpose:

A spec that never changes (what to build)
A plan that tracks progress (what's done, what's next)
Execution rules that enforce discipline (how to work)
Living docs that stay accurate (architecture + user docs)
A production readiness gate that ensures the final output is deployment-ready, not a demo or prototype

The interview phase is critical — it forces clarity before any code is written, which saves hours of rework later.

当上下文偏移或执行者忘记已完成和待完成的任务时，长期任务容易失败。此工作流通过将关注点分离为多个用途明确的独立文档，避免了这种情况：

spec（需求规格）：永不更改（明确要构建的内容）
plan（计划）：跟踪进度（已完成项、待完成项）
Execution rules（执行规则）：确保工作规范性（明确工作方式）
Living docs（动态文档）：保持内容准确（架构 + 用户文档）
Production Readiness Gate：确保最终输出可部署，而非演示版或原型

访谈阶段至关重要——它要求在编写任何代码前明确所有细节，从而节省后续大量的返工时间。

Mode Detection

模式检测

At the start, detect which mode to use:

Check if
```
docs/architecture.md
```
and
```
docs/plans.md
```
already exist in the project
If both exist → Update mode (the project was previously initialized with this skill)
If neither exists → Init mode (new project)
If only one exists → Potentially corrupted state. Inform the user which file is missing and ask: init from scratch (overwrite), or attempt update with incomplete docs?
If ambiguous for other reasons, ask the user whether they are modifying the existing project or starting fresh

开始时，检测应使用的模式：

检查项目中是否已存在
```
docs/architecture.md
```
和
```
docs/plans.md
```
如果两者均存在 → 更新模式（该项目此前已通过此技能初始化）
如果两者均不存在 → 初始化模式（新项目）
如果仅存在其中一个 → 状态可能已损坏。告知用户缺失的文件，并询问：是从头开始初始化（覆盖现有文件），还是尝试使用不完整的文档进行更新？
如果因其他原因存在歧义，询问用户是要修改现有项目还是从头开始

Complexity Tiers

复杂度层级

After Step 2 (Project Goals), assess complexity and assign a tier. This determines interview depth, milestone count, and review scope throughout the entire workflow.

Default tier is Standard. Only downgrade to Lite if the user explicitly requests a simplified interview or the project is clearly trivial (e.g., a single-file script, a config wrapper). When in doubt, stay at Standard.

Tier	When	Target Questions	Interview Rounds	Follow-up Cap	Milestones	Review
Lite	Single-purpose tool, 1 role, no auth, no integrations — only if user explicitly requests simplified interview	~10	7-9 base rounds (may condense Rounds 4-5, 8-9 but do NOT skip entirely)	5	4-6	Agent 1 + Agent 2
Standard	Default for all projects — most projects fall here	~15	All applicable rounds (full protocol; GUI ~10-11, CLI ~10-13 effective rounds)	8	7-10	Agent 1 + Agent 2 + Agent 3
Complex	Multi-role, multi-platform, integration-heavy, enterprise	~25-30	All applicable rounds (full protocol) + extended depth on architecture, security, scale	20	10-14	Agent 1 + Agent 2 + Agent 3, then second-pass recheck

Announce the tier to the user after Step 2 and let them override it. Default assumption is Standard.

完成步骤2（项目目标）后，评估复杂度并分配层级。这将决定访谈深度、里程碑数量以及整个工作流中的评审范围。

默认层级为标准级。仅当用户明确要求简化访谈，或项目明显非常简单（例如单文件脚本、配置包装器）时，才降级为轻量级。如有疑问，保持标准级。

层级	适用场景	目标问题数	访谈轮次	跟进能力	里程碑数量	评审方式
轻量级	单一用途工具、单角色、无认证、无集成 — 仅当用户明确要求简化访谈时使用	~10	7-9基础轮次（可合并第4-5、8-9轮，但不得完全跳过）	5	4-6	Agent 1 + Agent 2
标准级	所有项目的默认层级 — 大多数项目适用	~15	所有适用轮次（完整流程；GUI约10-11轮，CLI约10-13轮有效访谈）	8	7-10	Agent 1 + Agent 2 + Agent 3
复杂级	多角色、多平台、重度集成、企业级项目	~25-30	所有适用轮次（完整流程） + 针对架构、安全、扩展性的深度访谈	20	10-14	Agent 1 + Agent 2 + Agent 3，然后进行二次复查

完成步骤2后向用户宣布当前层级，并允许其修改。默认假设为标准级。

Workflow

工作流

Phase 1: Interactive Interview

阶段1：交互式访谈

Collect project information through an interactive conversation. See

references/interview.md

for the full interview protocol including all rounds, follow-up triggers, and examples.

Steps overview:

Project Name — Ask the user for the project name
Project Goals — Free-form description of what they're building, the problem, and target users
Clarifying Questions — AI-driven discovery interview (rounds and depth determined by complexity tier, covering user journeys, components, tech stack finalization, UI/CLI preferences, and deployment). Adaptive follow-ups for ambiguities. Tech stack is locked during this step (Round 10.7).
Tier Recheck — After all interview rounds, reassess tier based on what was discovered. If the project turned out more complex than initially assessed, upgrade the tier and announce the change to the user.
Synthesis & Confirmation — Present a complete project summary for user approval before generating docs

通过交互式对话收集项目信息。完整的访谈流程（包括所有轮次、触发跟进的条件及示例）请参见

references/interview.md

。

步骤概述：

项目名称 — 询问用户项目名称
项目目标 — 自由描述要构建的内容、解决的问题及目标用户
澄清问题 — 由AI驱动的发现式访谈（轮次和深度由复杂度层级决定，涵盖用户旅程、组件、技术栈最终确定、UI/CLI偏好及部署）。针对模糊点进行自适应跟进。技术栈在此步骤（第10.7轮）锁定。
层级复查 — 完成所有访谈轮次后，根据收集到的信息重新评估层级。如果项目实际复杂度高于初始评估，升级层级并告知用户。
综合与确认 — 在生成文档前，向用户呈现完整的项目摘要以获得批准

Phase 2: Generate Documentation

阶段2：生成文档

After confirmation, create the

docs/

directory and generate all documents. See

references/templates.md

for the full templates and structure of each file.

Documents generated:

```
docs/architecture.md
```
— Single source of truth: project background, user journeys, components, product spec, technical architecture
```
docs/plans.md
```
— Execution plan with milestones, sub-tasks, acceptance criteria, verification commands
```
docs/implement.md
```
— Non-negotiable execution rules for disciplined autonomous work
```
docs/secrets.md
```
— Secrets & API keys guidance (env vars + safe key handling)
```
docs/documentation.md
```
— User-facing documentation, kept in sync with reality
```
CLAUDE.md
```
+
```
AGENT.md
```
— Quick-reference files for AI coding tools (identical content, under 120 lines)

获得批准后，创建

docs/

目录并生成所有文档。各文件的完整模板和结构请参见

references/templates.md

。

生成的文档：

```
docs/architecture.md
```
— 唯一事实来源：项目背景、用户旅程、组件、产品规格、技术架构
```
docs/plans.md
```
— 执行计划，包含里程碑、子任务、验收标准、验证命令
```
docs/implement.md
```
— 用于规范自主工作的不可协商的执行规则
```
docs/secrets.md
```
— 密钥与API密钥管理指南（环境变量 + 安全密钥处理）
```
docs/documentation.md
```
— 面向用户的文档，与实际情况保持同步
```
CLAUDE.md
```
+
```
AGENT.md
```
— AI编码工具的快速参考文件（内容相同，不超过120行）

Phase 2.5: Multi-Agent Documentation Review

阶段2.5：多Agent文档评审

Launch a multi-agent review team to validate documentation quality, consistency, and completeness. See

references/review.md

for the full review protocol and agent definitions. If multi-agent spawning isn't available in your environment, run the same checklists sequentially as a self-review.

Review agents:

Agent 1 — Architecture & Spec Reviewer (validates architecture.md completeness)
Agent 2 — Plans & Milestones Reviewer (validates plans.md coverage and ordering)
Agent 3 — Execution Rules & Cross-doc Consistency Reviewer (validates all docs are consistent)

Fix all issues found, then proceed.

启动多Agent评审团队，验证文档的质量、一致性和完整性。完整的评审流程及Agent定义请参见

references/review.md

。如果你的环境不支持多Agent并行运行，请依次执行相同的检查清单进行自我评审。

评审Agent：

Agent 1 — 架构与规格评审者（验证
```
architecture.md
```
的完整性）
Agent 2 — 计划与里程碑评审者（验证
```
plans.md
```
的覆盖范围和排序）
Agent 3 — 执行规则与跨文档一致性评审者（验证所有文档的一致性）

修复所有发现的问题后，继续下一步。

Phase 3: Next Steps

阶段3：后续步骤

After review, tell the user:

The docs are ready at
```
docs/
```
Suggest they review
```
docs/architecture.md
```
and
```
docs/plans.md
```
Explain they can start execution by feeding
```
docs/implement.md
```
as instructions
Mention they can adjust milestone count/scope in
```
docs/plans.md
```
before starting
Emphasize: The final milestone is a Production Readiness Gate — the project is NOT considered complete until it passes all production-readiness checks. Every milestone builds toward a production-grade deliverable, not a demo or prototype.

评审完成后，告知用户：

文档已准备就绪，位于
```
docs/
```
目录
建议他们查看
```
docs/architecture.md
```
和
```
docs/plans.md
```
说明他们可以通过传入
```
docs/implement.md
```
作为指令来启动执行
提及他们可以在启动前调整
```
docs/plans.md
```
中的里程碑数量/范围
重点强调：最终里程碑是Production Readiness Gate — 项目只有通过所有生产就绪检查后才算完成。每个里程碑都朝着生产级交付物推进，而非演示版或原型。

Update Mode (modifying an existing project)

更新模式（修改现有项目）

When mode detection determines Update mode, follow this lighter workflow instead of the full Init flow. See

references/interview.md

§ "Update Mode Interview" for the full protocol.

当模式检测确定为更新模式时，遵循此简化工作流，而非完整的初始化流程。完整流程请参见

references/interview.md

中的“Update Mode Interview”章节。

Update Phase 1: Context Loading

更新阶段1：上下文加载

Read all existing docs:

docs/architecture.md

docs/plans.md

docs/implement.md

docs/secrets.md

docs/documentation.md

Identify: current milestone progress, existing features, tech stack, established patterns
Briefly summarize the project's current state to the user to confirm alignment

读取所有现有文档：

docs/architecture.md

、

docs/plans.md

、

docs/implement.md

、

docs/secrets.md

、

docs/documentation.md

识别：当前里程碑进度、现有功能、技术栈、已确立的模式
向用户简要总结项目的当前状态，以确认对齐

Update Phase 1.5: Update Type Classification

更新阶段1.5：更新类型分类

Ask the user what kind of change they're making, or infer from their description:

Type	When	Interview Rounds	Follow-up Cap
New Feature	Adding new functionality to the project	3-8 rounds (F1-F8)	8-15
Bug Fix	Fixing a bug that may change behavior, architecture, or require doc updates	1-3 rounds (B1-B3)	5
Change	Requirement changes, refactors, tech migrations, removing features	2-5 rounds (C1-C5)	8

Announce the classified type to the user and let them override.

Type reclassification: If during the interview the actual scope significantly exceeds the classified type (e.g., a Bug Fix turns out to require architectural changes, or a Change reveals new feature needs), re-classify the update type, announce the reclassification to the user, and adjust the remaining interview rounds accordingly.

询问用户要进行的变更类型，或从他们的描述中推断：

类型	适用场景	访谈轮次	跟进能力
新增功能	为项目添加新功能	3-8轮（F1-F8）	8-15
Bug修复	修复可能改变行为、架构或需要更新文档的Bug	1-3轮（B1-B3）	5
变更	需求变更、重构、技术迁移、移除功能	2-5轮（C1-C5）	8

向用户宣布分类的类型，并允许其修改。

类型重新分类：如果在访谈过程中发现实际范围显著超出分类类型（例如，Bug修复需要更改架构，或变更涉及新功能需求），重新分类更新类型，告知用户，并相应调整剩余的访谈轮次。

Update Phase 2: Update Interview

更新阶段2：更新访谈

A focused interview scoped to the change (NOT a full project interview). See

references/interview.md

for the full protocol for each update type.

Steps overview:

Description — Ask the user to describe the change in their own words
Clarifying Questions — Rounds and depth determined by update type (see table above)
Synthesis & Confirmation — Present a change summary for user approval

针对变更的聚焦式访谈（而非完整的项目访谈）。每种更新类型的完整流程请参见

references/interview.md

。

步骤概述：

变更描述 — 请用户用自己的话描述变更内容
澄清问题 — 轮次和深度由更新类型决定（见上表）
综合与确认 — 向用户呈现变更摘要以获得批准

Update Phase 3: Update Documentation

更新阶段3：更新文档

After confirmation, update (not recreate) the existing documents. What to update depends on the type:

All types:

```
docs/plans.md
```
— Insert new milestones before the Production Readiness Gate (Milestone PR), not after it. The PR milestone must always remain the final milestone. For Bug Fix, add a fix milestone before PR. Follow the same milestone format. Keep existing milestones intact. Update Milestone PR sub-tasks if the change introduces new production-readiness requirements.
```
docs/documentation.md
```
— Add new milestones to the status section

New Feature:

```
docs/architecture.md
```
— Append new user journeys, pages, components, and product spec sections. Update technical architecture if the feature introduces new patterns or integrations.
```
docs/secrets.md
```
— Update if the feature introduces new secrets or integrations
```
CLAUDE.md
```
+
```
AGENT.md
```
— Update if new commands, structure, or conventions are introduced

Bug Fix:

```
docs/architecture.md
```
— Update only if the fix changes documented behavior or reveals a spec gap. Add a note in the relevant product spec section describing the corrected behavior.
```
docs/plans.md
```
— Record the bug in Implementation Notes

Change:

```
docs/architecture.md
```
— Modify affected sections (user journeys, components, tech architecture, etc.). Mark removed or replaced content clearly — do not silently delete.
```
docs/secrets.md
```
— Update if integrations or secrets change
```
CLAUDE.md
```
+
```
AGENT.md
```
— Update if commands, structure, or conventions change
```
docs/implement.md
```
— Update only if the change alters execution rules (e.g., new tech stack, new workflow)

Do NOT modify:

Existing completed milestone content (unless fixing a discovered inconsistency)
```
docs/implement.md
```
(unless the change genuinely requires new execution rules)

获得批准后，更新（而非重新创建）现有文档。更新内容取决于变更类型：

所有类型通用：

```
docs/plans.md
```
— 在**Production Readiness Gate（PR里程碑）**之前插入新的里程碑，不得在之后插入。PR里程碑必须始终是最后一个里程碑。对于Bug修复，在PR之前添加修复里程碑。遵循相同的里程碑格式。保留现有里程碑不变。如果变更引入了新的生产就绪要求，更新PR里程碑的子任务。
```
docs/documentation.md
```
— 在状态部分添加新里程碑

新增功能：

```
docs/architecture.md
```
— 追加新的用户旅程、页面、组件和产品规格章节。如果功能引入了新的模式或集成，更新技术架构部分。
```
docs/secrets.md
```
— 如果功能引入了新的密钥或集成，进行更新
```
CLAUDE.md
```
+
```
AGENT.md
```
— 如果引入了新的命令、结构或约定，进行更新

Bug修复：

```
docs/architecture.md
```
— 仅当修复更改了文档中记录的行为或暴露了规格缺口时才更新。在相关产品规格章节中添加说明，描述修正后的行为。
```
docs/plans.md
```
— 在实现说明中记录该Bug

变更：

```
docs/architecture.md
```
— 修改受影响的章节（用户旅程、组件、技术架构等）。清晰标记已移除或替换的内容 — 不得静默删除。
```
docs/secrets.md
```
— 如果集成或密钥发生变化，进行更新
```
CLAUDE.md
```
+
```
AGENT.md
```
— 如果命令、结构或约定发生变化，进行更新
```
docs/implement.md
```
— 仅当变更改变了执行规则（例如新的技术栈、新的工作流）时才更新

禁止修改：

已完成的现有里程碑内容（除非发现不一致需要修复）
```
docs/implement.md
```
（除非变更确实需要新的执行规则）

Update Phase 3.5: Documentation Review

更新阶段3.5：文档评审

Run a lighter review focused on the changes. See

references/review.md

for full checklist details.

Use Agent 2 (Plans reviewer) + Agent 3 (Consistency reviewer). Skip Agent 1 unless the change adds entirely new user roles or major architectural changes.

Focus areas:

Agent 2: Verify new/modified milestones cover all aspects of the change; new milestones are inserted before Milestone PR; milestone ordering is logical
Agent 3: Verify no contradictions between new and existing content; updated architecture sections are consistent; CLAUDE.md/AGENT.md are updated if needed

针对变更内容进行简化评审。完整的检查清单详情请参见

references/review.md

。

使用Agent 2（计划评审者） + Agent 3（一致性评审者）。除非变更添加了全新的用户角色或重大架构变更，否则跳过Agent 1。

重点关注领域：

Agent 2：验证新增/修改的里程碑是否覆盖了变更的所有方面；新里程碑是否插入在PR里程碑之前；里程碑排序是否合理
Agent 3：验证新内容与现有内容之间是否存在矛盾；更新后的架构章节是否一致；
```
CLAUDE.md
```
/
```
AGENT.md
```
是否已按需更新

Update Phase 4: Next Steps

更新阶段4：后续步骤

Tell the user:

The docs have been updated
Summarize what was changed (new/modified milestones, updated architecture sections, etc.)
Suggest they review the changes in
```
docs/architecture.md
```
and
```
docs/plans.md
```
Mention they can adjust the new milestones before starting execution
Remind: New milestones follow the same production-quality standard — every sub-task produces deployment-ready code. If the update adds significant new functionality, ensure the Production Readiness Gate milestone is updated to cover the new scope.

告知用户：

文档已更新
总结变更内容（新增/修改的里程碑、更新的架构章节等）
建议他们查看
```
docs/architecture.md
```
和
```
docs/plans.md
```
中的变更
提及他们可以在启动执行前调整新里程碑
提醒：新里程碑遵循相同的生产质量标准 — 每个子任务都生成可部署的代码。如果更新添加了重要的新功能，确保Production Readiness Gate里程碑已更新以覆盖新范围。

Language

语言设置

Follow the user's language preference. If they write in Chinese, generate documents in Chinese. If they write in English, generate in English. Technical terms (file names, commands, code) stay in English regardless.

遵循用户的语言偏好。如果用户使用中文，生成中文文档；如果用户使用英文，生成英文文档。无论使用哪种语言，技术术语（文件名、命令、代码）均保留英文。