sdtk-kit 0.3.6 → 0.3.8

package/assets/toolkit/toolkit/skills/sdtk-arch/SKILL.md

@@ -5,6 +5,10 @@ description: Solution Architect workflow for SDTK. Use when you need to convert
 
 # SDTK ARCH (Solution Architecture)
 
+## Critical Constraints
+- I do not generate `FLOW_ACTION_SPEC` before `DESIGN_LAYOUT` for UI-scope features.
+- I do not let API, DB, and UI artifacts drift from the same BA and PM source of truth.
+
 ## Outputs
 - `docs/architecture/ARCH_DESIGN_[FEATURE_KEY].md`
 - If applicable:
@@ -16,6 +20,19 @@ description: Solution Architect workflow for SDTK. Use when you need to convert
   - `docs/design/DESIGN_LAYOUT_[FEATURE_KEY].md`
   - `docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md`
 
+## Flow Overview
+
+```dot
+digraph sdtk_arch_flow {
+  rankdir=TB;
+  BA_SPEC -> ARCH_DESIGN;
+  ARCH_DESIGN -> DESIGN_LAYOUT;
+  DESIGN_LAYOUT -> FLOW_ACTION_SPEC;
+  ARCH_DESIGN -> API_YAML;
+  API_YAML -> API_DETAIL;
+}
+```
+
 ## Process
 1. Read BA spec and PRD/backlog.
 2. Read `sdtk.config.json` for project stack assumptions (backend/frontend/db/auth).
@@ -27,8 +44,9 @@ description: Solution Architect workflow for SDTK. Use when you need to convert
 5. If API detail spec is required, use `sdtk-api-design-spec` to build/update `docs/api/[FEATURE_KEY]_API_DESIGN_DETAIL.md` using YAML + flow list.
 6. For UI-scope features, enforce this generation sequence:
    a. Generate/update `docs/design/DESIGN_LAYOUT_[FEATURE_KEY].md` first (using `sdtk-design-layout`).
-   b. Then generate/update `docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md` (using `sdtk-screen-design-spec`).
-   c. The flow-action spec must reference the design-layout doc as its design source when no Figma/screenshot is available (Design Source Type: `generated-draft`).
+   b. Attempt to render screen preview images from the layout using `render_design_layout_images.py`. Output: `docs/specs/assets/<feature_snake>/screens/<screen_id>.svg`. If rendering fails (no Java/plantuml.jar), fall back to the render-skipped note -- do not silently skip.
+   c. Then generate/update `docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md` (using `sdtk-screen-design-spec`).
+   d. The flow-action spec must reference the design-layout doc as its design source when no Figma/screenshot is available (Design Source Type: `generated-draft`). Use rendered `.svg` files as the screen image. If render failed, use the render-skipped note instead of a broken image reference.
 7. For complex UI flow-action specs, use `sdtk-screen-design-spec` to build/update `docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md`.
 8. Define:
    - System components + data model
@@ -49,3 +67,17 @@ description: Solution Architect workflow for SDTK. Use when you need to convert
 12. If anything is unclear, record OQ-xx in ARCH_DESIGN "Open Questions" and escalate to `@pm` for a decision.
 13. Update shared state + Phase 3 checklist.
 14. Handoff: `@dev please implement ...`.
+
+## Order-Critical Hard Gate
+For UI-scope features, do not generate or update `docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md` until `docs/design/DESIGN_LAYOUT_[FEATURE_KEY].md` already exists and is current enough to serve as the design source for the same scope.
+
+If the layout is missing, stale, or cannot support the flow-action spec, stop and fix the layout first. Do not reverse the order and repair it later.
+
+
+## Common Mistakes
+
+| Mistake | Why it is wrong | Do instead |
+|---|---|---|
+| Generate `FLOW_ACTION_SPEC` before `DESIGN_LAYOUT` for UI scope | Forces the spec to invent screen behavior without a design source | Create or refresh the layout first, then derive the flow-action spec |
+| Treat API YAML, API detail, and flow-action outputs as independent documents | Causes naming and traceability drift across artifacts | Keep ARCH outputs linked through shared requirements and path policy |
+| Close open questions silently during ARCH | Hides unresolved design decisions from downstream roles | Record `OQ-xx` explicitly and escalate through `@pm` |

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

@@ -7,10 +7,16 @@ The active rule source for API design detail and API flowchart behavior is now:
 - `API_DESIGN_FLOWCHART_CREATION_RULES_FINAL.md` (root)
 - `templates/docs/api/API_DESIGN_FLOWCHART_CREATION_RULES.md` (toolkit)
 
-Use that file for:
+Even in compatibility mode, generated API design detail docs must still include:
+- a top-level `## Assumptions` section
+- this table format: `| # | Assumption | Verified | Risk if wrong |`
+- explicit unresolved assumptions when downstream review depends on them
+
+Use the active rule file for:
 - API design detail markdown structure
 - flowchart integration and synchronization rules
 - error section rules
 - flow summary / notes / login rules
+- assumptions-section requirements
 
 This compatibility note should remain only until all references are migrated.

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

@@ -38,6 +38,23 @@ Primary sample references:
 - `GET /bukken/info/{company_uuid}/{bukken_uuid}` style
 - search API query-builder style shown in the Bukken sample helper flow
 
+## 2.1 API Design Detail Markdown Requirements
+
+Generated `*_API_DESIGN_DETAIL.md` files must keep this minimum structure:
+- `## 0. Abbreviations`
+- `## 1. Document Scope`
+- `## Assumptions`
+- per-endpoint `## <n>. API Detail ...` sections
+- `## 3. Generation Notes` or the current equivalent final notes section
+
+`## Assumptions` must use this table shape:
+
+```text
+| # | Assumption | Verified | Risk if wrong |
+```
+
+If an assumption is not verified yet, keep it explicit and treat it as a downstream review risk instead of silently collapsing it into a fact.
+
 ## 3. Core Flowchart Writing Rules
 
 ### Rule A. Add a visible API header for every block

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

@@ -19,12 +19,13 @@ A flow-action spec should include, at minimum:
 
 1. `Abbreviations`
 2. `Feature overview`
-3. `Screen flow action` (with PlantUML)
-4. `Screen layout spec by flow action`
-5. `System processing flow`
-6. `Open questions`
-7. `Screen - API mapping`
-8. `Document history`
+3. `Assumptions`
+4. `Screen flow action` (with PlantUML)
+5. `Screen layout spec by flow action`
+6. `System processing flow`
+7. `Open questions`
+8. `Screen - API mapping`
+9. `Document history`
 
 If a section is not in scope, keep the section and mark explicitly as `N/A` with reason.
 
@@ -40,7 +41,34 @@ If a section is not in scope, keep the section and mark explicitly as `N/A` with
 - Table rows must keep column count consistent with the header (no broken or merged rows).
 - Avoid single-line merged content that collapses multiple logical items into one table row.
 
-### 3.1 Language and Encoding Standards (EN Artifacts)
+### 3.1 Action Table Mapping Completion Rules
+
+- After API endpoint spec and database spec are available, the action-table columns `Attribute`, `DB Column`, `Size`, and `Default Value` must not be left blank when the mapping can be derived from current source-of-truth inputs.
+- Fill these four columns only after the relevant API contract and DB schema are stable enough to be treated as the current source of truth for the active phase.
+- Source priority for filling the four columns:
+  1. `docs/api/*_ENDPOINTS.md` and OpenAPI YAML for request/response contract
+  2. `docs/database/DATABASE_SPEC_*.md` for physical column names, nullability, storage shape, and query-source aliases
+  3. confirmed flow/business rules for default state and behavior
+  4. design source (Figma/Excel) for screen label and control type only
+- `Attribute` rules:
+  - input item: use the canonical request payload path
+  - display item: use the canonical response path
+  - UI-only item: use `ui.*` namespace
+- `DB Column` rules:
+  - use physical DB column names or query-source aliases from the API/database spec
+  - if multiple columns participate, list them explicitly
+  - if the control is UI-only, write `N/A`
+- `Size` rules:
+  - document data format/type, not pixel width
+  - prefer canonical forms such as `uuid`, `DATE (YYYY-MM-DD)`, `DATETIME`, `TIME (HH:mm)`, `boolean`, `array[uuid]`, `enum(...)`, `JSON string`
+  - prefer DB storage type first; if not available, fall back to API schema type/format
+- `Default Value` rules:
+  - use confirmed business, UI, or runtime defaults
+  - if the default comes from settings or environment, state that clearly
+  - if not finalized, use `TBD` and keep or raise an open-question reference in `Note`
+- If screen labels conflict with canonical API/DB naming, preserve the original screen label in the visible screen columns, but keep `Attribute` and `DB Column` aligned to API/DB source of truth and explain the mismatch in `Note`.
+
+### 3.2 Language and Encoding Standards (EN Artifacts)
 
 - For EN artifacts (`docs/en/**` or explicitly requested EN version), narrative text must be English.
 - JP labels, if provided by the input, should be kept in a clearly marked appendix or note column, not in the default item table columns.
@@ -49,12 +77,19 @@ If a section is not in scope, keep the section and mark explicitly as `N/A` with
 - Save files as UTF-8 and avoid mojibake/broken glyphs (`�`, `ↁE`, garbled sequences).
 - Keep canonical terminology stable across documents (for example: `bukken`, `sagyo`, `customer employee`).
 
-### 3.2 Markdown Structure Hygiene
+### 3.3 Markdown Structure Hygiene
 
 - Keep each heading on its own line; do not concatenate multiple headings/sections on one line.
 - Keep metadata blocks (`Information`, `Note`, `Behavior notes`) as structured bullet blocks, not single compressed lines.
 - Keep image, table, and separator (`---`) boundaries explicit to preserve parser/render stability.
 
+### 3.4 Assumptions Section
+
+- Every flow-action spec must include a top-level `## Assumptions` section.
+- Use this table format exactly: `# | Assumption | Verified | Risk if wrong`.
+- Keep assumptions explicit when downstream mapping or behavior depends on an unresolved decision.
+- If an assumption affects UI behavior, API mapping, or DB mapping, reflect the risk in `Note` and keep or raise the related `OQ-xx` item.
+
 ## 4. Item Numbering and Duplication Rules
 
 - Use one numbering mode only: `global across document`.
@@ -115,6 +150,17 @@ Rules:
 - Store images in repository-relative paths.
 - Do not keep temporary local absolute paths in markdown.
 
+### 8.1 Rendered Screen Images for Generated-Draft Screens
+
+When `Design Source Type` is `generated-draft`:
+- Screen preview images may be rendered from `DESIGN_LAYOUT_[FEATURE_KEY].md` PlantUML SALT wireframes.
+- Renderer: `toolkit/skills/sdtk-design-layout/scripts/render_design_layout_images.py`
+- Expected output path: `docs/specs/assets/<feature_snake>/screens/<screen_id>.svg`
+- If the rendered `.svg` file exists, use it as the `Screen image:` reference.
+- If rendering is unavailable or the `.svg` does not exist, replace the image line with:
+  `> Screen image not rendered in this environment. See Design Source Reference for layout.`
+- Do not leave a broken image reference pointing to a non-existent file.
+
 ## 9. Consistency with Other Specs
 
 - Align terms with:
@@ -145,8 +191,9 @@ Rules:
 - All mandatory sections exist.
 - All tables include `No`.
 - Numbering is global across the document (no resets).
-- No broken image links.
+- No broken image links (for `generated-draft` screens: `.svg` exists or render-skipped note is present).
 - Screen/API mappings are consistent with `*_ENDPOINTS.md`.
+- Assumptions section exists and unresolved assumptions are traceable.
 - Open questions are explicit and traceable.
 - For EN artifact: no leftover VI text outside allowed `Original Text` appendix blocks.
 - No mojibake/encoding corruption markers.

package/assets/toolkit/toolkit/skills/sdtk-ba/SKILL.md

@@ -5,6 +5,10 @@ description: Business Analyst workflow for SDTK. Use when you need to turn PM in
 
 # SDTK BA (Business Analysis)
 
+## Critical Constraints
+- I do not mark BA analysis complete until `REQ`, `UC`, `BR`, and `AC` traceability is explicit.
+- I do not silently resolve business ambiguities that belong to PM or the user.
+
 ## Output
 - `docs/specs/BA_SPEC_[FEATURE_KEY].md`
 

package/assets/toolkit/toolkit/skills/sdtk-design-layout/SKILL.md

@@ -5,6 +5,10 @@ description: Generate UI screen layout documentation for a feature, including Pl
 
 # SDTK Screen Layout Design
 
+## Critical Constraints
+- I do not skip screen IDs or item numbering alignment with the wireframe.
+- I do not hide render limitations; I record when screen preview rendering is unavailable.
+
 ## Output
 - `docs/design/DESIGN_LAYOUT_[FEATURE_KEY].md`
 
@@ -15,6 +19,22 @@ description: Generate UI screen layout documentation for a feature, including Pl
    - API list table
    - Item table with numbering that matches the wireframe
 3. Keep screen IDs consistent (A-*, B-*, C-*).
+4. After writing `DESIGN_LAYOUT`, attempt to render screen preview images by default:
+   - Run `render_design_layout_images.py` to extract `@startsalt` blocks and render `.svg` files.
+   - Output path: `docs/specs/assets/<feature_snake>/screens/<screen_id>.svg`
+   - If PlantUML is unavailable, rendering is skipped with a warning and the render-skipped note is used in `FLOW_ACTION_SPEC`. The layout doc remains valid.
+
+## Screen Image Renderer
+- Script: `toolkit/skills/sdtk-design-layout/scripts/render_design_layout_images.py`
+- Usage:
+  ```
+  python "toolkit/skills/sdtk-design-layout/scripts/render_design_layout_images.py" \
+    --design-layout "docs/design/DESIGN_LAYOUT_[FEATURE_KEY].md" \
+    --feature-key [FEATURE_KEY]
+  ```
+- Requires: Java + `plantuml.jar` (auto-detected from VSCode PlantUML extension, or pass `--plantuml-jar`)
+- Output: `.svg` files under `docs/specs/assets/<feature_snake>/screens/`
+- Failure policy: non-blocking. Warns and continues if rendering is unavailable.
 
 ## Template
 - Use `toolkit/templates/docs/design/DESIGN_LAYOUT_TEMPLATE.md` as starting structure.

package/assets/toolkit/toolkit/skills/sdtk-design-layout/scripts/render_design_layout_images.py

@@ -0,0 +1,213 @@
+#!/usr/bin/env python3
+"""
+Render screen preview SVGs from DESIGN_LAYOUT PlantUML SALT wireframes.
+
+Extracts @startsalt blocks from a DESIGN_LAYOUT_[FEATURE_KEY].md file,
+renders each to .svg using a local plantuml.jar, and writes the images
+to docs/specs/assets/<feature_snake>/screens/.
+
+Graceful failure: if PlantUML is unavailable or a block fails to render,
+the script warns but does not exit with an error code.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Render screen images from DESIGN_LAYOUT PlantUML SALT blocks."
+    )
+    parser.add_argument(
+        "--design-layout",
+        required=True,
+        help="Path to DESIGN_LAYOUT_[FEATURE_KEY].md",
+    )
+    parser.add_argument(
+        "--feature-key",
+        required=True,
+        help="Feature key, e.g. CRM_LITE",
+    )
+    parser.add_argument(
+        "--output-dir",
+        default="",
+        help="Output directory for SVGs. Default: docs/specs/assets/<feature_snake>/screens/",
+    )
+    parser.add_argument(
+        "--plantuml-jar",
+        default="",
+        help="Explicit path to plantuml.jar. Auto-detected if omitted.",
+    )
+    parser.add_argument(
+        "--skip-render",
+        action="store_true",
+        help="Extract .puml files only, skip SVG rendering.",
+    )
+    return parser.parse_args()
+
+
+def normalize_feature_snake(feature_key: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "_", feature_key.lower()).strip("_")
+
+
+def find_plantuml_jar(explicit: str) -> Optional[Path]:
+    if explicit:
+        p = Path(explicit).expanduser().resolve()
+        return p if p.exists() else None
+    user_home = Path.home()
+    candidates = sorted(
+        (user_home / ".vscode" / "extensions").glob("jebbs.plantuml-*/plantuml.jar")
+    )
+    if candidates:
+        return candidates[-1]
+    return None
+
+
+def extract_screens(text: str) -> List[Tuple[str, str]]:
+    """Extract (screen_id, plantuml_block) pairs from DESIGN_LAYOUT markdown.
+
+    Looks for heading patterns like '## A-1. Screen Name' or '## SCR-01 Screen Name'
+    followed by a fenced plantuml block containing @startsalt.
+    """
+    screens: List[Tuple[str, str]] = []
+    heading_pattern = re.compile(
+        r"^##\s+([A-Z]+-?\d+|SCR-?\d+)[.\s]",
+        re.MULTILINE,
+    )
+    salt_pattern = re.compile(
+        r"```plantuml\s*\n(@startsalt[\s\S]*?@endsalt)\s*\n```",
+        re.MULTILINE,
+    )
+
+    headings = list(heading_pattern.finditer(text))
+    for i, match in enumerate(headings):
+        screen_id = match.group(1).strip().lower().replace("-", "_")
+        start = match.start()
+        end = headings[i + 1].start() if i + 1 < len(headings) else len(text)
+        section = text[start:end]
+
+        salt_match = salt_pattern.search(section)
+        if salt_match:
+            screens.append((screen_id, salt_match.group(1)))
+
+    return screens
+
+
+def render_svg(
+    plantuml_jar: Path, puml_path: Path, output_dir: Path
+) -> Optional[str]:
+    """Render a single .puml to .svg. Returns error string or None on success."""
+    proc = subprocess.run(
+        ["java", "-jar", str(plantuml_jar), "-tsvg", str(puml_path)],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+        check=False,
+    )
+    # PlantUML writes .svg next to the .puml file.
+    svg_path = puml_path.with_suffix(".svg")
+    if not svg_path.exists():
+        return f"Render failed (no svg produced): {puml_path.name}"
+
+    # If .puml is already in the output dir, no copy needed.
+    # Otherwise move the svg to the output dir.
+    svg_dst = output_dir / svg_path.name
+    if svg_path.resolve() != svg_dst.resolve():
+        shutil.copy2(svg_path, svg_dst)
+        svg_path.unlink(missing_ok=True)
+        svg_path = svg_dst
+
+    svg_text = svg_path.read_text(encoding="utf-8", errors="ignore")
+    if any(
+        x in svg_text
+        for x in ("Cannot find group", "Syntax Error", "contains errors")
+    ):
+        return f"Rendered with error content: {svg_path.name}"
+    if proc.returncode != 0:
+        return f"PlantUML exit={proc.returncode} for {puml_path.name}"
+    return None
+
+
+def main() -> int:
+    args = parse_args()
+
+    feature_key = args.feature_key.strip()
+    if not feature_key:
+        print("[ERROR] --feature-key is empty", file=sys.stderr)
+        return 1
+
+    feature_snake = normalize_feature_snake(feature_key)
+    layout_path = Path(args.design_layout)
+    if not layout_path.exists():
+        print(f"[ERROR] Design layout not found: {layout_path}", file=sys.stderr)
+        return 1
+
+    if args.output_dir:
+        output_dir = Path(args.output_dir)
+    else:
+        output_dir = Path(f"docs/specs/assets/{feature_snake}/screens")
+
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    text = layout_path.read_text(encoding="utf-8")
+    screens = extract_screens(text)
+
+    if not screens:
+        print("[WARN] No screen sections with @startsalt blocks found.")
+        print("[OK] Nothing to render.")
+        return 0
+
+    print(f"[OK] Found {len(screens)} screen(s) with SALT wireframes.")
+
+    # Write .puml files
+    puml_files: List[Path] = []
+    for screen_id, salt_block in screens:
+        puml_name = f"{screen_id}.puml"
+        puml_path = output_dir / puml_name
+        puml_path.write_text(salt_block + "\n", encoding="utf-8")
+        puml_files.append(puml_path)
+
+    if args.skip_render:
+        print(f"[OK] Wrote {len(puml_files)} .puml file(s). Render skipped (--skip-render).")
+        return 0
+
+    # Find PlantUML
+    jar = find_plantuml_jar(args.plantuml_jar)
+    if not jar:
+        print("[WARN] PlantUML jar not found. SVG rendering skipped.")
+        print("       Use --plantuml-jar or install VSCode PlantUML extension.")
+        print(f"[OK] Wrote {len(puml_files)} .puml file(s) without SVG rendering.")
+        return 0
+
+    # Render SVGs
+    errors: List[str] = []
+    rendered = 0
+    for puml_path in puml_files:
+        err = render_svg(jar, puml_path, output_dir)
+        if err:
+            errors.append(err)
+        else:
+            rendered += 1
+
+    print(f"[OK] Rendered {rendered}/{len(puml_files)} screen image(s) to: {output_dir}")
+    if errors:
+        print("[WARN] Render issues:")
+        for item in errors:
+            print(f"  - {item}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except Exception as exc:
+        print(f"[ERROR] {exc}", file=sys.stderr)
+        raise

package/assets/toolkit/toolkit/skills/sdtk-dev/SKILL.md

@@ -5,16 +5,86 @@ description: Developer workflow for SDTK. Use when you need to implement a featu
 
 # SDTK DEV (Implementation + Code Review)
 
+## Critical Constraints
+- I do not start implementation before the current `FEATURE_IMPL_PLAN` scope is approved.
+- I do not claim implementation is complete without fresh verification evidence.
+
 ## Outputs
 - `docs/dev/FEATURE_IMPL_PLAN_[FEATURE_KEY].md`
 - Code + tests (follow repo conventions)
 
+## Prompt Templates
+- `./prompts/implementer.md`
+- `./prompts/spec-reviewer.md`
+- `./prompts/code-quality-reviewer.md`
+
+Use these templates when you need a controller -> subagent execution loop for implementation and review. The controller owns context selection and pastes the task text into the template placeholders.
+
 ## Process
 1. Read `ARCH_DESIGN_*` + backlog.
 2. Read `sdtk.config.json` for project stack + test/lint commands.
 3. Write `FEATURE_IMPL_PLAN_*` (scope, file list, test plan).
-4. If anything is unclear: record OQ-xx in FEATURE_IMPL_PLAN “Open Questions” and escalate to `@pm` for a decision (PM asks the user if still missing info).
-5. Implement incrementally with tests.
-6. Complete mandatory code review gate (self + peer checklist; AI peer review allowed).
-7. Update `SHARED_PLANNING.md` + `QUALITY_CHECKLIST.md` Phase 4.
-8. Handoff: `@qa please test …` (only after code review PASS).
+4. If anything is unclear: record OQ-xx in FEATURE_IMPL_PLAN "Open Questions" and escalate to `@pm` for a decision (PM asks the user if still missing info).
+5. Dispatch implementation work with `./prompts/implementer.md` when task slicing or delegated execution is needed. The controller must paste the full task text and relevant constraints into the template; do not make the implementer subagent discover missing context on its own.
+6. Implement incrementally with tests.
+7. Run the verification commands that prove the current claim (unit tests, lint, typecheck, build, or targeted smoke checks as applicable) and read the full output before saying the work is done.
+8. If delegated review is needed, run the review loop in this order:
+   - `./prompts/spec-reviewer.md` first for artifact/spec compliance
+   - `./prompts/code-quality-reviewer.md` only after spec reviewer PASS is documented
+9. Complete mandatory code review gate (self + peer checklist; AI peer review allowed).
+10. Update `SHARED_PLANNING.md` + `QUALITY_CHECKLIST.md` Phase 4.
+11. Handoff: `@qa please test ...` (only after code review PASS and fresh verification evidence is recorded).
+
+## Delegated Execution Contract
+- The implementer subagent receives the full task text directly in the prompt.
+- Required implementer status values:
+  - `DONE`
+  - `DONE_WITH_CONCERNS`
+  - `NEEDS_CONTEXT`
+  - `BLOCKED`
+- `DONE_WITH_CONCERNS` means the task is complete but the controller must read the concerns before review.
+- `NEEDS_CONTEXT` means the controller must supply missing information and re-dispatch.
+- `BLOCKED` means do not retry the same task unchanged; resolve the blocker first.
+- The spec reviewer must verify real artifacts, not trust implementer claims.
+- The code-quality reviewer is a second-stage review and must not run before spec compliance passes.
+
+## Model Selection Guidance
+Choose the cheapest model that can safely complete the task without creating avoidable rework.
+
+| Task type | Recommended model tier | Why |
+|---|---|---|
+| Single-file mechanical change with a clear spec | Fast model | Speed matters more than deep judgment |
+| Multi-file integration that follows an approved plan | Standard model | Needs pattern matching across several files |
+| Architecture or design tradeoff for the current implementation slice | Most capable model | Requires judgment and ambiguity handling |
+| Stage 1 artifact/spec review | Standard model | Needs careful comparison against requirements |
+| Stage 2 code-quality review | Standard or most capable model | Choose most capable when boundaries or refactors are non-trivial |
+| Cross-artifact consistency investigation | Most capable model | Requires broader synthesis across docs and code |
+
+Blocked-task rule:
+- If an implementer returns `BLOCKED`, do not force the same model to retry the same task unchanged.
+- First resolve missing context or reduce task scope.
+- Escalate to a stronger model only when the blocker is judgment or synthesis bound, not because the prompt was incomplete.
+
+## Verification Before Completion
+Apply `governance/ai/core/SDTK_VERIFICATION_BEFORE_COMPLETION_POLICY.md`.
+
+Do not:
+- say implementation is done, passing, or QA-ready without fresh verification evidence
+- use `should`, `probably`, or `seems` in place of executed checks
+- rely on partial output, stale command runs, or unchecked agent reports
+
+If verification fails or cannot be run, report the status as not verified and explain the blocker.
+
+## Order-Critical Hard Gate
+Do not start implementation work until `docs/dev/FEATURE_IMPL_PLAN_[FEATURE_KEY].md` exists and the current execution scope is explicitly approved in that plan for implementation.
+
+If the plan is missing, incomplete, or still awaiting approval for the current task slice, stop and update the plan first. Do not implement first and backfill the plan later.
+
+
+## Common Mistakes
+
+| Mistake | Why it is wrong | Do instead |
+|---|---|---|
+| Start coding before the implementation plan is approved | Causes scope drift and invalidates review order | Finish and approve `FEATURE_IMPL_PLAN` first |
+| Run Stage 2 code-quality review before Stage 1 spec review passes | Hides requirement mismatches behind style feedback | Keep the review order strict: spec first, quality second |
+| Retry a `BLOCKED` implementer with the same prompt and same model | Repeats the same failure mode | Add missing context, split the task, or change model tier intentionally |

package/assets/toolkit/toolkit/skills/sdtk-dev/prompts/code-quality-reviewer.md

@@ -0,0 +1,35 @@
+# SDTK DEV Code Quality Reviewer Prompt Template
+
+You are the Stage 2 code-quality reviewer for a completed SDTK development task.
+
+## Gate Position
+Run this prompt only after the spec reviewer has passed Stage 1 artifact/spec compliance.
+
+## Inputs From Controller
+- Task ID: `{{TASK_ID}}`
+- Feature key: `{{FEATURE_KEY}}`
+- Stage 1 PASS evidence: `{{SPEC_REVIEW_PASS_EVIDENCE}}`
+- Files to review:
+
+```text
+{{FILES_TO_REVIEW}}
+```
+
+- Relevant coding standards or repo conventions:
+
+```text
+{{CODE_QUALITY_RULES}}
+```
+
+## Review Rules
+- Confirm Stage 1 PASS before reviewing code quality.
+- Review structure, naming, maintainability, boundary clarity, and test quality.
+- Flag issues that make the implementation fragile even if it is spec-compliant.
+- Do not reopen Stage 1 scope unless you find a direct contradiction in the shipped code.
+
+## Response Format
+- Gate result: `{{GATE_RESULT}}`
+- Code quality findings: `{{QUALITY_FINDINGS}}`
+- Test quality findings: `{{TEST_FINDINGS}}`
+- Required improvements: `{{REQUIRED_IMPROVEMENTS}}`
+- Final recommendation: `{{FINAL_RECOMMENDATION}}`

package/assets/toolkit/toolkit/skills/sdtk-dev/prompts/implementer.md

@@ -0,0 +1,61 @@
+# SDTK DEV Implementer Prompt Template
+
+You are the implementation subagent for a single SDTK development task.
+
+## Mission
+Implement exactly the task provided by the controller, then report one of the required status values.
+
+## Inputs From Controller
+- Task ID: `{{TASK_ID}}`
+- Feature key: `{{FEATURE_KEY}}`
+- Scene-setting context: `{{SCENE_CONTEXT}}`
+- Full task text:
+
+```text
+{{FULL_TASK_TEXT}}
+```
+
+- Relevant requirements or constraints:
+
+```text
+{{RELEVANT_CONSTRAINTS}}
+```
+
+- Files already identified by the controller:
+
+```text
+{{KNOWN_FILE_PATHS}}
+```
+
+- Verification commands to run before claiming completion:
+
+```text
+{{VERIFICATION_COMMANDS}}
+```
+
+## Before You Begin
+1. Read the full task text carefully.
+2. If required information is missing, ask focused questions immediately instead of guessing.
+3. Do not ask the controller to make you read unrelated planning files. The controller is responsible for pasting the task context you need.
+
+## Working Rules
+- Stay within the provided task scope.
+- Follow repo conventions and existing patterns in the touched files.
+- Update or add tests when the task requires it.
+- Run the provided verification commands before reporting `DONE` or `DONE_WITH_CONCERNS`.
+- Perform a short self-review against the task requirements and obvious code quality issues before you report back.
+
+## Required Status Taxonomy
+Return exactly one of these statuses:
+- `DONE`
+- `DONE_WITH_CONCERNS`
+- `NEEDS_CONTEXT`
+- `BLOCKED`
+
+## Response Format
+- Status: `{{STATUS}}`
+- Files changed: `{{FILES_CHANGED}}`
+- What was implemented: `{{IMPLEMENTATION_SUMMARY}}`
+- Verification evidence: `{{VERIFICATION_RESULTS}}`
+- Open concerns or blocker details: `{{CONCERNS_OR_BLOCKERS}}`
+- Questions for the controller (if any): `{{FOLLOW_UP_QUESTIONS}}`