ShipGuard

Ship with confidence. Every time.

ShipGuard is a gate-driven development workflow for AI-assisted software projects. It solves the core problem of AI-assisted development: one sentence in, massive undocumented changes out, invisible breakage everywhere.

Load references/ docs on demand. On first project association, run the onboarding questionnaire to generate PROJECT.md.

When to activate

• Any code change request on a shared or production codebase
• When the user says: build / fix / refactor / add / change / optimize
• When a change could touch DB schema, models, shared services, auth, or >3 files
• When the project has a .dev-workflow/PROJECT.md (auto-load it)

Core principle

No code without a confirmed plan. No merge without verified delivery. No close without regression. No surprise, ever.

Six gates. Each gate requires explicit user confirmation (✅) before proceeding. Skipping a gate requires explicit user override. The only exception: low-risk changes (see Execution Policy).

Request → [G0 Intake+TC] → [G1 Impact] → [G2 Build] → [G3 Feature QA] → [G4 Regression] → [G5 Lessons] → Closed

Project Onboarding (First Use)

When ShipGuard is associated with a project for the first time, run this questionnaire before handling any request:

【ShipGuard 项目初始化】

我需要了解这个项目，让我问你几个问题：

① 项目名称和一句话描述？
② 技术栈？（前端框架 / 后端语言 / 数据库 / 部署方式）
③ 当前阶段？开发中 / 生产运行中 / 维护期
④ 核心业务主流程是什么？（用户视角，列出 3-5 个关键步骤）
⑤ 哪些模块绝对不能出问题？（出问题直接影响生产或客户）
⑥ 已知的「永远不做」有哪些？（过去踩过的坑）
⑦ 谁是需要确认的负责人？
⑧ 有没有特殊部署限制？（如：DB 迁移必须备份、重启必须在低峰期）

After answers, AI scans the project structure automatically, then generates PROJECT.md:

# PROJECT.md — ShipGuard Project Profile

Project: \x3Cname>
Stack: \x3Ctech stack>
Stage: \x3Cdevelopment / production / maintenance>

## Critical Paths (changes always require confirmation)
1. \x3Ccore flow step 1>
2. \x3Ccore flow step 2>
...

## Protected Modules
- \x3Cmodule>: \x3Cwhy it's protected>

## Hard Rules (永远不做)
- \x3Crule derived from user input or past lessons>

## Owner
\x3Cname / contact>

## Deployment Constraints
- \x3Cconstraint>

Generated: YYYY-MM-DD
Last updated: YYYY-MM-DD

User confirms PROJECT.md before any work begins. This file is the source of truth for all future sessions.

Project Directory Structure

ShipGuard maintains a .dev-workflow/ directory in the project root:

.dev-workflow/
  PROJECT.md              # Project profile (generated at onboarding)
  CHANGELOG.md            # Auto-maintained change log
  requirements/           # One file per NR
    NR-YYYYMMDD-NN.md
  changes/                # One file per CR (impact + manifest + results)
    CR-YYYYMMDD-NN.md
  test-cases/
    all-test-cases.md     # Cumulative TC registry (auto-updated)
  regression/
    CR-YYYYMMDD-NN-regression.md
  lessons/
    hard-rules.md         # Permanent rules, never expire
    lessons.md            # Historical lessons, dated entries

On new session start: auto-load PROJECT.md + lessons/hard-rules.md + lessons/lessons.md. These files are the AI's persistent memory across sessions.

Task Types & Execution Policy

Classify every request before acting. Type determines allowed scope and whether confirmation is required.

Critical Path Rule: Any change touching the paths defined in PROJECT.md > Critical Paths is automatically elevated to "Confirm required", regardless of perceived size. The AI must not self-downgrade a critical path change.

Split Rule: When a request spans two types (e.g., fix a bug AND add a field), split into two separate CRs. Never merge types in one CR.

Scope Creep Rule: If during implementation the actual scope exceeds G1 estimates, stop immediately and issue a Scope Change Notice. Never silently expand scope.

Gate 0 — Requirement Intake + Test Case Definition

Output a Requirement Card immediately. No code yet.

【需求理解卡 #NR-YYYYMMDD-NN】
原始需求：\x3Cuser's exact words>
任务类型：🎨 UI微调 / 🐛 Bug Fix / ✨ Feature / 📋 Product / 🏗️ Architecture / 📄 Docs
执行策略：直接执行 / 需要确认

理解：\x3Cconcrete behavioral description, not paraphrase>
范围：\x3Cwhich modules / pages / APIs>
排除：\x3Cwhat is explicitly NOT changing>
假设：\x3Cany ambiguities and how they're resolved>
已知风险：\x3Cfrom hard-rules.md and lessons.md relevant to this request>

Test Cases：
  TC-01【正常流程】\x3Caction> → \x3Cexpected result>
  TC-02【正常流程】\x3Caction> → \x3Cexpected result>
  TC-03【边界条件】\x3Caction> → \x3Cexpected result>
  TC-04【异常流程】\x3Caction> → \x3Cexpected result>

✅ 确认（含 Test Cases）后开始 / ❌ 有误，请纠正

TC rules:

• 正常流程 (Happy path): core functionality works as expected
• 边界条件 (Edge case): empty data, max values, unusual states
• 异常流程 (Error path): what happens when things fail
• Every TC must have a specific, verifiable expected result — never "should work normally"
• TC is co-defined with the user. AI proposes, user confirms. AI does not unilaterally decide.

Write confirmed NR to .dev-workflow/requirements/NR-YYYYMMDD-NN.md.

Gate 1 — Change Impact Analysis

After NR confirmed, output a Change Impact Card. Still no code.

【变更影响分析 #CR-YYYYMMDD-NN】
关联需求：#NR-YYYYMMDD-NN

改动文件：
  - path/to/file（风险：低/中/高，原因：\x3Cwhy>）

影响范围：
  直接：\x3Cdirectly affected features>
  间接：\x3Cpotentially affected modules>
  无影响：\x3Cexplicitly excluded>

改动量：小(\x3C20行) / 中(20-100行) / 大(>100行)
风险等级：🟢低 / 🟡中 / 🔴高
DB变更：无 / 有（迁移脚本：\x3Cname>）
需要重启：无 / api / worker / all
预计耗时：\x3Cminutes>

风险说明：\x3Crequired when 🔴>
回滚方案：\x3Chow to revert if things go wrong>
关联回归模块：\x3Cmodules G4 must cover>

✅ 开始开发 / ❌ 重新评估

Risk levels:

• 🟢 Low: single file, UI only, no shared logic
• 🟡 Medium: multi-file, API changes, logic modification
• 🔴 High: DB migration, model changes, shared services, auth, critical path, >5 files

Write confirmed CR skeleton to .dev-workflow/changes/CR-YYYYMMDD-NN.md.

Gate 2 — Implementation

Execute within the boundaries defined by task type. Rules:

• Touch only files listed in G1. Any additional file = stop and issue Scope Change Notice
• Atomic changes: one logical unit at a time, not one file at a time
• If discovering unexpected complexity, stop and report before continuing

On completion, append Change Manifest to the CR file:

【变更清单 #CR-YYYYMMDD-NN】
状态：已完成 ✅

文件变更：
  path/to/file
    + \x3Cadded>
    ~ \x3Cmodified: what and why>
    - \x3Cremoved>

配套操作：
  迁移：\x3Cscript name, execution status>
  重启：\x3Cwhich containers>
  其他：

未改动（排除确认）：
  - \x3Cfile/module>: \x3Creason confirmed out of scope>

Gate 3 — Feature QA

Execute the test cases from Gate 0. No new TCs invented here.

【功能验收清单 #CR-YYYYMMDD-NN】
对应需求：#NR-YYYYMMDD-NN

执行 Gate 0 定义的 Test Cases：
  □ TC-01【正常流程】\x3Cdescription> → \x3Cexpected>
  □ TC-02【正常流程】...
  □ TC-03【边界条件】...
  □ TC-04【异常流程】...

请逐项验收后回复：
✅ 全部通过 → 进入回归测试
❌ TC-? 失败：\x3Cdescribe what happened>

On ✅: proceed to G4. On ❌: return to G2 for targeted fix. Re-run only failed TCs after fix.

Gate 4 — Regression Testing

Generate regression scope from G1's "关联回归模块", then execute.

【回归测试范围 #CR-YYYYMMDD-NN】

本次改动模块：\x3Cfrom G1>

需要回归：
  ├── \x3CModule A>
  │   ├── \x3Cfeature / page 1>
  │   └── \x3Cfeature / page 2>
  └── \x3CModule B>

不需要回归（确认无关联）：
  - \x3Cmodule>: \x3Creason>

---

【回归验收清单 #CR-YYYYMMDD-NN】

\x3CModule A>：
  □ R01. \x3Cspecific action> → \x3Cexpected>
  □ R02. \x3Cspecific action> → \x3Cexpected>

\x3CModule B>：
  □ R03. \x3Cspecific action> → \x3Cexpected>

请逐项验收后回复：
✅ 全部通过 → CR 关闭
❌ R? 失败：\x3Cdescribe>

Regression depth by risk:

• 🟢 Low: smoke (open page, no errors)
• 🟡 Medium: functional (core CRUD operations work)
• 🔴 High: full scenario (create / edit / delete / edge cases / error handling)

Write results to .dev-workflow/regression/CR-YYYYMMDD-NN-regression.md.

On ✅: trigger commit and proceed to G5.

Gate 5 — Lessons (Auto, no confirmation needed)

Run automatically after CR closes. No user action required.

【经验沉淀 #CR-YYYYMMDD-NN】
任务类型：\x3Ctype>

本次教训：
  - \x3Cwhat operation caused what problem>
  - \x3Cwhat to watch for next time with similar requests>

新增底层规则：
  ✅ 永远要做：\x3Crule>
  ❌ 永远不做：\x3Crule>

写入：
  lessons/lessons.md → \x3Cdated entry>
  lessons/hard-rules.md → \x3Cif new permanent rule established>
  test-cases/all-test-cases.md → \x3Cappend TCs from this CR>
  CHANGELOG.md → \x3Cappend entry>

Hard rules never expire. On every new session, load hard-rules.md and apply before handling any request.

Commit Format

\x3Ctype>(\x3Cscope>): \x3Csummary> #CR-YYYYMMDD-NN

Changed:
- \x3Cfile>: \x3Cwhat and why>

Side effects:
- Migration: \x3CSQL or "none">
- Restart: \x3Ccontainers or "none">
- Breaking: yes / no

Feature QA: ✅ (TC-01 to TC-0N)
Regression: ✅ (\x3Cmodules tested>)
Date: YYYY-MM-DD

Types: feat fix refactor style chore docs migration

Scope Change Notice

Issue this when implementation scope exceeds G1 estimate:

【范围变更通知 #CR-YYYYMMDD-NN】
发现：\x3Cwhat was discovered>
原估计：\x3CG1 scope>
实际需要：\x3Cadditional scope>
影响：\x3Cwhat this changes about risk/time/restart>

建议：
  A. 继续，扩大本 CR 范围
  B. 拆分：当前 CR 只做原范围，新开 CR 处理额外部分
  C. 回滚当前改动，重新评估

✅ 选 A / 🔀 选 B / ❌ 选 C

Scope Discovery Commands

# Who imports this module?
grep -rn "from \x3Cmodule> import\|import \x3Cmodule>" \x3Cbackend_dir>/ --include="*.py"

# What has a relationship to this model?
grep -rn 'relationship.*"\x3CModel>"' \x3Cbackend_dir>/ --include="*.py"

# Which frontend pages call this API route?
grep -rn "api\.\(get\|post\|put\|patch\|delete\)" \x3Cfrontend_dir>/ --include="*.vue" | grep "\x3Croute-keyword>"

# Run full scope check
python ~/.openclaw/skills/shipguard/scripts/scope_check.py \x3CIdentifier> \x3Cproject_root>

Dependency Rules for Regression Scope

Anti-patterns (never do)

• ❌ Write code before requirement is confirmed
• ❌ Change DB schema without a migration script
• ❌ Restart only api when models change — always restart dependent workers too
• ❌ Use broad exception handlers to change entity status (use typed exceptions only)
• ❌ Close a CR without regression testing
• ❌ Silently expand scope mid-implementation
• ❌ Self-downgrade a critical path change to "low risk"
• ❌ Mix two task types in one CR
• ❌ Invent new TCs at Gate 3 that weren't in Gate 0
• ❌ Skip Gate 5 — lessons must always be recorded