sdtk-kit 0.3.0

package/assets/toolkit/toolkit/scripts/uninstall-codex-skills.ps1

@@ -0,0 +1,116 @@
+param(
+  [string]$SkillName,
+  [switch]$All,
+  [switch]$BackupExisting,
+  [string]$BackupPath
+)
+
+$ErrorActionPreference = 'Stop'
+Set-StrictMode -Version Latest
+
+function Backup-Directory {
+  param(
+    [Parameter(Mandatory = $true)][string]$SourcePath,
+    [Parameter(Mandatory = $true)][string]$BackupRoot,
+    [Parameter(Mandatory = $true)][string]$Name
+  )
+
+  if (-not (Test-Path -LiteralPath $SourcePath)) {
+    return $null
+  }
+
+  New-Item -ItemType Directory -Force -Path $BackupRoot | Out-Null
+  $dest = Join-Path $BackupRoot $Name
+  if (Test-Path -LiteralPath $dest) {
+    Remove-Item -LiteralPath $dest -Recurse -Force
+  }
+  Copy-Item -LiteralPath $SourcePath -Destination $dest -Recurse -Force
+  return $dest
+}
+
+if ($All -and $SkillName) {
+  throw "Use either -All or -SkillName, not both."
+}
+
+$repoRoot = Resolve-Path (Join-Path $PSScriptRoot '..')
+$skillsSrc = Join-Path $repoRoot 'skills'
+if (-not (Test-Path -LiteralPath $skillsSrc)) {
+  throw "Missing toolkit skills source directory: $skillsSrc"
+}
+
+$managedSkillNames = Get-ChildItem -LiteralPath $skillsSrc -Directory | Select-Object -ExpandProperty Name
+if (-not $managedSkillNames -or $managedSkillNames.Count -eq 0) {
+  throw "No managed skills found in: $skillsSrc"
+}
+
+$targetNames = @()
+if ($SkillName) {
+  if ($managedSkillNames -notcontains $SkillName) {
+    throw "Skill '$SkillName' is not in managed toolkit skills list. Known skills: $($managedSkillNames -join ', ')"
+  }
+  $targetNames = @($SkillName)
+} elseif ($All) {
+  $targetNames = @($managedSkillNames)
+} else {
+  # Default behavior: uninstall all toolkit-managed skills.
+  $targetNames = @($managedSkillNames)
+}
+
+$codexHome = $env:CODEX_HOME
+if (-not $codexHome) {
+  $codexHome = Join-Path $HOME '.codex'
+}
+
+$skillsDest = Join-Path $codexHome 'skills'
+if (-not (Test-Path -LiteralPath $skillsDest)) {
+  Write-Host "Codex skills directory not found: $skillsDest"
+  exit 0
+}
+
+$backupRootResolved = $null
+if ($BackupExisting) {
+  if (-not $BackupPath -or $BackupPath.Trim().Length -eq 0) {
+    $timestamp = Get-Date -Format 'yyyyMMdd-HHmmss'
+    $BackupPath = Join-Path $codexHome (Join-Path 'skills-backups' ("uninstall-" + $timestamp))
+  }
+  New-Item -ItemType Directory -Force -Path $BackupPath | Out-Null
+  $backupRootResolved = (Resolve-Path -LiteralPath $BackupPath).Path
+  Write-Host "Backup mode enabled: $backupRootResolved"
+}
+
+$removed = New-Object System.Collections.Generic.List[string]
+$missing = New-Object System.Collections.Generic.List[string]
+
+foreach ($name in $targetNames) {
+  $dest = Join-Path $skillsDest $name
+  if (-not (Test-Path -LiteralPath $dest)) {
+    $missing.Add($name) | Out-Null
+    Write-Warning "Skill not installed, skipping: $name"
+    continue
+  }
+
+  if ($BackupExisting) {
+    $backupDest = Backup-Directory -SourcePath $dest -BackupRoot $backupRootResolved -Name $name
+    if ($backupDest) {
+      Write-Host "Backed up: $name -> $backupDest"
+    }
+  }
+
+  Remove-Item -LiteralPath $dest -Recurse -Force
+  $removed.Add($name) | Out-Null
+  Write-Host "Uninstalled: $name"
+}
+
+Write-Host ""
+Write-Host "Uninstall summary:"
+Write-Host "- Removed: $($removed.Count)"
+if ($removed.Count -gt 0) {
+  $removed | ForEach-Object { Write-Host "  - $_" }
+}
+Write-Host "- Missing/Skipped: $($missing.Count)"
+if ($missing.Count -gt 0) {
+  $missing | ForEach-Object { Write-Host "  - $_" }
+}
+if ($backupRootResolved) {
+  Write-Host "- Backup directory: $backupRootResolved"
+}

package/assets/toolkit/toolkit/sdtk.config.json

@@ -0,0 +1,28 @@
+{
+  "docs": {
+    "artifactsLanguage": "EN",
+    "guidanceLanguage": "VI",
+    "preserveOriginalInput": true,
+    "appendixIncludeEnglishTranslation": true,
+    "aiPeerReviewAllowed": true
+  },
+  "orchestration": {
+    "apiDesignDetailMode": "auto",
+    "testCaseSpecMode": "auto"
+  },
+  "stack": {
+    "backend": "Set your backend stack (example: Python Django REST Framework)",
+    "frontend": "Set your frontend stack (example: React + Vite)",
+    "mobile": "N/A",
+    "database": "Set your database (example: PostgreSQL 15)",
+    "auth": "Set your auth strategy (example: JWT/OAuth2)"
+  },
+  "commands": {
+    "backendTests": "UPDATE_ME: set backend test command",
+    "backendTypecheck": "UPDATE_ME: set backend typecheck command",
+    "backendLint": "UPDATE_ME: set backend lint command",
+    "frontendTests": "UPDATE_ME: set frontend test command",
+    "frontendLint": "UPDATE_ME: set frontend lint command",
+    "e2eTests": "UPDATE_ME: set e2e test command"
+  }
+}

package/assets/toolkit/toolkit/sdtk.config.profiles.example.json

@@ -0,0 +1,50 @@
+{
+  "profiles": {
+    "django-react": {
+      "orchestration": {
+        "apiDesignDetailMode": "auto",
+        "testCaseSpecMode": "auto"
+      },
+      "stack": {
+        "backend": "Python 3.11 + Django 4.x + Django REST Framework",
+        "frontend": "React 18 + Vite",
+        "mobile": "N/A",
+        "database": "PostgreSQL 15",
+        "auth": "JWT"
+      },
+      "commands": {
+        "backendTests": "python -m pytest",
+        "backendTypecheck": "python -m mypy src/backend",
+        "backendLint": "python -m ruff check src/backend",
+        "frontendTests": "npm run test",
+        "frontendLint": "npm run lint",
+        "e2eTests": "npm run e2e"
+      }
+    },
+    "node-nextjs": {
+      "orchestration": {
+        "apiDesignDetailMode": "auto",
+        "testCaseSpecMode": "auto"
+      },
+      "stack": {
+        "backend": "Node.js 20 + Express/Fastify",
+        "frontend": "Next.js 14",
+        "mobile": "N/A",
+        "database": "PostgreSQL 15",
+        "auth": "OAuth2 + JWT"
+      },
+      "commands": {
+        "backendTests": "npm run test:api",
+        "backendTypecheck": "npm run typecheck:api",
+        "backendLint": "npm run lint:api",
+        "frontendTests": "npm run test:web",
+        "frontendLint": "npm run lint:web",
+        "e2eTests": "npm run test:e2e"
+      }
+    }
+  },
+  "notes": [
+    "Copy one profile into sdtk.config.json and adjust for your project.",
+    "Do not keep UPDATE_ME placeholders before running real delivery gates."
+  ]
+}

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

@@ -0,0 +1,78 @@
+---
+name: sdtk-api-design-spec
+description: Generate detailed API design markdown (`[FEATURE_KEY]_API_DESIGN_DETAIL.md`) 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.
+---
+
+# SDTK API Design Detail Spec
+
+## Outputs
+- `docs/api/[FEATURE_KEY]_API_DESIGN_DETAIL.md`
+- Supporting generated assets:
+  - `docs/api/flows/*.puml`
+  - `docs/api/images/*.svg`
+
+## Required Inputs
+- Feature key (`FEATURE_KEY`)
+- API contract YAML:
+  - Preferred: `docs/api/[FeaturePascal]_API.yaml`
+  - Fallback: a specified YAML file path
+- API flow list:
+  - Preferred: `docs/api/[feature_snake]_api_flow_list.txt`
+  - Fallback: a specified flow list path
+
+## Core Rules
+- Apply `./references/API_DESIGN_CREATION_RULES.md` first.
+- Keep endpoint contracts consistent with source YAML.
+- Keep process flow source synchronized with flow list (`*_api_flow_list.txt`).
+- Keep one visible flowchart per API section (embed image), avoid duplicate preview rendering.
+
+## Generation Procedure
+1. Resolve input files (`yaml`, `flow_list`, `output`).
+2. Parse YAML endpoints (method, path, request schema, success/error schema).
+3. Parse flow blocks from flow list (`@startuml ... @enduml`) and map by `METHOD + path`.
+4. Generate detailed markdown sections per API:
+   - Process flow source block (`text` fenced block)
+   - Embedded flowchart image
+   - Path parameter table
+   - Request table (hierarchy levels + type + format + required)
+   - Success response table
+   - Error response table
+5. Generate/update `.puml` per API under `docs/api/flows`.
+6. Render `.svg` images under `docs/api/images`.
+7. Validate:
+   - every API section has one embedded image
+   - every embed path exists
+   - no render error image output
+   - markdown tables keep `No` sequential numbering
+
+## Script
+- `scripts/generate_api_design_detail.py`
+
+### Typical command
+```powershell
+python "toolkit/skills/sdtk-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
+```powershell
+python "toolkit/skills/sdtk-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}" `
+  --include "POST /api/whiteboard/assignment/edit/{company_uuid}/{sagyo_assign_uuid}" `
+  --include "POST /api/whiteboard/assignment/delete/{company_uuid}/{sagyo_assign_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.
+  - `on`: always generate API design detail for API scope (fail if required sources are missing).
+  - `off`: skip unless user explicitly requests.
+
+

package/assets/toolkit/toolkit/skills/sdtk-api-design-spec/references/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 |
+