# New Plan

> Create a new plan directory (P{NNN}-{slug}/) through an interactive, approval-gated document pipeline. Use when starting a new feature, bugfix effort, or architectural change — any work that needs structured tracking across multiple sessions.

- **Type:** Skill
- **Install:** `agentstack add skill-testfree2023-airein-new-plan`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [testfree2023](https://agentstack.voostack.com/s/testfree2023)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [testfree2023](https://github.com/testfree2023)
- **Source:** https://github.com/testfree2023/airein/tree/main/skills/new-plan
- **Website:** https://github.com/testfree2023/airein#readme

## Install

```sh
agentstack add skill-testfree2023-airein-new-plan
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Create New Plan

**CRITICAL: This skill is the planning workflow. Do NOT call Claude Code `EnterPlanMode` or `ExitPlanMode`. Do NOT use built-in plan mode. Create files directly under `docs/plans/P{NNN}-{slug}/` following this document pipeline.**

Create a new plan directory and register it in the roadmap. The process is interactive: first complete a unified communication/brainstorming phase, then create each configured document one at a time with approval between documents.

## Global template root (P004 — kernel only)

Airein **global** templates live in the install **kernel**, not under `~/.claude/`:

| Asset | Path |
|-------|------|
| Pipeline definitions | `~/.airein/templates/pipelines.json` |
| Doc structure templates | `~/.airein/templates/docs/{doc-type}.md` |
| Design tier templates | `~/.airein/templates/docs/design/{s\|m\|l}.md` |
| Design sub-doc templates | `~/.airein/templates/docs/design-*/` |
| Language profiles | `~/.airein/templates/language-profiles/{lang}.json` |
| Default quality.json | `~/.airein/templates/quality.json` |

**Do not** read `~/.claude/templates/` — that path is legacy / absent after P004 unified install. Hooks and lib code resolve templates from the kernel (`~/.airein/`).

Project config: `.airein/config/quality.json` (legacy fallback: `.claude/config/quality.json`).

## Phase 0: Context Gathering (l-feature / l-bugfix only)

For complex features, gather project intelligence before the communication phase:

1. **Read steering docs**: `docs/steering/product.md`, `docs/steering/tech.md`, `docs/steering/structure.md`
2. **Read lessons learned**: `docs/plans/*/progress.md` (Blockers section), `docs/roadmap.md` (## Issues section)
3. **Scan codebase**: Identify reusable modules and existing patterns

→ Output: Context Brief (embedded into the first document that needs it, usually `requirements.md`)

## Phase 1: Communication / Grilling / Brainstorming

Before creating any requirements/design/tasks document, align with the user through structured Q&A. This phase is the same role as `/openspec-explore`: clarify intent, challenge assumptions, and turn vague requests into concrete scope.

**Rules:**
- Ask **one question at a time**, wait for the user's answer before continuing
- If a question can be answered by exploring the codebase → explore instead of asking
- When a term conflicts with steering docs → call it out immediately
- When the user uses vague terms → propose a precise term
- When the user states how something works → check whether code agrees; surface contradictions
- Use concrete scenarios to stress-test: invent edge cases that force precise boundaries
- Only skip discussion if the user explicitly says to skip discussion / 跳过讨论

**Questions to resolve:**
1. What is the desired outcome? (Goal)
2. What triggers this? (Trigger — new feature, bug, requirement change?)
3. Priority? (P1=critical, P2=high, P3=medium, P4=low)
4. What tests will verify success? (Success Criteria)
5. Any related plans or issues? (Related)
6. What is the scope boundary? (What is NOT in scope)

**Progress state:**
- When creating `progress.md`, set `grilling: in_progress`
- After discussion is complete, update `progress.md` to `grilling: completed`
- Continue to create the first pipeline document after grilling completes (no mandatory pause between grilling and document creation)

**Complexity determination:**
- Read `quality.json` → `planWorkflow.pipeline` to get the pipeline name
- Read `~/.airein/templates/pipelines.json` → `definitions.{pipeline}` to get the doc list
- If `pipeline` is `"auto"` or missing, determine from project size and scenario
- The `complexity` field in `progress.md` should be the pipeline name (e.g. `m-feature`), not `simple/medium/complex`
- The `## Approval State` section must have one entry per pipeline doc
- Default pipelines (auto mode only, resolves to `m-feature`):
  - **s-feature**: `requirements`, `tasks` — 小型项目新功能
  - **s-bugfix**: `tasks` — 小型项目缺陷修复
  - **m-feature**: `requirements`, `design`, `test-plan`, `tasks` — 中型项目新功能（默认）
  - **m-bugfix**: `requirements`, `tasks` — 中型项目缺陷修复
  - **m-urgent**: `tasks` — 中型项目紧急需求
  - **l-feature**: `requirements`, `design`, `test-plan`, `deployment`, `tasks` — 大型项目新功能
  - **l-bugfix**: `requirements`, `design`, `test-plan`, `tasks` — 大型项目缺陷修复
  - **hotfix**: `tasks` — 紧急修复（不限规模）

**⚠️ IMPORTANT**: Before writing `progress.md`, you MUST read both `quality.json` and `~/.airein/templates/pipelines.json` to determine the correct pipeline and approval keys. Never hardcode approval states.

## Phase 2: Create Plan Directory + progress.md

1. Determine the next plan ID from existing directories in `docs/plans/`
2. Create directory: `docs/plans/P{NNN}-{slug}/`
3. Create `progress.md` only at first, with `grilling: in_progress`
4. Append the plan entry to `docs/roadmap.md` active section
5. Add an entry to `docs/roadmap.md` ## Recent Changes section
6. Complete Phase 1 communication; then set `grilling: completed`

## Phase 3: Configured Document Pipeline

Read `quality.json` → `planWorkflow.pipelines.{complexity}` and create documents in that exact order.

**Mandatory document approval sequence (file-based, NOT Claude Code Plan Mode):**
1. Create only the next document in the pipeline
2. Mark its approval state as `draft` in `progress.md`
3. Present it to the user for approval
4. Wait for approval-guard / user approval
5. After approval, update that document's approval state to `approved` in `progress.md`, and set the phase doc footer `## Status: approved` (replacing `draft`)
6. Only then create the next document

Examples:
- `medium`: create `requirements.md` → approval → create `tasks.md`
- `complex`: create `requirements.md` → approval → create `design.md` → approval → create `tasks.md`
- custom: if `planWorkflow.pipelines.complex = ["requirements", "tasks", "test-plan"]`, follow that order

## Design Documents: Establishing vs Referencing

When the pipeline includes a `design` document, determine whether this plan
**establishes** or **references** the project's design docs. Run the resolver:

```bash
node ~/.airein/scripts/lib/design-doc-resolver.js
```

It checks two locations for existing project-level design docs and prints JSON:
- **Archived** (project-level, stable): `docs/conventions.md`, `docs/architecture.md`
- **In-flight plans**: `docs/plans/{plan}/design-conventions.md`, `design-architecture.md`

Output: `{ establishing: bool, conventions: {exists, path, source}, architecture: {exists, path, source}, deployment: {exists, path, source} }`.

### establishing: true (no project-level design docs anywhere)

This is the **first design-bearing plan** for the project. Generate BOTH:
- `design-architecture.md` — from `~/.airein/templates/docs/design-architecture/{lang}.md`
- `design-conventions.md` — from `~/.airein/templates/docs/design-conventions/{lang}.md`
- `design.md` — from `resolveDesignTemplate` tier template; indexes them via a `## Sub-documents` section

**Regardless of complexity tier** (s/m/l) and **regardless of frontend-or-backend**.
Even a pure-frontend project has architecture — use the nearest language template
(JS frontend → `typescript.md` fallback), or write free-form if no template matches.

> **Conventions lifecycle (P018)**: `design-conventions.md` lives in the plan
> directory during development. At archive time, the `archive-plan` skill
> migrates it to `docs/conventions-{lang}.md` (single source of truth) and
> generates the thin-shell `.claude/rules/conventions-{lang}.md` — a CC native
> conditional rule that auto-injects conventions when editing matching source
> files (replaces the deleted `conventions-trigger` hook). `{lang}` is the
> `design-conventions` template's language token (`javascript`/`typescript`/
> `python`/`go`/`rust`/`java`/`kotlin`/`bash`).

### establishing: false (project-level design docs already exist)

This is a **subsequent plan**. Generate a unified `design.md` ONLY (from the matching
tier template), with a section that LINKS to the existing conventions/architecture
(use the resolver's reported paths). Do NOT regenerate `design-conventions.md` / `design-architecture.md`.

### Exception: architecture upgrade

If the user declares an architecture upgrade (e.g. "重构架构", "迁移到 X"), this
plan may UPDATE the existing `design-architecture.md` / `design-conventions.md`.
Prompt the user to confirm the overwrite before regenerating.

> Module sub-documents (`design-domain-model.md`, `design-database.md`,
> `design-security.md`, `design-deployment.md`) remain l-feature-driven — see
> Compound Documents below.

## Deployment Step (l-feature only)

When the pipeline includes `deployment` (l-feature only), run the resolver to get
`deployment.exists` and follow one of three paths:

### establishing: deployment.exists === false

This is the **first deployment-bearing plan** for the project. Generate `deployment.md`
from `~/.airein/templates/docs/deployment.md`. At archive time, `archive-plan` migrates it to
`docs/deployment.md` (single source of truth).

### referencing: deployment.exists === true (no deployment change signal)

A deployment doc already exists (archived `docs/deployment.md` or in-flight plan).
Do NOT regenerate `deployment.md`. Instead, LINK to the existing deployment doc in the
plan's `design.md` (use resolver's `deployment.path` for the link).

### Exception: deployment upgrade

If the user declares a deployment change (e.g. "迁移到 k8s", "换 CI-CD", "新增环境",
"改部署目标", "改运行时"), this plan may UPDATE the existing `docs/deployment.md`.
Prompt the user to confirm the overwrite before regenerating. Zero silent false positives.

## Tasks Step（全生命周期 · 可执行可验收）

`tasks.md` 不是「开发任务清单」，而是本计划在**软件开发生命周期**上的工作分解：**Implement / Verify / Deploy / Accept** 凡计划涉及的，都必须拆成**可执行、可验收**的任务（有命令或逐步操作 + 可观察断言）。

Every generated `tasks.md` follows `~/.airein/templates/docs/tasks.md`.

### Mandatory structures

1. **Global Constraints** — version floors, dependency limits, naming, exact values. Bind ALL tasks.
2. **Traceability Index** — UC / Critical / VS / INV → task IDs（上游规格总表；供 Coverage Gate）.
3. **Entry Coverage** — PRD Story→UC + 入口；每行 ≥1 Must Implement. **禁止**入口降为 Should；**禁止**「前端收口」.
4. **Lifecycle Phases** — Implement / Verify / Deploy / Accept; Kind: `implement` | `verify` | `deploy` | `accept`（**每条任务 Kind 必填**；仅 implement 强制 `tests.md`）.
5. **per-task Interfaces** — `consume` / `produce`.
6. **Implement fields** — `UC-id`, **Design refs**（API / 表|模型 / INV- / DD）, Persona, UI Entry, dual Acceptance.
7. **Verify fields** — **Source**（Critical- | VS-{UC}-{维} | Exit- | INV- | PRD-UC-）必填；**禁止无源**；`Ledger:` 可选指向 Implement 台账行（Verify **不**强制 `tests.md` 行）.
8. **Coverage Gate** — every UC + Critical（及关键 VS）mapped；自检清单保留在 tasks.md.

### Slicing rules（vertical only for product capabilities）

- Prefer **角色能力垂直片**（例：销售代报修 = 菜单权限 + FAB 入口 + 表单页 + API + 来源枚举），not 全后端做完再「前端收口」。
- Horizontal layering (DDL → 全 API → 最后 UI) is allowed only for pure infra with **no** persona UI; product 入口任务仍须 early Must.
- Each task Acceptance must be **可执行**（命令或逐步操作）and **可验收**（可观察结果）. Role-entry tasks MUST assert「用该 Persona 登录后入口可见/可点」.

### Test Plan = 测试策略（Critical + VS）

When the pipeline includes `test-plan`, resolve the tier template before writing `test-plan.md`:

```js
const { resolveTestPlanTemplate } = require('…/scripts/lib/test-plan-template.js');
resolveTestPlanTemplate('m-feature');
// → { applicable: true, tier: 'm', relativePath: 'templates/docs/test-plan/m.md', fallback: false }
```

| Pipeline | Template |
|----------|----------|
| `m-feature`（及含 test-plan 的 m-*） | `templates/docs/test-plan/m.md` — Critical + **关键 UC** 轻量 VS |
| `l-feature` / `l-bugfix` | `templates/docs/test-plan/l.md` — 全量 VS + Invariants + Data Strategy |
| `s-*` / `m-bugfix`（pipeline 无 test-plan） | 不适用；Verify 从 PRD UC 生成 |

**精炼 ≠ 稀疏**：m 不必七维全表，但资金/一致性 UC 仍须可证伪断言。

### Verify tasks（from test-plan or PRD AC）

When `test-plan.md` exists (m-feature / l-* pipelines), parse in this order (m: Critical + key-UC VS; l: full VS + invariants):

1. **Critical Acceptance Index**（产品级门禁索引，一行一路径）— **一行一个 Persona**；勿合并「销售/门店」。UI 行：步骤从**入口**起（打开页 → 见控件 → 动作）。每行 → `Kind: verify` 任务 `验收测试：{id} · {persona} · {behavior}`。
2. **Verification Specs by UC（VS-{UC-id}）** — test-plan **本体**（场景穷举 + 不变量断言 + 数据矩阵）。资金/一致性 UC 的主成功/扩展/异常/边界/并发/幂等/降级各维，凡有可跑命令或夹具的，拆成或挂靠 Verify 任务；禁止只生成 Critical 主路径而丢掉 VS 穷举。
3. **Invariant Verification Specs** + **Exit Criteria** → `Kind: verify` / `accept`（覆盖率、不变量、缺陷门禁等）。Exit 须绑「可执行命令 + pass 输出」。

**精炼 ≠ 稀疏**：禁止把 TC 逐步操作抄进 Markdown（真相在测试代码）；但场景维度/断言规格/数据矩阵必须穷尽——只填 Critical Index 不填 VS = 验收规格不完整。

If `test-plan.md` is absent or only has Critical Index without VS: **still** generate Verify tasks from PRD **Use Case** 主成功/扩展（及 Traceability 表）— do **not** ship Implement-only `tasks.md`. Cite **UC-id** in task titles/Acceptance.

### Deploy tasks（from deployment.md / runbook）

When `deployment.md` exists (or design links a project `docs/deployment.md`), generate **Kind: deploy** Must tasks: migrations, rollouts, config flags, smoke after deploy, rollback path. Acceptance = executable runbook step + observable env result.

If the pipeline has no deployment doc and the change is docs/skill-only with nothing to ship, write `Deploy: n/a — {reason}` once under Lifecycle Phases — do not invent fake deploys.

### Accept tasks

PRD §交付物（菜单角色初始化、培训要点、验收报告）→ `Kind: accept` tasks when they are product obligations, not optional notes.

### Anti-patterns（P099-class failures）

| 反模式 | 正确做法 |
|--------|----------|
| 多角色入口合并成「E 前端收口」 | Entry Coverage 每角色一行 + 垂直片 |
| 销售/门店 UI 标 Should，仅 E.1 挡归档 | 入口行一律 Must |
| Critical Path「三角色发起」一行 | 客服 / 销售 / 门店 分三条 verify |
| 只有 API/UT，无 Persona 登录断言 | Acceptance 含入口可见 |
| tasks 只有实现、测试/部署写在别处口头说 | Verify / Deploy 必须落在 tasks.md |
| Verify 无 Source / 只拆 Critical 丢 VS | Source 必填；VS 可跑维须有 Verify |
| Implement 不回指 Design 契约 | 填写 Design refs（API / INV / DD） |

## File Templates

Read structural templates from `~/.airein/templates/docs/{doc-type}.md` for guidance on document structure. Fill each document with plan-specific content based on the communication phase output.

### Requirements = 产品需求说明书（PRD）

When the pipeline includes `requirements`, the plan file is still named `requirements.md`, but content MUST be a **产品需求说明书（PRD）**, not a thin summary of Problem + WHEN/THEN.

**Agent Teams v0:** Check `quality.json` → **`pipelineRoles.enabled`** (default `true`).

- **`true`:** Before writing `requirements.md`, dispatch **`product-expert`** (`agents/product-expert.md`) to author the PRD + lightweight prototype per the requirements template. PM (`agents/pm.md`) only orchestrates and presents for approval — do not solo-author the full PRD unless the user explicitly exempts and Notes record it. **Before writing `design.md`**, prefer dispatch **`tech-lead`** with **mode: design** (template-aligned).
- **`false` (Solo PM):** PM may author `requirements.md` / `design.md` directly (still template-aligned). No Notes exemption required for skipping specialists.

**Before writing `requirements.md`**, resolve the tier template via the kernel lib (after sync: `~/.airein/scripts/lib/requirements-template.js`; in-repo: `scripts/lib/requirements-template.js`):

```js
const { resolveRequirementsTemplate } = require('…/scripts/lib/requirements-template.js');
resolveRequirementsTemplate('m-feature');
// → { applicable: true, tier: 'm', relativePath: 'templates/docs/requirements/m.md', fallback: false }
```

Then read `~/.airein/{relativePath}` (or the in-repo `templates/docs/requirements/{s|m|l}.md`) and fill the plan file.

| Pipeline prefix | Template |
|-----------------|----------|
| `s-*` (and docs include requirements) | `templates/docs/requirements/s.md` |
| `m-*` | `templates/docs/requirements/m.md` |
| `l-*` | `templates/docs/requirements/l.md` |
| Custom name with requirements step | **m.md** (`fallback: true`) |
| Docs omit requirements (e.g. `s-bugfix`, `hotfix`) | skip — do not create requirements |

**PRD structur

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [testfree2023](https://github.com/testfree2023)
- **Source:** [testfree2023/airein](https://github.com/testfree2023/airein)
- **License:** Apache-2.0
- **Homepage:** https://github.com/testfree2023/airein#readme

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-testfree2023-airein-new-plan
- Seller: https://agentstack.voostack.com/s/testfree2023
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.