ShipGuard

SKILL.md

---
name: shipguard
description: "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."
homepage: https://github.com/morelapAI/shipguard
license: MIT
---

# 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`:

```markdown
# 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

```bash
# 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