ShipGuard

Dev Tools

Structured software development workflow for AI-assisted codebases: gated requirement intake with test cases, change impact analysis, typed implementation boundaries, verified delivery, full regression testing, and experience accumulation. Prevents silent breakage and scope creep.

Install

openclaw skills install shipguard

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: <name>
Stack: <tech stack>
Stage: <development / production / maintenance>

## Critical Paths (changes always require confirmation)
1. <core flow step 1>
2. <core flow step 2>
...

## Protected Modules
- <module>: <why it's protected>

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

## Owner
<name / contact>

## Deployment Constraints
- <constraint>

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.

Type	Marker	Allowed scope	Forbidden	Execution
UI Tweak	🎨	Styles, labels, layout, field order	Backend logic, API structure, DB	Auto — notify after
Bug Fix (isolated)	🐛	The broken code only	UI redesign, unrelated features, requirements	Auto — notify after
Bug Fix (critical path)	🐛⚠️	The broken code only	Same as above	Confirm required
Feature	✨	New end-to-end functionality	Existing unrelated features	Confirm required, full G0–G4
Product Change	📋	Business logic, field definitions, flows	Architecture layer	Confirm required, full G0–G4
Architecture	🏗️	Refactor, performance, structure	Business behavior must stay identical	Confirm required, full G0–G4
Docs / Config	📄	Documentation, config files	Code logic	Auto — notify after

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】
原始需求：<user's exact words>
任务类型：🎨 UI微调 / 🐛 Bug Fix / ✨ Feature / 📋 Product / 🏗️ Architecture / 📄 Docs
执行策略：直接执行 / 需要确认

理解：<concrete behavioral description, not paraphrase>
范围：<which modules / pages / APIs>
排除：<what is explicitly NOT changing>
假设：<any ambiguities and how they're resolved>
已知风险：<from hard-rules.md and lessons.md relevant to this request>

Test Cases：
  TC-01【正常流程】<action> → <expected result>
  TC-02【正常流程】<action> → <expected result>
  TC-03【边界条件】<action> → <expected result>
  TC-04【异常流程】<action> → <expected 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（风险：低/中/高，原因：<why>）

影响范围：
  直接：<directly affected features>
  间接：<potentially affected modules>
  无影响：<explicitly excluded>

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

风险说明：<required when 🔴>
回滚方案：<how to revert if things go wrong>
关联回归模块：<modules 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
    + <added>
    ~ <modified: what and why>
    - <removed>

配套操作：
  迁移：<script name, execution status>
  重启：<which containers>
  其他：

未改动（排除确认）：
  - <file/module>: <reason 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【正常流程】<description> → <expected>
  □ TC-02【正常流程】...
  □ TC-03【边界条件】...
  □ TC-04【异常流程】...

请逐项验收后回复：
✅ 全部通过 → 进入回归测试
❌ TC-? 失败：<describe 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】

本次改动模块：<from G1>

需要回归：
  ├── <Module A>
  │   ├── <feature / page 1>
  │   └── <feature / page 2>
  └── <Module B>

不需要回归（确认无关联）：
  - <module>: <reason>

---

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

<Module A>：
  □ R01. <specific action> → <expected>
  □ R02. <specific action> → <expected>

<Module B>：
  □ R03. <specific action> → <expected>

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

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】
任务类型：<type>

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

新增底层规则：
  ✅ 永远要做：<rule>
  ❌ 永远不做：<rule>

写入：
  lessons/lessons.md → <dated entry>
  lessons/hard-rules.md → <if new permanent rule established>
  test-cases/all-test-cases.md → <append TCs from this CR>
  CHANGELOG.md → <append entry>

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

Commit Format

<type>(<scope>): <summary> #CR-YYYYMMDD-NN

Changed:
- <file>: <what and why>

Side effects:
- Migration: <SQL or "none">
- Restart: <containers or "none">
- Breaking: yes / no

Feature QA: ✅ (TC-01 to TC-0N)
Regression: ✅ (<modules 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】
发现：<what was discovered>
原估计：<G1 scope>
实际需要：<additional scope>
影响：<what 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 <module> import\|import <module>" <backend_dir>/ --include="*.py"

# What has a relationship to this model?
grep -rn 'relationship.*"<Model>"' <backend_dir>/ --include="*.py"

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

# Run full scope check
python ~/.openclaw/skills/shipguard/scripts/scope_check.py <Identifier> <project_root>

Dependency Rules for Regression Scope

Changed	Must also regress
DB model	All pages/APIs using that table
ORM relationship	All tasks and services that import that model
Shared service	All callers
Auth / middleware	All protected routes
Celery task	Task schedule config page + related data display pages
API router	All frontend pages calling that endpoint
Frontend store / composable	All components using it

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

ShipGuard

Install

ShipGuard

When to activate

Core principle

Project Onboarding (First Use)

Project Directory Structure

Task Types & Execution Policy

Gate 0 — Requirement Intake + Test Case Definition

Gate 1 — Change Impact Analysis

Gate 2 — Implementation

Gate 3 — Feature QA

Gate 4 — Regression Testing

Gate 5 — Lessons (Auto, no confirmation needed)

Commit Format

Scope Change Notice

Scope Discovery Commands

Dependency Rules for Regression Scope

Anti-patterns (never do)

Related skills