mancode 0.2.0 → 0.3.0

package/README.md

@@ -16,9 +16,9 @@
 
 <p align="center">
   <a href="./LICENSE"><img src="https://img.shields.io/badge/License-AGPL--3.0-blue.svg?style=flat-square" alt="License: AGPL-3.0" /></a>
-  <img src="https://img.shields.io/badge/status-stable%20v0.2.0-green?style=flat-square" alt="Status: stable v0.2.0" />
+  <img src="https://img.shields.io/badge/status-stable%20v0.2.1-green?style=flat-square" alt="Status: stable v0.2.1" />
   <img src="https://img.shields.io/badge/platforms-Claude%20Code%20%7C%20Cursor%20%7C%20Codex%20%7C%20Copilot%20%7C%20ZCode-5865F2?style=flat-square" alt="Platforms: Claude Code, Cursor, Codex CLI, GitHub Copilot, ZCode" />
-  <img src="https://img.shields.io/badge/tests-313%20passed-brightgreen?style=flat-square" alt="Tests: 305 passed" />
+  <img src="https://img.shields.io/badge/tests-364%20passed-brightgreen?style=flat-square" alt="Tests: 364 passed" />
 </p>
 
 <p align="center">
@@ -43,10 +43,10 @@ mancode installs three things:
 
 1. **Hooks** that inject project context, design tokens, and YAGNI checks into
    agent prompts.
-2. **Skills / modes** for `solo`, `/man8`, `/man`, `/manteam`, `/manps`, and
+2. **Skills / modes** for `solo`, `/mamba`, `/man`, `/manteam`, `/manps`, and
    `/mansolo`.
-3. **Coaching-staff subagents**: Scout, Head Coach, Film Analyst (Offense), and
-   Film Analyst (Defense).
+3. **Coaching-staff subagents**: Scout, Plan Coach, Head Coach, Film Analyst
+   (Offense), and Film Analyst (Defense).
 
 Use mancode when an AI coding agent writes too much code, ignores your existing
 UI system, skips planning, or needs a repeatable engineering workflow for
@@ -82,9 +82,9 @@ testing, and multi-agent review: playoffs, every possession counts.
 .claude/                         # Claude Code: hooks, skills, agents
 .cursor/rules/                   # Cursor: project rules
 AGENTS.md                        # Codex CLI: managed instruction block
-.codex/skills/                   # Codex CLI: mode skills
+.agents/skills/                   # Codex CLI: mode skills
 .github/copilot-instructions.md  # GitHub Copilot: managed instruction block
-.zcode/skills/                   # ZCode: project mode skills
+.agents/skills/                   # ZCode: project mode skills
 ```
 
 `.mancode/` stores local state, project style signals, workflow reports, and
@@ -95,9 +95,10 @@ coding agent reads.
 
 - **Reduce AI over-engineering**: prefer existing code, standard libraries,
   installed dependencies, and one-line fixes before writing new abstractions.
-- **Match your frontend design system**: scan Tailwind, package metadata, and
-  existing components so the agent reuses your colors, fonts, and UI patterns.
-- **Add structured AI code review**: use `/man` for an 8-step workflow with
+- **Match an existing UI system when present**: inspect project UI dependencies,
+  Tailwind configuration, CSS variables, and components so the agent reuses
+  established colors, fonts, and interaction patterns.
+- **Add structured AI code review**: use `/man` for a 9-step workflow with
   research, plan approval, implementation, tests, and dual review.
 - **Keep workflow artifacts on disk**: save research, plans, review reports,
   and summaries under `.mancode/workflows/<taskId>/`.
@@ -110,12 +111,12 @@ coding agent reads.
 
 mancode is useful for:
 
-- Developers using AI coding agents on JavaScript or TypeScript projects
+- Developers using AI coding agents on backend, web, mobile, desktop, CLI,
+  library, data, or mixed projects
 - Claude Code users who want hooks, skills, and subagents today
 - Teams that want AI agents to reuse existing components and patterns
 - Projects that need a repeatable AI-assisted code review workflow
-- Frontend codebases with Tailwind, shadcn/ui, MUI, Ant Design, or similar UI
-  conventions
+- UI codebases with existing design conventions (when a UI is present)
 - Teams that want local workflow memory without telemetry
 
 mancode is not a replacement for your coding agent. It is a workflow layer that
@@ -136,19 +137,22 @@ design tokens:
 </Button>
 ```
 
-The default workflow asks three questions before writing code:
+The default workflow asks six questions before writing code:
 
 1. What problem does this change solve?
 2. Can an existing implementation be reused?
 3. What is the smallest change that works?
+4. Can this avoid a new subsystem?
+5. What is the smallest meaningful runtime check?
+6. What remains uncertain after checking the code and docs?
 
 ## Modes
 
 | Mode | Best For | What It Does |
 |---|---|---|
 | `solo` | Daily coding · practice day | Lightweight hooks, style awareness, and YAGNI checks |
-| `/man8` | Research before implementation · 4 AM warmup | Scout investigates the codebase, then Head Coach writes a plan |
-| `/man` | Production or high-risk changes · playoffs | Full 8-step workflow with dual multi-agent review |
+| `/mamba` | Diagnosis and real validation · Mamba mentality | Reproduces defects, finds root causes, drives real user flows, and runs regression checks |
+| `/man` | Production or high-risk changes · playoffs | Full 9-step workflow with dual multi-agent review |
 | `/manteam` | Team projects · five on the floor, one mind | Shared memory, decisions, coordination, and Conventional Commits |
 | `/manps` | Cleanup and maintenance · preseason | Project health scan with Markdown and JSON reports |
 | `/mansolo` | Returning to default mode | Resets current mode back to `solo` |
@@ -156,18 +160,17 @@ The default workflow asks three questions before writing code:
 ## How `/man` Works: Playoffs Mode
 
 `/man` is playoffs mode for production work. It creates a durable workflow under
-`.mancode/workflows/<taskId>/` and moves through eight steps:
-
-1. **Scout report**: a research subagent maps the code you are about to touch.
-2. **Game plan**: Head Coach writes an implementation plan.
-3. **Plan approval**: a human approves the plan before code changes begin.
-4. **Implementation and self-test**: build, lint, and tests must pass.
-5. **Film session 1**: code quality review for readability, DRY, YAGNI, and
-   complexity.
-6. **Fix round**: Head Coach addresses review findings.
-7. **Film session 2**: security and edge-case review for auth, XSS, SQL
-   injection, concurrency, and resource leaks.
-8. **Post-game summary**: final summary, skipped steps, and artifact locations.
+`.mancode/workflows/<taskId>/` and moves through nine steps:
+
+1. **Scout report**: maps existing code, risks, and unknowns.
+2. **Clarification**: resolves requirements in up to two rounds.
+3. **Plan**: Plan Coach creates a durable, verifiable plan.
+4. **Plan gate**: choose plan-only, execution, or plan revision.
+5. **Implementation**: Head Coach applies the confirmed plan.
+6. **Validation**: build, lint, tests, smoke checks, and `/mamba` when real diagnosis is needed.
+7. **Film session 1**: code quality review and fixes.
+8. **Film session 2**: security and boundary review.
+9. **Wrap-up**: final verification, summary, workflow status, and memory updates.
 
 Skipped steps are recorded. Artifacts remain on disk so you can inspect why a
 decision was made later.
@@ -189,7 +192,10 @@ rules or instruction files that carry the same practice rules and mode guidance.
 
 ### Design Token Awareness
 
-mancode scans project files such as:
+mancode first writes `.mancode/project-profile.json` from detected project facts.
+It can work with backend services, web applications, mobile apps, desktop apps,
+CLIs, libraries, and mixed repositories; it does not assume a JavaScript or UI
+stack. It scans signals such as:
 
 ```text
 tailwind.config.js
@@ -199,13 +205,14 @@ src/components/
 
 It detects common signals:
 
-- Tech stack: React, Vue, Svelte, TypeScript, Tailwind, styled-components
-- UI libraries: shadcn/ui, MUI, Ant Design, Headless UI
-- Design tokens: colors, fonts, spacing, components
+- Languages, manifests, source roots, and available validation commands
+- UI assets and UI libraries when they are actually detected (for example, a web UI)
+- Design signals: colors, fonts, CSS variables, and components
 - Team status: contributor count and team-mode hints
 
-For frontend work, the agent is nudged to reuse existing UI components and
-design tokens instead of inventing generic styles.
+For UI work in a project with detected UI assets, the agent is nudged to reuse
+existing components and design tokens instead of inventing generic styles.
+For other project types, it follows the detected runtime and validation path.
 
 ### YAGNI Ladder
 
@@ -234,7 +241,7 @@ it should behave, and why previous decisions were made.
 
 ## Installation
 
-**Status**: stable v0.2.0. Claude Code, Cursor, Codex CLI, and GitHub Copilot
+**Status**: stable v0.2.1. Claude Code, Cursor, Codex CLI, and GitHub Copilot
 are supported. ZCode adapter support is included, with project skill discovery
 kept behind a verification gate before release.
 
@@ -252,7 +259,7 @@ Supported platforms:
 - Codex CLI: managed `AGENTS.md` block
 - GitHub Copilot: managed `.github/copilot-instructions.md` block
 - ZCode: managed `AGENTS.md` block and provisional `$man*` skills in
-  `.zcode/skills/`; project skill discovery and slash commands pending verified
+  `.agents/skills/`; project skill discovery and slash commands pending verified
   workspace paths
 - Windsurf, Cline, Roo Code: planned later
 
@@ -272,8 +279,8 @@ mancode install --minimal # Install only solo-mode essentials
 ## Agent Modes
 
 ```bash
-/man8                      # Research and plan before implementation
-/man                       # Full 8-step workflow with dual review
+/mamba                      # Diagnose bugs and validate real user flows
+/man                       # Full 9-step workflow with dual review
 /manps                     # Project health check
 /manteam                   # Team mode and shared memory
 /mansolo                   # Return to solo mode
@@ -287,10 +294,10 @@ mancode status
 mancode status --json
 mancode install <claude-code|cursor|codex|copilot|zcode>
 mancode list-platforms
-mancode workflow create <man8|man> "<task>"
-mancode workflow update <taskId> [--step N] [--status in_progress|completed|abandoned]
-mancode workflow list
-mancode workflow show <taskId>
+mancode workflow create <man|mamba|manteam> "<task>" [--parent-task <taskId>]
+mancode workflow update <taskId> [--step N] [--status in_progress|planned|completed|blocked|abandoned] [--blocking-reason "<reason>"] [--outcome fixed|verified|no_repro|manual_test_required] [--plan-version N] [--skipped a,b]
+mancode workflow list [--json]
+mancode workflow show <taskId> [--json]
 mancode workflow clean [--older-than 30d] [--dry-run]
 mancode manps [area]
 mancode refresh-style
@@ -301,6 +308,8 @@ mancode version
 
 ### `mancode status`
 
+Example output for a UI project (not a default stack):
+
 ```text
 mancode v0.2.0
 
@@ -320,9 +329,9 @@ Installed platforms:
 Platform status:
   ✓ Claude Code: ready (.claude/)
   ✓ Cursor: ready (.cursor/rules/)
-  ✓ Codex CLI: ready (AGENTS.md + .codex/skills/)
+  ✓ Codex CLI: ready (AGENTS.md + .agents/skills/)
   ✓ GitHub Copilot: ready (.github/copilot-instructions.md)
-  ✓ ZCode: ready (AGENTS.md + .zcode/skills/)
+  ✓ ZCode: ready (AGENTS.md + .agents/skills/)
 
 Hooks:
   ✓ session-start.sh
@@ -364,12 +373,16 @@ mancode status --json
 
 ### `mancode workflow`
 
-Creates and manages workflow metadata used by `/man8` and `/man`.
+Creates and manages validated workflow metadata used by `/mamba`, `/man`, and
+`/manteam`. A linked `/mamba` child can only be created while its parent is
+active at Step 6.
 
 ```bash
 mancode workflow create man "refactor auth module"
-mancode workflow update <taskId> --step 4
-mancode workflow show <taskId>
+mancode workflow update <taskId> --step 4 --plan-version 2
+mancode workflow create mamba "verify auth regression" --parent-task <taskId>
+mancode workflow update <mambaTaskId> --status completed --outcome verified
+mancode workflow show <taskId> --json
 mancode workflow clean --older-than 30d --dry-run
 ```
 
@@ -395,10 +408,12 @@ Outputs:
 
 ### `mancode refresh-style`
 
-Rescans project design tokens and updates:
+Refreshes the project profile and, when UI assets are detected, rescans design
+tokens. It updates:
 
 ```text
 .mancode/aesthetics/style-tokens.json
+.mancode/project-profile.json
 ```
 
 Claude Code reads refreshed tokens through hooks. Cursor, Codex CLI, and GitHub
@@ -420,13 +435,15 @@ mancode/
 │
 ├── Skills
 │   ├── solo/SKILL.md
-│   ├── man8/SKILL.md
+│   ├── mamba/SKILL.md
 │   ├── man/SKILL.md
 │   ├── manteam/SKILL.md
-│   └── manps/SKILL.md
+│   ├── manps/SKILL.md
+│   └── mansolo/SKILL.md
 │
 └── Subagents
     ├── Scout
+    ├── Plan Coach
     ├── Head Coach
     ├── Film Analyst (Offense)
     └── Film Analyst (Defense)
@@ -437,7 +454,9 @@ mancode/
 - mancode is local-first.
 - Scans are written under `.mancode/`.
 - No telemetry is sent by mancode.
-- `.mancode/` is git-ignored by default unless you choose to commit parts of it.
+- mancode does not rewrite your project's `.gitignore`. Review `.mancode/`
+  before committing and ignore local workflow evidence or browser artifacts
+  that may contain sensitive data.
 - `/manps` scans only; remediation should be explicitly confirmed before code
   changes.
 - Irreversible operations such as force pushes, schema migrations, and bulk
@@ -448,7 +467,7 @@ mancode/
 | Phase | Focus |
 |---|---|
 | MVP-1 | solo mode, aesthetics, and Claude Code hooks |
-| MVP-2 | `/man8`, `/man`, `/manteam`, `/manps`, and coaching-staff subagents |
+| MVP-2 | `/mamba`, `/man`, `/manteam`, `/manps`, and coaching-staff subagents |
 | MVP-3 | Cursor, Codex CLI, and GitHub Copilot adapters |
 | Public Release | stable npm release, marketplace distribution, docs, and demos |
 
@@ -456,8 +475,10 @@ mancode/
 
 ### `mancode init` says "not a project directory"
 
-mancode requires either a `.git` directory or a `package.json` in the target
-folder. Run `mancode init` inside a git repository or a Node.js project.
+mancode requires either a `.git` directory or a recognized project manifest
+(such as `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `pom.xml`,
+`build.gradle`, `build.gradle.kts`, `Package.swift`, or `pubspec.yaml`). Run `mancode init` inside
+a git repository or a supported project directory.
 
 ### Claude Code hooks not triggering
 
@@ -480,7 +501,7 @@ markers is preserved.
 
 ### ZCode skills not appearing
 
-Ensure `.zcode/skills/man8/SKILL.md` through `.zcode/skills/mansolo/SKILL.md`
+Ensure `.agents/skills/mamba/SKILL.md` through `.agents/skills/mansolo/SKILL.md`
 exist, then restart or refresh ZCode. ZCode slash commands are not generated
 yet because the workspace command file path still needs explicit verification.
 
@@ -488,8 +509,8 @@ yet because the workspace command file path still needs explicit verification.
 
 Ensure the `.cursor/rules/mancode-*.mdc` files exist. Rules with
 `alwaysApply: true` (context, practice, solo) load on every conversation.
-Mode-specific rules (man8, man, manteam, manps) trigger based on the
-description field — invoke them by asking for `/man8` or similar.
+Mode-specific rules (mamba, man, manteam, manps) trigger based on the
+description field — invoke them by asking for `/mamba` or similar.
 
 ### How to do a clean reinstall
 

package/README.zh-CN.md

@@ -15,9 +15,9 @@
 
 <p align="center">
   <a href="./LICENSE"><img src="https://img.shields.io/badge/License-AGPL--3.0-blue.svg?style=flat-square" alt="许可证：AGPL-3.0" /></a>
-  <img src="https://img.shields.io/badge/status-stable%20v0.2.0-green?style=flat-square" alt="状态：稳定版 v0.2.0" />
+  <img src="https://img.shields.io/badge/status-stable%20v0.2.1-green?style=flat-square" alt="状态：稳定版 v0.2.1" />
   <img src="https://img.shields.io/badge/platforms-Claude%20Code%20%7C%20Cursor%20%7C%20Codex%20%7C%20Copilot%20%7C%20ZCode-5865F2?style=flat-square" alt="平台：Claude Code、Cursor、Codex CLI、GitHub Copilot、ZCode" />
-  <img src="https://img.shields.io/badge/tests-313%20passed-brightgreen?style=flat-square" alt="测试：305 通过" />
+  <img src="https://img.shields.io/badge/tests-364%20passed-brightgreen?style=flat-square" alt="测试：364 通过" />
 </p>
 
 <p align="center">
@@ -39,10 +39,10 @@ skills 或 instructions 文件提供降级适配。
 mancode 会安装三类能力：
 
 1. **Hooks**：在 agent 提示词中注入项目上下文、设计 token 和 YAGNI 检查。
-2. **Skills / modes**：提供 `solo`、`/man8`、`/man`、`/manteam`、`/manps`、
+2. **Skills / modes**：提供 `solo`、`/mamba`、`/man`、`/manteam`、`/manps`、
    `/mansolo` 工作流模式。
-3. **教练组 subagents**：Scout、Head Coach、Film Analyst (Offense) 和
-   Film Analyst (Defense)。
+3. **教练组 subagents**：Scout、Plan Coach、Head Coach、Film Analyst
+   (Offense) 和 Film Analyst (Defense)。
 
 当 AI 编码代理写太多代码、忽略已有 UI 系统、跳过计划，或者关键改动需要稳定工程流程时，
 mancode 可以作为一层本地工作流约束。
@@ -76,9 +76,9 @@ mancode init
 .claude/                         # Claude Code：hooks、skills、agents
 .cursor/rules/                   # Cursor：项目 rules
 AGENTS.md                        # Codex CLI：托管 instruction block
-.codex/skills/                   # Codex CLI：mode skills
+.agents/skills/                   # Codex CLI：mode skills
 .github/copilot-instructions.md  # GitHub Copilot：托管 instruction block
-.zcode/skills/                   # ZCode：项目 mode skills
+.agents/skills/                   # ZCode：项目 mode skills
 ```
 
 `.mancode/` 保存本地状态、项目风格信号、工作流报告和团队记忆。平台文件保存对应
@@ -87,8 +87,8 @@ AGENTS.md                        # Codex CLI：托管 instruction block
 ## 为什么使用 mancode？
 
 - **减少 AI 过度设计**：先复用已有代码、标准库、已安装依赖和一行修复，再考虑新增抽象。
-- **匹配前端设计系统**：扫描 Tailwind、package 元数据和已有组件，让 agent 复用项目颜色、字体和 UI 模式。
-- **加入结构化 AI 代码审查**：`/man` 提供 8 步流程，包括调研、计划审批、实现、测试和双重审查。
+- **在存在 UI 时匹配现有设计系统**：检查项目 UI 依赖、Tailwind 配置、CSS 变量和已有组件，让 agent 复用现有颜色、字体和交互模式。
+- **加入结构化 AI 代码审查**：`/man` 提供 9 步流程，包括调研、计划审批、实现、测试和双重审查。
 - **保留工作流产物**：调研、计划、审查报告和总结会保存到 `.mancode/workflows/<taskId>/`。
 - **支持团队记忆**：`/manteam` 读写 `.mancode/memory/` 下的共享项目上下文。
 - **扫描项目健康度**：`mancode manps` 检测陈旧 TODO、未使用依赖、风险依赖和硬编码设计值。
@@ -97,11 +97,11 @@ AGENTS.md                        # Codex CLI：托管 instruction block
 
 mancode 适合：
 
-- 正在使用 AI 编码代理的 JavaScript 或 TypeScript 项目
+- 正在使用 AI 编码代理的后端、Web、移动端、桌面端、CLI、库、数据或混合项目
 - 当前希望在 Claude Code 中使用 hooks、skills 和 subagents 的用户
 - 希望 AI 代理复用已有组件和代码模式的团队
 - 需要可重复 AI 辅助代码审查流程的项目
-- 使用 Tailwind、shadcn/ui、MUI、Ant Design 等 UI 约定的前端代码库
+- 已有 UI 组件、主题、CSS 变量或设计约定的界面项目
 - 希望保留本地团队记忆、但不希望引入遥测的团队
 
 mancode 不是 Claude Code、Cursor、Codex CLI 或 Copilot 的替代品。它是在现有 agent
@@ -120,19 +120,22 @@ mancode 不是 Claude Code、Cursor、Codex CLI 或 Copilot 的替代品。它
 </Button>
 ```
 
-默认工作流会在写代码前推动 agent 思考三个问题：
+默认工作流会在写代码前推动 agent 思考六个问题：
 
 1. 这个改动解决什么问题？
 2. 能否复用已有实现？
 3. 最小可行改动是什么？
+4. 能否不拆新系统？
+5. 非平凡逻辑怎样做最小运行验证？
+6. 有什么没把握的（先自查，仍不确定再问用户）？
 
 ## 模式
 
 | 模式 | 适合场景 | 做什么 |
 |---|---|---|
 | `solo` | 日常编码 · 日常训练 | 轻量 hooks、风格感知、YAGNI 检查 |
-| `/man8` | 实现前调研 · 凌晨 4 点热身 | Scout 调研代码库，Head Coach 输出计划 |
-| `/man` | 生产级或高风险改动 · 季后赛 | 完整 8 步工作流和双重多 agent 审查 |
+| `/mamba` | 诊断与真实验证 · 曼巴心态 | 复现缺陷、定位根因、驱动真实用户路径并执行回归检查 |
+| `/man` | 生产级或高风险改动 · 季后赛 | 完整 9 步工作流和双重多 agent 审查 |
 | `/manteam` | 团队项目 · 上场五人，一条心 | 共享记忆、决策记录、协作和 Conventional Commits |
 | `/manps` | 清理和维护 · 季前赛 | 输出 Markdown 和 JSON 项目健康报告 |
 | `/mansolo` | 回到默认模式 | 将当前模式重置为 `solo` |
@@ -140,16 +143,17 @@ mancode 不是 Claude Code、Cursor、Codex CLI 或 Copilot 的替代品。它
 ## `/man` 如何工作：季后赛模式
 
 `/man` 是面向关键任务的季后赛模式。它会在 `.mancode/workflows/<taskId>/`
-下创建可追溯工作流，并推进八个步骤：
-
-1. **球探报告**：调研 subagent 梳理即将修改的代码。
-2. **比赛计划**：Head Coach 写实现计划。
-3. **计划审批**：人类审批后才开始改代码。
-4. **实现和自测**：build、lint、test 必须通过。
-5. **录像分析 1**：审查可读性、DRY、YAGNI 和复杂度。
-6. **修复轮**：Head Coach 修复审查发现。
-7. **录像分析 2**：审查认证、XSS、SQL 注入、并发和资源泄漏等边界。
-8. **赛后总结**：总结改动、跳过步骤和产物位置。
+下创建可追溯工作流，并推进九个步骤：
+
+1. **球探报告**：梳理既有代码、风险和未知项。
+2. **需求澄清**：最多两轮确认需求。
+3. **计划**：Plan Coach 输出可验证的持久计划。
+4. **计划关卡**：选择只要计划、继续执行或修改计划。
+5. **实施**：Head Coach 按确认计划实现。
+6. **验证**：build、lint、test、smoke test；需要真实诊断时使用 `/mamba`。
+7. **录像分析 1**：代码质量审查与修复。
+8. **录像分析 2**：安全与边界审查。
+9. **收尾**：最终复验、summary、workflow 状态和 memory 更新。
 
 跳过的步骤会被记录。所有产物保留在本地，之后可以回看当时为什么做某个决策。
 
@@ -168,7 +172,7 @@ rules 或 instruction 文件，把同一套实践规则和模式指导带过去
 
 ### 设计 Token 感知
 
-mancode 会扫描这些项目文件：
+mancode 会先把检测到的项目事实写入 `.mancode/project-profile.json`。它可用于后端服务、Web、移动端、桌面端、CLI、库和混合仓库；不会预设 JavaScript 或 UI 技术栈。它会扫描如下信号：
 
 ```text
 tailwind.config.js
@@ -178,12 +182,12 @@ src/components/
 
 它会检测常见信号：
 
-- 技术栈：React、Vue、Svelte、TypeScript、Tailwind、styled-components
-- UI 库：shadcn/ui、MUI、Ant Design、Headless UI
-- 设计 token：颜色、字体、间距、组件
+- 语言、manifest、源码目录和可用验证命令
+- 仅在确实检测到时记录 UI 资产和 UI 库（例如 Web UI）
+- 设计信号：颜色、字体、CSS 变量和组件
 - 团队状态：贡献者数量和团队模式提示
 
-在前端任务中，mancode 会推动 agent 复用已有 UI 组件和设计 token，而不是生成通用样式。
+只有在 profile 确认存在 UI 资产且任务涉及界面时，mancode 才会推动 agent 复用已有组件和设计 token，而不是生成通用样式。其他项目类型则遵循已检测到的运行时和验证路径。
 
 ### YAGNI 阶梯
 
@@ -211,7 +215,7 @@ src/components/
 
 ## 安装
 
-**状态**：稳定版 v0.2.0。Claude Code、Cursor、Codex CLI 和 GitHub Copilot
+**状态**：稳定版 v0.2.1。Claude Code、Cursor、Codex CLI 和 GitHub Copilot
 均已支持。ZCode adapter 已接入，但项目级 skill 发现路径在发布前仍作为验证门禁。
 
 ```bash
@@ -227,7 +231,7 @@ mancode init --platform cursor
 - Cursor：`.cursor/rules/*.mdc` rules
 - Codex CLI：托管 `AGENTS.md` block
 - GitHub Copilot：托管 `.github/copilot-instructions.md` block
-- ZCode：托管 `AGENTS.md` block，并暂按 `.zcode/skills/` 生成 `$man*`
+- ZCode：托管 `AGENTS.md` block，并暂按 `.agents/skills/` 生成 `$man*`
   skills；项目级 skill 发现和 slash commands 仍需确认 workspace 路径后再发布承诺
 - Windsurf、Cline、Roo Code：后续计划
 
@@ -247,8 +251,8 @@ mancode install --minimal # 只安装 solo 必需文件
 ## Agent Modes
 
 ```bash
-/man8                      # 实现前调研和计划
-/man                       # 完整 8 步流程和双重审查
+/mamba                      # 定位 bug 并验证真实用户路径
+/man                       # 完整 9 步流程和双重审查
 /manps                     # 项目健康检查
 /manteam                   # 团队模式和共享记忆
 /mansolo                   # 回到 solo 模式
@@ -262,10 +266,10 @@ mancode status
 mancode status --json
 mancode install <claude-code|cursor|codex|copilot|zcode>
 mancode list-platforms
-mancode workflow create <man8|man> "<task>"
-mancode workflow update <taskId> [--step N] [--status in_progress|completed|abandoned]
-mancode workflow list
-mancode workflow show <taskId>
+mancode workflow create <man|mamba|manteam> "<task>" [--parent-task <taskId>]
+mancode workflow update <taskId> [--step N] [--status in_progress|planned|completed|blocked|abandoned] [--blocking-reason "<reason>"] [--outcome fixed|verified|no_repro|manual_test_required] [--plan-version N] [--skipped a,b]
+mancode workflow list [--json]
+mancode workflow show <taskId> [--json]
 mancode workflow clean [--older-than 30d] [--dry-run]
 mancode manps [area]
 mancode refresh-style
@@ -276,6 +280,8 @@ mancode version
 
 ### `mancode status`
 
+以下是 UI 项目的输出示例，并非默认技术栈：
+
 ```text
 mancode v0.2.0
 
@@ -295,9 +301,9 @@ Installed platforms:
 Platform status:
   ✓ Claude Code: ready (.claude/)
   ✓ Cursor: ready (.cursor/rules/)
-  ✓ Codex CLI: ready (AGENTS.md + .codex/skills/)
+  ✓ Codex CLI: ready (AGENTS.md + .agents/skills/)
   ✓ GitHub Copilot: ready (.github/copilot-instructions.md)
-  ✓ ZCode: ready (AGENTS.md + .zcode/skills/)
+  ✓ ZCode: ready (AGENTS.md + .agents/skills/)
 
 Hooks:
   ✓ session-start.sh
@@ -337,12 +343,14 @@ mancode status --json
 
 ### `mancode workflow`
 
-创建和管理 `/man8`、`/man` 使用的 workflow 元数据。
+创建和管理 `/mamba`、`/man` 和 `/manteam` 使用的受校验 workflow 元数据。关联 `/mamba` 子任务只能在父任务处于 Step 6 且正在进行时创建。
 
 ```bash
 mancode workflow create man "refactor auth module"
-mancode workflow update <taskId> --step 4
-mancode workflow show <taskId>
+mancode workflow update <taskId> --step 4 --plan-version 2
+mancode workflow create mamba "verify auth regression" --parent-task <taskId>
+mancode workflow update <mambaTaskId> --status completed --outcome verified
+mancode workflow show <taskId> --json
 mancode workflow clean --older-than 30d --dry-run
 ```
 
@@ -368,10 +376,11 @@ mancode manps config
 
 ### `mancode refresh-style`
 
-重新扫描项目设计 token，并更新：
+刷新项目 profile；检测到 UI 资产时，还会重新扫描设计 token。它会更新：
 
 ```text
 .mancode/aesthetics/style-tokens.json
+.mancode/project-profile.json
 ```
 
 Claude Code 会通过 hooks 读取刷新后的 token。Cursor、Codex CLI 和 GitHub Copilot 使用静态生成的
@@ -393,13 +402,15 @@ mancode/
 │
 ├── Skills
 │   ├── solo/SKILL.md
-│   ├── man8/SKILL.md
+│   ├── mamba/SKILL.md
 │   ├── man/SKILL.md
 │   ├── manteam/SKILL.md
-│   └── manps/SKILL.md
+│   ├── manps/SKILL.md
+│   └── mansolo/SKILL.md
 │
 └── Subagents
     ├── Scout
+    ├── Plan Coach
     ├── Head Coach
     ├── Film Analyst (Offense)
     └── Film Analyst (Defense)
@@ -410,7 +421,7 @@ mancode/
 - mancode 本地优先。
 - 扫描结果写入 `.mancode/`。
 - mancode 不发送遥测。
-- `.mancode/` 默认被 git 忽略，除非你选择提交其中部分文件。
+- mancode 不会改写项目的 `.gitignore`。提交前请检查 `.mancode/`，并忽略可能含敏感信息的本地 workflow 证据或浏览器产物。
 - `/manps` 默认只扫描；进入整改前应明确确认代码改动。
 - force push、schema migration、批量删除等不可逆操作需要明确人工确认。
 
@@ -419,7 +430,7 @@ mancode/
 | 阶段 | 重点 |
 |---|---|
 | MVP-1 | solo 模式、审美扫描、Claude Code hooks |
-| MVP-2 | `/man8`、`/man`、`/manteam`、`/manps` 和教练组 subagents |
+| MVP-2 | `/mamba`、`/man`、`/manteam`、`/manps` 和教练组 subagents |
 | MVP-3 | Cursor、Codex CLI、GitHub Copilot 适配 |
 | 公开发布 | npm 稳定版、marketplace 分发、文档和演示 |
 
@@ -427,8 +438,7 @@ mancode/
 
 ### `mancode init` 提示"not a project directory"
 
-mancode 要求目标目录有 `.git` 或 `package.json`。请在 git 仓库或 Node.js
-项目目录中运行 `mancode init`。
+mancode 要求目标目录有 `.git` 或已识别的项目 manifest（如 `package.json`、`pyproject.toml`、`go.mod`、`Cargo.toml`、`pom.xml`、`build.gradle`、`build.gradle.kts`、`Package.swift` 或 `pubspec.yaml`）。请在 git 仓库或支持的项目目录中运行 `mancode init`。
 
 ### Claude Code hooks 不生效
 
@@ -449,15 +459,15 @@ mancode 要求目标目录有 `.git` 或 `package.json`。请在 git 仓库或 N
 
 ### ZCode skills 未出现
 
-确认 `.zcode/skills/man8/SKILL.md` 到 `.zcode/skills/mansolo/SKILL.md`
+确认 `.agents/skills/mamba/SKILL.md` 到 `.agents/skills/mansolo/SKILL.md`
 都存在，然后重启或刷新 ZCode。当前尚不生成 ZCode `/man*` slash commands，
 因为 workspace command 的文件路径仍需显式验证。
 
 ### Cursor rules 不触发
 
 确认 `.cursor/rules/mancode-*.mdc` 文件存在。`alwaysApply: true` 的规则
-（context、practice、solo）在每次对话加载。模式规则（man8、man、manteam、
-manps）按 description 触发——输入 `/man8` 等关键词即可激活。
+（context、practice、solo）在每次对话加载。模式规则（mamba、man、manteam、
+manps）按 description 触发——输入 `/mamba` 等关键词即可激活。
 
 ### 如何完全重装