sdtk-kit 0.3.1 → 0.3.3

package/assets/toolkit/toolkit/skills/sdtk-arch/references/FLOWCHART_CREATION_RULES.md

@@ -1,397 +1,20 @@
-# Flowchart Creation Rules for AI Agents (PlantUML)
+# FLOWCHART CREATION RULES (Compatibility Note)
 
-This document defines reusable rules for creating and updating API flowcharts in this project.
-Target files are usually API flow list documents (for example `*_api.txt`) and API YAML files (for example `docs/api/*.yaml`).
+This file is kept only for backward compatibility.
 
-## 1. Scope and Goal
+Do not use this file as the primary source of truth anymore.
+The rule set has been split into two files:
+- `YAML_CREATION_RULES_FINAL.md` (root) / `templates/docs/api/YAML_CREATION_RULES.md` (toolkit)
+- `API_DESIGN_FLOWCHART_CREATION_RULES_FINAL.md` (root) / `templates/docs/api/API_DESIGN_FLOWCHART_CREATION_RULES.md` (toolkit)
 
-- Use PlantUML activity diagrams for API process flows.
-- Keep diagrams readable, implementation-aware, and consistent with current backend logic.
-- Prefer minimal-impact documentation changes when existing customer logic is already running.
+Use the YAML rules file for:
+- endpoint path/method conventions
+- request/response schema design
+- contract-level API rules
 
-## 2. File and Diagram Structure
-
-- One API flow = one `@startuml ... @enduml` block.
-- If helper logic is extracted, add a separate `@startuml ... @enduml` block for that helper.
-- Keep API title in `partition`:
-  - `partition "POST  **/api/path/{company_uuid}**  Japanese summary" { ... }`
-- Optional helper flow style:
-  - `rectangle "Logic function name" { ... }`
-
-## 3. Mandatory Activity Syntax Rules
-
-- Every action line must end with `;`
-- Every `if (...) then (...)` must be closed by `endif`
-- Use `else (no)` and `then (yes)` labels explicitly for branch readability.
-- Use `repeat ... repeat while ...` only when loop behavior is required.
-
-## 4. Color/Highlight Rules (Non-deprecated)
-
-Use stereotype-based color syntax (new style), not old prefix style.
-
-- Correct:
-  - `:Return Error status = 100: Parameter invalid;<<#pink>>`
-  - `:Call query_search_by_keyword() function;<<#lightGreen>>`
-- Avoid deprecated old style:
-  - `#pink:...`
-  - `#lightGreen:...`
-
-## 5. Standard API Flow Skeleton
-
-```plantuml
-@startuml
-partition "POST  **/sample/path/{company_uuid}**  API summary" {
-  start
-  :Process authentication\\nCommon auth process;
-  :Validate parameter;
-  if (is valid) then (no)
-    :Return Error status = 100: Parameter invalid;<<#pink>>
-    stop
-  else (yes)
-  endif
-  :Main process;
-  :Close DB connection;
-  :Create api response;
-  stop
-}
-@enduml
-```
-
-## 6. Query-Building Style Rules
-
-When describing SQL-like logic in flowchart:
-
-- Build query in steps:
-  1. `Create search query and condition statement from request.data;`
-  2. `query = "...";`
-  3. `condition = "...";`
-  4. optional condition append blocks
-  5. `Compose full query: fullQuery = query + condition;`
-  6. apply order/paging
-  7. execute query
-
-- Keyword pattern:
-  - `LIKE '%data.info.keyword%'`
-- Order pattern:
-  - `Add order by data.info.order_flg data.info.order_type into fullQuery;`
-- Paging pattern:
-  - `Add "LIMIT = data.info.limit OFFSET = data.info.offset" into fullQuery;`
-
-### 6.1 Endpoint-level Mapping Must Be Explicit
-
-For keyword/order enhancements, always document mapping between request params and DB columns per endpoint.
-
-- `keyword` must list all searchable columns/tables.
-- `order_flg` must list allowed sort targets and mapped columns.
-- `order_type` must be documented as `asc/desc`.
-- If payload includes new fields that are not handled by current legacy code,
-  add explicit processing logic for those new fields in the helper flow.
-  Do not silently ignore newly introduced request fields.
-
-Example (`/bukken-manager/regno/customer/search/{company_uuid}`):
-- `keyword`:
-  - `CLD_DAT_CUSTOMER_REG_NO_INFO.customer_reg_no`
-  - `CLD_MST_LOCATION_INFO.location_name`
-  - `CLD_MST_REG_NO_TYPE_INFO.name`
-- `order_flg`:
-  - `customer_reg_no` / `location_name` / `name`
-- `order_type`:
-  - `asc` / `desc`
-
-## 7. Backward-Compatible Merge Pattern
-
-When new requirements are added to an existing API:
-
-- Keep current handler path for old request behavior.
-- Add conditional branch for new logic only when required params exist.
-- Recommended branch style:
-  - If all new params are null -> keep old logic
-  - Else -> call extracted helper function
-- Use this exact "no-impact first" branch when preserving customer legacy handlers:
-  - `if (data.info.keyword null and data.info.order_flg null and data.info.order_type null) then (yes)`
-  - `:Keep the current search logic handler: <existing_handler>();`
-  - `else (no)` -> call helper for new query logic
-- In the legacy branch, do not duplicate old internal sub-steps unless explicitly requested.
-  - Avoid extra lines like mapping/query detail when they are already part of existing handler behavior.
-  - Prefer one concise line:
-    - `:Keep the current search logic handler: <existing_handler>();`
-
-Example:
-
-```plantuml
-if (data.info.keyword null and data.info.order_flg null and data.info.order_type null) then (yes)
-  :Keep the current search logic handler: regno_search();
-else (no)
-  :Call query_search_by_keyword() function;<<#lightGreen>>
-endif
-```
-
-## 8. Helper Function Diagram Pattern
-
-```plantuml
-@startuml
-rectangle "Logic query search by keyword" {
-  :query_search_by_keyword();<<#lightGreen>>
-  :Create search query and condition statement from request.data;
-  :query = "...";
-  :condition = "...";
-  if (data.info.keyword not null) then (yes)
-    :condition += "...";
-  else (no)
-  endif
-  :Compose full query:\\nfullQuery = query + condition;
-  :Add order by data.info.order_flg data.info.order_type into fullQuery;
-  :Add "LIMIT = data.info.limit OFFSET = data.info.offset" into fullQuery;
-  :Execute fullQuery and get data;
-  :return return_datas;
-}
-@enduml
-```
-
-### 8.1 Helper Naming Rule
-
-- Use helper names that include endpoint domain to avoid collisions across many APIs.
-- Recommended:
-  - `query_search_by_keyword()` for generic case
-  - `query_search_by_keyword_customer_regno()` for customer-regno endpoint
-
-### 8.2 Legacy Fallback Rule (Search APIs)
-
-- When modernizing an existing search endpoint, explicitly describe legacy fallback behavior:
-  - soft-delete flag fallback from existing code path (if any)
-  - default order fallback when `order_flg/order_type` is absent
-  - default filters applied when optional inputs are null
-- Keep these fallback notes visible in flowchart text to avoid behavior drift.
-
-### 8.3 Extended Filter Branch/Response Rule
-
-- If new optional filter fields are added, include all of them in the no-impact branch check.
-- When relation-based filters are used, explicitly show join/filter logic in helper flow.
-- If response contains multiple typed lists, keep each list explicit in flowchart/YAML (for example `data.<entity>_info[]`) and include summary metadata such as `count` when applicable.
-
-## 9. Path Canonicalization Rule
-
-- If YAML path and actual route path are different, use the confirmed actual route path in flowchart.
-- Always prioritize route path defined in backend code (`urls.py`) over YAML documentation.
-- If route path cannot be found in code, fallback to YAML path and mark it as assumed/temporary.
-- Always confirm this with user before finalizing.
-
-## 9A. API Endpoint Design Rules (Project Standard)
-
-These rules must be applied when creating/updating API flowcharts and YAML in this project.
-
-- Use singular object keyword in endpoint path:
-  - Correct: `/invoice`, `/assignment`, `/personal-schedule`
-  - Avoid: `/invoices`, `/assignments`
-- Use canonical business-domain keywords from glossary/spec terminology.
-- Avoid ambiguous aliases when official domain terms exist.
-- Use action keywords that describe behavior clearly:
-  - List: `.../list/...`
-  - Update: `.../edit/...`
-  - Delete: `.../delete/...`
-  - Multi-create: `.../multi-create`
-  - Avoid vague action keyword `bulk` when behavior is multi-create.
-
-### 9A.1 Endpoint Pattern
-
-- List API:
-  - `GET /{object}/list/{company_uuid}/{bukken_uuid}`
-- Create API:
-  - `POST /{object}/{company_uuid}/{bukken_uuid}`
-- Edit API:
-  - `POST /{object}/edit/{company_uuid}/{object_uuid}`
-- Detail API:
-  - `GET /{object}/edit/{company_uuid}/{object_uuid}`
-- Delete API:
-  - `POST /{object}/delete/{company_uuid}/{object_uuid}`
-
-### 9A.2 HTTP Method Policy
-
-- Do not use `PUT` for update APIs. Use `POST .../edit/{uuid}`.
-- Do not use `DELETE` method for delete APIs. Use `POST .../delete/{uuid}`.
-
-### 9A.3 Canonical Examples
-
-- Invoice sample:
-  - `GET /invoice/list/{company_uuid}/{bukken_uuid}`
-  - `POST /invoice/{company_uuid}/{bukken_uuid}`
-  - `POST /invoice/edit/{company_uuid}/{invoice_uuid}`
-  - `GET /invoice/edit/{company_uuid}/{invoice_uuid}`
-  - `POST /invoice/delete/{company_uuid}/{bukken_uuid}`
-
-## 9B. General Design and Documentation Governance Rules
-
-Apply the rules below as cross-project standards for API YAML and flowchart generation.
-These rules complement section `9A` (path syntax + method policy) and avoid redefining it.
-
-### 9B.1 Rule Precedence and Consistency
-
-- Endpoint naming/method conventions must follow section `9A`.
-- If a feature needs an exception from `9A`, document the reason and get explicit confirmation before finalizing.
-- Keep terminology consistent across path, request/response schema, flowchart labels, and API summary tables.
-
-### 9B.2 Parameter Placement Rule
-
-- Path parameters: identity and routing keys (`{company_uuid}`, `{resource_uuid}`).
-- Query parameters: lightweight filtering/sorting/paging.
-- Request body: complex/multi-field search criteria.
-- If retrieval requires many filter fields, prefer dedicated `POST .../search` over overloaded query strings.
-
-### 9B.3 Read Contract Shape Rule (List vs Search)
-
-- Use list-style read API for simple retrieval contracts.
-- Use search-style read API when filter logic is complex or payload-based.
-- If one endpoint forces heavy client-side matching/filtering for different screen modes, split read endpoints by view purpose.
-
-### 9B.4 Endpoint Split vs Merge Decision Rule
-
-- Split endpoints when:
-  - view/use-case shaping is materially different
-  - one endpoint causes excessive client orchestration
-- Merge endpoints/datasets when:
-  - data is always consumed together under the same filter context
-  - separate endpoints only add latency and maintenance cost
-- Record split/merge rationale in API description and flowchart notes.
-
-### 9B.5 Reuse vs New Endpoint Rule
-
-- Reuse existing endpoints only when request/response contract is truly compatible with target screen logic.
-- If existing API is semantically close but contract-incompatible, create a bounded new endpoint for that use case.
-- Mark endpoint lifecycle in docs via `API Type` classification (see `9B.8`).
-
-### 9B.6 Namespace and Path Redundancy Rule
-
-- Separate namespaces by bounded context/domain.
-- Avoid repeating parent namespace meaning in child path segments.
-- Keep paths concise but semantically clear.
-
-### 9B.7 Screen-to-API Traceability Rule
-
-- Every UI flow/action section must map:
-  - trigger/action
-  - called API
-  - response fields used for rendering
-- Explicitly mark when a single endpoint serves multiple actions (initial load, search, refresh, etc.).
-
-### 9B.8 API List Governance Rule (Markdown Specs)
-
-- API summary tables must include at least:
-  - `No`
-  - `Method`
-  - `Endpoint`
-  - `API Type`
-  - `Description`
-- Group APIs by delivery status for planning visibility:
-  1. `New`
-  2. `Deferred`
-  3. `Existing (reuse)`
-- After regrouping, renumber `No` sequentially.
-
-### 9B.9 Change Management Rule
-
-- For every endpoint rename/add/remove/merge:
-  - update endpoint detail sections
-  - update API summary tables
-  - update screen-to-API mapping
-  - append a new row in document history
-- Preserve old history rows; never rewrite historical entries.
-
-### 9B.10 Canonical Response Envelope Rule
-
-- Use one canonical response envelope across a bounded module/feature.
-- Keep the envelope shape consistent in YAML examples, flowchart return nodes, and markdown endpoint tables.
-- Recommended normalized envelope keys:
-  - `status`
-  - `msg`
-  - `data`
-  - `format_version`
-- If a legacy API has a different wrapper, document it explicitly as an exception.
-
-### 9B.11 Business Status Rule
-
-- Business execution result must be represented in response body `status` (not only by HTTP code).
-- Flowchart branches must map to business status outcomes, including validation and duplicate/conflict-like results.
-- Document endpoint-level status code matrix in API docs when branching is non-trivial.
-- HTTP status policy can vary by system profile, but body `status` must remain deterministic.
-
-### 9B.12 Request Body Wrapper Rule
-
-- For write/search APIs that use POST payloads, prefer a stable top-level wrapper object:
-  - `data: { ... }`
-- Keep filter/search fields under `data` when criteria are complex or nested.
-- If legacy contracts do not use wrapper objects, document exception and compatibility reason.
-
-### 9B.13 Traceability Metadata Rule
-
-- YAML should include explicit traceability metadata for each endpoint (for example `x-traceability`).
-- Minimum mapping targets:
-  - BR (business rule)
-  - UC (use case)
-  - AC (acceptance criteria)
-- Flow list and markdown API docs should preserve the same mapping IDs to keep cross-artifact traceability.
-
-### 9B.14 Language and Encoding Governance
-
-- EN artifact set must use English narrative consistently.
-- Save generated markdown/YAML as UTF-8 and remove mojibake/corrupted characters before handoff.
-- If source input is VI/JP, keep original text only in dedicated appendix/quotation blocks when needed for traceability.
-
-### 9B.15 Abbreviations and Table Numbering Governance
-
-- For generated markdown specs, include an `Abbreviations` section near the top when acronyms are used.
-- Apply `No` column and sequential renumbering policy by following section `9B.8`.
-
-## 9C. Project Profile Overlay Rule (Cross-Project Reuse)
-
-- Separate reusable core rules from system-specific constraints.
-- Keep system-specific choices in a project profile layer, for example:
-  - fixed HTTP policy patterns
-  - datetime timezone/local-naive policy
-  - method conventions such as POST-based edit/delete
-- When reusing these rules for a new system, adopt core rules first, then explicitly decide profile overrides.
-- Do not silently promote one system profile as global default for all projects.
-
-## 10. Wording Rules
-
-- Use concrete action verbs:
-  - `Select ...`
-  - `Update ...`
-  - `Insert ...`
-  - `Create api response;`
-- For existing behavior preservation, use explicit wording:
-  - `Keep the current search logic handler: <function>();`
-- Do not add redundant response details if globally standardized.
-  - Prefer `:Create api response;` over verbose wrappers.
-
-## 11. Error/Status Rules in Flow Text
-
-- Parameter validation error: usually `status = 100` (unless API-specific rule says otherwise).
-- Temporary unknown error code policy may use `status = 900` if already agreed.
-- Keep status usage consistent with confirmed project decisions.
-
-## 12. Common Preview Errors and Fixes
-
-- Error: `Cannot find group ... @enduml`
-  - Cause: missing `endif` or malformed action statement
-  - Fix: close all branches and ensure each action line ends with `;`
-
-- Warning: `This syntax is deprecated...`
-  - Cause: old color syntax (`#pink:...`, `#lightGreen:...`)
-  - Fix: move color marker to end of action:
-    - `:...;<<#pink>>`
-    - `:...;<<#lightGreen>>`
-
-## 13. Final Checklist Before Handoff
-
-- Diagram renders in PlantUML Preview without error.
-- No deprecated color syntax warnings.
-- All `if` blocks have matching `endif`.
-- New logic branch does not remove old logic path unless explicitly requested.
-- SQL condition/order/paging statements match agreed spec.
-- API path and method match the confirmed actual route (use YAML path only when they are identical).
-- Response envelope is consistent with module-level canonical contract.
-- Business `status` mapping is explicit in both YAML and flow branches.
-- POST search/write payload wrapper (`data`) is consistent (or exception documented).
-- Traceability links (BR/UC/AC) are present and consistent across artifacts.
-- EN/UTF-8 quality check passed (no mixed-language drift, no mojibake).
+Use the API design + flowchart rules file for:
+- flow list writing
+- PlantUML flow depth and wording
+- API design detail markdown rules
 
+This compatibility note should remain only until all references are migrated.

package/assets/toolkit/toolkit/skills/sdtk-arch/references/YAML_CREATION_RULES.md

@@ -0,0 +1,128 @@
+# YAML CREATION RULES FINAL
+
+This file is the canonical rule set for designing and maintaining feature-level OpenAPI YAML.
+
+Use this file for:
+- OpenAPI YAML contract design
+- endpoint path/method decisions
+- request/response schema design
+- endpoint summary and contract consistency checks
+
+Do not use this file as the primary rule source for:
+- flowchart writing details
+- API design detail markdown layout
+
+Use `API_DESIGN_FLOWCHART_CREATION_RULES_FINAL.md` for those.
+
+## 1. Rule Precedence
+- Priority 1: follow the existing system's real route, method, payload, and response conventions.
+- Priority 2: match the current source code and runtime behavior.
+- Priority 3: apply the reusable standards in this document.
+- If a reusable rule conflicts with the target system, keep the system rule and document the exception explicitly.
+
+## 2. API Scope Classification
+- Every endpoint must be classified as one of:
+  - `New`
+  - `Deferred`
+  - `Existing (reuse)`
+- Do not silently create a new feature-local API if an existing system API already provides the same behavior with a compatible contract.
+- If the existing API is close in purpose but payload or response is incompatible with the feature need, create a bounded new API.
+
+## 3. Endpoint Path Design
+- Use singular resource names in endpoint paths.
+- Use explicit action segments only when needed by system convention:
+  - `list`
+  - `search`
+  - `edit`
+  - `delete`
+  - `multi-create`
+- Prefer stable system-style patterns such as:
+  - list: `GET /{resource}/list/{company_uuid}/{parent_uuid}`
+  - search: `POST /{resource}/search/{company_uuid}`
+  - view-specific search: `POST /{resource}/bukken-view/search/{company_uuid}`
+  - create: `POST /{resource}/{company_uuid}`
+  - detail: `GET /{resource}/{company_uuid}/{resource_uuid}`
+  - edit: `POST /{resource}/edit/{company_uuid}/{resource_uuid}`
+  - delete: `POST /{resource}/delete/{company_uuid}/{resource_uuid}`
+- Separate namespaces by bounded context.
+- Do not repeat namespace meaning in child path segments.
+
+## 4. Request Contract Rules
+- For feature-owned POST search and write APIs, prefer a stable wrapper:
+  - `data: { ... }`
+- For complex filters, place fields under:
+  - `data.info`
+- If reusing an existing system API, keep the owning module's contract shape exactly as-is.
+- Do not force reused APIs into the feature wrapper pattern.
+- If a payload field changes behavior, the field must be explicit in the schema and must not remain only in examples.
+
+## 5. Response Contract Rules
+- Success responses must include `status` at minimum.
+- Create APIs should return the minimum new identifier required by the caller.
+  - Example: `status + sagyo_assign_uuid`
+- Edit and delete APIs should return status-only unless the target system has a stronger standard.
+- Pre-check or validation helper APIs should return only the minimum boolean or status needed by the UI.
+  - Do not return detail payloads the UI does not consume.
+- Do not add FE-only visual helper payloads when the client can derive them safely.
+  - Example: remove `timeline_backgrounds` if the frontend renders timeline lines from existing data.
+
+## 6. Naming and Field Mapping Rules
+- Use canonical business-domain terminology from the system glossary and database.
+- Prefer actual system terms such as:
+  - `bukken`
+  - `sagyo`
+  - `sagyoin`
+  - `certification`
+- Avoid legacy aliases when an official term already exists.
+- Field names should align with database semantics when they represent the same concept.
+- If the DB uses a string state code, the API field must not be modeled as an integer.
+- If a field is date-only (`format: date`), include the display format in the description.
+  - Example: `Start date (YYYYMMDD)`
+
+## 7. Search and List API Rules
+- One search API may serve multiple UI actions when the logic is the same:
+  - initial load
+  - search button
+  - refresh after mode/date change
+- If one endpoint serves multiple UI actions, document that explicitly in YAML description and endpoint docs.
+- Search APIs must define filter combination semantics clearly:
+  - AND across different fields
+  - OR within each `*_uuids` array
+- If UI rendering depends on stable order, the YAML description must state the confirmed ORDER BY logic.
+
+## 8. Split vs Reuse Rules
+- Split read/search endpoints when the FE needs materially different grouped or view-shaped datasets.
+- Merge or remove helper payloads when they add maintenance cost without business value.
+- Reuse existing platform APIs when behavior already exists and only a feature-level mapping layer is needed.
+  - Example: reuse shared environment setting APIs instead of creating feature-local setting APIs.
+
+## 9. Sample Data Rules
+- For fields declared as `format: uuid`, use canonical UUID samples.
+  - Example: `123e4567-e89b-12d3-a456-426614174000`
+- Do not use placeholder UUID-like labels such as:
+  - `customer-uuid-001`
+  - `assign-uuid-001`
+- Keep sample data deterministic and internally consistent across request and response examples.
+
+## 10. Cross-Artifact Consistency Rules
+- The YAML contract is the source of truth for:
+  - endpoint path
+  - method
+  - request wrapper
+  - response shape
+- After any YAML contract change, sync these artifacts:
+  - endpoint markdown
+  - flow list
+  - PlantUML flow assets
+  - API design detail markdown
+- If any artifact cannot yet be synced, note the mismatch explicitly rather than leaving stale content.
+
+## 11. Minimum YAML Quality Gate
+- Path/method follow the target system convention.
+- API type is classified (`New`, `Deferred`, `Existing (reuse)`).
+- Request/response wrappers are stable and explicit.
+- FE-only helper payloads are removed.
+- Field names and types match DB semantics.
+- UUID examples are valid UUIDs.
+- Date descriptions include display format where needed.
+- Search/list APIs document filter semantics and ordering when relevant.

package/assets/toolkit/toolkit/skills-claude/api-design-spec/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: api-design-spec
+description: Generate detailed API design markdown from OpenAPI YAML and API flow list using Excel-style structure rules. Use when you need field-level request/response tables + per-endpoint process flow images for implementation/review handoff.
+---
+
+## Required Inputs (read before proceeding)
+Read the following artifacts for the current feature:
+1. `docs/api/[FeaturePascal]_API.yaml` — API contract
+2. `docs/api/[feature_snake]_api_flow_list.txt` — flow list
+
+## Input
+$ARGUMENTS
+
+# SDTK API Design Detail Spec
+
+## Outputs
+- `docs/api/[FEATURE_KEY]_API_DESIGN_DETAIL.md`
+- Supporting generated assets:
+  - `docs/api/flows/*.puml`
+  - `docs/api/images/*.svg`
+
+## Required Inputs
+- Feature key (`FEATURE_KEY`)
+- API contract YAML:
+  - Preferred: `docs/api/[FeaturePascal]_API.yaml`
+  - Fallback: a specified YAML file path
+- API flow list:
+  - Preferred: `docs/api/[feature_snake]_api_flow_list.txt`
+  - Fallback: a specified flow list path
+
+## Core Rules
+- Apply `.claude/skills/references/API_DESIGN_FLOWCHART_CREATION_RULES.md` first.
+- Keep endpoint contracts consistent with source YAML.
+- Keep process flow source synchronized with flow list (`*_api_flow_list.txt`).
+- Keep one visible flowchart per API section (embed image), avoid duplicate preview rendering.
+- Keep `Process Flow` sections implementation-readable:
+  - include YAML-derived flow summary / notes / login bullets
+  - keep error sections aligned with actual flow exits, not `None`
+
+## Generation Procedure
+1. Resolve input files (`yaml`, `flow_list`, `output`).
+2. Parse YAML endpoints (method, path, request schema, success/error schema).
+3. Parse flow blocks from flow list (`@startuml ... @enduml`) and map by `METHOD + path`.
+4. Generate detailed markdown sections per API:
+   - Flow summary / notes / login bullets from YAML `description`
+   - Process flow source block (`text` fenced block)
+   - Embedded flowchart image
+   - Path parameter table
+   - Request table (hierarchy levels + type + format + required)
+   - Success response table
+   - Error response table (explicit schema if defined, otherwise shared envelope + inferred business statuses from flow)
+5. Generate/update `.puml` per API under `docs/api/flows`.
+6. Render `.svg` images under `docs/api/images`.
+7. Validate:
+   - every API section has one embedded image
+   - every embed path exists
+   - no render error image output
+   - markdown tables keep `No` sequential numbering
+
+## Script
+- `scripts/generate_api_design_detail.py`
+
+### Typical command
+```bash
+python scripts/generate_api_design_detail.py \
+  --feature-key SCHEDULE_WHITEBOARD \
+  --yaml "docs/api/ScheduleWhiteboard_API.yaml" \
+  --flow-list "docs/api/schedule_whiteboard_api_flow_list.txt" \
+  --output "docs/api/SCHEDULE_WHITEBOARD_API_DESIGN_DETAIL.md"
+```
+
+## Orchestrator Integration (Hybrid)
+- `apiDesignDetailMode` in `sdtk.config.json` controls orchestration behavior:
+  - `auto` (default): generate API design detail when ARCH has API scope and YAML/flow sources are available.
+  - `on`: always generate API design detail for API scope (fail if required sources are missing).
+  - `off`: skip unless user explicitly requests.

package/assets/toolkit/toolkit/skills-claude/api-doc/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: api-doc
+description: Generate OpenAPI 3.x YAML and PlantUML flow diagrams for a feature following this toolkit's API conventions. Use when you need to create/update docs/api/* (API spec + flow list) from BA_SPEC/ARCH_DESIGN.
+---
+
+## Required Inputs (read before proceeding)
+Read the following artifacts for the current feature:
+1. `docs/specs/BA_SPEC_*.md` — business rules, use cases
+2. `docs/architecture/ARCH_DESIGN_*.md` — system components, data model
+
+## Input
+$ARGUMENTS
+
+# SDTK API Documentation
+
+## Outputs
+- `docs/api/[FeaturePascal]_API.yaml`
+- `docs/api/[FEATURE_KEY]_ENDPOINTS.md`
+- `docs/api/[feature_snake]_api_flow_list.txt`
+- Optional downstream (via `/api-design-spec`):
+  - `docs/api/[FEATURE_KEY]_API_DESIGN_DETAIL.md`
+
+## Inputs (minimum)
+- Feature name/key
+- Entities + key fields
+- Use cases (UC-xx) + business rules (BR-xx)
+- Auth/permission model
+
+## Process
+1. Read `docs/specs/BA_SPEC_[FEATURE_KEY].md` and/or `docs/architecture/ARCH_DESIGN_[FEATURE_KEY].md`.
+2. Read and apply split API rule sources:
+   - `.claude/skills/references/YAML_CREATION_RULES.md` for YAML contract rules
+   - `.claude/skills/references/API_DESIGN_FLOWCHART_CREATION_RULES.md` for flow list / flowchart rules
+3. Define endpoints mapped to UC-xx; keep path naming consistent across CRUD/search/list/mst patterns.
+4. For each endpoint, document request/response schema and error cases.
+5. Generate/update endpoint markdown (`[FEATURE_KEY]_ENDPOINTS.md`) with summary tables, API type grouping, and screen-logic mapping.
+6. Generate PlantUML flows including: auth, permission check, validation, main logic, error exits.
+7. Ensure traceability notes reference UC/BR where relevant.
+8. Validate English output hygiene when generating English artifacts:
+   - no mixed-language leftovers in narrative text
+   - no mojibake/encoding corruption markers
+   - terminology consistency across endpoint detail, summary tables, and flow labels
+9. If orchestrator mode requires API design detail generation (`apiDesignDetailMode=auto/on`), handoff to `/api-design-spec` after YAML + flow list are updated.
+
+## Reference
+- Deeper analysis: `docs/specs/API_DOC_SKILL_ANALYSIS.md` (if present).