sdtk-kit 0.3.0

package/assets/toolkit/toolkit/templates/README.md

@@ -0,0 +1,56 @@
+# Templates (SDTK)
+
+Files in `toolkit/templates/` are skeleton artifacts used by `init-feature.ps1`
+to bootstrap a new feature across the SDLC phases.
+
+## Tokens
+- `{{FEATURE_KEY}}` (UPPER_SNAKE_CASE), example: `WORKFLOW_ENGINE`
+- `{{FEATURE_NAME}}`, example: `Workflow Engine`
+- `{{FEATURE_PASCAL}}`, example: `WorkflowEngine`
+- `{{FEATURE_SNAKE}}` (lower_snake_case), example: `workflow_engine`
+- `{{DATE}}` format: `YYYY-MM-DD`
+- `{{DATETIME}}` format: `YYYY-MM-DD HH:mm`
+
+## Generate
+Run from project root:
+
+`powershell -ExecutionPolicy Bypass -File ".\\toolkit\\\scripts\\init-feature.ps1" -FeatureKey YOUR_FEATURE -FeatureName "Your Feature"`
+
+The script renders templates into `docs/**` and updates:
+- `SHARED_PLANNING.md`
+- `QUALITY_CHECKLIST.md`
+
+## Stack Configuration
+- Stack and command values come from `sdtk.config.json` (project root).
+- `init-feature.ps1` reads config values and injects them into templates.
+
+## Added Architecture Outputs
+- `docs/api/[FEATURE_KEY]_ENDPOINTS.md`
+- `docs/api/[FEATURE_KEY]_API_DESIGN_DETAIL.md`
+- `docs/database/DATABASE_SPEC_[FEATURE_KEY].md`
+- `docs/specs/[FEATURE_KEY]_FLOW_ACTION_SPEC.md`
+
+## Added QA Outputs
+- `docs/qa/[FEATURE_KEY]_TEST_CASE.md`
+- `docs/qa/QA_RELEASE_REPORT_[FEATURE_KEY].md`
+
+## ARCH Orchestration Mapping
+- API scope: use `sdtk-api-doc`.
+- API detail scope (from YAML + flow list): use `sdtk-api-design-spec` (mode `apiDesignDetailMode: auto|on|off`).
+- UI flow-action scope: use `sdtk-screen-design-spec`.
+
+## QA Orchestration Mapping
+- QA release decision/report scope: use `sdtk-qa`.
+- QA detailed test-case spec scope: use `sdtk-test-case-spec` (mode `testCaseSpecMode: auto|on|off`).
+
+## Rules Used by Toolkit
+- API design/flowchart rules:
+  - `templates/docs/api/FLOWCHART_CREATION_RULES.md`
+  - `templates/docs/api/API_DESIGN_CREATION_RULES.md`
+- Screen flow-action spec rules:
+  - `templates/docs/specs/FLOW_ACTION_SPEC_CREATION_RULES.md`
+  - Numbering mode is fixed: global numbering across full document (no screen-level reset).
+- QA test-case spec rules:
+  - `templates/docs/qa/TEST_CASE_CREATION_RULES.md`
+
+

package/assets/toolkit/toolkit/templates/SHARED_PLANNING.md

@@ -0,0 +1,80 @@
+# SHARED PLANNING DOCUMENT
+## Multi-Agent Development Pipeline Tracker (v2.1 - 6 Phases)
+
+**Current Feature:** `{{FEATURE_KEY}}`
+**Feature Name:** `{{FEATURE_NAME}}`
+**Last Updated:** `{{DATETIME}}`
+**Pipeline Status:** `PHASE 1 - PM INITIATION (IN PROGRESS)`
+
+---
+
+## PIPELINE STATUS TABLE (6 Phases)
+
+| Phase | Status | Owner | Start Date | Finish Date | Primary Artifact | Secondary Artifacts | Notes/Blockers |
+|-------|--------|-------|------------|-------------|------------------|-------------------|---------------|
+| **1. PM Init** | IN_PROGRESS | `@pm` | {{DATE}} | - | `PROJECT_INITIATION_{{FEATURE_KEY}}.md` | Scope + REQ-xx | |
+| **2. BA** | Pending | `@ba` | - | - | `BA_SPEC_{{FEATURE_KEY}}.md` | BR/UC/AC/NFR | |
+| **2+. PM Plan** | Pending | `@pm` | - | - | `PRD_{{FEATURE_KEY}}.md` | `BACKLOG_{{FEATURE_KEY}}.md` | |
+| **3. ARCH** | Pending | `@arch` | - | - | `ARCH_DESIGN_{{FEATURE_KEY}}.md` | API + API_DETAIL + DB + UI specs | |
+| **4. Dev** | Pending | `@dev` | - | - | `FEATURE_IMPL_PLAN_{{FEATURE_KEY}}.md` | Code + Tests + Code Review | |
+| **5. QA** | Pending | `@qa` | - | - | `QA_RELEASE_REPORT_{{FEATURE_KEY}}.md` | `{{FEATURE_KEY}}_TEST_CASE.md` + Test results | |
+| **6. PM Closure** | Pending | `@pm` | - | - | Release decision recorded | Handoff complete | |
+
+---
+
+## VISUAL PIPELINE STATUS
+```
+[PM Init] IN_PROGRESS --> [BA] PENDING --> [PM Plan] PENDING --> [ARCH] PENDING --> [Dev] PENDING --> [QA] PENDING --> [PM Closure] PENDING
+```
+
+---
+
+## ARTIFACTS LOCATION GUIDE
+
+```
+PM OUTPUTS:          docs/product/PROJECT_INITIATION_{{FEATURE_KEY}}.md
+                     docs/product/PRD_{{FEATURE_KEY}}.md
+                     docs/product/BACKLOG_{{FEATURE_KEY}}.md
+BA OUTPUTS:          docs/specs/BA_SPEC_{{FEATURE_KEY}}.md
+ARCH OUTPUTS:        docs/architecture/ARCH_DESIGN_{{FEATURE_KEY}}.md
+                     docs/api/{{FEATURE_PASCAL}}_API.yaml
+                     docs/api/{{FEATURE_KEY}}_ENDPOINTS.md
+                     docs/api/{{FEATURE_KEY}}_API_DESIGN_DETAIL.md
+                     docs/api/{{FEATURE_SNAKE}}_api_flow_list.txt
+                     docs/database/DATABASE_SPEC_{{FEATURE_KEY}}.md
+                     docs/specs/{{FEATURE_KEY}}_FLOW_ACTION_SPEC.md
+                     docs/design/DESIGN_LAYOUT_{{FEATURE_KEY}}.md
+DEV OUTPUTS:         docs/dev/FEATURE_IMPL_PLAN_{{FEATURE_KEY}}.md
+QA OUTPUTS:          docs/qa/{{FEATURE_KEY}}_TEST_CASE.md
+                     docs/qa/QA_RELEASE_REPORT_{{FEATURE_KEY}}.md
+SHARED STATE:        SHARED_PLANNING.md + QUALITY_CHECKLIST.md
+```
+
+---
+
+## CURRENT BLOCKERS / ISSUES
+```
+NO BLOCKERS
+```
+
+---
+
+## OPEN QUESTIONS (Summary)
+List any unresolved OQ-xx items here with a pointer to the owning artifact (PM consolidates).
+
+| Q-ID | Summary | Owner | Source Doc | Status |
+|------|---------|-------|------------|--------|
+| OQ-01 | TBD | PM | docs/specs/BA_SPEC_{{FEATURE_KEY}}.md | OPEN |
+
+---
+
+## RECENT ACTIVITY LOG (Agent Updates)
+
+```
+{{DATETIME}} | [SYSTEM] | INIT | Toolkit initialized for {{FEATURE_KEY}} | @pm please create PROJECT_INITIATION
+```
+
+**Append updates with format:**
+```
+YYYY-MM-DD HH:MM | [PM/BA/ARCH/DEV/QA] | [Status] | [Artifact] | @next_agent
+```

package/assets/toolkit/toolkit/templates/docs/api/API_DESIGN_CREATION_RULES.md

@@ -0,0 +1,212 @@
+# API Design Creation Rules for AI Agents (Excel Template)
+
+This document defines reusable rules for creating API design documents in Excel format based on `Example/Docs/API/API_design.xlsx`.
+
+## 1. Scope and Goal
+
+- Reuse one consistent Excel structure for API contract documentation.
+- Keep flow, endpoint parameters, request schema, response schema, and revision history in one workbook.
+- Keep generated sheets deterministic and review-friendly.
+
+## 2. Source Template Baseline
+
+| No | Sheet Pattern | Purpose |
+| ---: | --- | --- |
+| 1 | `History` | Global workbook change history |
+| 2 | `API detail (...)` | One API per sheet |
+
+Observed baseline in `API_design.xlsx`:
+- 1 history sheet.
+- 5 API detail sheets (list/create/detail/update/logical delete).
+
+## 3. Workbook Rules
+
+### 3.1 Sheet Naming
+
+- Use one API per sheet.
+- Recommended naming style:
+  - `API detail (<domain action>)`
+- Keep API sheet order stable (for example: list -> create -> detail -> update -> delete).
+
+### 3.2 History Sheet
+
+- Keep `History` as the first sheet.
+- Header layout:
+  - `A3=Date`
+  - `C3=Version`
+  - `F3=Editor`
+  - `M3=Edit content`
+- Append rows only. Do not rewrite historical rows.
+
+## 4. API Detail Sheet Layout
+
+### 4.1 Header Metadata Block
+
+Use this label/value map:
+
+| No | Label Cell Group | Value Cell Group | Meaning |
+| ---: | --- | --- | --- |
+| 1 | `Q1:X1` | `Y1:AQ1` | System name |
+| 2 | `Q2:X2` | `Y2:AQ2` | System ID |
+| 3 | `Q3:X3` | `Y3:AQ3` | Subsystem name |
+| 4 | `Q4:X4` | `Y4:AQ4` | Function name |
+| 5 | `AR1:AV1` | `AW1:BC1` | Created by |
+| 6 | `AR2:AV2` | `AW2:BC2` | Created date |
+| 7 | `AR3:AV3` | `AW3:BC3` | Revised by |
+| 8 | `AR4:AV4` | `AW4:BC4` | Revised date |
+
+Also keep document title block:
+- `A1:P4` = document title area.
+
+### 4.2 Mandatory Section Order
+
+Each API sheet must keep this order:
+1. Process flow section
+2. `Parameters:`
+3. Request parameter section (JSON format)
+4. Success response section (JSON format)
+5. Error response section (JSON format)
+
+### 4.3 Endpoint Title Placement
+
+- Put endpoint summary at top flow area: `B7`.
+  - Format: `<METHOD> <PATH> <summary>`
+- Repeat the same endpoint summary in contract area:
+  - Column `A`, one row above `Parameters:`.
+- Both endpoint strings must be identical.
+
+### 4.4 Flowchart Placement
+
+- Put PlantUML text in `BG8` (multi-line content in one cell).
+- `BG6` can contain tool/reference note.
+- Helper + main flows can be placed in one cell value if clearly separated.
+- Flow syntax/content standards follow:
+  - `Example/Docs/API/FLOWCHART_CREATION_RULES.md`
+
+## 5. Endpoint and Parameter Rules
+
+### 5.1 Path Parameter Block
+
+- Anchor row: column `B` equals `Parameters:`.
+- Parameter rows:
+  - parameter key in column `C`
+  - description in column `K`
+- Include every path placeholder from endpoint path.
+- Keep parameter order aligned with placeholder order.
+
+### 5.2 Consistency Checks
+
+- Every `{placeholder}` in path must exist exactly once in the parameter rows.
+- Avoid duplicate parameter names unless explicitly documented.
+- Remove stale parameter rows after endpoint rename.
+
+## 6. Request/Response Table Rules
+
+### 6.1 Common Column Model
+
+| No | Column Group | Meaning |
+| ---: | --- | --- |
+| 1 | `A:B` | Row No |
+| 2 | `C:J` | Item label |
+| 3 | `K:N` | Hierarchy level 1 |
+| 4 | `O:R` | Hierarchy level 2 |
+| 5 | `S:V` | Hierarchy level 3 |
+| 6 | `W:Z` | Hierarchy level 4 |
+| 7 | `AA:AD` | Hierarchy level 5 |
+| 8 | `AE:AH` | Hierarchy level 6 |
+| 9 | `AI:AK` | Data type |
+
+### 6.2 Request Header Mode
+
+For write/search request tables, include:
+- `No`
+- `Item Name`
+- `Item`
+- `Type`
+- `Format`
+- `Length`
+- `Required`
+
+Column groups:
+- `AL:AN` -> `Format`
+- `AO:AP` -> `Length`
+- `AQ:AR` -> `Required`
+
+### 6.3 Response Header Mode
+
+For response tables, include:
+- `No`
+- `Item Name`
+- `Item`
+- `Type`
+- `Note`
+
+Column group:
+- `AL:AN` -> `Note`
+
+### 6.4 GET Request Body Rule
+
+- If API has no JSON request body, set request body to:
+  - `None`
+
+### 6.5 Hierarchy Modeling Rule
+
+- Use hierarchy columns (level 1 to level 6) to represent nesting.
+- Represent root wrapper explicitly (for example `data`).
+- For array object children, define parent array node first, then child fields at deeper levels.
+
+## 7. Status and Error Contract Rules
+
+- Success response must include `status` at minimum.
+- Error response must include:
+  - `status`
+  - `data` (message or detail payload)
+- If status detail references an external code table, note that in response notes.
+
+## 8. Type and Format Rules
+
+- Use stable type keywords:
+  - `string`
+  - `integer`
+  - `number`
+  - `object`
+  - `array`
+- If datetime format is constrained, write it in `Format` or `Note` (for example `yyyymmddHHMMSS`).
+- Business constraints (constant flags, nullable behavior, etc.) go to `Note`.
+
+## 9. Recommended Generation Procedure
+
+1. Duplicate an existing API detail sheet.
+2. Update metadata fields (`Q..BC` blocks).
+3. Update endpoint title in `B7`.
+4. Update PlantUML in `BG8`.
+5. Update repeated endpoint title above `Parameters:`.
+6. Update path parameters (`C/K` rows).
+7. Update request section:
+   - `None` for no-body APIs.
+   - request table for body APIs.
+8. Update success response table.
+9. Update error response table.
+10. Append one new row in `History`.
+
+## 10. Quality Gate Checklist Before Handoff
+
+- Section order is complete and unchanged.
+- Endpoint title in `B7` matches the endpoint title above `Parameters:`.
+- Path placeholders and parameter rows are 1:1 matched.
+- Request/response sections use correct header mode.
+- `No` is sequential in every table.
+- Hierarchy columns reflect actual payload nesting.
+- `status` and error payload structure are documented.
+- PlantUML in `BG8` matches endpoint behavior.
+- `History` has a new appended entry.
+
+## 11. Known Pitfalls and Prevention
+
+| No | Pitfall | Prevention Rule |
+| ---: | --- | --- |
+| 1 | Endpoint placeholder renamed but parameter rows not synced | Run path-vs-parameter check for every API sheet |
+| 2 | Request/response headers mixed (`Note` vs `Required`) | Use section-specific header mode only |
+| 3 | Nested array fields placed at wrong hierarchy level | Define parent array first, then child fields deeper |
+| 4 | Endpoint summary mismatch between top and contract blocks | Maintain a single canonical endpoint title string and reuse it |
+

package/assets/toolkit/toolkit/templates/docs/api/API_DESIGN_DETAIL_TEMPLATE.md

@@ -0,0 +1,62 @@
+# {{FEATURE_KEY}} API DESIGN DETAIL
+
+## 0. Abbreviations
+
+| No | Term | Meaning |
+| ---: | --- | --- |
+| 1 | API | Application Programming Interface |
+| 2 | UUID | Universally Unique Identifier |
+| 3 | FE | Frontend |
+| 4 | BE | Backend |
+| 5 | DT | Datetime |
+
+## 1. Document Scope
+
+| No | Method | Endpoint | Reference Template |
+| ---: | --- | --- | --- |
+| 1 | TBD | TBD | `API_design.xlsx` |
+
+## 2. API Detail 1 - TBD
+
+**Endpoint:** `TBD`
+
+### 2.1 Process Flow
+
+Source of truth: `docs/api/{{FEATURE_SNAKE}}_api_flow_list.txt`
+
+```text
+@startuml
+partition "TBD" {
+start
+:TBD;
+stop
+}
+@enduml
+```
+
+![Flowchart - API 1](./images/{{FEATURE_SNAKE}}__api_1.svg)
+
+### 2.2 Parameters
+
+`None`
+
+### 2.3 Request Parameters (JSON format)
+
+`None`
+
+### 2.4 Success Response (JSON format)
+
+`None`
+
+### 2.5 Error Response (JSON format)
+
+`None`
+
+## 3. Generation Notes
+
+- This file should be generated/updated by skill `sdtk-api-design-spec`.
+- Rules source: `templates/docs/api/API_DESIGN_CREATION_RULES.md`.
+- Contract source:
+  - `docs/api/{{FEATURE_PASCAL}}_API.yaml`
+  - `docs/api/{{FEATURE_SNAKE}}_api_flow_list.txt`
+

package/assets/toolkit/toolkit/templates/docs/api/API_ENDPOINTS_TEMPLATE.md

@@ -0,0 +1,229 @@
+# {{FEATURE_KEY}} API ENDPOINTS
+
+**Document ID:** {{FEATURE_KEY}}_ENDPOINTS
+**Version:** 1.0.0
+**Date:** {{DATE}}
+**Author:** ARCH Agent
+**Status:** DRAFT
+**Related Specs:** `docs/specs/BA_SPEC_{{FEATURE_KEY}}.md`, `docs/specs/{{FEATURE_KEY}}_FLOW_ACTION_SPEC.md`, `docs/database/DATABASE_SPEC_{{FEATURE_KEY}}.md`, `docs/api/{{FEATURE_KEY}}_API_DESIGN_DETAIL.md`
+
+---
+
+## Abbreviations
+
+| No | Abbreviation | Meaning |
+| ---: | --- | --- |
+| 1 | API | Application Programming Interface |
+| 2 | DB | Database |
+| 3 | UI | User Interface |
+| 4 | BR | Business Rule |
+| 5 | UC | Use Case |
+| 6 | OQ | Open Question |
+
+---
+
+## Domain Keywords
+
+| No | Keyword | Source Term | Meaning Used In This API Spec |
+| ---: | --- | --- | --- |
+| 1 | `resource_a` | TBD | TBD |
+| 2 | `resource_b` | TBD | TBD |
+
+---
+
+## Table of Contents
+
+1. [Overview](#1-overview)
+2. [Authentication & Authorization](#2-authentication--authorization)
+3. [Common Response Formats](#3-common-response-formats)
+4. [Core APIs](#4-core-apis)
+5. [Master/Reuse APIs](#5-masterreuse-apis)
+6. [Error Codes Reference](#6-error-codes-reference)
+7. [Appendices](#appendix-a-data-model-reference)
+8. [Document History](#document-history)
+
+---
+
+## 1. Overview
+
+### 1.1 Base URL
+```
+{BASE_URL}/api
+```
+
+### 1.2 API Versioning
+Current version: `v1` (confirm final path policy in BA/ARCH decisions).
+
+### 1.3 Content Type
+- Request: `application/json`
+- Response: `application/json`
+
+### 1.4 Date/Time Format
+- Date: `YYYY-MM-DD`
+- DateTime: `YYYY-MM-DDTHH:mm:ss` (or timezone-aware per project decision)
+
+### 1.5 Endpoint Naming Convention
+- Apply `FLOWCHART_CREATION_RULES.md` (API endpoint design + governance rules).
+- Keep resource naming and method policy consistent across all sections.
+
+---
+
+## 2. Authentication & Authorization
+
+### 2.1 Authentication
+All endpoints require Bearer token authentication unless explicitly documented.
+
+### 2.2 Permission Model
+
+| No | Permission | Description | Allowed Operations |
+| ---: | --- | --- | --- |
+| 1 | `feature:view` | Read permission | Read/search endpoints |
+| 2 | `feature:edit` | Write permission | Create/edit/delete endpoints |
+
+---
+
+## 3. Common Response Formats
+
+### 3.1 Success Response
+```json
+{
+  "status": 0,
+  "msg": "success",
+  "data": {},
+  "errors": []
+}
+```
+
+### 3.2 Error Response
+```json
+{
+  "status": 100,
+  "msg": "validation error",
+  "data": {},
+  "errors": [
+    {
+      "field": "field_name",
+      "code": "INVALID",
+      "detail": "TBD"
+    }
+  ]
+}
+```
+
+### 3.3 Pagination Parameters
+
+| No | Parameter | Type | Default | Description |
+| ---: | --- | --- | --- | --- |
+| 1 | `page` | integer | 1 | Page number |
+| 2 | `page_size` | integer | 20 | Items per page |
+
+---
+
+## 4. Core APIs
+
+### 4.1 METHOD /api/... (TBD)
+
+**Description:** TBD  
+**Related Use Cases:** UC-xx  
+**Authentication:** Required (`feature:view` or `feature:edit`)
+
+**Request Schema:**
+
+| No | Field | Type | Required | Description |
+| ---: | --- | --- | --- | --- |
+| 1 | `field_1` | string | Yes | TBD |
+
+**Request Example:**
+```http
+METHOD /api/...
+Authorization: Bearer {token}
+Content-Type: application/json
+```
+
+```json
+{
+  "field_1": "value"
+}
+```
+
+**Response Schema (key fields):**
+```json
+{
+  "status": 0,
+  "msg": "success",
+  "data": {
+    "items": []
+  },
+  "errors": []
+}
+```
+
+**Possible Error Codes:**
+
+| No | Code | Description |
+| ---: | --- | --- |
+| 1 | `ERR-xxx` | TBD |
+
+---
+
+## 5. Master/Reuse APIs
+
+| No | Method | Endpoint | API Type | Description |
+| ---: | --- | --- | --- | --- |
+| 1 | GET | /api/... | Existing (reuse) | TBD |
+
+---
+
+## 6. Error Codes Reference
+
+### 6.1 Standard HTTP Status Codes
+
+| No | Code | Description |
+| ---: | --- | --- |
+| 1 | 200 | Success |
+| 2 | 400 | Bad Request |
+| 3 | 401 | Unauthorized |
+| 4 | 403 | Forbidden |
+| 5 | 404 | Not Found |
+| 6 | 409 | Conflict |
+| 7 | 500 | Internal Server Error |
+
+### 6.2 Application Error Codes
+
+| No | Code | HTTP Status | Description |
+| ---: | --- | --- | --- |
+| 1 | `ERR-VALIDATION` | 400 | Request validation failed |
+| 2 | `ERR-AUTH` | 401/403 | Auth/permission failure |
+| 3 | `ERR-CONFLICT` | 409 | Business conflict |
+
+---
+
+## Appendix A: Data Model Reference
+
+| No | Entity | Key Fields | Notes |
+| ---: | --- | --- | --- |
+| 1 | TBD | TBD | TBD |
+
+---
+
+## Appendix B: API Endpoint Summary
+
+| No | Method | Endpoint | API Type | Description |
+| ---: | --- | --- | --- | --- |
+| 1 | METHOD | /api/... | New | TBD |
+
+---
+
+## Appendix C: API Required For Screen Logic
+
+| No | Method | Endpoint | API Type | Description (screen logic) | Spec can confirm (Q&A) |
+| ---: | --- | --- | --- | --- | --- |
+| 1 | METHOD | /api/... | New | TBD | TBD |
+
+---
+
+## Document History
+
+| No | Version | Date | Author | Changes |
+| ---: | --- | --- | --- | --- |
+| 1 | 1.0.0 | {{DATE}} | ARCH Agent | Initial template-based version |

package/assets/toolkit/toolkit/templates/docs/api/FEATURE_API_TEMPLATE.yaml

@@ -0,0 +1,20 @@
+openapi: '3.0.3'
+info:
+  title: '{{FEATURE_NAME}} API'
+  version: '1.0.0'
+  description: |
+    # {{FEATURE_NAME}} API
+    - FeatureKey: {{FEATURE_KEY}}
+servers:
+  - url: /api/v1
+security:
+  - Bearer: []
+paths: {}
+components:
+  securitySchemes:
+    Bearer:
+      type: http
+      scheme: bearer
+      description: Access token
+  schemas: {}
+