sdtk-kit 0.3.6 → 0.3.8

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/templates/docs/api/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/templates/docs/api/API_DESIGN_DETAIL_TEMPLATE.md

@@ -16,6 +16,12 @@
 | ---: | --- | --- | --- |
 | 1 | TBD | TBD | `API_design.xlsx` |
 
+## Assumptions
+
+| # | Assumption | Verified | Risk if wrong |
+| ---: | --- | --- | --- |
+| 1 | TBD | No | TBD |
+
 ## 2. API Detail 1 - TBD
 
 **Endpoint:** `TBD`

package/assets/toolkit/toolkit/templates/docs/api/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/templates/docs/specs/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/templates/docs/specs/FLOW_ACTION_SPEC_TEMPLATE.md

@@ -33,6 +33,12 @@
 ### 1.3 Implementation direction
 - TBD
 
+## Assumptions
+
+| # | Assumption | Verified | Risk if wrong |
+| ---: | --- | --- | --- |
+| 1 | TBD | No | TBD |
+
 ---
 
 ## 2) Screen flow action
@@ -76,7 +82,10 @@ Information:
 - Design Source Reference: Figma URL | screenshot path | `docs/design/DESIGN_LAYOUT_{{FEATURE_KEY}}.md` section reference | `N/A - no UI scope`
 
 Screen image:
-![3.1 Screen A](assets/{{FEATURE_SNAKE}}/screens/screen_3_1_screen_a.png)
+![3.1 Screen A](assets/{{FEATURE_SNAKE}}/screens/scr_01.svg)
+
+<!-- If the .svg file does not exist (render unavailable), replace the image line above with: -->
+<!-- > Screen image not rendered in this environment. See Design Source Reference for layout. -->
 
 | No | Item Name | Item Type | Attribute | DB Column | Size | Default Value | Action | Description | Note |
 | ---: | --- | --- | --- | --- | --- | --- | --- | --- | --- |
@@ -100,7 +109,10 @@ Information:
 - Design Source Reference: Figma URL | screenshot path | `docs/design/DESIGN_LAYOUT_{{FEATURE_KEY}}.md` section reference | `N/A - no UI scope`
 
 Screen image:
-![3.2 Screen B](assets/{{FEATURE_SNAKE}}/screens/screen_3_2_screen_b.png)
+![3.2 Screen B](assets/{{FEATURE_SNAKE}}/screens/scr_02.svg)
+
+<!-- If the .svg file does not exist (render unavailable), replace the image line above with: -->
+<!-- > Screen image not rendered in this environment. See Design Source Reference for layout. -->
 
 | No | Item Name | Item Type | Attribute | DB Column | Size | Default Value | Action | Description | Note |
 | ---: | --- | --- | --- | --- | --- | --- | --- | --- | --- |

package/assets/toolkit/toolkit/templates/handoffs/ARCH_TO_DEV.md

@@ -0,0 +1,31 @@
+# ARCH to DEV Handoff
+
+## Required Inputs
+- `docs/architecture/ARCH_DESIGN_[FEATURE_KEY].md`
+- `docs/product/BACKLOG_[FEATURE_KEY].md`
+- when applicable:
+  - `docs/api/[FeaturePascal]_API.yaml`
+  - `docs/api/[FEATURE_KEY]_ENDPOINTS.md`
+  - `docs/database/DATABASE_SPEC_[FEATURE_KEY].md`
+  - `docs/design/DESIGN_LAYOUT_[FEATURE_KEY].md`
+  - `docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md`
+
+## Required Outputs
+- `docs/dev/FEATURE_IMPL_PLAN_[FEATURE_KEY].md`
+- code and tests
+- Stage 1 and Stage 2 review evidence before QA handoff
+
+## Mandatory Checks
+- ARCH outputs are current and reference the same feature scope.
+- UI scope includes `DESIGN_LAYOUT` before `FLOW_ACTION_SPEC`.
+- API and DB source-of-truth files are available when implementation depends on them.
+
+## Forbidden Shortcuts
+- Do not start implementation before `FEATURE_IMPL_PLAN` is written and approved.
+- Do not treat architecture assumptions as verified facts without citing the source.
+
+## Handoff Message Shape
+- Feature: `[FEATURE_KEY]`
+- Required implementation slice: file or module scope
+- Required proving checks: test or lint or build commands
+- Upstream blockers or assumptions: explicit list

package/assets/toolkit/toolkit/templates/handoffs/BA_TO_ARCH.md

@@ -0,0 +1,28 @@
+# BA to ARCH Handoff
+
+## Required Inputs
+- `docs/specs/BA_SPEC_[FEATURE_KEY].md`
+- `docs/product/PRD_[FEATURE_KEY].md`
+- `docs/product/BACKLOG_[FEATURE_KEY].md`
+- current `SHARED_PLANNING.md`
+
+## Required Outputs
+- `docs/architecture/ARCH_DESIGN_[FEATURE_KEY].md`
+- API, DB, and UI design artifacts when in scope
+- updated `SHARED_PLANNING.md`
+- updated `QUALITY_CHECKLIST.md`
+
+## Mandatory Checks
+- `REQ -> UC/BR/AC` traceability exists in BA output.
+- unresolved `OQ-xx` items are visible to ARCH.
+- ARCH knows whether API, DB, and UI scope are required.
+
+## Forbidden Shortcuts
+- Do not jump into implementation details before architecture scope is mapped.
+- Do not hide unresolved business rules inside architecture assumptions.
+
+## Handoff Message Shape
+- Feature: `[FEATURE_KEY]`
+- In-scope use cases: `UC-xx`
+- Key business rules: `BR-xx`
+- Blocking open questions: `OQ-xx` or `None`

package/assets/toolkit/toolkit/templates/handoffs/DEV_STAGE1_SPEC_REVIEW.md

@@ -0,0 +1,26 @@
+# DEV Stage 1 Spec Review
+
+## Required Inputs
+- implementation diff or changed files
+- `docs/specs/BA_SPEC_[FEATURE_KEY].md`
+- `docs/api/[FeaturePascal]_API.yaml` and `docs/api/[FEATURE_KEY]_ENDPOINTS.md` when API scope exists
+- `docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md` when UI scope exists
+- `docs/database/DATABASE_SPEC_[FEATURE_KEY].md` when data scope exists
+
+## Required Outputs
+- PASS or FAIL verdict
+- mismatch table with exact file references
+- explicit handoff decision to Stage 2 or back to DEV
+
+## Mandatory Checks
+- code matches BA, API, DB, and flow-action requirements line by line
+- missing mappings and drift are called out explicitly
+- unresolved assumptions that affect behavior are treated as blockers
+
+## Verification Evidence
+- quote the exact specification text before declaring a match or mismatch
+- use: `Spec says: "[exact quote]" -> Evidence: [match/mismatch + file reference]`
+
+## Forbidden Shortcuts
+- Do not start with style or maintainability feedback.
+- Do not trust the implementer report without checking artifacts directly.

package/assets/toolkit/toolkit/templates/handoffs/DEV_STAGE2_CODE_QUALITY_REVIEW.md

@@ -0,0 +1,20 @@
+# DEV Stage 2 Code Quality Review
+
+## Required Inputs
+- Stage 1 review result marked PASS
+- implementation diff or changed files
+- relevant test or lint outputs
+
+## Required Outputs
+- PASS or FAIL verdict
+- quality findings with file references
+- recommendation for QA handoff readiness
+
+## Mandatory Checks
+- Stage 1 spec review already passed
+- naming, structure, tests, and maintainability are reviewed
+- verification commands cited are fresh and relevant to the current diff
+
+## Forbidden Shortcuts
+- Do not reopen Stage 1 requirement matching as a substitute for quality review.
+- Do not declare QA-ready without confirming Stage 1 PASS and fresh verification evidence.

package/assets/toolkit/toolkit/templates/handoffs/DEV_TO_QA.md

@@ -0,0 +1,23 @@
+# DEV to QA Handoff
+
+## Required Inputs
+- `docs/dev/FEATURE_IMPL_PLAN_[FEATURE_KEY].md`
+- implementation diff summary
+- Stage 1 spec review PASS evidence
+- Stage 2 code-quality review PASS evidence
+- fresh test or lint outputs used for QA handoff
+
+## Required Outputs
+- QA test scope
+- explicit release-risk notes
+- updated `SHARED_PLANNING.md`
+- updated `QUALITY_CHECKLIST.md`
+
+## Mandatory Checks
+- both DEV review gates are PASS
+- verification evidence is fresh
+- known limitations or assumptions are recorded, not hidden
+
+## Forbidden Shortcuts
+- Do not hand off to QA with only one review gate complete.
+- Do not describe expected behavior as if it were verified runtime evidence.

package/assets/toolkit/toolkit/templates/handoffs/PM_TO_BA.md

@@ -0,0 +1,26 @@
+# PM to BA Handoff
+
+## Required Inputs
+- `docs/product/PROJECT_INITIATION_[FEATURE_KEY].md`
+- source requirement notes or attachments
+- current `SHARED_PLANNING.md`
+
+## Required Outputs
+- `docs/specs/BA_SPEC_[FEATURE_KEY].md`
+- updated `SHARED_PLANNING.md`
+- updated `QUALITY_CHECKLIST.md`
+
+## Mandatory Checks
+- `REQ-xx` scope is explicit and testable.
+- in-scope and out-of-scope are visible.
+- unresolved ambiguities are logged as `OQ-xx`, not hidden.
+
+## Forbidden Shortcuts
+- Do not skip glossary, BR, UC, AC, or traceability expectations.
+- Do not invent missing stakeholder decisions without logging them.
+
+## Handoff Message Shape
+- Feature: `[FEATURE_KEY]`
+- PM scope summary: 3 to 7 bullets
+- Known open questions: `OQ-xx` list or `None`
+- Expected BA focus: rules, use cases, acceptance criteria, NFRs