Api Plan

Name: Api Plan
Author: YuDefine

ASecurity

Truth owner skill。根據 plan package、system-analysis handoff 與現有 API truth，更新 `specs/truth/contracts/**`，支援 ADD / MODIFY / DELETE / NOOP API 語意單元，並委派 `/truth-delta` 記錄本輪 API truth 改動。

44 stars
0 votes
0 copies
1 view
Added September 24, 2026

developmentapi

Works with

cursor
api

Security analysis

A100/100

Pro scans all 3 files and shows the line behind each finding

Scanned September 24, 2026

npx -y skills add Charles5277/nuxt-supabase-starter --skill api-plan --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Api Plan?

Add the live security badge to your README. It updates with every re-scan.

[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/charles5277-api-plan/badge)](https://www.skillsdirectory.com/skills/charles5277-api-plan)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro

SKILL.md

---
name: api-plan
description: >-
  Truth owner skill。根據 plan package、system-analysis handoff 與現有 API truth，更新
  `specs/truth/contracts/**`，支援 ADD / MODIFY / DELETE / NOOP API 語意單元，並委派
  `/truth-delta` 記錄本輪 API truth 改動。
metadata:
  clade:
    invocation: explicit
---
<!-- LOCKED: mirrored from Waterball-Software-Academy/aixbdd@58960f8375d14d9c598eb2c350582917fe9b249c via scripts/sync-upstream-mirrors.ts — edit upstream, never here -->
<!-- clade-targets: claude,codex,cursor -->

# API Plan

`api-plan` 是 `specs/truth/contracts/**` 的 truth owner。它不再產出 package-local contract，而是直接維護整個系統目前唯一 API truth。

# SOP

## Phase 1 -- 對齊 API truth 與 plan handoff

1. READ 讀取使用者需求、呼叫者 handoff、plan package 的 `spec.md`、`research.md`、`plan.md`、`truth-delta.md`、`specs/truth/techstack.md`、既有 `specs/truth/contracts/**` 與指定後端 / API 介面名稱。
   - 命中 clade lifecycle repo 判準（本次 plan package 的 `plan.md` frontmatter 同時含 `work_id:` 與 `truth_baseline:`）時，`plan.md` 是 lifecycle 檔：系統分析內容改讀同 package 的 `system-analysis.md`，本輪 truth delta 改讀 `plan.md` 的 `## Truth delta` 表，該 package 沒有 `truth-delta.md`。判準只看那兩個 frontmatter 鍵，NEVER 用 repo 名、manifest 或其他檔案存在與否推斷。
2. READ 讀取 `templates/openapi.yaml` 與 `templates/openapi.example.yaml`，確認 contract artifact 的固定結構與完成樣貌。
3. READ 讀取 `.agents/constitution/CONSTITUTION.md`、`.agents/constitution/shared.md` 與 `.agents/constitution/skills/api-plan/openapi.md`。

## Phase 2 -- 盤點 API ADD / MODIFY / DELETE

1. THINK 依需求、handoff、現有 OpenAPI 與 truth-delta，整理本輪要新增、修改、刪除或保持不變的 operation、schema、field、response、error code 與狀態轉移語意。
2. DELEGATE 若高影響 MODIFY / DELETE 會改變既有對外契約、請求/回應形狀、錯誤模型或狀態轉移，且尚未有明確使用者決策，呼叫 `/clarify`；未收斂前停止。

## Phase 3 -- 更新 API truth

1. WRITE 直接更新 `specs/truth/contracts/**`，使 API truth 成為目前完整系統契約，不留下「仍以某 plan 契約為準」的分散引用。
2. READ 回頭檢查 contract 是否符合已載入憲法、指定介面需求與既有 truth 的相容性；若不符合，立即修正。
3. THINK 將 API truth 改動整理為語意單元層級的 ADD / MODIFY / DELETE / NOOP 列。

## Phase 4 -- 更新 truth-delta 並交付

1. DELEGATE 呼叫 `/truth-delta`，傳入 plan package、truth root、owner `/api-plan` 與本輪 API truth 改動列。
2. WRITE 向使用者回報更新的 API truth 路徑、主要操作與 schema 變更、是否進入 `/clarify`、truth-delta 更新結果，以及是否可交給後續實作或 `/tasks`。