pre-deploy

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

@rules/parallel-remediation.md @rules/tracked-remediation.md

Pre-Deploy Skill

部署前技能

Prove a repository is deploy-ready, or fix only the reproduced quality/build blockers that prevent that proof.

<request_routing>

证明代码仓库已具备部署就绪条件，或仅修复那些阻碍该证明的、已重现的质量/构建阻塞问题。

<request_routing>

Positive triggers

正向触发条件

"Run a pre-deploy check" or "check if this is ready to deploy."
"Make this repo deploy-ready" or "fix blockers before deploying."
"Run final lint/typecheck/build validation before release."
"Validate this Node/Rust/Python workspace before deployment."

"执行部署前检查" 或 "检查是否已准备好部署"。
"让这个仓库具备部署条件" 或 "修复部署前的阻塞问题"。
"发布前执行最终的lint/类型检查/构建验证"。
"部署前验证这个Node/Rust/Python工作区"。

Out-of-scope

超出范围场景

A concrete failed deployment log, platform build failure, CI-only environment mismatch, or production deploy issue. Route to
```
deploy-fix
```
.
A runtime bug with reproduction steps or wrong application behavior. Route to
```
bug-fix
```
.
New feature work, broad refactors, or speculative cleanup not tied to a reproduced pre-deploy blocker. Route to
```
execute
```
or the relevant implementation skill.

Unsupported repositories with no root marker for

package.json

Cargo.toml

pyproject.toml

requirements.txt

setup.py

Pipfile

, or

poetry.lock

具体的部署失败日志、平台构建失败、仅CI环境存在的不匹配问题，或生产部署问题。请路由至
```
deploy-fix
```
。
带有复现步骤的运行时bug或应用行为异常问题。请路由至
```
bug-fix
```
。
新功能开发、大范围重构，或与已重现的部署前阻塞问题无关的预防性清理工作。请路由至
```
execute
```
或相关的实现技能。

不支持的代码仓库：无

package.json

、

Cargo.toml

、

pyproject.toml

、

requirements.txt

、

setup.py

、

Pipfile

或

poetry.lock

根标记的仓库。

Boundary cases

边界情况

If the user asks for validation only, run checks and report blockers without editing.
If the initial check exposes one obvious low-risk blocker, use Fix-now.
If failures span multiple stacks, workspaces, or ambiguous dependency/config chains, use tracked remediation and parallel lanes where available.
If a failure is actually a deploy-platform or runtime app issue, stop pre-deploy remediation and hand off instead of absorbing the wrong problem.

</request_routing>

<argument_validation>

If no argument is provided, default to the current repository root.
If the user names a subdirectory or workspace, verify it exists, switch commands to that directory, and restart stack detection there.
If the user says validate-only, report-only, audit-only, or similar, do not edit files.
Always run stack detection from the target root before claiming the skill applies.
If no supported stack is detected, stop immediately and report that
```
pre-deploy
```
does not apply; do not enter a fake fix loop.

</argument_validation>

如果用户仅要求验证，则执行检查并报告阻塞问题，不进行编辑操作。
如果初始检查发现一个明显的低风险阻塞问题，使用即时修复（Fix-now）。
如果失败涉及多个技术栈、工作区，或模糊的依赖/配置链，使用跟踪式修复（tracked remediation），并在可用时采用并行处理通道。
如果失败实际是部署平台或应用运行时问题，则停止部署前修复流程，转而移交至对应技能，而非处理错误的问题。

</request_routing>

<argument_validation>

如果未提供参数，默认使用当前代码仓库根目录。
如果用户指定了子目录或工作区，需验证其是否存在，切换命令至该目录，并在该位置重新启动技术栈检测。
如果用户要求仅验证、仅报告、仅审计等类似操作，请勿编辑文件。
在声明技能适用前，务必从目标根目录执行技术栈检测。
如果未检测到支持的技术栈，立即停止并报告
```
pre-deploy
```
不适用；请勿进入虚假修复循环。

</argument_validation>

Available scripts

可用脚本

Run scripts with the current working directory set to the target root so detection is accurate. If the target root is the repository root, use these repository-relative paths; if the target is a subdirectory/workspace, invoke the same scripts by absolute path or by the correct relative path back to the repository root:

Script	Purpose
`skills/pre-deploy/scripts/stack-detect.sh`	Detect project stacks ( `node` , `rust` , `python` )
`skills/pre-deploy/scripts/deploy-check.sh`	Full verification ( `lint/type checks + build` )
`skills/pre-deploy/scripts/lint-check.sh`	Run stack-specific quality checks
`skills/pre-deploy/scripts/build-run.sh`	Run stack-specific build phase
`skills/pre-deploy/scripts/pm-detect.sh`	Node package manager detection ( `npm/yarn/pnpm/bun` )

Notes:

Helper scripts detect stacks and package managers relative to the current working directory.
```
lint-check.sh
```
already runs independent Node typecheck and lint commands concurrently when both are configured; do not duplicate that internal parallelism with extra agents.
Treat skipped checks as "not configured" or "tool unavailable," not as passed.

</scripts>

<mandatory_reasoning>

执行脚本时，将当前工作目录设置为目标根目录，以确保检测准确。如果目标根目录是仓库根目录，使用这些仓库相对路径；如果目标是子目录/工作区，通过绝对路径或相对于仓库根目录的正确相对路径调用相同脚本：

脚本	用途
`skills/pre-deploy/scripts/stack-detect.sh`	检测项目技术栈（ `node` 、 `rust` 、 `python` ）
`skills/pre-deploy/scripts/deploy-check.sh`	完整验证（lint/类型检查 + 构建）
`skills/pre-deploy/scripts/lint-check.sh`	执行技术栈专属的质量检查
`skills/pre-deploy/scripts/build-run.sh`	执行技术栈专属的构建阶段
`skills/pre-deploy/scripts/pm-detect.sh`	Node包管理器检测（ `npm/yarn/pnpm/bun` ）

注意事项：

辅助脚本相对于当前工作目录检测技术栈和包管理器。
当同时配置了Node类型检查和lint命令时，
```
lint-check.sh
```
已在内部并发执行这两个命令；请勿通过额外Agent重复该内部并行操作。
将跳过的检查视为"未配置"或"工具不可用"，而非通过。

</scripts>

<mandatory_reasoning>

Adaptive Sequential Thinking

自适应顺序思维

Use

sequential-thinking

before implementation and scale depth to the failure shape:

Complexity	Thinking depth	Signals
Simple	3 thoughts	One stack, one failing command, clear root cause, low-risk fix
Medium	5 thoughts	Multiple related failures in one stack, moderate config/dependency impact
Complex	7+ thoughts	Multiple stacks/workspaces, ambiguous fix strategy, shared config, dependency chain, or CI/deploy boundary

Recommended sequence: classify -> read exact failure output -> identify root cause -> choose targeted validation -> decide direct fix, parallel lanes, tracked remediation, or handoff.

</mandatory_reasoning>

<complexity_classification>

Classify after the first full deploy check fails:

Complexity	Signals	Path
Simple	Single failing check, one stack, clear file/config owner, one safe fix path	Fix-now
Medium	Several failures in one stack or one workspace, independent enough for targeted fixes	Fix-now with TodoWrite tracking
Complex	Multi-stack failures, shared configs, monorepo/build graph issues, uncertain repair options, or likely cross-cutting side effects	Tracked remediation; use `rules/parallel-remediation.md` before subagents

When uncertain, classify upward. It is better to preserve evidence and ownership than to silently make broad changes.

</complexity_classification>

<execution_modes>

Validate-only: run detection and
```
deploy-check.sh
```
, report detected stacks, passed/failed/skipped checks, and blockers. No edits.
Fix-now: for simple/medium reproduced blockers, create TodoWrite items, fix narrowly, re-run targeted checks, then re-run full deploy check.
Parallel remediation: after failure grouping, use bounded subagents/background agents only for independent diagnosis or disjoint edit lanes. The leader owns integration and final verification. Load
```
rules/parallel-remediation.md
```
first.

Tracked remediation: for complex cases, load

rules/tracked-remediation.md

, then create or resume

.hypercore/pre-deploy/flow.json

with phases

detect

baseline

triage

fix

verify

report

Handoff: route platform deployment failures to
```
deploy-fix
```
, runtime application bugs to
```
bug-fix
```
, and unrelated implementation requests to
```
execute
```
.

</execution_modes>

在实施前使用

sequential-thinking

，并根据失败情况调整思考深度：

复杂度	思考深度	信号
简单	3个思考步骤	单一技术栈、单一失败命令、明确根因、低风险修复
中等	5个思考步骤	同一技术栈内多个相关失败、对配置/依赖有中等影响
复杂	7个及以上思考步骤	多个技术栈/工作区、模糊的修复策略、共享配置、依赖链，或CI/部署边界问题

推荐流程：分类 -> 读取准确的失败输出 -> 识别根因 -> 选择针对性验证 -> 决定直接修复、并行通道、跟踪式修复或移交。

</mandatory_reasoning>

<complexity_classification>

首次完整部署检查失败后进行分类：

复杂度	信号	处理路径
简单	单一失败检查、单一技术栈、明确的文件/配置归属、单一安全修复路径	即时修复（Fix-now）
中等	同一技术栈或工作区内多个失败、可独立进行针对性修复	结合TodoWrite跟踪的即时修复
复杂	多技术栈失败、共享配置、单体仓库/构建图问题、不确定的修复方案，或可能产生跨领域副作用	跟踪式修复；在使用子Agent前加载 `rules/parallel-remediation.md`

若不确定，向上归类。保留证据和归属权比静默进行大范围更改更稳妥。

</complexity_classification>

<execution_modes>

仅验证模式：执行检测和
```
deploy-check.sh
```
，报告检测到的技术栈、通过/失败/跳过的检查，以及阻塞问题。不进行编辑。
即时修复模式：针对简单/中等复杂度的已重现阻塞问题，创建TodoWrite条目，进行精准修复，重新执行针对性检查，然后重新运行完整部署检查。
并行修复模式：失败分组后，仅为独立诊断或不相交的编辑通道使用有限的子Agent/后台Agent。主导Agent负责集成和最终验证。先加载
```
rules/parallel-remediation.md
```
。
跟踪式修复模式：针对复杂场景，加载
```
rules/tracked-remediation.md
```
，然后创建或恢复
```
.hypercore/pre-deploy/flow.json
```
，包含
```
detect
```
、
```
baseline
```
、
```
triage
```
、
```
fix
```
、
```
verify
```
、
```
report
```
阶段。
移交模式：将平台部署失败路由至
```
deploy-fix
```
，运行时应用bug路由至
```
bug-fix
```
，无关的实现请求路由至
```
execute
```
。

</execution_modes>

Full validation proof

完整验证流程

From the repository root:

bash

skills/pre-deploy/scripts/deploy-check.sh

Do not skip this initial command unless the target root has no supported stack. It establishes the baseline and captures exact blockers.

从仓库根目录执行：

bash

skills/pre-deploy/scripts/deploy-check.sh

除非目标根目录无支持的技术栈，否则请勿跳过此初始命令。它用于建立基准并捕获准确的阻塞问题。

Step-by-step validation

分步验证流程

From the repository root:

bash

undefined

从仓库根目录执行：

bash

undefined

1) quality checks

1) 质量检查

skills/pre-deploy/scripts/lint-check.sh

2) build phase

2) 构建阶段

skills/pre-deploy/scripts/build-run.sh


Use step-by-step commands for targeted rechecks after a fix, but the final readiness claim still requires a full `deploy-check.sh` run.

skills/pre-deploy/scripts/build-run.sh


修复后使用分步命令进行针对性复查，但最终就绪性声明仍需运行完整的`deploy-check.sh`。

Stack behavior summary

技术栈行为概述

Node.js: typecheck/lint (if configured) + build script (if configured)

Rust:

cargo fmt --check

cargo clippy

cargo check

cargo build --release

Python: lint (
```
ruff
```
/
```
flake8
```
if available) + type/syntax check (
```
mypy
```
or
```
compileall
```
) + build (
```
poetry build
```
or
```
python -m build
```
, fallback
```
compileall
```
)
Unsupported repository: stop with the detected unsupported-stack error and do not continue into remediation

</workflow>

<implementation_rules>

Read the exact command output before editing; do not guess failures.
Convert failures into TodoWrite items by stack, command, and priority.
Fix the first/root failure before chasing cascading errors unless failures are demonstrably independent.
Keep each edit scoped to the reproduced blocker and its direct dependency.
Re-run the narrowest relevant check after each edit.
If using subagents, give each lane objective, scope, ownership, output, and stop condition; never let two lanes edit the same file or shared config concurrently.
The leader must synthesize subagent results, inspect the final diff, and run the final proof command directly.

</implementation_rules>

<completion_report>

Use this report shape:

markdown

undefined

Node.js：类型检查/lint（若已配置） + 构建脚本（若已配置）

Rust：

cargo fmt --check

cargo clippy

cargo check

cargo build --release

Python：lint（若可用则使用
```
ruff
```
/
```
flake8
```
） + 类型/语法检查（
```
mypy
```
或
```
compileall
```
） + 构建（
```
poetry build
```
或
```
python -m build
```
， fallback为
```
compileall
```
）
不支持的仓库：停止并报告检测到的不支持技术栈错误，不继续修复流程

</workflow>

<implementation_rules>

编辑前读取准确的命令输出；请勿猜测失败原因。
按技术栈、命令和优先级将失败转换为TodoWrite条目。
修复首个/根因失败后再处理连锁错误，除非失败可证明是独立的。
每次编辑仅针对已重现的阻塞问题及其直接依赖。
每次编辑后重新执行最相关的窄范围检查。
如果使用子Agent，为每个通道指定目标、范围、归属、输出和停止条件；绝不让两个通道同时编辑同一文件或共享配置。
主导Agent必须综合子Agent的结果，检查最终差异，并直接运行最终验证命令。

</implementation_rules>

<completion_report>

使用以下报告格式：

markdown

undefined

Done

完成情况

Scope: [repo root or workspace] Stacks detected: [node/rust/python] Mode: [validate-only/fix-now/parallel remediation/tracked remediation/handoff] Initial blockers: [none or summarized failures] Fixes applied: [changed files or none] Validation:

skills/pre-deploy/scripts/deploy-check.sh

: [passed/failed/not run with reason]

Skipped/not configured checks: [list] Remaining risks: [none or explicit caveats]


Only say "ready to deploy" when the final full `deploy-check.sh` run passed.

</completion_report>

<validation>

Execution checklist:

- [ ] Target root or workspace validated
- [ ] Supported stack detected, or unsupported stack reported and stopped
- [ ] Full `skills/pre-deploy/scripts/deploy-check.sh` run first for supported stacks
- [ ] Failures tracked by stack/command/priority
- [ ] Root-cause evidence collected before edits
- [ ] Sequential thinking completed at the right depth
- [ ] Parallel lanes, if used, were independent and bounded
- [ ] Targeted validation run after each fix
- [ ] Full deploy check passed before readiness claim
- [ ] Skipped checks reported separately from passed checks

Forbidden:

- [ ] Claiming deploy readiness without a passing full deploy check
- [ ] Editing without a reproduced failure unless the user explicitly requested implementation work outside this skill
- [ ] Treating skipped checks as passed
- [ ] Continuing after unsupported-stack detection
- [ ] Requiring product-specific subagent syntax as if every runtime supports it
- [ ] Letting subagents edit overlapping files or own the final readiness decision

</validation>

范围：[仓库根目录或工作区] 检测到的技术栈：[node/rust/python] 模式：[仅验证/即时修复/并行修复/跟踪式修复/移交] 初始阻塞问题：[无或已总结的失败情况] 已应用修复：[已修改文件或无] 验证结果：

skills/pre-deploy/scripts/deploy-check.sh

：[通过/失败/未执行及原因]

已跳过/未配置的检查：[列表] 剩余风险：[无或明确的注意事项]


仅当最终完整的`deploy-check.sh`运行通过时，才可声明"已准备好部署"。

</completion_report>

<validation>

执行检查清单：

- [ ] 已验证目标根目录或工作区
- [ ] 已检测到支持的技术栈，或已报告不支持的技术栈并停止流程
- [ ] 针对支持的技术栈，已首先运行完整的`skills/pre-deploy/scripts/deploy-check.sh`
- [ ] 已按技术栈/命令/优先级跟踪失败情况
- [ ] 编辑前已收集根因证据
- [ ] 已完成对应深度的顺序思维
- [ ] 若使用并行通道，通道间相互独立且有限制
- [ ] 每次修复后已执行针对性验证
- [ ] 就绪性声明前已通过完整部署检查
- [ ] 已将跳过的检查与通过的检查分开报告

禁止操作：

- [ ] 未通过完整部署检查就声称已准备好部署
- [ ] 无已重现的失败就进行编辑，除非用户明确要求该技能之外的实现工作
- [ ] 将跳过的检查视为通过
- [ ] 检测到不支持的技术栈后仍继续流程
- [ ] 要求使用特定产品的子Agent语法，假设所有运行时都支持该语法
- [ ] 允许子Agent编辑重叠文件，或让子Agent拥有最终就绪性决策权

</validation>