ys-team 0.2.0

package/skills/ys-team-doc-build/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: ys-team-doc-build
+description: "Build or rebuild the reality index for a ys-team project. Generates module-level index with relationship graph and business summaries. Called automatically by ys-team-init and ys-team-rebuild, or invoked manually."
+---
+
+# ys-team-doc-build
+
+Use this skill to generate or rebuild the project's reality index.
+
+## Purpose
+
+The reality index (`docs/project/module-index.md`) gives AI team roles a shared understanding of the project's module structure and dependencies — so that during spec discussion, roles can reason about impact scope without re-exploring the codebase from scratch each time.
+
+This is not javadoc. It is not for humans to read. It is a collaboration substrate for AI roles.
+
+## Core Principles
+
+- **Relationship-first**: Record cross-file relationships (inter-module dependencies, data access, messaging, external APIs). These are expensive to re-derive dynamically.
+- **Summary-aided**: Each module gets 2–3 sentences on business responsibility. This lets roles assess impact scope during control phase without reading source files.
+- **Scale-adaptive**: Index granularity adjusts to project size.
+- **Language-agnostic**: Detect project type from build files; adapt index structure to match.
+
+## Scale Strategy
+
+| Project Scale | Index Strategy |
+|--------------|----------------|
+| Small (<500 files) | Detailed module index + key class descriptions |
+| Medium (500–2000 files) | Module index + entry point lists |
+| Large (>2000 files) | Core modules only + layered entry point lists |
+
+## Execution Steps
+
+### Phase 1: Project Analysis
+
+1. **Detect language and build tool**:
+   - `pom.xml` → Java Maven
+   - `build.gradle` → Java Gradle
+   - `pyproject.toml` or `setup.py` → Python
+   - `package.json` → Node.js / TypeScript
+   - Other → Generic
+
+2. **Estimate scale**: Count source files (exclude build output dirs: `target/`, `dist/`, `node_modules/`, `venv/`, `.git/`)
+
+3. **Select strategy** based on file count
+
+### Phase 2: Module Discovery
+
+Identify module boundaries using language-specific signals:
+
+- **Java Maven**: Parse `<modules>` in root `pom.xml`; top-level application classes (`@SpringBootApplication`); DDD layer packages (`application/`, `domain/`, `service/`)
+- **Java Gradle**: Parse `include` in `settings.gradle`
+- **Python**: Top-level packages under `src/` or project root
+- **Node.js/TS**: Directories with `index.ts` or dedicated `package.json`
+- **Generic**: Top-level directories with source files
+
+### Phase 3: Relationship Extraction
+
+For each module, use Grep to extract:
+
+- Entry points (service classes, application classes, API controllers)
+- Domain/business services
+- Data access layer (mappers, repositories, DAOs)
+- Outbound messaging (MQ producers, event publishers)
+- Inbound messaging (MQ listeners, event consumers)
+- Scheduled jobs
+- External service dependencies (API clients, SDK calls)
+- Which other modules depend on this module (reverse dependency)
+- Configuration key prefixes (Apollo, env vars, application.properties)
+
+### Phase 4: Summary Generation
+
+Read the primary entry class for each module. Generate 2–3 sentences describing:
+- What business problem this module solves
+- Its primary responsibilities
+- Any notable design pattern (strategy, adapter, etc.) if central to understanding
+
+Keep summaries factual and stable — avoid implementation details that change frequently.
+
+### Phase 5: Index Generation
+
+Write `docs/project/module-index.md` using the format below.
+
+For medium and large projects, also generate `docs/project/entry-points/generate.sh` — a shell script that, when run, produces fresh lists of key entry points (services, mappers, listeners, jobs).
+
+## Output Format
+
+```markdown
+# Module Index
+
+**Project Type**: [detected type]
+**Project Scale**: [Small/Medium/Large] (~N files)
+**Index Strategy**: [strategy description]
+**Last Updated**: [YYYY-MM-DD]
+
+## [Module Name]（[Chinese label if applicable]）
+**职责**：[2–3 sentence business summary]
+
+**关系**：
+- 入口：[entry class(es)]
+- 领域服务：[domain service classes] (if applicable)
+- [Framework] 服务：[service impl classes] (if applicable)
+- 数据访问：[mapper/repository classes]
+- 外部依赖：[external API/SDK names]
+- 被依赖：[modules that depend on this one, with brief reason]
+- 消息：[listener/producer classes and topic] (omit if none)
+- 定时任务：[job class names] (omit if none)
+- 配置前缀：[config key prefix] (omit if unknown)
+```
+
+Omit fields that do not apply. Do not fabricate entries.
+
+## Entry Point Script (Medium/Large projects)
+
+Generate `docs/project/entry-points/generate.sh`:
+
+```bash
+#!/bin/bash
+# Regenerate key entry point lists for this project
+# Run from project root
+
+OUTDIR="docs/project/entry-points"
+mkdir -p "$OUTDIR"
+
+# Example for Java Maven + Dubbo + MyBatis + RocketMQ:
+grep -r "@DubboService" --include="*.java" -l | sort > "$OUTDIR/dubbo-services.txt"
+ls src/main/resources/mapper/*.xml 2>/dev/null | sed 's|.*/||;s|Mapper.xml||' | sort > "$OUTDIR/mappers.txt"
+grep -r "@RocketMQMessageListener\|implements.*Listener" --include="*.java" -l | sort > "$OUTDIR/listeners.txt"
+grep -r "@Scheduled\|@Job\|@ElasticJob" --include="*.java" -l | sort > "$OUTDIR/jobs.txt"
+
+echo "Entry points updated in $OUTDIR/"
+```
+
+Adapt the script to the actual project's framework and conventions. Make it executable.
+
+## Validation
+
+Before finalizing:
+
+- Every module listed has a non-empty **职责** summary
+- Every dependency relationship is bidirectional (if A depends on B, B lists A under 被依赖)
+- No invented entries — only what Grep or Read confirmed
+
+## Token Cost Check
+
+If generation would exceed ~80k tokens (e.g., large project with many modules), warn the user and suggest reducing scope to core modules only.
+
+## Trigger Conditions
+
+- Automatically called by `ys-team-init` after baseline generation
+- Automatically called by `ys-team-rebuild` after baseline update
+- Manually invoked when project module structure has materially changed
+
+## After Generation
+
+Inform the user:
+- Location of the generated index
+- Number of modules indexed
+- Whether an entry point script was generated
+- Suggested next step (e.g., run `ys-team-rebuild` if project has evolved, or begin spec work)

package/skills/ys-team-init/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: ys-team-init
+description: "Initialize a repository-local ys-team baseline once. Generate the smallest useful .ys_team setup from project reality without forcing a heavy process."
+---
+
+# ys-team-init
+
+Use this skill when a repository wants to start using `ys-team` and does not yet have a project-local `.ys_team/`.
+
+## Purpose
+
+Create the first project-local ys-team baseline with the lightest useful footprint.
+
+`ys-team-init` is not a project modeling ceremony.
+It is a one-time repository specialization step.
+
+Its default workflow source is `examples/baseline/`.
+
+## 语言检测
+
+Init 的第一步是确认用户主语言，所有角色名、角色卡、team.md、selection rules 将使用该语言。
+
+检测逻辑：
+1. 检查用户 CLAUDE.md 中是否有语言偏好声明
+2. 检查系统 locale 环境
+3. 如无法判断，直接询问用户："团队角色使用什么语言命名？（如：中文/English）"
+
+确认后：
+- baseline 中的角色模板按用户语言生成
+- `team.md` 的选择规则使用用户语言
+- 角色卡文件名使用用户语言
+
+## Core Rules
+
+- Read repository reality before generating anything.
+- Start from `examples/baseline/` as the default workflow source.
+- Prefer the smallest useful local baseline.
+- Do not require the user to understand internal ys-team structure first.
+- Do not block init only because some docs are missing; generate a minimal skeleton when needed.
+- Keep the result repository-local.
+
+## Minimum Outputs
+
+Generate or adapt:
+
+- `.ys_team/README.md`
+- `.ys_team/team.md`
+- `.ys_team/methods.md`
+- `.ys_team/policy.md`
+- `.ys_team/templates/`
+- `docs/specs/`
+- `docs/roadmap/`
+
+When the repository lacks a current-state project doc, create a minimal `docs/project/overview.md` skeleton.
+
+If the repository does not have an `AGENTS.md`, generate one from `examples/baseline/AGENTS.md`, adapted to the project's name and stack.
+
+## Language Sensitivity
+
+The method is language-agnostic, but local wording should match project reality.
+
+Examples:
+
+- Python services should reflect their actual package manager, test command, and runtime boundaries.
+- Java services should reflect their build tool, multi-module structure, compatibility concerns, release order, migration surface, and async contracts.
+
+## Success Criteria
+
+The repository can start using ys-team immediately after init, without first rewriting the whole project.
+
+That means:
+
+- discussion can converge into spec
+- spec can guide execution
+- execution can be accepted with evidence
+
+## 工具内化（Toolbox Internalization）
+
+基础 init 完成后，自动执行工具内化流程：
+
+### 步骤
+
+1. **创建 toolbox 目录**：从 `examples/baseline/.ys_team/toolbox/` 复制模板（`_sources.md`、`_candidates.md`）
+
+2. **扫描项目类型**：根据仓库中的文件特征判断项目类型：
+   - `requirements.txt` / `pyproject.toml` / `setup.py` → python-backend
+   - `pom.xml` / `build.gradle` → java-backend
+   - `package.json` + React 依赖 → frontend-react
+   - 前后端都有 → fullstack
+   - 无法判断 → general
+
+3. **匹配 registry 推荐**：读取 `registry/{项目类型}.md` + `registry/general.md`，合并推荐列表
+
+4. **检索与安装**：
+   - 对推荐列表中的每个工具，检查是否已安装
+   - 已安装的：直接进入内化流程
+   - 未安装但有明确来源的：静默安装后内化
+   - 如果用户安装了 `find-skills` 等检索工具，额外根据项目特征搜索适合的 skill，和用户确认后安装
+
+5. **选择性内化**：对每个选中的工具：
+   - 阅读原 skill 内容
+   - 提取对团队有用的部分（不是完整复制）
+   - 改写成符合 ys-team 方法论的格式
+   - 保留源链接（skill 名、版本、URL）
+   - 写入 `.ys_team/toolbox/{能力名}.md`
+
+6. **角色绑定**：根据推荐的绑定角色建议，更新 `team.md` 中对应角色的 `tools` 字段
+
+7. **更新源索引**：将所有内化工具记录到 `.ys_team/toolbox/_sources.md`
+
+### 内化文件格式
+
+```markdown
+# [能力名称]
+
+source: [原 skill 全名]
+source_url: [GitHub 或 marketplace 地址]
+version: [内化时的版本]
+internalized: [日期]
+
+## 团队用法
+
+[改写后的、融入团队方法论的能力描述]
+
+## 绑定角色
+
+- [角色名]（[使用场景]）
+
+## 重新内化触发条件
+
+[什么情况下应该回到原 skill 重新学习]
+```
+
+### 完成提示
+
+```
+团队基础配置已完成，已内化 N 个工具。
+如需调整工具配置，可运行 /ys-team-rebuild。
+```
+
+## Status 初始化
+
+Init 时从 `examples/baseline/.ys_team/status.md` 复制空模板到项目的 `.ys_team/status.md`。
+
+提示用户可选配置 hooks 以增强状态追踪：
+
+```
+团队状态追踪已初始化（.ys_team/status.md）。
+各工作流环节会在关键节点自动更新状态。
+
+如需更细粒度的事件采集（文件变更、session 等），可参考 scripts/hooks-template.json 配置 Claude Code hooks。
+```
+
+## After Init
+
+- Use the generated local `.ys_team/` as the project's baseline.
+- Treat `examples/baseline/` as the default workflow source, not as a rigid project copy.
+- Do not rerun init for normal project work.
+- Use `ys-team-rebuild` only when project reality has materially changed.
+
+After `.ys_team/` is generated, automatically invoke `ys-team-doc-build` to create the initial reality index (`docs/project/module-index.md`). This is required — the shared reality index is part of the minimum useful baseline.

package/skills/ys-team-rebuild/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: ys-team-rebuild
+description: "Reassess an existing project-local ys-team baseline and minimally update it when the project, stack, or collaboration shape has materially changed."
+---
+
+# ys-team-rebuild
+
+Use this skill when a repository already has `.ys_team/`, but the current local method no longer matches repository reality.
+
+## Purpose
+
+Refresh the local ys-team baseline without reintroducing heavy process or unnecessary churn.
+
+## Rebuild Triggers
+
+- stack changed
+- project gained or lost major modules
+- existing local roles no longer fit delivery reality
+- current templates no longer match acceptance or rollback needs
+- documentation authority is no longer aligned with the codebase
+
+## Rules
+
+- Change the smallest surface that fixes the mismatch.
+- Preserve stable local wording and role boundaries when they still fit.
+- Keep the local method weak-guidance, strong-result.
+- Update local templates only when repository reality really changed.
+
+## Version Check
+
+Before rebuilding, check version alignment:
+
+1. Read project `.ys_team/VERSION` (if exists)
+2. Compare with `examples/baseline/.ys_team/VERSION` from the installed ys-team skill
+3. If versions differ, inform user: "ys-team baseline 有更新（当前 X.Y.Z → 最新 A.B.C）。是否同步？"
+4. On user confirmation: merge baseline updates into project `.ys_team/`, preserving project-local customizations
+5. Update project `.ys_team/VERSION` to match baseline
+
+## 工具重新内化
+
+Rebuild 时除了更新基础配置，还需评估和更新工具内化：
+
+### 步骤
+
+1. **检查候选列表**：读取 `.ys_team/toolbox/_candidates.md`，这些是用户在工作流中显式使用过的未内化 skill，作为内化评估输入
+
+2. **检查深化标记**：遍历 `.ys_team/toolbox/*.md`（排除 `_sources.md` 和 `_candidates.md`），检查是否有"需要深化"标记
+
+3. **重新匹配推荐**：如果项目类型发生变化，重新匹配 `registry/` 推荐
+
+4. **处理候选**：
+   - 对每个候选工具，评估是否值得内化
+   - 和用户确认后，执行内化流程（同 init 的内化步骤）
+   - 处理完毕后清空 `_candidates.md`
+
+5. **深化已有工具**：
+   - 对标记"需要深化"的工具，回到原 skill 源（通过 `_sources.md` 中的链接）
+   - 重新阅读原 skill 最新内容
+   - 提取更深入的部分，更新内化文件
+   - 清除深化标记
+
+6. **更新角色绑定**：如果新增或移除了工具，同步更新 `team.md` 中的 tools 字段
+
+7. **更新源索引**：同步 `_sources.md`
+
+### 自我学习
+
+当团队成员在某个环节发现内化程度不够时，可以在对应的内化文件末尾追加：
+
+```markdown
+## 需要深化
+
+[具体哪方面不够，需要从原 skill 补充什么]
+```
+
+下次 rebuild 时会自动处理。
+
+## Doc-Build Integration
+
+After baseline update is complete, automatically invoke `ys-team-doc-build` to rebuild the reality index. This ensures `docs/project/module-index.md` reflects current project structure after any rebuild.
+
+## Output
+
+Summarize:
+
+- what changed
+- why it changed
+- whether existing specs need follow-up
+- 工具变化（新增内化、深化、移除）

package/skills/ys-team-spec-talk/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: ys-team-spec-talk
+description: Discuss a non-trivial change using the repository's local .ys_team setup, load only the selected local role files, escalate to additional roles when needed, and output specs or roadmaps only when the current objective actually requires them.
+---
+
+# ys-team-spec-talk
+
+Use this skill to discuss a non-trivial change using project-local team guidance.
+
+## Read Order
+
+1. `.ys_team/README.md`
+2. `.ys_team/team.md`
+3. `.ys_team/methods.md` if present
+4. `.ys_team/policy.md`
+5. repository project/docs context
+6. relevant active or queued specs or roadmaps if the task extends existing work
+
+## Loading Discipline
+
+- Start by reading only the short header block of candidate role files.
+- Load full role files only for roles that actually participate.
+- Do not retain or write full discussion transcripts.
+
+## Intent First
+
+Do not assume every discussion should immediately draft a spec.
+
+Before selecting the exact path, infer from the conversation:
+
+- what object is being discussed now
+- what the current objective is
+- whether the current blocker is clarity, execution readiness, missing evidence, missing expertise, or something else
+
+If that is materially unclear, ask a concise clarification before continuing.
+
+## Output Routing
+
+- initiative-level executable acceptance work -> `docs/specs/`
+- stage or directional planning -> `docs/roadmap/`
+- discussion-only clarification -> no required repo artifact unless the user asked for one
+
+## Standard Flow
+
+1. Select the default discussion team from `.ys_team/team.md` unless the local method says otherwise.
+2. Run one internal discussion round using the selected roles.
+3. Identify risks, disagreements, capability gaps, and whether the current objective requires a spec, a roadmap, a revision to an existing artifact, or no file output.
+4. After each round, check whether the discussion is still converging (see `.ys_team/methods.md` Discussion Cost Awareness). If warning signs appear, prefer to stop and emit a result card rather than silently entering another round.
+5. If a gap exists and an external role may be needed, stop and produce an external support request instead of introducing that role immediately.
+6. Ask the user before introducing an external role.
+7. Only after approval, load the external role and continue the next round.
+8. Assign one participating role with `discussion.report` responsibility to write the final summary.
+9. If the current objective requires repository output, write it using `.ys_team/templates/control.md` and `.ys_team/templates/work.md` for specs, or `.ys_team/templates/roadmap-version.md` for roadmaps.
+
+## Required Discussion Result
+
+Every substantial discussion round must end with a result card for the user. Light discussion should still return a compact result card and role brief.
+
+Required fields:
+
+- `Current Mode`
+- `Decision`: `PASS`, `BLOCKED`, or `REJECT`
+- `Current State`
+- `Why`
+- `Needed Changes`
+- `Next Step`
+
+Optional fields when needed:
+
+- `Need Your Input`
+- `External Support Request`
+
+Also include a short `Role Brief` section that summarizes each participating role's current conclusion in one or two lines. User-facing role names should prefer repository-local Chinese titles when available; otherwise use a readable fallback such as `中文标题（role-id）` or `role-id`.
+
+Do not end with a vague recap.
+
+## Required Additions For Written Specs Or Roadmaps
+
+Every generated or updated spec should include:
+
+- `Collaboration Summary`
+- `Discussion Digest`
+
+Every generated or updated roadmap should include role participation and final conclusion summary consistent with the roadmap template.
+
+These sections should summarize:
+
+- which roles participated
+- the user-facing role titles when available
+- how many rounds were used
+- what escalations happened
+- estimated discussion cost
+- whether `ys-team-submit` is recommended for delivery review
+- each role's final contribution, not a transcript
+
+## 进化感知（角色缺口）
+
+讨论过程中，主动检测是否存在角色缺口：
+
+**触发条件**（满足任一即触发）：
+- 讨论涉及某专业领域（安全、数据库迁移、无障碍等），但 `team.md` 中没有对应角色
+- result card 中出现 `External Support Request`，且原因是缺少专业角色
+- 讨论收敛为 BLOCKED，且阻塞原因涉及"缺少 XX 领域的评审/判断"
+
+**触发后动作**：
+1. 写入 `.ys_team/evolution/requests.md` 的"待处理"区：
+   ```
+   ### [EVO-YYYY-MM-DD-N] [日期] [类型: 角色]
+   
+   - 来源环节：spec-talk
+   - 关联 Spec：[当前讨论的 spec]
+   - 缺口描述：[具体缺什么角色/能力]
+   - 发现角色：[哪个角色发现的]
+   - 建议方案：[建议引入什么角色]
+   - 讨论状态：待讨论
+   ```
+2. 在当前响应中提示用户：
+   ```
+   发现团队能力缺口：[描述]。已记录进化申请（EVO-YYYY-MM-DD-N）。
+   建议发起一轮进化评估讨论，由团队评估是否引入新角色。
+   ```
+3. 如果用户同意，立即发起进化评估讨论（由现有角色参与，讨论是否引入新角色）
+4. 讨论收敛后：PASS → 创建角色卡并加入 team.md / REJECT → 记录原因关闭申请
+
+## Status 写入
+
+讨论收敛后（产出 result card 时），必须同步更新 `.ys_team/status.md`：
+
+1. 读取当前 `.ys_team/status.md`
+2. 更新以下内容：
+   - `updated` 时间戳
+   - `活跃 Spec` 表：新增或更新当前讨论的 spec 条目（阶段 = spec-talk，状态 = 讨论中/已收敛）
+   - `最新判断` 表：追加本轮 result card 的决定（PASS/BLOCKED/REJECT），保留最近 10 条
+   - `阻塞项`：如果决定为 BLOCKED，追加阻塞原因；如果之前阻塞已解除，移除
+   - `待办`：根据 Next Step 更新
+3. 写入完成后再输出 Host Summary
+
+此写入是 spec-talk 的固定环节，不可跳过。
+
+## Host Summary
+
+After writing or updating the target document (or concluding a discussion-only round), close the response with a **[主持人]** summary block. This block is mandatory — it is the visible signal that ys-team workflow ran.
+
+Format:
+
+```
+---
+**[主持人]** ys-team · spec-talk
+
+[1–2 sentences describing what was decided or produced.]
+
+- 参与角色：[localized role titles, comma-separated]
+- 决策：PASS / BLOCKED / REJECT
+- 产出：[artifact path, e.g. docs/specs/active/xxx/control.md, or "无文件输出"]
+- 下一步：[one concrete next action]
+---
+```
+
+Rules:
+- Use repository-local localized role titles when available; otherwise use readable fallback.
+- Keep the block to 5–7 lines. Do not expand into a full recap.
+- If the discussion was BLOCKED or REJECT, the 下一步 line must state what is needed to unblock.
+- Do not omit this block even for discussion-only rounds with no file output.

package/skills/ys-team-spec-work/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: ys-team-spec-work
+description: "Silent internal execution capability for approved ys-team specs. Execute repository work against the local spec baseline and keep docs and evidence aligned."
+---
+
+# ys-team-spec-work
+
+This is a silent internal skill.
+
+Use it to execute approved work against an existing repository spec.
+
+## Purpose
+
+- implement against the approved spec
+- keep write-scope explicit
+- update authoritative docs in the same delivery
+- collect evidence for acceptance
+
+## Rules
+
+- do not execute against vague discussion alone
+- use the local spec as the working contract
+- keep implementation, docs, and evidence in sync
+- surface blockers instead of silently changing scope
+
+## 进化感知（工具缺口）
+
+执行过程中，主动检测是否存在工具缺口：
+
+**触发条件**（满足任一即触发）：
+- 执行需要某种工作方法（如 TDD、前端设计规范、性能基准测试）但 `.ys_team/toolbox/` 中没有对应工具
+- 执行到某个步骤发现"如果有 XX 工具会更高效/更安全"
+- 角色的 tools 字段为空，但执行内容明显需要工具辅助
+
+**触发后动作**：
+1. 写入 `.ys_team/evolution/requests.md` 的"待处理"区：
+   ```
+   ### [EVO-YYYY-MM-DD-N] [日期] [类型: 工具]
+   
+   - 来源环节：spec-work
+   - 关联 Spec：[当前执行的 spec]
+   - 缺口描述：[具体缺什么工具/能力]
+   - 发现角色：[哪个角色在执行中发现的]
+   - 建议方案：[建议内化什么工具]
+   - 讨论状态：待讨论
+   ```
+2. 在当前响应中提示用户：
+   ```
+   发现工具缺口：[描述]。已记录进化申请（EVO-YYYY-MM-DD-N）。
+   建议在当前 spec-work 完成后发起进化评估，由团队评估是否内化新工具。
+   ```
+3. **不中断当前执行**——工具缺口不阻塞 spec-work，先记录，完成后再评估
+
+## Status 写入
+
+在以下关键节点必须同步更新 `.ys_team/status.md`：
+
+**执行开始时**：
+1. 读取当前 `.ys_team/status.md`
+2. 更新 `updated` 时间戳
+3. 更新 `活跃 Spec` 表：当前 spec 阶段改为 spec-work，状态改为"执行中"
+4. 写入
+
+**执行完成时**：
+1. 读取当前 `.ys_team/status.md`
+2. 更新 `updated` 时间戳
+3. 更新 `活跃 Spec` 表：当前 spec 状态改为"待验收"
+4. `待办` 追加：建议运行 submit 验收
+5. 写入
+
+**遇到阻塞时**：
+1. 更新 `活跃 Spec` 表状态为"已阻塞"
+2. `阻塞项` 追加阻塞原因
+3. 写入
+
+此写入是 spec-work 的固定环节，不可跳过。
+
+## Visible Marker
+
+每次 `spec-work` 对用户输出后，必须以以下块结尾，作为工作流正在执行的可见标志：
+
+```markdown
+---
+**[执行中]** ys-team · spec-work
+
+[1–2 句说明当前执行内容或本轮完成内容。]
+
+- 关联 Spec：[spec id 或 work 文件]
+- 状态：[执行中 / 待验收 / 已阻塞]
+- 下一步：[一个明确动作]
+---
+```