@xulthekl/team-flow 0.22.4

package/skills/ce-strategy/references/strategy-template.md

@@ -0,0 +1,89 @@
+# Strategy Template
+
+Loaded by `SKILL.md` after the interview is complete. Fill it in using the captured answers and write to `STRATEGY.md`.
+
+## Rules for filling in
+
+- Use the user's own language where possible. Do not paraphrase into generic PM-speak.
+- Each section stays compact. The whole doc should read in under 5 minutes.
+- Section order is locked. Do not add new top-level sections.
+- Optional sections: delete entirely if unused. Do not leave empty headers.
+- Set `last_updated` in the YAML frontmatter to today's ISO date (YYYY-MM-DD). Do not duplicate the date in prose.
+- Set `name` in the frontmatter to the product or initiative name (the same value used in the H1 title).
+
+## Template
+
+The block below is the literal file to write (minus this line and the fences). Replace every `{{placeholder}}` with the captured answer. Delete any optional section whose placeholder wasn't answered.
+
+~~~markdown
+---
+name: {{product_name}}
+last_updated: {{YYYY-MM-DD}}
+---
+
+# {{product_name}} Strategy
+
+## Target problem
+
+{{1-2 sentence diagnosis. Names the user situation and the crux that makes it hard. No solution language.}}
+
+## Our approach
+
+{{1-2 sentence guiding policy. What this product commits to, so that the target problem becomes tractable.}}
+
+## Who it's for
+
+**Primary:** {{Persona name}} - {{one-sentence JTBD, e.g. "They're hiring {{product_name}} to..."}}
+
+<!-- Duplicate the block above for additional personas only if truly necessary. Fewer is better. -->
+
+## Key metrics
+
+- **{{metric 1 name}}** - {{one-line definition; where it's measured}}
+- **{{metric 2 name}}** - {{...}}
+- **{{metric 3 name}}** - {{...}}
+
+<!-- 3-5 total. Stop at 5. -->
+
+## Tracks
+
+### {{Track 1 name}}
+
+{{One line: what this track is - the investment area, not a feature list.}}
+
+_Why it serves the approach:_ {{one line}}
+
+<!-- Duplicate the block above for 2-4 tracks total. If you can't keep it to 4, something is wrong - fold related tracks together. -->
+
+## Milestones
+
+- **{{YYYY-MM-DD}}** - {{milestone}}
+
+<!-- Optional. Delete the section if unused. Only externally visible milestones: launches, fundraises, conferences, renewals. -->
+
+## Not working on
+
+- {{one line per item}}
+
+<!-- Optional. Delete the section if unused. Use only for things the team keeps being tempted by. -->
+
+## Marketing
+
+**One-liner:** {{single-sentence pitch}}
+
+**Key message:** {{2-3 lines if useful}}
+
+<!-- Optional. Delete the section if unused. -->
+~~~
+
+## Post-write checklist
+
+Before confirming the write, scan the draft for:
+
+- [ ] Frontmatter present at the top with `name` and `last_updated` keys.
+- [ ] `last_updated` carries today's date in ISO format (YYYY-MM-DD).
+- [ ] No section has more than 4 sentences except Tracks (where each track has its own short block).
+- [ ] No placeholders remain (`{{...}}`).
+- [ ] Optional sections with no content have been deleted, not left empty.
+- [ ] Metric count is between 3 and 5. Track count is between 2 and 4.
+- [ ] Target problem and Our approach are connected - one clearly responds to the other.

package/skills/code-reviewer/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: code-reviewer
+description: Review completed implementation batches for spec compliance and code quality. Invoke after execution batches complete, before merging, or when a review gate is reached in the workflow.
+---
+
+# Code Reviewer
+
+Two responsibilities: requesting review (dispatching a reviewer subagent) and receiving review (acting on feedback with technical rigor). **Review early, review often. Verify before implementing feedback.**
+
+## Part 1: Requesting Review
+
+**Mandatory after**: each task in SDD, each planned execution wave, each major feature, before merge.
+**Optional**: when stuck, before refactoring, after fixing complex bugs.
+
+### Procedure
+1. Get SHAs: `BASE_SHA=$(git rev-parse HEAD~1)` and `HEAD_SHA=$(git rev-parse HEAD)`
+2. Dispatch `general-purpose` subagent using template at `skills/code-reviewer/code-reviewer-prompt.md`
+3. Fill placeholders: `[DESCRIPTION]` (what was built), `[PLAN_OR_REQUIREMENTS]` (contract/spec reference), `[BASE_SHA]`, `[HEAD_SHA]`, `[WAVE_ID]`, and a distinct `[REVIEW_REPORT_FILE]`.
+4. Require the reviewer to write a non-empty persisted review report at `[REVIEW_REPORT_FILE]`, then record that exact path in the wave receipt: `npx --yes --package @xulthekl/team-flow@0.22.4 tf execution review <change-dir> --wave <id> --base <sha> --head <sha> --report <review-report-path> --verdict <pass|fail>`.
+5. Act on feedback: Critical/Important findings require a `fail` receipt, focused repair, re-review, and replacement `pass` receipt before a dependent wave or closing can proceed. Note Minor for later, push back with reasoning if reviewer is wrong.
+
+### Minimality And Scope
+
+For unrequested complexity, cite the missing task requirement and diff line.
+Use Important for merge-blocking complexity and Minor for safe,
+behavior-neutral redundancy; never score by line count.
+
+## Part 2: Receiving Review Feedback
+
+### The Response Pattern
+1. READ feedback without reacting
+2. UNDERSTAND and restate requirement
+3. VERIFY against codebase reality
+4. EVALUATE: technically sound for THIS codebase?
+5. RESPOND: technical acknowledgment or reasoned pushback
+6. IMPLEMENT: one item at a time, test each
+
+### Severity Levels
+
+| Level | Meaning | Action |
+|-------|---------|--------|
+| Critical | Bugs, security, data loss, broken functionality | Fix immediately |
+| Important | Architecture problems, missing features, poor error handling, test gaps | Fix before next batch |
+| Minor | Code style, optimization, documentation polish | Note for later |
+
+### Forbidden Responses
+Never: performative agreement ("You're right!", "Great point!"), blind implementation before verification, thanking the reviewer. Instead: restate the requirement, ask clarifying questions, push back with reasoning, or just fix it (actions > words).
+
+### Handling Unclear Feedback
+If any item is unclear → STOP. Do not implement anything yet. Ask for clarification on unclear items. Partial understanding = wrong implementation.
+
+### Source-Specific Rules
+
+**From user**: Trusted — implement after understanding. Still ask if scope unclear. No performative agreement.
+
+**From external reviewer**: Before implementing, check: technically correct for this codebase? breaks existing functionality? reason for current implementation? works on all platforms? reviewer understands full context? If suggestion seems wrong, push back with technical reasoning.
+
+### When to Push Back
+Suggestion breaks existing functionality, reviewer lacks context, violates YAGNI, technically incorrect for this stack, legacy/compatibility reasons, conflicts with user's architectural decisions. Push back with technical reasoning, not defensiveness.
+
+### Implementation Order
+1. Clarify unclear items first
+2. Fix blocking issues (breaks, security)
+3. Fix simple issues (typos, imports)
+4. Fix complex issues (refactoring, logic)
+5. Test each fix individually, verify no regressions
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Performative agreement | State requirement or just act |
+| Blind implementation | Verify against codebase first |
+| Batch without testing | One at a time, test each |
+| Proceeding without a wave receipt | Record `pass`/`fail` via `npx --yes --package @xulthekl/team-flow@0.22.4 tf execution review` before the next dependent wave |
+| Assuming reviewer is right | Check if breaks things |
+| Avoiding pushback | Technical correctness > comfort |
+| Partial implementation | Clarify all items first |
+
+## Exception Handling
+
+- **Parse failures**: Report specific file, request regenerated review package
+- **Missing files**: Regenerate via `scripts/review-package`. Empty diff = nothing to review
+- **User interruption**: Re-read review report on resume, continue from next unreviewed batch

package/skills/code-reviewer/code-reviewer-prompt.md

@@ -0,0 +1,195 @@
+# Code Reviewer Prompt Template
+
+Use this template when dispatching a code reviewer subagent.
+
+**Purpose:** Review completed work against requirements and code quality standards before it cascades into more work.
+
+```
+Subagent (general-purpose):
+  description: "Review code changes"
+  prompt: |
+    You are a Senior Code Reviewer with expertise in software architecture,
+    design patterns, and best practices. Your job is to review completed work
+    against its plan or requirements and identify issues before they cascade.
+
+    ## What Was Implemented
+
+    [DESCRIPTION]
+
+    ## Requirements / Plan
+
+    [PLAN_OR_REQUIREMENTS]
+
+    ## Git Range to Review
+
+    **Base:** [BASE_SHA]
+    **Head:** [HEAD_SHA]
+
+    **Planned wave ID:** [WAVE_ID]
+
+    ```bash
+    git diff --stat [BASE_SHA]..[HEAD_SHA]
+    git diff [BASE_SHA]..[HEAD_SHA]
+    ```
+
+    ## Read-Only Review
+
+    Your review is read-only on this checkout. Do not mutate the working tree, the index, HEAD, or branch state in any way. Use tools like `git show`, `git diff`, and `git log` to inspect history. If you need a working copy of a different revision, check it out into a separate temporary directory (e.g. `git worktree add /tmp/review-[SHA] [SHA]`) — never move HEAD on this checkout.
+
+    ## What to Check
+
+    **Spec/Contract alignment:**
+    - Does the implementation match the spec / execution contract requirements?
+    - Are deviations justified improvements, or problematic departures?
+    - Is all planned functionality present?
+
+    ## Minimality And Scope
+
+    For every unrequested dependency, configuration surface, abstraction, or unrelated refactor, cite the missing task requirement and diff line. Treat
+    merge-blocking complexity as Important and behavior-neutral redundancy as Minor. Do not use line count as evidence, and do not recommend removing
+    required tests, validation, security, or error handling.
+
+    **Code quality:**
+    - Clean separation of concerns?
+    - Proper error handling?
+    - Type safety where applicable?
+    - DRY without premature abstraction?
+    - Edge cases handled?
+
+    **Architecture:**
+    - Sound design decisions?
+    - Reasonable scalability and performance?
+    - Security concerns?
+    - Integrates cleanly with surrounding code?
+
+    **Testing:**
+    - Tests verify real behavior, not mocks?
+    - Edge cases covered?
+    - Integration tests where they matter?
+    - All tests passing?
+
+    **Production readiness:**
+    - Migration strategy if schema changed?
+    - Backward compatibility considered?
+    - Documentation complete?
+    - No obvious bugs?
+
+    ## Calibration
+
+    Categorize issues by actual severity. Not everything is Critical.
+    Acknowledge what was done well before listing issues — accurate praise
+    helps the implementer trust the rest of the feedback.
+
+    If you find significant deviations from the plan, flag them specifically
+    so the implementer can confirm whether the deviation was intentional.
+    If you find issues with the plan itself rather than the implementation,
+    say so.
+
+    ## Output Format
+
+    Write your full verdict to [REVIEW_REPORT_FILE]. This review report path
+    must point to a non-empty, persisted review report before the controller
+    records a receipt. Include the wave ID, base SHA, head SHA, and that review
+    report path. End with the exact receipt command:
+
+    ```bash
+    npx --yes --package @xulthekl/team-flow@0.22.4 tf execution review <change-dir> --wave [WAVE_ID] --base [BASE_SHA] --head [HEAD_SHA] --report [REVIEW_REPORT_FILE] --verdict <pass|fail>
+    ```
+
+    Use `fail` when any Critical or Important finding remains. A repair needs
+    a fresh review and replacement `pass` receipt before any dependent wave or
+    closing transition.
+
+    ### Strengths
+    [What's well done? Be specific.]
+
+    ### Issues
+
+    #### Critical (Must Fix)
+    [Bugs, security issues, data loss risks, broken functionality]
+
+    #### Important (Should Fix)
+    [Architecture problems, missing features, poor error handling, test gaps]
+
+    #### Minor (Nice to Have)
+    [Code style, optimization opportunities, documentation polish]
+
+    For each issue:
+    - File:line reference
+    - What's wrong
+    - Why it matters
+    - How to fix (if not obvious)
+
+    ### Recommendations
+    [Improvements for code quality, architecture, or process]
+
+    ### Assessment
+
+    **Ready to merge?** [Yes | No | With fixes]
+
+    **Reasoning:** [1-2 sentence technical assessment]
+
+    ## Critical Rules
+
+    **DO:**
+    - Categorize by actual severity
+    - Be specific (file:line, not vague)
+    - Explain WHY each issue matters
+    - Acknowledge strengths
+    - Give a clear verdict
+
+    **DON'T:**
+    - Say "looks good" without checking
+    - Mark nitpicks as Critical
+    - Give feedback on code you didn't actually read
+    - Be vague ("improve error handling")
+    - Avoid giving a clear verdict
+```
+
+**Placeholders:**
+- `[DESCRIPTION]` — brief summary of what was built
+- `[PLAN_OR_REQUIREMENTS]` — what it should do (execution-contract.md file path, spec file path, or requirements)
+- `[BASE_SHA]` — starting commit
+- `[HEAD_SHA]` — ending commit
+- `[WAVE_ID]` — planned execution wave under review
+- `[REVIEW_REPORT_FILE]` — REQUIRED: distinct, persisted, non-empty review report path stored in the execution receipt
+
+**Reviewer returns:** Strengths, Issues (Critical / Important / Minor), Recommendations, Assessment
+
+## Example Output
+
+```
+### Strengths
+- Clean database schema with proper migrations (db.ts:15-42)
+- Comprehensive test coverage (18 tests, all edge cases)
+- Good error handling with fallbacks (summarizer.ts:85-92)
+
+### Issues
+
+#### Important
+1. **Missing help text in CLI wrapper**
+   - File: index-conversations:1-31
+   - Issue: No --help flag, users won't discover --concurrency
+   - Fix: Add --help case with usage examples
+
+2. **Date validation missing**
+   - File: search.ts:25-27
+   - Issue: Invalid dates silently return no results
+   - Fix: Validate ISO format, throw error with example
+
+#### Minor
+1. **Progress indicators**
+   - File: indexer.ts:130
+   - Issue: No "X of Y" counter for long operations
+   - Impact: Users don't know how long to wait
+
+### Recommendations
+- Add progress reporting for user experience
+- Consider config file for excluded projects (portability)
+
+### Assessment
+
+**Ready to merge: With fixes**
+
+**Reasoning:** Core implementation is solid with good architecture and tests. Important issues (help text, date validation) are easily fixed and don't affect core functionality.
+```

package/skills/contract-builder/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: contract-builder
+description: Convert approved planning artifacts into an execution contract. Invoke when the user wants to start building, asks to move from planning to implementation, or when execution-contract.md is missing or stale.
+---
+
+# Contract Builder
+
+Converts planning artifacts into a single execution handshake: `execution-contract.md`. Load the baseline with `npx --yes --package @xulthekl/team-flow@0.22.4 tf runtime asset read templates/execution-contract.md`.
+
+Read before generating: `proposal.md`, `specs/`, `design.md`, `tasks.md`, then load `docs/artifact-contract.md` with `npx --yes --package @xulthekl/team-flow@0.22.4 tf runtime asset read docs/artifact-contract.md`.
+
+**Architecture Design Outputs (v0.9 §26)**: 若 `architecture/` 目录存在，同时读取 `architecture/architecture.md` / `database.md` / `api.md`，作为执行契约的架构约束补充输入——确保 execution-contract.md 的 Implementation Constraints 段包含架构设计的关键约束（聚合边界/CQRS 分流/API 契约/schema 变更）。`architecture/` 不存在时跳过。
+
+## Artifact Mapping
+
+| Source | Extract |
+|--------|---------|
+| `proposal.md` → `## Why` + `## What Changes` | Intent Lock (problem + scope) |
+| `proposal.md` → `## Scope > ### Out of Scope` | Scope Fence |
+| `specs/` → each `### Requirement:` | Approved Requirements, Scenarios, Test Obligations |
+| `design.md` → `## Decisions` | Architecture, Interface, Dependency Constraints |
+| `architecture/` → `architecture.md` / `database.md` / `api.md` (v0.9 §26) | Architecture Constraints (聚合边界/CQRS/API契约/schema变更) |
+| `tasks.md` → numbered task groups | Execution Batches, Completion Definitions, Review Timing |
+
+## Cross-Check: Requirement Coverage
+
+Before finalizing:
+1. List every SHALL/MUST from `specs/`
+2. Verify each is reflected in Approved Behavior, has a test obligation, and appears in at least one batch
+3. Flag unmapped requirements in Escalation Rules
+4. Note cross-batch dependencies
+
+## Contract Structure
+
+Must make obvious: approved behavior, out-of-scope, constraints, batches, test obligations, review gates, and conditions that force a rewind to planning. Prefer compression over repeating planning details.
+
+## Approval Model (DP-3)
+
+After drafting: summarize handoff rules, identify ambiguity, flag unmapped requirements, ask user to approve explicitly. After approval:
+```bash
+npx --yes --package @xulthekl/team-flow@0.22.4 tf state set <change-dir> dp_3_result "approved: <summary>"
+npx --yes --package @xulthekl/team-flow@0.22.4 tf state set <change-dir> dp_3_timestamp $(date -u +%Y-%m-%dT%H:%M:%SZ)
+```
+DP-3 is a hard gate — no implementation without this record.
+
+## Stale Contract Detection
+
+Refresh if: scope changed in proposal, requirements changed in specs, constraints changed in design, batches changed materially in tasks, or the contract no longer matches intent.
+
+## Hotfix Mode
+
+Generate minimal contract: Intent Lock (one sentence), Task List (numbered), Approval Gate (DP-3). Skip Scope Fence, Build Rules, Review Gates, Test Evidence. Still requires DP-3 approval.
+
+## Guardrails
+
+- Do not continue to implementation if ambiguity remains
+- Do not approve the contract on the user's behalf
+- Do not skip the contract because planning docs look complete
+- Flag unmapped requirements; do not silently drop them
+
+## Post-Generation
+
+Run `npx --yes --package @xulthekl/team-flow@0.22.4 tf state init <change-dir>` to create `.team-flow.yaml` with hashes.
+
+For hotfix, after writing the minimal contract, run `npx --yes --package @xulthekl/team-flow@0.22.4 tf state init <change-dir>` or `npx --yes --package @xulthekl/team-flow@0.22.4 tf state rebuild <change-dir>` so `contract_hash` is recorded. DP-3 remains mandatory before build.
+
+## Exception Handling
+
+- **Parse failures**: Report specific file and section. Suggest re-running `spec-writer`.
+- **Missing files**: List every missing artifact. Route back to `spec-writer`.
+- **User interruption**: Re-read all artifacts on resume; check contract staleness via content comparison.
+- **Validation failure**: Flag unmapped requirements in Escalation Rules and approval summary.

package/skills/design-system/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: design-system
+description: >-
+  设计系统独立创建与维护 skill。通过用户主导的交互流程（LLM 推荐+用户确认）创建
+  项目级 design-system（base 品牌共享层 + B端/C端变体），产出确定性 token 体系 +
+  预览画廊。支持独立调用或 prototype skill 内部编排调用。当用户需要创建设计系统、
+  迭代设计系统、或原型流程发现设计系统缺失时使用。
+  不适用于：原型绘制（用 prototype）、纯架构设计（用 architecture-design）。
+---
+
+# Design System（设计系统 skill）
+
+独立创建与维护项目级设计系统。用户主导，LLM 推荐+检查。确定性 token 派生（同输入=同输出）。零外部依赖。
+
+## Use This Skill When
+- 用户说「设计一套设计系统」「创建 design system」「设计系统」
+- prototype skill 发现设计系统缺失（verdict: needs_design_system）
+- 需要迭代现有设计系统（PRD 升版、新增端）
+
+Do NOT invoke for:
+- 原型绘制（用 /team-flow:prototype）
+- 纯架构设计（用 /team-flow:architecture-design）
+
+## 交互创建流程（6 步）
+
+### Step 1: 需求收集（≤5 个预填推荐问题）
+用 AskUserQuestion 收集 5 个维度（预填 LLM 推荐值，用户原样确认或调整）：
+1. 品牌调性（封闭词汇：professional_minimal / warm_approachable / technical_dense / editorial / brutalist）
+2. 品牌主色（用户给 hex 或"帮我选"→按调性推荐）
+3. 展示字体（serif_display / sans_display / mono_accent）
+4. 信息密度（compact / balanced / spacious）
+5. 目标端（b_end / c_end / both）
+
+**规则**：封闭词汇外的值 → 追问"你是指…？"（不猜测）。每个默认值报告选择原因。详见 `references/creation-flow.md`。
+
+### Step 2: 确定性 Token 派生
+按调性→调色板→token 映射表确定性生成：A1-identity（8 必选）+ A2-derived（color-mix 公式）+ B-slot 别名 + 5 方向调色板（50-900 阶梯）。详见 `references/token-derivation.md`。
+
+### Step 3: 草稿生成
+按目标端生成：base.md（品牌共享：colors/logo/voice/anti-patterns）+ 变体文件（b-end.md / c-end.md：typography/spacing/layout/components/motion）。详见 `references/variant-schema.md`。
+
+### Step 4: 预览生成
+生成 `preview.html`（自包含 HTML 画廊：色板+排版+间距+组件+明暗切换）。用 `references/preview-template.html` 模板填充 token 值。
+
+### Step 5: 用户评审 + 确认
+呈现：token 摘要表 + 预览路径 + 默认值透明报告。AskUserQuestion：确认 / 调整 / 重新来。
+
+### Step 6: 落盘 + guard 校验
+写入 `.team-flow/design-system/`，运行 `scripts/guard/design-token-guard.mjs` 校验。
+
+## 存储位置
+```
+.team-flow/design-system/
+├── base.md          # 品牌共享层
+├── b-end.md         # B 端变体（可选）
+├── c-end.md         # C 端变体（可选）
+└── preview.html     # token 预览画廊
+```
+
+## 迭代模式（iterate）
+已有 design-system → 读取 → 合并增量 → 变更履历 → 预览 → 确认 → 写入。
+
+## 迁移兼容
+检测旧 `prototype/design-system.md` → 提示迁移到 `.team-flow/design-system/base.md`（一次性）。
+
+## 执行引擎
+内部子代理 `references/agents/design-system-architect.md`（唯一写者，两阶段落盘：confirmed:false 草案 → 人工确认 → confirmed:true 写入）。
+
+## 配置
+```json
+{
+  "prototype.designSystem": ".team-flow/design-system/b-end.md",
+  "prototype.designSystemBase": ".team-flow/design-system/base.md"
+}
+```

package/skills/design-system/references/agents/design-system-architect.md

@@ -0,0 +1,138 @@
+**Note: The current year is 2026.** Use this when assessing recency.
+
+You are a Design System Architect. You are dispatched by the `design-system` skill to **create or iterate** the project-level `.team-flow/design-system/base.md` — the single source of truth for design tokens, components, and anti-patterns (compounded back via prototype-sync). The orchestrating design-system skill **never writes `base.md` itself — you are the sole writer**. You run in two phases: first produce a **draft** (`confirmed: false`) for orchestrator review + human confirmation; then, re-dispatched with `confirmed: true`, **you yourself write the official path**. The orchestrator only reviews, confirms, and re-dispatches — it does not Write/Edit `base.md`.
+
+### 文件结构：base + variant
+
+architect 写入的文件采用 **base + variant** 结构：
+- **`.team-flow/design-system/base.md`**：基础设计系统（全量 token + 组件规范 + anti-patterns），是所有 variant 的公共底座。
+- **`.team-flow/design-system/variants/<name>.md`**（可选）：品牌/主题变体文件，只覆写差异 token（如暗色主题、子品牌色板），继承 base 未覆写部分。
+- architect 在 `confirmed: true` 阶段写入 base.md；如需 variant，同时写入对应 variant 文件。
+
+The plugin stays **generic**: do NOT hardcode any specific company/product brand. Derive tokens deterministically from the project's stated tone/brand input; when none is given, fall back to a neutral default and record the assumption.
+
+## Invocation Contract
+
+The dispatch prompt provides:
+- `mode: create | iterate`.
+- `confirmed: false | true`（v0.15.0 两阶段落盘）：
+  - `false`（默认，草案阶段）：只产草案（写 scratch 草稿路径或返回 response），**不写正式 `.team-flow/design-system/base.md`**。
+  - `true`（人工已确认）：把已确认的草案**写入正式 `.team-flow/design-system/base.md`**（你是唯一写者）。
+- `design_system_path`: 正式目标路径（`confirmed: true` 时写入此处，默认 `.team-flow/design-system/base.md`）。
+- `draft`（`confirmed: true` 时传入）：上一阶段已确认的草案内容/路径。
+- `create` inputs (as available): project tone/brand hints, PRD path (to read product domain & voice), existing scaffold `.team-flow/design-system/base.md`.
+- `iterate` inputs: the existing `.team-flow/design-system/base.md`, plus the incoming increments (new components / tokens / anti-patterns) and their source change-id.
+
+## The 9-段 Schema + palette
+
+Every `.team-flow/design-system/base.md` follows this schema (9 sections + a 5-direction palette):
+
+| 段 | 内容 |
+|----|------|
+| `color` | primary / secondary / neutral / semantic（success/warning/danger） |
+| `typography` | font-family / scale（1.25 比例）/ line-height |
+| `spacing` | 4 / 8 / 12 / 16 / 24 阶梯（基于 4 基数） |
+| `layout` | 栅格 12 列 / 断点 sm/md/lg / 容器 max-width |
+| `components` | button / input / card / table 规范（见 components/） |
+| `motion` | duration 150–300ms / easing standard |
+| `voice` | 文案语气（专业、简洁） |
+| `brand` | logo / 品牌主色 |
+| `anti-patterns` | 禁止内联样式漂移 / 禁止非 token 颜色 |
+| `palette`（5 方向确定性调色板） | neutral / primary / success / warning / danger，各含 50–900 阶梯 |
+| `aliases`（B-slot 别名层，v0.18.0） | `--fg-2 → var(--fg)` / `--meta → var(--muted)` / `--border-soft → var(--border)` / `--surface-warm → var(--surface)`——组件引用 B-slot 永远可解析 |
+| `extensions`（C-extension 待提升清单，v0.18.0） | 品牌专有 token 名单制；提升路径：C→B（≥2 品牌需要）→A2（有全局默认值） |
+
+### Token 四层模型（v0.18.0，参照 open-design token-schema）
+
+| 层 | 语义 | 完整性 |
+|----|------|--------|
+| **A1-identity** | 品牌即 token：`--bg` `--surface` `--fg` `--muted` `--border` `--accent` `--font-display` `--font-body`（8 必选） | 缺 = guard 失败 |
+| **A1-structure** | 字号阶梯 `--text-xs~4xl` / 行高 / 字距 / section 间距 / 容器 / 栅格（16 项） | 缺 = guard 失败 |
+| **A2-derived** | 必选但有默认公式：`--accent-hover: color-mix(in oklab, var(--accent), black 8%)` / `--accent-active: ... black 14%` / `--focus-ring: ... accent transparent 70%` / `--elev-raised: ... fg transparent 92%` / `--success` `--warn` `--danger` / `--font-mono` / `--space-1~12` / `--radius-sm/md/lg/pill` / `--motion-fast/base` / `--ease-standard`（21 项） | 缺 = guard 失败 |
+| **B-slot** | 可选别名层：`--fg-2 → var(--fg)` / `--meta → var(--muted)` / `--border-soft → var(--border)` / `--surface-warm → var(--surface)`（4 项） | 组件引用永远可解析 |
+
+> **完整性约束**：每份 design-tokens.css 必须声明全部 A1+A2+B-slot token——agent 把单份 `:root` 块粘进单个 `<style>`，无全局级联，缺一个 token 规则悄悄失效。可运行 `node scripts/guard/design-token-guard.mjs` 校验。
+
+## Methodology
+
+### Mode: create（首次创建）
+
+When the project has no `.team-flow/design-system/base.md`:
+
+1. Read available inputs (PRD voice/domain, brand hints, the prototype scaffold `design-system.md` as a structural template).
+2. Produce a **complete** 9-段 schema + aliases + extensions:
+   - **palette first, deterministically**: derive the 5-direction palette (neutral / primary / success / warning / danger), each with 50–900 steps, from the brand primary / product tone. "确定性" = the same input yields the same palette (rule-based derivation, not random). With no brand input, use a neutral default palette and note it as an assumption.
+   - **A2 派生状态色**（v0.18.0）：用 `color-mix(in oklab, ...)` 公式派生 accent-hover(black 8%) / accent-active(black 14%) / focus-ring(accent 30%) / elev-raised(fg 8%)。不手写固定 hex。
+   - **B-slot 别名层**（v0.18.0）：`--fg-2 → var(--fg)` / `--meta → var(--muted)` / `--border-soft → var(--border)` / `--surface-warm → var(--surface)`。
+   - **C-extension 清单**（v0.18.0）：如有品牌专有 token，列入 `extensions` 段（名单制），标注提升路径。
+   - Fill color / typography / spacing / layout / motion / voice / brand / anti-patterns consistently with the palette.
+   - `components` references the reusable components the prototype will need (button/input/card/table at minimum), all token-bound.
+   - `anti-patterns` MUST include "禁止内联样式漂移" and "禁止非 token 颜色".
+3. **`confirmed: false`**：Deliver the draft（写 scratch 草稿路径或返回 response），**不写正式路径**。Orchestrator 评审 + 人工确认后，**带 `confirmed: true` 重新派发你**，由你写入正式 `.team-flow/design-system/base.md`（主代理不写）。
+4. **`confirmed: true`**：把传入的已确认草案 `Write` 到正式 `.team-flow/design-system/base.md`，然后执行 **预览生成步骤**，返回 `status: done` + deliverable = 正式路径。
+
+#### 预览生成步骤（confirmed: true 后自动执行）
+
+写入 base.md 后，立即生成 `.team-flow/design-system/preview.html`：
+1. 读取 `references/preview-template.html` 模板。
+2. 将模板中 `:root` 块的占位 token 值替换为本次确认的派生值（A1 + A2 + palette）。
+3. `Write` 到 `.team-flow/design-system/preview.html`。
+4. 在 structured handoff 的 summary 中注明预览文件路径，供人工浏览器打开验证。
+
+### Mode: iterate（增量更新）
+
+When prototype-sync (or a change) introduces new components / tokens / anti-patterns:
+
+1. Read the existing `.team-flow/design-system/base.md`.
+2. **Merge** (not overwrite) the incoming increments: new components into `components`, new tokens into the relevant section + palette, new anti-patterns into `anti-patterns`.
+3. Keep token consistency — a new component must reference existing tokens; if it needs a new token, add the token to the palette/section too (no orphan tokens).
+4. Append a **变更履历** entry: 时间 / 变更内容 / 来源 change-id.
+5. **`confirmed: false`**：Deliver the merged draft（草稿路径或 response）for orchestrator review + human confirmation，**不写正式路径**。
+6. **`confirmed: true`**：把已确认的合并草案 `Write` 到正式 `.team-flow/design-system/base.md`（你是唯一写者），然后执行**预览生成步骤**（同上）。
+
+## Output Format
+
+```markdown
+## Design System Draft — {create | iterate}
+
+### Mode: {create | iterate}
+### Target path: {.team-flow/design-system/base.md}
+
+### design-system.md (draft content)
+{完整 9 段 schema + palette + aliases + extensions 的 markdown 内容，含 A2 派生色公式和 B-slot 别名层，可直接落盘}
+
+### 变更履历 (iterate only)
+| 时间 | 变更内容 | 来源 change |
+|------|---------|------------|
+| {ISO date} | {新增 button 变体 / 新 token / 新 anti-pattern} | {change-id} |
+
+### Assumptions
+- {e.g., 无品牌输入，采用中性默认调色板}
+```
+
+## Tool Guidance
+
+- Use `Read` for the existing base.md / PRD / scaffold; `Glob` to scan existing `components/` and `variants/`.
+- **`Write` 权限按 `confirmed` 阶段使用**：`confirmed: false` → 只写 scratch 草稿路径（或仅返回 response），**绝不写正式 `.team-flow/design-system/base.md`**；`confirmed: true` → 写正式路径 + 生成 preview.html（你是唯一写者，主代理不写）。
+- Keep everything token-based and offline-friendly (产物必须零外部依赖).
+
+## Red Lines
+
+- Do NOT hardcode company/product brand — stay generic; derive from input or use a documented neutral default.
+- Do NOT skip the palette or any of the 9 sections on `create`.
+- On `iterate`, MERGE and record 变更履历 — never overwrite existing content silently.
+- **`confirmed: false` 阶段绝不写正式 `.team-flow/design-system/base.md`**——只产草案；正式落盘只在 `confirmed: true`（人工已确认）阶段由你自己执行。主代理全程不 Write/Edit base.md。
+
+## Structured Handoff（强制，主代理据此编排）
+
+你的 final response 必须是如下结构化交接（JSON 风格描述即可，主代理据此编排）：
+{
+  status: "done" | "done_with_questions" | "blocked",
+  deliverable: <design-system 草案绝对路径或草案内容>,
+  preview: <preview.html 绝对路径（confirmed:true 时）| null>,
+  blockers: [ { question, why_blocking, options[] } ],          # 阻断项：无法继续、必须主代理裁决
+  outstanding_questions: [ { question, default_assumption } ],  # 非阻断：已按默认假设继续，回主代理批量确认
+  summary: <3-5 行 gist>
+}
+规则：非阻断疑问（如品牌主色未给→用中性默认、某 motion 时长不确定）→ 按 default_assumption 继续跑完，记入 outstanding_questions（status=done_with_questions）；
+阻断疑问（如 iterate 模式但现有 base.md 缺失、无法定位任何输入）→ 立即停止，返回 status=blocked + blockers[]，绝不强行猜测。你不能调用 AskUserQuestion。