Docs Maintenance

Quick Start

• Run scripts/docs_inventory.py <path> to inventory Markdown docs and common documentation signals.
• Run ../workflow-maintainer/scripts/audit_workflow_library.py when maintaining this agent-workflows repository.
• Read references/docs-maintenance-checklist.md before finalizing documentation changes.
• Follow shared safety, validation, and scope rules in ../_shared/references/skill-operating-rules.md.
• Keep edits scoped to the documentation goal; do not change workflow semantics accidentally.

Maintenance Workflow

1. Identify the doc change type: new doc, renamed file, changed workflow step, new skill, example update, typo, or consistency fix.
2. Inventory docs:

python3 scripts/docs_inventory.py /path/to/agent-workflows

3. Update all cross-references affected by the change:

• README inventories and setup instructions.
• Workflow routing and library-loading references.
• Skill docs and canonical agent metadata prompts in agents/interface.yaml.
• Shared conventions if repeated wording appears in multiple workflow files.

4. Validate links, anchors, inventories, and helper scripts.
5. Report changed docs, validation run, and any skipped checks.

Output Rules

• Prefer precise wording over broad rewrites.
• Preserve existing tone and structure.
• Keep examples executable or clearly marked as templates.
• Do not add duplicate safety language if a shared reference is the canonical source.

Migration Planning

Quick Start

• Run scripts/migration_signal_scan.py <path> when a repository or change path is available.
• Read references/migration-checklist.md before finalizing the plan.
• Follow shared safety, validation, and scope rules in ../_shared/references/skill-operating-rules.md.
• Prefer expand-contract migrations for databases and public contracts.
• Do not run migrations, mutate data, deploy, commit, or push without explicit permission.

Planning Workflow

1. Identify what is migrating: schema, data, API, event contract, config, dependency, or runtime behavior.
2. Define compatibility requirements: old code with new data, new code with old data, old clients with new API, rollback path.
3. Split rollout into phases:

• Prepare: additive changes, dual-read or dual-write, feature flags.
• Backfill: idempotent, resumable, observable data changes.
• Switch: traffic or behavior moves to the new path.
• Contract: remove old fields, code, flags, or compatibility shims only after safety is proven.

4. Produce a migration plan with validation and rollback for every phase.
5. Mark irreversible steps explicitly and require approval before execution.

Output Rules

• Include deployment order and rollback order.
• Include data validation queries or checks.
• Include monitoring and alerting signals.
• Include blast radius and expected duration.
• State what must be true before removing compatibility code.

Performance Review

Quick Start

• Run scripts/performance_signal_scan.py <path> when a repository or changed-file path is available.
• Read references/performance-review-checklist.md before finalizing findings.
• Follow shared safety, validation, and scope rules in ../_shared/references/skill-operating-rules.md.
• Focus on hot paths, data size, request rate, and operational cost.
• Stay read-only unless the user explicitly asks for fixes.

Review Workflow

1. Establish expected scale: records, requests per second, concurrency, payload size, memory budget, latency budget.
2. Identify hot paths and expensive dependencies: database, network, filesystem, CPU, serialization, rendering, queues.
3. Run signal scan:

python3 scripts/performance_signal_scan.py /path/to/repo-or-file

4. Trace loops, queries, API calls, and allocations through realistic worst-case inputs.
5. Recommend validation: targeted tests, profiling, explain plans, benchmarks, load tests, or production metrics.

Output Rules

• Findings must include scale assumptions and the cost mechanism.
• Distinguish measured issues from plausible risks.
• Prefer concrete mitigations: add pagination, batch calls, add index, cache with invalidation, stream data, avoid repeated work.
• If no findings are found, state residual risk and whether profiling or benchmarks were skipped.

Project Initialization

Quick Start

• Find the nearest agent-workflows library. If it is not near the workspace, ask for AGENT_WORKFLOWS_ROOT or the library path.
• Read project-initialization-agent-workflow.md.
• Read ../_shared/references/skill-operating-rules.md.
• Apply the workflow directly. Do not just restate prompt templates unless the user explicitly asks for templates.
• Require an explicit target directory before creating files.

Operating Rules

• Use this skill for new projects, greenfield codebases, initial repository scaffolds, and project tooling setup.
• Treat the workflow file as the source of truth for preflight, triage, planning, scaffolding, validation, and handoff.
• Run the workflow's preflight before triage so target-directory state, parent workspace rules, local instructions, available tooling, and unrelated local changes are known.
• For Minimal projects, scaffold directly with sensible defaults after confirming the target directory.
• For Standard and Complex projects, follow the plan/review/scaffold/validate/handoff sequence in the workflow.
• Do not commit or push without explicit permission.
• Do not overwrite, revert, delete, or reformat unrelated user changes.
• Stop and ask if the target directory is missing, ambiguous, or unexpectedly pre-populated.

Execution Guidance

1. Confirm the target directory and inspect its current state.
2. Load and follow the triage gate from project-initialization-agent-workflow.md.
3. Select the appropriate path:
   • Minimal: use the Minimal Project Prompt.
   • Standard: gather requirements, create/review the plan, then scaffold and validate.
   • Complex: complete the full workflow with separate review and validation passes.
4. When scaffolding, keep generated files inside the confirmed target directory.
5. Validate with the ecosystem's relevant install, lint, type check, build, test, and smoke commands.
6. Report files created, tooling configured, validation results, deviations, known limitations, and next steps.

References

• ../../project-initialization-agent-workflow.md
• ../_shared/references/skill-operating-rules.md

Handoff

• If the initialized project is ready for feature work, hand off to the feature development workflow.
• If validation exposes a narrow defect in the scaffold, fix it inside this workflow.
• If validation exposes a larger design or technology decision, return to the project plan before changing the scaffold.

Release Prep

Quick Start

• Run scripts/prepare_release_report.py from this skill directory, or by absolute path, to collect release inputs.
• Run the workflow-maintainer audit before drafting release notes if that skill is available in this repository.
• Read references/release-checklist.md for release judgment checks and final handoff content.
• Follow shared safety, validation, and scope rules in ../_shared/references/skill-operating-rules.md.
• Do not create tags, commits, pushes, GitHub releases, or package uploads without explicit permission.

Release Workflow

1. Establish repository state:

python3 scripts/prepare_release_report.py

2. Run deterministic validation:

python3 ../workflow-maintainer/scripts/audit_workflow_library.py
python3 ../workflow-automation/scripts/find_workflow_library.py --json

3. Inspect changed files and classify release impact:

• major: breaking workflow semantics, renamed files, removed workflows, or incompatible skill behavior.
• minor: new workflows, new skills, new checks, or backward-compatible capability additions.
• patch: typo fixes, docs clarifications, metadata corrections, non-breaking script fixes.

4. Draft release notes with:

• Summary
• User-facing changes
• New or changed skills
• Validation performed
• Breaking changes, if any
• Migration notes, if any
• Known limitations or follow-ups

5. Final handoff must state whether commits, tags, pushes, and publish actions were performed. Default answer should be no unless the user explicitly approved them.

Maintenance Rules

• Keep release notes factual and tied to observed changes.
• Do not invent version numbers if the repo does not define a versioning convention; ask or label the release as “unversioned draft.”
• Treat failed audits, broken links, missing required files, stale README inventory, invalid skill metadata, or unvalidated helper scripts as release blockers.
• If the working tree is not a Git repository, produce a filesystem-based release report and state that Git diff metadata was unavailable.

Security Review

Quick Start

• Use this skill as a focused review layer, not a replacement for normal correctness review.
• Run scripts/security_signal_scan.py <path> when a repository or changed-file path is available.
• Read references/security-review-checklist.md before finalizing findings.
• Follow shared safety, validation, and scope rules in ../_shared/references/skill-operating-rules.md.
• Stay read-only unless the user explicitly asks for fixes.
• Do not commit, push, deploy, rotate secrets, revoke keys, or run destructive commands without explicit permission.

Review Workflow

1. Establish scope:

• Review target: PR, branch, workspace changes, or specific files.
• Comparison base, if reviewing a diff.
• Trust boundaries affected by the change.
• Security-sensitive domains touched: auth, permissions, secrets, payments, PII, file upload, network calls, command execution, database access, dependency upgrades, logging, or telemetry.

2. Run signal scan:

python3 scripts/security_signal_scan.py /path/to/repo-or-file

3. Manually trace high-risk flows:

• External input to sink: database query, shell command, HTML/template rendering, file path, network request, deserialization, logging, or redirect.
• Identity to authorization decision: authentication source, user/session lookup, role/permission check, tenant or ownership boundary.
• Secret creation to storage/use/logging.
• Sensitive data from storage to response, logs, analytics, or third-party calls.

4. Report findings first, ordered by severity. Use this format:

### [Severity] Finding title

- Location:
- Problem:
- Why it matters:
- Attack or failure scenario:
- Recommended fix:
- Severity: Critical / Major / Minor / Nit

5. If no findings are found, state that explicitly and list residual risks, skipped checks, and validation performed.

Severity Guidance

• Critical: Direct data exposure, authentication bypass, authorization bypass, credential leak, remote code execution, destructive data mutation, or exploitable injection.
• Major: Missing edge-case authorization, unsafe input handling with plausible exploit path, sensitive logs, insecure defaults, unsafe dependency upgrade, or tenant-boundary risk.
• Minor: Defense-in-depth gap, weak validation, incomplete audit trail, ambiguous security behavior, or low-likelihood exposure.
• Nit: Naming, comment, or structure issue with no meaningful security impact.

Coordination With Other Workflows

• Use code-review-agent-workflow.md for broad review and this skill for focused security depth.
• If the security review finds a bug, hand off to the bug-fix workflow after reporting the finding.
• If the review finds a design or policy decision gap, hand off to the feature workflow rather than inventing security policy.

Test Strategy

Quick Start

• Run scripts/test_inventory.py <path> when a repository path is available.
• Read references/test-strategy-checklist.md before finalizing the test plan.
• Follow shared safety, validation, and scope rules in ../_shared/references/skill-operating-rules.md.
• Map tests to observable behavior, not implementation details.
• Prefer targeted validation first, then broader validation when risk justifies it.
• Do not edit code unless the user explicitly asks for implementation.

Strategy Workflow

1. Identify changed or proposed behavior.
2. List risk areas: permissions, data shape, API contracts, UI states, errors, concurrency, migrations, performance, and integrations.
3. Inventory existing test structure and commands:

python3 scripts/test_inventory.py /path/to/repo

4. Produce a coverage matrix:

| Behavior | Existing coverage | Needed test | Priority |
| --- | --- | --- | --- |
| <behavior> | covered / partial / missing | <test idea> | P0 / P1 / P2 |

5. Separate automated tests from manual QA and validation commands.
6. Call out tests that should not be updated because they assert stable behavior.

Output Rules

• Include exact scenarios, inputs, expected results, and why each test matters.
• Mark regression tests that should fail before the fix and pass after it.
• State skipped tests or validations with reasons.
• Flag weak tests: broad snapshots, tautological assertions, timing-sensitive tests, and tests that mirror implementation instead of behavior.

Workflow Automation

Description: Automate the agent-workflows library by routing a task to the correct workflow and executing the matching steps directly.

Quick Start

• Run scripts/find_workflow_library.py --json from this skill directory, or run the script by its absolute path, to locate the nearest agent-workflows library and get the file map.
• If the library is not near the current workspace, set AGENT_WORKFLOWS_ROOT to the library root before running the script.
• Read references/workflow-routing.md to classify the task.
• Read references/library-loading.md to know which shared docs and workflow file to load.
• Follow shared safety, validation, and scope rules in ../_shared/references/skill-operating-rules.md.
• Apply the workflow directly. Do not just restate the prompt text unless the user explicitly asks for prompt templates.

Operating Rules

• Treat the workflow markdown files as operating instructions, not as documentation to paraphrase back to the user.
• Use one primary workflow at a time. If a task crosses workflow boundaries, complete or pause the current workflow and then hand off explicitly to the next one.
• Respect an explicitly requested workflow unless it is clearly unsafe or mismatched; if you override it, explain why.
• Keep context lean: load README.md, the relevant shared docs, and the selected workflow file. Do not load every workflow file.
• For code-changing workflows, execute the workflow steps in the repository, including validation and final reporting.
• For read-only workflows such as code review or survey-only cleanup, stay read-only unless the user explicitly asks for edits.

Route the Task

Read references/workflow-routing.md when the correct workflow is not obvious. Use these defaults:

• New capability, design change, or product behavior change: feature workflow.
• New project, greenfield codebase, repository scaffold, or initial tooling setup: project initialization workflow.
• Existing behavior is wrong or regressed: bug-fix workflow.
• User asks for review, findings, PR review, or diff review: code-review workflow.
• Live or recent production outage, mitigation, alert, or incident: incident workflow.
• Behavior must stay the same while structure improves: refactoring workflow.
• Cleanup, dependency upgrade, dead code removal, TODO resolution, or debt survey: tech-debt cleanup workflow.

If the classification is materially ambiguous, ask one short clarifying question. If the ambiguity is low-risk, choose the most likely workflow and state the assumption.

Locate the Library

• Use scripts/find_workflow_library.py --json first, resolving the path relative to this skill directory if the current working directory is elsewhere.
• The script checks AGENT_WORKFLOWS_ROOT, then script-relative paths, then walks upward from the start path.
• If the script finds a library root, use the returned paths.
• If no library is found, ask the user for the agent-workflows path instead of guessing.

Execute the Workflow

• Read references/library-loading.md before opening files.
• Run the workflow’s preflight, safety rule, triage gate, and only the necessary steps for the current task.
• Follow the library’s shared conventions plus the workflow-specific rules.
• For incident work, prioritize mitigation first and treat destructive actions as approval-gated.
• For review work, default to findings-first and avoid edits unless explicitly asked.

References

• references/workflow-routing.md
• references/library-loading.md
• scripts/find_workflow_library.py

Workflow Maintainer

Quick Start

• Locate the library root. The audit script auto-checks AGENT_WORKFLOWS_ROOT, script-relative paths, and the current workspace.
• Run scripts/audit_workflow_library.py from this skill directory, or by absolute path.
• Read references/audit-checklist.md before making maintenance edits.
• Follow shared safety, validation, and scope rules in ../_shared/references/skill-operating-rules.md.
• Fix only the reported drift or the user-requested maintenance scope. Do not rewrite workflow content unless the issue requires it.
• Re-run the audit script and any affected helper scripts before final handoff.

Maintenance Rules

• Preserve the library's separation of concerns: workflow-specific guidance stays in workflow files; repeated safety, preflight, and conventions stay in shared/; skill-specific routing stays in the relevant skill.
• When workflow names, filenames, or shared docs change, update all references together: README.md, skills/workflow-automation/references/library-loading.md, skills/workflow-automation/references/workflow-routing.md, and related scripts.
• Treat broken links, missing required files, stale skill metadata, and invalid manifests as blocking issues.
• Treat style-only edits, wording improvements, and optional examples as non-blocking unless the user asked for them.
• Never commit or push without explicit permission.

Audit Workflow

1. Run the audit script:

python3 scripts/audit_workflow_library.py

2. If the script reports errors, inspect only the affected files first.
3. If the issue concerns judgment rather than deterministic validation, use the checklist reference.
4. Apply narrow fixes.
5. Re-run:

python3 scripts/audit_workflow_library.py
python3 skills/workflow-automation/scripts/find_workflow_library.py --json

6. Report findings fixed, commands run, remaining warnings, and whether any validation was skipped.

When to Read the Checklist

Read references/audit-checklist.md when the user asks for a human review of the library, release readiness, docs consistency, routing changes, or when the script reports no errors but the change may still have workflow-design risk.

文档维护

快速开始

• 运行 scripts/docs_inventory.py <path> 来盘点 Markdown 文档和常见文档信号。
• 在维护当前 agent-workflows 仓库时，运行 ../workflow-maintainer/scripts/audit_workflow_library.py。
• 在完成文档变更前，先阅读 references/docs-maintenance-checklist.md。
• 遵循 ../_shared/references/skill-operating-rules.md 中共享的安全、验证和范围规则。
• 让修改严格围绕文档目标展开；不要不小心改变工作流语义。

维护流程

1. 识别文档变更类型：新增文档、文件重命名、工作流步骤变更、新技能、示例更新、错字修复或一致性修复。
2. 盘点文档：

python3 scripts/docs_inventory.py /path/to/agent-workflows

3. 更新所有受影响的交叉引用：

• README 清单和设置说明。
• 工作流路由和库加载参考。
• 技能文档以及 agents/interface.yaml 中的规范代理元数据提示词。
• 如果多个工作流文件里出现重复措辞，则更新共享约定。

4. 验证链接、锚点、清单和辅助脚本。
5. 报告已修改的文档、执行的验证以及任何被跳过的检查。

输出规则

• 优先使用精确措辞，而不是大范围重写。
• 保持现有语气和结构。
• 让示例可执行，或清楚标记为模板。
• 如果某条共享参考资料已经是规范来源，就不要再重复添加安全相关样板文字。

迁移规划

快速开始

• 当仓库路径或变更路径可用时，运行 scripts/migration_signal_scan.py <path>。
• 在完成计划前，先阅读 references/migration-checklist.md。
• 遵循 ../_shared/references/skill-operating-rules.md 中共享的安全、验证和范围规则。
• 对数据库和公共契约优先采用 expand-contract 迁移模式。
• 未经明确许可，不要执行迁移、修改数据、部署、提交或推送。

规划流程

1. 识别迁移对象：schema、数据、API、事件契约、配置、依赖或运行时行为。
2. 定义兼容性要求：旧代码配合新数据、新代码配合旧数据、旧客户端配合新 API，以及回滚路径。
3. 把发布拆成多个阶段：

• Prepare：加法式变更、双读或双写、特性开关。
• Backfill：幂等、可恢复、可观测的数据变更。
• Switch：把流量或行为切换到新路径。
• Contract：只有在安全性被证明之后，才移除旧字段、旧代码、旧开关或兼容垫片。

4. 为每个阶段产出带验证和回滚方案的迁移计划。
5. 明确标记不可逆步骤，并在执行前要求批准。

输出规则

• 包含部署顺序和回滚顺序。
• 包含数据验证查询或检查项。
• 包含监控和告警信号。
• 包含影响面和预期耗时。
• 说明移除兼容性代码之前必须满足哪些条件。

性能评审

快速开始

• 当仓库路径或变更文件路径可用时，运行 scripts/performance_signal_scan.py <path>。
• 在输出发现前，先阅读 references/performance-review-checklist.md。
• 遵循 ../_shared/references/skill-operating-rules.md 中共享的安全、验证和范围规则。
• 关注热点路径、数据规模、请求速率和运维成本。
• 除非用户明确要求修复，否则保持只读。

评审流程

1. 先明确预期规模：记录数、每秒请求数、并发度、负载大小、内存预算和延迟预算。
2. 识别热点路径和高成本依赖：数据库、网络、文件系统、CPU、序列化、渲染、队列。
3. 运行信号扫描：

python3 scripts/performance_signal_scan.py /path/to/repo-or-file

4. 针对现实中的最坏输入，追踪循环、查询、API 调用和分配路径。
5. 推荐验证方式：定向测试、性能剖析、explain plan、基准测试、压测或生产指标观察。

输出规则

• 每个发现都必须包含规模假设和成本机制。
• 区分“已经测量到的问题”和“合理推断的风险”。
• 优先给出具体缓解措施：加分页、批量调用、加索引、带失效机制的缓存、流式处理数据、避免重复工作。
• 如果没有发现问题，也要说明剩余风险，以及是否跳过了性能剖析或基准测试。

项目初始化

快速开始

• 找到最近的 agent-workflows 库。如果它不在当前工作区附近，询问 AGENT_WORKFLOWS_ROOT 或该库路径。
• 阅读 project-initialization-agent-workflow.md。
• 阅读 ../_shared/references/skill-operating-rules.md。
• 直接应用工作流。除非用户明确要求模板，否则不要只是复述提示词。
• 在创建文件前，必须先拿到明确的目标目录。

执行规则

• 该技能用于新项目、绿地代码库、初始仓库脚手架和项目工具链设置。
• 把工作流文件视为预检、分诊、规划、脚手架搭建、验证和交接的唯一事实来源。
• 在分诊前先运行工作流中的预检，这样才能提前知道目标目录状态、父级工作区规则、本地说明、可用工具链以及无关本地变更。
• 对于 Minimal 项目，在确认目标目录后，用合理默认值直接搭建脚手架。
• 对于 Standard 和 Complex 项目，按工作流中的“规划 / 评审 / 搭建 / 验证 / 交接”顺序执行。
• 未经明确许可，不要提交或推送。
• 不要覆盖、回退、删除或重新格式化无关的用户变更。
• 如果目标目录缺失、有歧义，或意外地已经有内容，先停下来提问。

执行指引

1. 确认目标目录并检查其当前状态。
2. 加载并遵循 project-initialization-agent-workflow.md 中的分诊门。
3. 选择合适路径：
   • Minimal：使用 Minimal Project Prompt。
   • Standard：先收集需求，再创建/评审计划，然后搭建并验证。
   • Complex：完整执行整个工作流，并分别进行评审与验证。
4. 搭建脚手架时，让所有生成文件都留在已确认的目标目录内。
5. 使用该生态系统相关的安装、lint、类型检查、构建、测试和冒烟命令进行验证。
6. 报告创建的文件、配置的工具链、验证结果、偏差、已知限制和下一步建议。

参考资料

• ../../project-initialization-agent-workflow.md
• ../_shared/references/skill-operating-rules.md

交接

• 如果初始化后的项目已经可以进入功能开发，则交接给功能开发工作流。
• 如果验证阶段暴露出脚手架中的局部缺陷，就在该工作流内修复。
• 如果验证暴露出更大的设计或技术决策问题，则先回到项目计划，再修改脚手架。

发布准备

快速开始

• 在此技能目录下运行 scripts/prepare_release_report.py，或使用其绝对路径，来收集发布输入。
• 如果该仓库里提供了 workflow-maintainer 技能，在起草发布说明前先运行其审计。
• 阅读 references/release-checklist.md 以获取发布判断检查项和最终交接内容。
• 遵循 ../_shared/references/skill-operating-rules.md 中共享的安全、验证和范围规则。
• 未经明确许可，不要创建标签、提交、推送、GitHub Release 或包上传。

发布流程

1. 确认仓库状态：

python3 scripts/prepare_release_report.py

2. 运行确定性验证：

python3 ../workflow-maintainer/scripts/audit_workflow_library.py
python3 ../workflow-automation/scripts/find_workflow_library.py --json

3. 检查变更文件并判断发布影响级别：

• major：破坏性的工作流语义变更、文件重命名、工作流移除，或不兼容的技能行为变更。
• minor：新增工作流、新增技能、新增检查项，或向后兼容的能力扩展。
• patch：错字修复、文档澄清、元数据修正、非破坏性的脚本修复。

4. 起草发布说明，包含：

• 摘要
• 面向用户的变更
• 新增或变更的技能
• 已执行的验证
• 破坏性变更（如果有）
• 迁移说明（如果有）
• 已知限制或后续事项

5. 最终交接必须明确说明是否执行了提交、打标签、推送和发布动作。除非用户明确批准，否则默认答案应为“否”。

维护规则

• 发布说明要基于实际观察到的变更，保持事实准确。
• 如果仓库没有定义版本规范，不要虚构版本号；应询问用户，或将本次发布标记为“未版本化草案”。
• 将失败的审计、损坏链接、必需文件缺失、README 清单过期、技能元数据无效或辅助脚本未验证视为发布阻塞项。
• 如果工作区不是 Git 仓库，则输出基于文件系统的发布报告，并明确说明无法获取 Git diff 元数据。

安全评审

快速开始

• 把这个技能当成聚焦型评审层，而不是正常正确性评审的替代品。
• 当仓库路径或变更文件路径可用时，运行 scripts/security_signal_scan.py <path>。
• 在输出发现前，先阅读 references/security-review-checklist.md。
• 遵循 ../_shared/references/skill-operating-rules.md 中共享的安全、验证和范围规则。
• 除非用户明确要求修复，否则保持只读。
• 未经明确许可，不要提交、推送、部署、轮换密钥、吊销凭证或执行破坏性命令。

评审流程

1. 明确范围：

• 评审目标：PR、分支、工作区变更或具体文件。
• 如果在评审 diff，确认比较基线。
• 该变更触及的信任边界。
• 被触及的安全敏感领域：认证、权限、密钥、支付、PII、文件上传、网络调用、命令执行、数据库访问、依赖升级、日志或遥测。

2. 运行信号扫描：

python3 scripts/security_signal_scan.py /path/to/repo-or-file

3. 手动追踪高风险链路：

• 外部输入到危险汇点：数据库查询、shell 命令、HTML/模板渲染、文件路径、网络请求、反序列化、日志或重定向。
• 身份到授权决策：认证来源、用户/会话查找、角色/权限检查、租户或归属边界。
• 密钥从创建到存储/使用/日志记录的路径。
• 敏感数据从存储到响应、日志、分析系统或第三方调用的路径。

4. 先报告发现项，并按严重级别排序。使用下面格式：

### [Severity] Finding title

- Location:
- Problem:
- Why it matters:
- Attack or failure scenario:
- Recommended fix:
- Severity: Critical / Major / Minor / Nit

5. 如果没有发现问题，要明确说明，同时列出剩余风险、跳过的检查和已执行的验证。

严重级别指引

• Critical：直接导致数据暴露、认证绕过、授权绕过、凭证泄漏、远程代码执行、破坏性数据修改或可利用注入。
• Major：缺少边界场景授权、存在可利用路径的不安全输入处理、敏感日志、不安全默认值、危险依赖升级或租户边界风险。
• Minor：纵深防御缺口、较弱的校验、不完整审计轨迹、含糊的安全行为或低概率暴露。
• Nit：没有实质性安全影响的命名、注释或结构问题。

与其他工作流协作

• 广泛代码评审用 code-review-agent-workflow.md；需要更深的安全视角时叠加本技能。
• 如果安全评审发现了缺陷，先报告发现项，再交接给缺陷修复工作流。
• 如果评审暴露出设计或策略决策缺口，交接给功能工作流，而不是自行发明安全策略。

测试策略

快速开始

• 当仓库路径可用时，运行 scripts/test_inventory.py <path>。
• 在完成测试计划前，先阅读 references/test-strategy-checklist.md。
• 遵循 ../_shared/references/skill-operating-rules.md 中共享的安全、验证和范围规则。
• 把测试映射到可观察行为，而不是实现细节。
• 先做定向验证，再在风险确实需要时扩大验证范围。
• 除非用户明确要求实现，否则不要改代码。

策略流程

1. 识别已经变更或计划变更的行为。
2. 列出风险区域：权限、数据形状、API 契约、UI 状态、错误、并发、迁移、性能和集成。
3. 盘点现有测试结构和命令：

python3 scripts/test_inventory.py /path/to/repo

4. 产出覆盖矩阵：

| Behavior | Existing coverage | Needed test | Priority |
| --- | --- | --- | --- |
| <behavior> | covered / partial / missing | <test idea> | P0 / P1 / P2 |

5. 把自动化测试、手工 QA 和验证命令分开列出。
6. 标明哪些测试不应被更新，因为它们断言的是稳定行为。

输出规则

• 包含精确场景、输入、期望结果，以及每个测试为什么重要。
• 标记回归测试：修复前应失败，修复后应通过。
• 说明跳过的测试或验证及其原因。
• 标出弱测试：宽泛快照、恒真断言、时间敏感测试，以及与实现一一映射而不是验证行为的测试。

工作流自动化

说明：通过把任务路由到正确的工作流并直接执行对应步骤，自动化使用 agent-workflows 库。

快速开始

• 在此技能目录下运行 scripts/find_workflow_library.py --json，或使用脚本绝对路径运行，以定位最近的 agent-workflows 库并获取文件映射。
• 如果当前工作区附近找不到该库，先设置 AGENT_WORKFLOWS_ROOT 指向库根目录，再运行脚本。
• 阅读 references/workflow-routing.md 来对任务分类。
• 阅读 references/library-loading.md 来确定需要加载哪些共享文档和工作流文件。
• 遵循 ../_shared/references/skill-operating-rules.md 中共享的安全、验证和范围规则。
• 直接应用工作流。除非用户明确要求提示词模板，否则不要只是复述提示词正文。

执行规则

• 把工作流 Markdown 文件当作操作说明，而不是要原样转述给用户的说明文档。
• 一次只使用一个主工作流。如果任务跨越工作流边界，先完成或暂停当前工作流，再明确交接到下一个工作流。
• 如果用户明确指定了某个工作流，应尊重该要求；只有在明显不安全或不匹配时才覆盖，并解释原因。
• 保持上下文精简：加载 README.md、相关共享文档和选中的工作流文件即可。不要把所有工作流文件都读进来。
• 对会改代码的工作流，在仓库中直接执行对应步骤，包括验证和最终汇报。
• 对代码评审或仅调查式清理这类只读工作流，除非用户明确要求编辑，否则保持只读。

任务路由

当正确工作流不明显时，阅读 references/workflow-routing.md。默认映射如下：

• 新能力、设计变更或产品行为变更：功能工作流。
• 新项目、绿地代码库、仓库脚手架或初始工具链搭建：项目初始化工作流。
• 现有行为错误或回归：缺陷修复工作流。
• 用户要求 review、findings、PR review 或 diff review：代码评审工作流。
• 线上或刚发生的生产故障、缓解、告警或事故：事故工作流。
• 目标是在不改变行为的前提下改善结构：重构工作流。
• 清理、依赖升级、删除死代码、处理 TODO 或技术债盘点：技术债清理工作流。

如果分类存在实质性歧义，提一个简短澄清问题即可。如果歧义风险较低，选择最可能的工作流并说明你的假设。

定位工作流库

• 先运行 scripts/find_workflow_library.py --json，必要时相对当前技能目录解析脚本路径。
• 该脚本会依次检查 AGENT_WORKFLOWS_ROOT、脚本相对路径，再从起始路径向上查找。
• 如果脚本找到了库根目录，就直接使用它返回的路径。
• 如果没有找到库，不要猜测，直接向用户询问 agent-workflows 的路径。

执行工作流

• 打开文件前先阅读 references/library-loading.md。
• 运行工作流中的预检、安全规则、分诊门，以及当前任务真正需要的步骤。
• 同时遵守库里的共享约定和工作流专属规则。
• 处理事故时，优先缓解影响，并把破坏性操作视为需要批准的动作。
• 处理评审任务时，以“先给发现项”为默认方式，除非用户明确要求，否则不要编辑。

参考资料

• references/workflow-routing.md
• references/library-loading.md
• scripts/find_workflow_library.py

工作流维护者

快速开始

• 定位库根目录。审计脚本会自动检查 AGENT_WORKFLOWS_ROOT、脚本相对路径以及当前工作区。
• 在此技能目录中运行 scripts/audit_workflow_library.py，或使用绝对路径运行。
• 在进行维护编辑前，先阅读 references/audit-checklist.md。
• 遵循 ../_shared/references/skill-operating-rules.md 中共享的安全、验证和范围规则。
• 只修复报告出的漂移问题，或用户明确指定的维护范围。除非问题确实要求，否则不要重写工作流内容。
• 最终交付前重新运行审计脚本和所有受影响的辅助脚本。

维护规则

• 保持库的职责分离：工作流专属指导留在工作流文件中；重复的安全规则、预检和约定留在 shared/ 中；技能专属路由规则留在相应技能里。
• 当工作流名称、文件名或共享文档发生变化时，要一起更新所有引用：README.md、skills/workflow-automation/references/library-loading.md、skills/workflow-automation/references/workflow-routing.md 以及相关脚本。
• 将损坏链接、必需文件缺失、过期的技能元数据和无效清单视为阻塞问题。
• 将纯样式改动、措辞优化和可选示例视为非阻塞，除非用户明确要求它们。
• 未经明确许可，绝不要提交或推送。

审计工作流

1. 运行审计脚本：

python3 scripts/audit_workflow_library.py

2. 如果脚本报告错误，先只检查受影响的文件。
3. 如果问题涉及人工判断，而不是确定性校验，参考清单文档。
4. 应用范围收窄的修复。
5. 重新运行：

python3 scripts/audit_workflow_library.py
python3 skills/workflow-automation/scripts/find_workflow_library.py --json

6. 报告已修复的问题、运行过的命令、剩余警告，以及是否跳过了任何验证。

何时阅读清单

当用户要求对该库进行人工评审、发布就绪性检查、文档一致性检查、路由变更检查，或脚本未报错但改动仍可能带来工作流设计风险时，阅读 references/audit-checklist.md。