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)

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.

Mode Detection

At the start, detect which mode to use:

1. Check if docs/architecture.md and docs/plans.md already exist in the project
2. If both exist → Update mode (the project was previously initialized with this skill)
3. If neither exists → Init mode (new project)
4. 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?
5. If ambiguous for other reasons, ask the user whether they are modifying the existing project or starting fresh

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.

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

Workflow

Phase 1: Interactive Interview

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:

1. Project Name — Ask the user for the project name
2. Project Goals — Free-form description of what they're building, the problem, and target users
3. 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).
4. 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.
5. Synthesis & Confirmation — Present a complete project summary for user approval before generating docs

Phase 2: Generate Documentation

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)

Phase 2.5: Multi-Agent Documentation Review

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.

Phase 3: Next Steps

After review, tell the user:

1. The docs are ready at docs/
2. Suggest they review docs/architecture.md and docs/plans.md
3. Explain they can start execution by feeding docs/implement.md as instructions
4. Mention they can adjust milestone count/scope in docs/plans.md before starting
5. 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.

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.

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
2. Identify: current milestone progress, existing features, tech stack, established patterns
3. Briefly summarize the project's current state to the user to confirm alignment

Update Phase 1.5: Update Type Classification

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

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.

Update Phase 2: Update Interview

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:

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

Update Phase 3: Update Documentation

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)

Update Phase 3.5: Documentation Review

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

Update Phase 4: Next Steps

Tell the user:

1. The docs have been updated
2. Summarize what was changed (new/modified milestones, updated architecture sections, etc.)
3. Suggest they review the changes in docs/architecture.md and docs/plans.md
4. Mention they can adjust the new milestones before starting execution
5. 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.

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.