sdtk-kit 0.3.7 → 0.3.9

package/assets/toolkit/toolkit/skills/sdtk-screen-design-spec/scripts/validate_flow_action_spec_numbering.py

@@ -10,6 +10,7 @@ from pathlib import Path
 TABLE_ROW_RE = re.compile(r"^\|.*\|\s*$")
 TABLE_SEP_RE = re.compile(r"^\|\s*:?-+:?\s*(\|\s*:?-+:?\s*)+\|\s*$")
 HEADING_RE = re.compile(r"^(#{1,6})\s+(.*\S)\s*$")
+SCREEN_SECTION_HEADING_RE = re.compile(r"^###\s+(.*\S)\s*$", re.MULTILINE)
 VI_DIACRITIC_RE = re.compile(r"[À-ỹ]")
 VI_PHRASE_RE = re.compile(
     r"\b("
@@ -19,6 +20,15 @@ VI_PHRASE_RE = re.compile(
     re.IGNORECASE,
 )
 INLINE_HEADING_RE = re.compile(r".+\s#{2,}\s+\S")
+IMAGE_LINK_RE = re.compile(r"!\[[^\]]*\]\(([^)]+)\)")
+PLANTUML_FENCE_START_RE = re.compile(r"^\s*```plantuml\s*$", re.IGNORECASE)
+NEW_STYLE_ACTIVITY_LINE_RE = re.compile(
+    r"^\s*(start|stop|partition\s+\"|if\s*\(|fork(?:\s+again)?\b|end\s+fork\b|note\s+(?:right|left|top|bottom)\b|:[^;\n]+;)",
+    re.IGNORECASE,
+)
+LEGACY_ACTIVITY_START_RE = re.compile(r"\(\*\)")
+LEGACY_EDGE_LABEL_RE = re.compile(r"-->\s*\[")
+MIXED_ACTIVITY_ARROW_RE = re.compile(r":[^;\n]+;\s*-->")
 
 
 @dataclass(frozen=True)
@@ -82,6 +92,134 @@ def collect_hygiene_issues(md_text: str, *, en_check: bool) -> dict[str, list[tu
     return issues
 
 
+def _is_root_relative_docs_href(href: str) -> bool:
+    normalized = href.strip().replace("\\", "/").lower()
+    if not normalized:
+        return False
+    if re.match(r"^[a-z][a-z0-9+.-]*://", normalized):
+        return False
+    if normalized.startswith(("mailto:", "tel:", "data:", "#")):
+        return False
+    return normalized.startswith(("docs/", "./docs/", "/docs/"))
+
+
+def collect_screen_image_path_issues(md_text: str) -> list[tuple[int, str]]:
+    issues: list[tuple[int, str]] = []
+    lines = md_text.splitlines()
+    in_code_block = False
+    expecting_image_line = False
+
+    for idx, line in enumerate(lines, start=1):
+        stripped = line.strip()
+        if stripped.startswith("```"):
+            in_code_block = not in_code_block
+            expecting_image_line = False
+            continue
+        if in_code_block:
+            continue
+        if not stripped:
+            continue
+
+        if stripped.lower().startswith("screen image:"):
+            expecting_image_line = stripped.lower() == "screen image:"
+            hrefs = IMAGE_LINK_RE.findall(stripped)
+        elif expecting_image_line and stripped.startswith("!["):
+            expecting_image_line = False
+            hrefs = IMAGE_LINK_RE.findall(stripped)
+        else:
+            hrefs = []
+            if not stripped.startswith("<!--"):
+                expecting_image_line = False
+
+        for href in hrefs:
+            if _is_root_relative_docs_href(href):
+                issues.append((idx, href))
+
+    return issues
+
+
+def collect_plantuml_activity_syntax_issues(md_text: str) -> list[tuple[int, str]]:
+    issues: list[tuple[int, str]] = []
+    lines = md_text.splitlines()
+    in_plantuml_block = False
+    block_start_line = 0
+    block_lines: list[str] = []
+
+    def flush_block() -> None:
+        nonlocal issues, block_lines, block_start_line
+        if not block_lines:
+            return
+        has_new_style = any(NEW_STYLE_ACTIVITY_LINE_RE.search(line) for line in block_lines)
+        if not has_new_style:
+            block_lines = []
+            block_start_line = 0
+            return
+
+        for offset, line in enumerate(block_lines, start=0):
+            line_no = block_start_line + offset
+            if LEGACY_ACTIVITY_START_RE.search(line):
+                issues.append(
+                    (line_no, "Legacy activity start marker `(*)` is not allowed in new-style activity diagrams.")
+                )
+            if MIXED_ACTIVITY_ARROW_RE.search(line):
+                issues.append(
+                    (line_no, "Do not append legacy `-->` transitions after a new-style `:Activity;` action line.")
+                )
+            elif LEGACY_EDGE_LABEL_RE.search(line):
+                issues.append(
+                    (line_no, "Legacy edge labels like `--> [label]` are not allowed in new-style activity diagrams.")
+                )
+
+        block_lines = []
+        block_start_line = 0
+
+    for idx, line in enumerate(lines, start=1):
+        if not in_plantuml_block and PLANTUML_FENCE_START_RE.match(line):
+            in_plantuml_block = True
+            block_start_line = idx + 1
+            block_lines = []
+            continue
+
+        if in_plantuml_block and line.strip().startswith("```"):
+            flush_block()
+            in_plantuml_block = False
+            continue
+
+        if in_plantuml_block:
+            block_lines.append(line)
+
+    if in_plantuml_block:
+        flush_block()
+
+    return issues
+
+
+def collect_wireframe_mapping_issues(md_text: str) -> list[tuple[int, str]]:
+    issues: list[tuple[int, str]] = []
+    sections = list(SCREEN_SECTION_HEADING_RE.finditer(md_text))
+    for idx, match in enumerate(sections):
+        start = match.start()
+        end = sections[idx + 1].start() if idx + 1 < len(sections) else len(md_text)
+        section_text = md_text[start:end]
+
+        if "Design Source Type: generated-draft" not in section_text:
+            continue
+        if "> Screen image not rendered in this environment." in section_text:
+            continue
+        if "Screen image:" not in section_text or "![" not in section_text:
+            continue
+        if "#### Wireframe Marker Mapping" in section_text:
+            continue
+
+        line_no = md_text.count("\n", 0, start) + 1
+        section_name = match.group(1).strip()
+        issues.append(
+            (line_no, f"{section_name}: missing `Wireframe Marker Mapping` table for generated-draft screen.")
+        )
+
+    return issues
+
+
 def parse_action_tables(md_text: str) -> list[Occurrence]:
     occurrences: list[Occurrence] = []
     current_section = ""
@@ -172,9 +310,6 @@ def main() -> int:
 
     text = _read_text(spec_path)
     occ = parse_action_tables(text)
-    if not occ:
-        print("[WARN] No action tables detected (| No | Action | Description | ... |).")
-        return 0
 
     by_number: dict[int, list[Occurrence]] = {}
     for o in occ:
@@ -191,16 +326,28 @@ def main() -> int:
 
     has_issues = bool(duplicates or decreases)
     hygiene = collect_hygiene_issues(text, en_check=args.en_check)
+    image_path_issues = collect_screen_image_path_issues(text)
+    plantuml_activity_issues = collect_plantuml_activity_syntax_issues(text)
+    wireframe_mapping_issues = collect_wireframe_mapping_issues(text)
     if hygiene["encoding"] or hygiene["inline_heading"]:
         has_issues = True
     if args.en_check and (hygiene["vi_diacritic"] or hygiene["vi_phrase"]):
         has_issues = True
+    if image_path_issues:
+        has_issues = True
+    if plantuml_activity_issues:
+        has_issues = True
+    if wireframe_mapping_issues:
+        has_issues = True
 
     print(f"Checked: {spec_path}")
     print(f"- Total numbered rows: {len(occ)}")
     print(f"- Unique numbers: {len(by_number)}")
     print(f"- EN hygiene check enabled: {args.en_check}")
 
+    if not occ:
+        print("[WARN] No action tables detected (| No | Action | Description | ... |).")
+
     if duplicates:
         print("\n[FAIL] Duplicate numbers found:")
         for n in sorted(duplicates.keys()):
@@ -233,6 +380,21 @@ def main() -> int:
         for line_no, line in hygiene["vi_phrase"][:20]:
             print(f"- line {line_no}: {line.strip()}")
 
+    if image_path_issues:
+        print("\n[FAIL] Screen image markdown paths must be file-relative, not docs-root-relative:")
+        for line_no, href in image_path_issues[:20]:
+            print(f"- line {line_no}: {href}")
+
+    if plantuml_activity_issues:
+        print("\n[FAIL] Mixed or legacy PlantUML activity syntax detected in a new-style screen-flow block:")
+        for line_no, message in plantuml_activity_issues[:20]:
+            print(f"- line {line_no}: {message}")
+
+    if wireframe_mapping_issues:
+        print("\n[FAIL] Missing wireframe-marker mapping tables for generated-draft screens:")
+        for line_no, message in wireframe_mapping_issues[:20]:
+            print(f"- line {line_no}: {message}")
+
     if not has_issues:
         print("\n[OK] Numbering and text hygiene checks passed.")
         return 0
@@ -240,6 +402,9 @@ def main() -> int:
     print("\nHint: Use global numbering across the full document.")
     print("- Do not repeat No values in any action table.")
     print("- Do not reset numbering per screen/dialog.")
+    print("- Use file-relative screen image paths such as assets/<feature>/screens/<screen>.svg.")
+    print("- Use new-style PlantUML activity syntax only for screen-flow diagrams.")
+    print("- Add a `Wireframe Marker Mapping` table when a generated-draft screen embeds a wireframe image.")
     print("- Keep EN artifacts free of Vietnamese leftovers and encoding corruption.")
     print("- Keep headings/sections on separate lines (avoid merged markdown blocks).")
     return 1

package/assets/toolkit/toolkit/skills/sdtk-test-case-spec/SKILL.md

@@ -5,6 +5,10 @@ description: Generate screen-based QA test-case markdown (`[FEATURE_KEY]_TEST_CA
 
 # SDTK Test Case Spec
 
+## Critical Constraints
+- I do not invent test coverage beyond BA, flow-action, and API sources.
+- I do not let test totals drift away from worksheet rows or the QA baseline.
+
 ## Outputs
 - `docs/qa/[FEATURE_KEY]_TEST_CASE.md`
 - Optional project variant:
@@ -28,6 +32,7 @@ description: Generate screen-based QA test-case markdown (`[FEATURE_KEY]_TEST_CA
 4. Keep one unified 18-column schema for UTC/ITC rows.
 5. Keep stable case IDs; do not renumber only because of regrouping.
 6. Track unresolved decisions via `OQ-xx` and keep benchmark-expected OQs explicitly OPEN per `governance/ai/core/SDTK_BENCHMARK_OQ_POLICY.md`.
+7. Quote exact BA, API, or flow-action requirement text when a testcase or coverage claim depends on that requirement.
 
 ## Procedure
 1. Resolve output path:
@@ -44,6 +49,12 @@ description: Generate screen-based QA test-case markdown (`[FEATURE_KEY]_TEST_CA
    - no placeholder tokens like `??`
    - out-of-scope boundaries are explicit
 
+## Specification Quoting
+When a testcase, coverage note, or defect check depends on a requirement, quote the exact source text before stating coverage or mismatch.
+
+Use this format:
+- `Spec says: "[exact quote]" -> Evidence: [covered/not covered + file reference]`
+
 ## Role Integration
 - Primary owner: `/qa`.
 - `/qa` uses this skill to design/update reusable test-case specs.

package/assets/toolkit/toolkit/skills/skills.catalog.yaml

@@ -0,0 +1,302 @@
+schema_version: 1
+skills:
+  - name: sdtk-pm
+    phase: pm
+    role_tag: /pm
+    use_when: Start feature scope or produce PM planning artifacts before BA or ARCH handoff.
+    primary_inputs:
+      - source requirements
+      - docs/product/PROJECT_INITIATION_[FEATURE_KEY].md
+      - docs/specs/BA_SPEC_[FEATURE_KEY].md
+    primary_outputs:
+      - docs/product/PROJECT_INITIATION_[FEATURE_KEY].md
+      - docs/product/PRD_[FEATURE_KEY].md
+      - docs/product/BACKLOG_[FEATURE_KEY].md
+    hard_gates:
+      - Do not hand off without updating SHARED_PLANNING.md and QUALITY_CHECKLIST.md.
+      - Keep unresolved OQ items explicit instead of silently deciding for other roles.
+    references: []
+    prompts: []
+    scripts: []
+    runtime_support: [claude, codex]
+    dependencies: []
+    pack: core
+
+  - name: sdtk-ba
+    phase: ba
+    role_tag: /ba
+    use_when: Convert PM initiation into a BA spec with glossary, BR, UC, AC, NFR, and traceability.
+    primary_inputs:
+      - docs/product/PROJECT_INITIATION_[FEATURE_KEY].md
+      - source requirements
+    primary_outputs:
+      - docs/specs/BA_SPEC_[FEATURE_KEY].md
+    hard_gates:
+      - Do not close BA output without explicit REQ to UC or BR or AC traceability.
+      - Keep unresolved OQ items visible for PM resolution.
+    references: []
+    prompts: []
+    scripts: []
+    runtime_support: [claude, codex]
+    dependencies: [sdtk-pm]
+    pack: core
+
+  - name: sdtk-arch
+    phase: arch
+    role_tag: /arch
+    use_when: Convert BA spec and PM backlog into architecture, API, DB, and UI design artifacts.
+    primary_inputs:
+      - docs/specs/BA_SPEC_[FEATURE_KEY].md
+      - docs/product/PRD_[FEATURE_KEY].md
+      - docs/product/BACKLOG_[FEATURE_KEY].md
+    primary_outputs:
+      - docs/architecture/ARCH_DESIGN_[FEATURE_KEY].md
+      - docs/api/[FeaturePascal]_API.yaml
+      - docs/api/[FEATURE_KEY]_ENDPOINTS.md
+      - docs/api/[FEATURE_KEY]_API_DESIGN_DETAIL.md
+      - docs/database/DATABASE_SPEC_[FEATURE_KEY].md
+      - docs/design/DESIGN_LAYOUT_[FEATURE_KEY].md
+      - docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md
+    hard_gates:
+      - For UI scope, DESIGN_LAYOUT must exist before FLOW_ACTION_SPEC.
+      - Keep API, DB, and screen outputs aligned to the same source requirements.
+    references:
+      - toolkit/skills/sdtk-arch/references/YAML_CREATION_RULES.md
+      - toolkit/skills/sdtk-arch/references/API_DESIGN_FLOWCHART_CREATION_RULES.md
+      - toolkit/skills/sdtk-arch/references/FLOW_ACTION_SPEC_CREATION_RULES.md
+    prompts: []
+    scripts: []
+    runtime_support: [claude, codex]
+    dependencies: [sdtk-pm, sdtk-ba]
+    pack: core
+
+  - name: sdtk-dev
+    phase: dev
+    role_tag: /dev
+    use_when: Implement a feature from approved architecture and backlog, then prepare QA handoff.
+    primary_inputs:
+      - docs/architecture/ARCH_DESIGN_[FEATURE_KEY].md
+      - docs/product/BACKLOG_[FEATURE_KEY].md
+      - docs/dev/FEATURE_IMPL_PLAN_[FEATURE_KEY].md
+    primary_outputs:
+      - docs/dev/FEATURE_IMPL_PLAN_[FEATURE_KEY].md
+      - code changes
+      - tests
+    hard_gates:
+      - Do not implement before the current FEATURE_IMPL_PLAN slice is approved.
+      - Run Stage 1 spec review before Stage 2 code-quality review.
+    references: []
+    prompts:
+      - toolkit/skills/sdtk-dev/prompts/implementer.md
+      - toolkit/skills/sdtk-dev/prompts/spec-reviewer.md
+      - toolkit/skills/sdtk-dev/prompts/code-quality-reviewer.md
+    scripts: []
+    runtime_support: [claude, codex]
+    dependencies: [sdtk-arch]
+    pack: core
+
+  - name: sdtk-qa
+    phase: qa
+    role_tag: /qa
+    use_when: Validate implementation against specs, run quality gates, and produce a release decision.
+    primary_inputs:
+      - docs/specs/BA_SPEC_[FEATURE_KEY].md
+      - docs/product/PRD_[FEATURE_KEY].md
+      - docs/product/BACKLOG_[FEATURE_KEY].md
+      - docs/dev/FEATURE_IMPL_PLAN_[FEATURE_KEY].md
+    primary_outputs:
+      - docs/qa/QA_RELEASE_REPORT_[FEATURE_KEY].md
+      - docs/qa/[FEATURE_KEY]_TEST_CASE.md
+    hard_gates:
+      - QA handoff is blocked until DEV Stage 1 and Stage 2 review gates PASS.
+      - Do not issue APPROVED without fresh verification evidence.
+    references: []
+    prompts: []
+    scripts: []
+    runtime_support: [claude, codex]
+    dependencies: [sdtk-dev]
+    pack: core
+
+  - name: sdtk-orchestrator
+    phase: orchestration
+    role_tag: /orchestrator
+    use_when: Coordinate the full six-phase workflow and keep phase handoffs in order.
+    primary_inputs:
+      - feature key
+      - feature name
+      - sdtk.config.json
+      - SHARED_PLANNING.md
+      - QUALITY_CHECKLIST.md
+    primary_outputs:
+      - phase handoffs
+      - updated SHARED_PLANNING.md
+      - updated QUALITY_CHECKLIST.md
+    hard_gates:
+      - Do not skip mandatory PM or BA or ARCH or DEV or QA phases.
+      - Do not hand off the next phase without evidence from the current phase.
+    references: []
+    prompts: []
+    scripts:
+      - toolkit/scripts/init-feature.ps1
+    runtime_support: [claude, codex]
+    dependencies: []
+    pack: core
+
+  - name: sdtk-dev-backend
+    phase: dev
+    role_tag: /dev-backend
+    use_when: Implement backend code that follows SDTK backend conventions for a scoped feature slice.
+    primary_inputs:
+      - docs/architecture/ARCH_DESIGN_[FEATURE_KEY].md
+      - docs/api/[FeaturePascal]_API.yaml
+      - docs/database/DATABASE_SPEC_[FEATURE_KEY].md
+    primary_outputs:
+      - backend code
+      - backend tests
+    hard_gates:
+      - Do not generate backend code without approved API and data-contract sources.
+      - Follow existing repository patterns before introducing new module structure.
+    references: []
+    prompts: []
+    scripts: []
+    runtime_support: [claude, codex]
+    dependencies: [sdtk-dev, sdtk-api-doc]
+    pack: core
+
+  - name: sdtk-dev-frontend
+    phase: dev
+    role_tag: /dev-frontend
+    use_when: Implement frontend code that follows SDTK frontend conventions for a scoped feature slice.
+    primary_inputs:
+      - docs/design/DESIGN_LAYOUT_[FEATURE_KEY].md
+      - docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md
+      - docs/architecture/ARCH_DESIGN_[FEATURE_KEY].md
+    primary_outputs:
+      - frontend code
+      - frontend tests
+    hard_gates:
+      - Do not implement screens without the current design and flow-action source.
+      - Preserve existing frontend patterns before introducing new abstractions.
+    references: []
+    prompts: []
+    scripts: []
+    runtime_support: [claude, codex]
+    dependencies: [sdtk-dev, sdtk-design-layout, sdtk-screen-design-spec]
+    pack: core
+
+  - name: sdtk-api-doc
+    phase: arch
+    role_tag: /api-doc
+    use_when: Generate or update OpenAPI YAML, API endpoints markdown, and flow-list files from architecture scope.
+    primary_inputs:
+      - docs/specs/BA_SPEC_[FEATURE_KEY].md
+      - docs/architecture/ARCH_DESIGN_[FEATURE_KEY].md
+    primary_outputs:
+      - docs/api/[FeaturePascal]_API.yaml
+      - docs/api/[FEATURE_KEY]_ENDPOINTS.md
+      - docs/api/[feature_snake]_api_flow_list.txt
+    hard_gates:
+      - Do not invent API paths or schemas that contradict BA or ARCH source.
+      - Keep YAML, endpoint markdown, and flow list synchronized.
+    references:
+      - toolkit/skills/sdtk-api-doc/references/YAML_CREATION_RULES.md
+      - toolkit/skills/sdtk-api-doc/references/API_DESIGN_FLOWCHART_CREATION_RULES.md
+    prompts: []
+    scripts: []
+    runtime_support: [claude, codex]
+    dependencies: [sdtk-arch, sdtk-ba]
+    pack: core
+
+  - name: sdtk-api-design-spec
+    phase: arch
+    role_tag: /api-design-spec
+    use_when: Generate API design detail markdown from OpenAPI YAML and API flow list.
+    primary_inputs:
+      - docs/api/[FeaturePascal]_API.yaml
+      - docs/api/[feature_snake]_api_flow_list.txt
+    primary_outputs:
+      - docs/api/[FEATURE_KEY]_API_DESIGN_DETAIL.md
+      - docs/api/flows/*.puml
+      - docs/api/images/*.svg
+    hard_gates:
+      - Do not drift from the source YAML or flow list.
+      - Do not leave broken flow image embeds in the generated markdown.
+    references:
+      - toolkit/skills/sdtk-api-design-spec/references/API_DESIGN_FLOWCHART_CREATION_RULES.md
+      - toolkit/skills/sdtk-api-design-spec/references/API_DESIGN_CREATION_RULES.md
+    prompts: []
+    scripts:
+      - toolkit/skills/sdtk-api-design-spec/scripts/generate_api_design_detail.py
+    runtime_support: [claude, codex]
+    dependencies: [sdtk-api-doc]
+    pack: core
+
+  - name: sdtk-design-layout
+    phase: arch
+    role_tag: /design-layout
+    use_when: Generate design-layout docs with PlantUML salt wireframes and item tables for UI scope.
+    primary_inputs:
+      - docs/specs/BA_SPEC_[FEATURE_KEY].md
+      - docs/api/[FEATURE_KEY]_ENDPOINTS.md
+    primary_outputs:
+      - docs/design/DESIGN_LAYOUT_[FEATURE_KEY].md
+      - docs/specs/assets/<feature_snake>/screens/*.svg
+    hard_gates:
+      - Do not skip screen IDs or item numbering alignment with the wireframe.
+      - If rendering is unavailable, record that explicitly instead of pretending render assets exist.
+    references: []
+    prompts: []
+    scripts:
+      - toolkit/skills/sdtk-design-layout/scripts/render_design_layout_images.py
+    runtime_support: [claude, codex]
+    dependencies: [sdtk-arch, sdtk-ba]
+    pack: core
+
+  - name: sdtk-screen-design-spec
+    phase: arch
+    role_tag: /screen-design-spec
+    use_when: Build flow-action specs from requirement sources, design source references, and API mappings.
+    primary_inputs:
+      - docs/specs/BA_SPEC_[FEATURE_KEY].md
+      - docs/design/DESIGN_LAYOUT_[FEATURE_KEY].md
+      - docs/api/[FEATURE_KEY]_ENDPOINTS.md
+    primary_outputs:
+      - docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md
+      - docs/specs/assets/<feature_snake>/screens/*
+    hard_gates:
+      - Do not finalize UI-scope screens without a valid design source type and reference.
+      - Do not leave broken image paths or missing API mappings in the spec.
+    references:
+      - toolkit/skills/sdtk-screen-design-spec/references/FLOW_ACTION_SPEC_CREATION_RULES.md
+      - toolkit/skills/sdtk-screen-design-spec/references/numbering-rules.md
+      - toolkit/skills/sdtk-screen-design-spec/references/figma-mcp.md
+      - toolkit/skills/sdtk-screen-design-spec/references/excel-image-export.md
+    prompts: []
+    scripts:
+      - toolkit/skills/sdtk-screen-design-spec/scripts/validate_flow_action_spec_numbering.py
+      - toolkit/skills/sdtk-screen-design-spec/scripts/renumber_flow_action_spec_global.py
+    runtime_support: [claude, codex]
+    dependencies: [sdtk-arch, sdtk-design-layout]
+    pack: core
+
+  - name: sdtk-test-case-spec
+    phase: qa
+    role_tag: /test-case-spec
+    use_when: Generate reusable screen-based test-case specifications before or during QA execution.
+    primary_inputs:
+      - docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md
+      - docs/specs/BA_SPEC_[FEATURE_KEY].md
+      - docs/api/[FEATURE_KEY]_ENDPOINTS.md
+    primary_outputs:
+      - docs/qa/[FEATURE_KEY]_TEST_CASE.md
+    hard_gates:
+      - Do not invent test coverage that is not grounded in BA, flow-action, or API sources.
+      - Keep totals and structured coverage counts consistent with the QA baseline.
+    references:
+      - toolkit/skills/sdtk-test-case-spec/references/TEST_CASE_CREATION_RULES.md
+    prompts: []
+    scripts:
+      - toolkit/skills/sdtk-test-case-spec/scripts/validate_test_case_spec.py
+    runtime_support: [claude, codex]
+    dependencies: [sdtk-qa, sdtk-screen-design-spec]
+    pack: core

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

@@ -1,18 +1,22 @@
 ---
 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.
+description: Generate detailed API design markdown from OpenAPI YAML and API flow list. Use when you need field-level request/response tables plus one visible process-flow diagram per API.
 ---
 
 ## 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
+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
 
+## Critical Constraints
+- I do not drift from the source YAML or flow list.
+- I do not leave broken flow image embeds in the generated markdown.
+
 ## Outputs
 - `docs/api/[FEATURE_KEY]_API_DESIGN_DETAIL.md`
 - Supporting generated assets:
@@ -40,15 +44,15 @@ $ARGUMENTS
 ## 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`.
+3. Parse flow blocks from flow list and map them by normalized `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)
+   - Request table
    - Success response table
-   - Error response table (explicit schema if defined, otherwise shared envelope + inferred business statuses from flow)
+   - Error response table
 5. Generate/update `.puml` per API under `docs/api/flows`.
 6. Render `.svg` images under `docs/api/images`.
 7. Validate:
@@ -58,17 +62,27 @@ $ARGUMENTS
    - markdown tables keep `No` sequential numbering
 
 ## Script
-- `scripts/generate_api_design_detail.py`
+- `.claude/skills/api-design-spec/scripts/generate_api_design_detail.py`
 
 ### Typical command
 ```bash
-python scripts/generate_api_design_detail.py \
+python ".claude/skills/api-design-spec/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"
 ```
 
+### Optional subset generation
+```bash
+python ".claude/skills/api-design-spec/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" \
+  --include "POST /api/whiteboard/assignment/{company_uuid}"
+```
+
 ## 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.