sdtk-ops-kit 0.2.5 → 0.2.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -5,7 +5,7 @@
5
5
  ## Package
6
6
 
7
7
  - Package: `sdtk-ops-kit`
8
- - Version in this source snapshot: `0.2.4`
8
+ - Version in this source snapshot: `0.2.8`
9
9
  - CLI: `sdtk-ops`
10
10
  - Latest published version lookup: `npm view sdtk-ops-kit version`
11
11
 
@@ -1,12 +1,12 @@
1
1
  {
2
- "version": "0.2.5",
3
- "sourceCommit": "17db9f2e515e7dc0cb120d0bf8dae4f01487a239",
2
+ "version": "0.2.8",
3
+ "sourceCommit": "12c007b7b4588c7cf1bf13a34ebee83bb9d2e40b",
4
4
  "fileCount": 36,
5
5
  "files": [
6
6
  {
7
7
  "path": "toolkit/AGENTS.md",
8
- "sha256": "0387e747b9eb4500f810b338b28d795841e796fdaa40c4002e07b0d88b724167",
9
- "size": 11053
8
+ "sha256": "5c76955ecabfae64759c11a3ee0fa777b1e0c0f78bdd177ae8f04340cd572e4b",
9
+ "size": 16469
10
10
  },
11
11
  {
12
12
  "path": "toolkit/install.ps1",
@@ -35,13 +35,13 @@
35
35
  },
36
36
  {
37
37
  "path": "toolkit/sdtk-spec.config.json",
38
- "sha256": "8247ddf24502ce285bee213eefc801ce6b0b83afe00efd828468ac9130f53b09",
39
- "size": 111
38
+ "sha256": "712382d838a18b6cc6a5285b3c536fac74138c752a3fa1fd318828b19ece6b8f",
39
+ "size": 1231
40
40
  },
41
41
  {
42
42
  "path": "toolkit/sdtk-spec.config.profiles.example.json",
43
- "sha256": "e63d512ef00b750fea1d952be28e827fba8577ba536f32fa74e8708f48655ca7",
44
- "size": 303
43
+ "sha256": "2a306c1609499fb4910b86d5ec6e8c796e0cdf72c5f97fe3df9c1388ac62b913",
44
+ "size": 2134
45
45
  },
46
46
  {
47
47
  "path": "toolkit/SDTKOPS_TOOLKIT.md",
@@ -1,11 +1,11 @@
1
- 0387e747b9eb4500f810b338b28d795841e796fdaa40c4002e07b0d88b724167 toolkit/AGENTS.md
1
+ 5c76955ecabfae64759c11a3ee0fa777b1e0c0f78bdd177ae8f04340cd572e4b toolkit/AGENTS.md
2
2
  e79e1ab404abf83a4f90838a2f6450c387ada7e65b137a18f70f0cab74fc14f0 toolkit/install.ps1
3
3
  5eae77f4d14b81d56c3c109f563fefafd1967d85093ff1b192293fe438aeabe5 toolkit/scripts/install-claude-skills.ps1
4
4
  68eb662bc9b8906882d32f6cd1247238f6ae663137a489f18054a75724cd1e81 toolkit/scripts/install-codex-skills.ps1
5
5
  2c629d8316b205c6a7cd0d95959b80801b281ef62e205c10a92e3a2568eb8b41 toolkit/scripts/uninstall-claude-skills.ps1
6
6
  fdb9631a80ecfb0d986a52a2833e88bf15c5303ab654d35bad6d64cca43046e8 toolkit/scripts/uninstall-codex-skills.ps1
7
- 8247ddf24502ce285bee213eefc801ce6b0b83afe00efd828468ac9130f53b09 toolkit/sdtk-spec.config.json
8
- e63d512ef00b750fea1d952be28e827fba8577ba536f32fa74e8708f48655ca7 toolkit/sdtk-spec.config.profiles.example.json
7
+ 712382d838a18b6cc6a5285b3c536fac74138c752a3fa1fd318828b19ece6b8f toolkit/sdtk-spec.config.json
8
+ 2a306c1609499fb4910b86d5ec6e8c796e0cdf72c5f97fe3df9c1388ac62b913 toolkit/sdtk-spec.config.profiles.example.json
9
9
  58cfc74a11b8a0a18d0113a12e0e0b7a1188b253f7d19ff259d551914a831c4e toolkit/SDTKOPS_TOOLKIT.md
10
10
  1cd81e12cebdb2be528803e2d8afe43959aab1493e55499af529b99ec566a56c toolkit/skills/ops-backup/references/backup-script-patterns.md
11
11
  76e8385190d967bf98b3cafbbf8925d9b9c656ee7a7ed66ff51285b6459ebff1 toolkit/skills/ops-backup/SKILL.md
@@ -1,5 +1,10 @@
1
1
  # SDTK Orchestrator Routing Contract
2
2
 
3
+ Version: 2.0
4
+ Last Updated: 2026-07-14
5
+
6
+ This file is the single source of the SDTK routing contract. `CLAUDE.md` and `CODEX.md` are thin runtime adapters that defer to it; when they appear to disagree with this file, this file wins.
7
+
3
8
  Goal: use the SDTK Suite as a coordinated operating model:
4
9
  - `SDTK-SPEC` governs upstream discovery, planning, design, traceability, and release gates.
5
10
  - `SDTK-CODE` is the default downstream system for implementation, bug fixing, refactoring, verification, and ship-ready code changes.
@@ -19,19 +24,26 @@ Orchestrator Intake is the always-winning front door for every unprefixed reques
19
24
  - Read stack and command configuration from `sdtk-spec.config.json` in the project root.
20
25
  - For VI/JP source requirements, keep original text in an appendix and add literal English translation for traceability.
21
26
  - `/dev` stops at `FEATURE_IMPL_PLAN + CODE_HANDOFF`; SDTK-CODE is the default downstream coding system.
22
- - Verification-before-completion: no phase may declare done, pass, or handoff-ready without fresh command evidence per `governance/ai/core/SDTK_VERIFICATION_BEFORE_COMPLETION_POLICY.md`.
27
+ - Verification-before-completion: no phase may declare done, pass, or handoff-ready without fresh command evidence — run the relevant verification commands in this session and quote their real output in the phase artifact; assumed, remembered, or stale results do not count.
23
28
  - `toolkit/skills/skills.catalog.yaml` is the inventory source of truth for the 14 core SDTK-SPEC skills, including the bounded `mailbox-dispatch` controller skill.
24
29
 
25
30
  ## 2) Session Bootstrap Protocol
26
31
  When starting a new session, read context in this order when the files exist:
27
32
  1. `AGENTS.md`
28
- 2. `governance/ai/session/SDTK_ACTIVE_BOOTSTRAP.md`
29
- 3. `governance/ai/session/SDTK_AGENT_WORKING_RULES.md`
30
- 4. `governance/ai/core/IMPROVEMENT_BACKLOG.md`
31
- 5. issue-specific controller spec and implementation plan
33
+ 2. `.sdtk/evolve/LEARNED.md` — locally learned, owner-approved lessons (managed by the evolve skill + `sdtk evolve`; never edit it directly)
34
+ 3. `governance/ai/session/SDTK_ACTIVE_BOOTSTRAP.md`
35
+ 4. `governance/ai/session/SDTK_AGENT_WORKING_RULES.md`
36
+ 5. `governance/ai/core/IMPROVEMENT_BACKLOG.md`
37
+ 6. issue-specific controller spec and implementation plan
38
+
39
+ Orientation and health:
40
+ - If `.sdtk/wiki/` exists, it is the project's committed memory layer: orient with `sdtk-wiki search "<topic>"` (entry points: `.sdtk/wiki/pages/_index.md`, the atlas summary) before falling back to repo-wide searching.
41
+ - If any `sdtk-*` CLI behaves unexpectedly (missing verbs, stale help, wrong version), run `sdtk doctor` to detect version fragmentation before debugging further.
32
42
 
33
43
  Do not read the entire historical session archive by default. Use `SDTK_SESSION_MEMORY_*.md` only when chronology or past acceptance details are required.
34
44
 
45
+ Active orchestration check: if `.sdtk/agent-runtime/runs/` holds a run whose state is not terminal (`running` or `waiting_for_approval`), surface it in one line (run id plus the blocking gate, if any) and offer `sdtk-agent run continue` before starting unrelated work, the same way `.sdtk/handoff/` items are surfaced.
46
+
35
47
  ## 3) Orchestrator-First Intake Protocol
36
48
  For every unprefixed user request:
37
49
  1. Classify the request intent before selecting PM/BA/ARCH/DEV/QA or a downstream product lane.
@@ -58,11 +70,14 @@ Use this compact matrix during intake so the agent picks the smallest sufficient
58
70
  | Formal feature delivery | `SDTK-SPEC` pipeline | PM -> BA -> ARCH -> DEV planning -> CODE handoff -> QA |
59
71
  | Build, fix, or refactor implementation | `SDTK-CODE` | code-brainstorm (when slice is ambiguous) -> start -> plan -> build -> verify -> ship |
60
72
  | Debug failure or unexpected behavior | `SDTK-CODE` debug | Root cause, bounded fix, regression verification |
73
+ | Screen/layout design, visual tokens, or prototype evidence before coding | `SDTK-DESIGN` | Reviewable screens/prototype plus a design handoff into SDTK-CODE |
61
74
  | Deployment, release, infra, or CI/CD work | `SDTK-OPS` | ops-plan -> ops-deploy/ops-incident/ops-monitor -> ops-verify |
62
75
  | Code review or spec review | Review / QA workflow | Findings, risks, blockers, acceptance signal |
63
76
  | Atlas graph build or viewer work | `sdtk-spec atlas` compatibility workflow or `sdtk-wiki atlas` for canonical SDTK-WIKI work | Local `.sdtk/atlas` compatibility graph or `.sdtk/wiki` SDTK-WIKI result |
77
+ | Question about existing project knowledge or docs | `sdtk-wiki search` (free) or `sdtk-wiki ask` when available | Grounded answer citing project pages before any repo-wide scan |
64
78
  | SDTK-WIKI Ask | `sdtk-wiki ask` | Grounded answer when `.sdtk/wiki/graph` plus `wiki.ask` entitlement/runtime preconditions are present, otherwise explicit blocker |
65
79
  | Existing project scan: project ingest, project refresh, or project audit | Matching premium project workflow | Project-local foundation, refresh, or audit result without overclaiming entitlement |
80
+ | Multi-step durable workflow: 3+ dependent steps, human gates between steps, must survive a pause, or spans multiple lanes/sessions | Propose `sdtk-agent` orchestration (opt-in, token-aware, see the orchestration cost gate in section 5) | `.sdtk/agent-runtime/runs/<run_id>/` ledger plus `reports/final_report.md` |
66
81
  | "what should we do next" | Orchestrator state review | Recommended next action with rationale and lane choice |
67
82
 
68
83
  Guardrails:
@@ -78,6 +93,7 @@ Ask clarification when:
78
93
  3. the target repo, project, or path is missing
79
94
  4. implementation is requested without an acceptance boundary
80
95
  5. the next command could mutate external state
96
+ 6. the next step would spawn multiple sub-agents or incur significant token cost, such as dispatching an `sdtk-agent` run
81
97
 
82
98
  Proceed when:
83
99
  1. the intent and target are clear
@@ -85,6 +101,16 @@ Proceed when:
85
101
  3. the user already approved the relevant plan or spec
86
102
  4. the requested change is bounded and verifiable
87
103
 
104
+ ### 5.1) Orchestration Cost Gate (sdtk-agent)
105
+ `sdtk-agent` chains multiple steps and dispatches each ready task through an adapter, so a single run can spawn many sub-agents and consume significant token budget. Because of that cost, orchestration is always opt-in:
106
+
107
+ 1. Never auto-start an `sdtk-agent` run on the user's behalf. Only propose it.
108
+ 2. Propose only when a routing trigger is hit (the multi-step row in section 4) and the workflow clears the minimum size (default: 3 dependent steps). One- or two-step bounded tasks route straight to a lane instead of orchestration.
109
+ 3. When proposing, state the trade-off concretely and let the user decide, defaulting to "no / run inline". Run `sdtk-agent workflow validate` first (it does not spawn anything) to count tasks, human gates, and adapter dispatches, then quote a cost band: dispatch count 3 or fewer is Low, 4-8 is Medium, more than 8 or any loop/retry is High. Example:
110
+ > This request fits sdtk-agent: durable, resumable, with hard approval gates, but it will spawn several agents and cost more tokens than an inline run. Estimate: 9 steps, 3 gates, 11 dispatches (token cost: HIGH). Use sdtk-agent for this, or run it inline? (default: inline)
111
+ 4. `run start` only creates the ledger and never spawns; treat it as the safe preview point. Dispatch happens on `run continue`, which is an explicit user action. Before a `run continue` that would dispatch several ready tasks at once, report how many tasks and which adapters are about to run, and let the user confirm or step through one task at a time.
112
+ 5. Honor `.sdtk/agent-runtime/config.json` `orchestration.confirmationMode` (`always` by default): no mode ever allows dispatch without at least one confirmation per run.
113
+
88
114
  ## 6) Clarification Protocol
89
115
  Apply for all roles (`/pm`, `/ba`, `/arch`, `/dev`, `/qa`):
90
116
  1. If there is ambiguity or missing data, log `Open Questions` as `OQ-xx` in the current phase artifact.
@@ -122,6 +148,9 @@ Use the suite products according to task intent:
122
148
  - requirements, BA, PRD, backlog, architecture, QA artifacts
123
149
  - handoff generation and release-gate traceability
124
150
  - entry: `/orchestrator` (recommended), `/pm`, `/ba`, `/arch`, `/dev`, `/qa`
151
+ - `SDTK-DESIGN`
152
+ - screen/layout design, visual tokens, prototype evidence, design handoff before coding
153
+ - use before `SDTK-CODE` when implementation needs reviewable screens or a design handoff
125
154
  - `SDTK-CODE`
126
155
  - build a feature
127
156
  - fix a bug
@@ -138,6 +167,18 @@ Use the suite products according to task intent:
138
167
  - monitoring, incident response, security-infra, backup, compliance
139
168
  - entry: `ops-discover` (when boundary is unclear), `ops-plan`, `ops-deploy`, `ops-incident`, `ops-monitor`, `ops-backup`, `ops-verify`, `ops-debug`
140
169
 
170
+ Cross-cutting capabilities (not a linear lane; usable across every phase):
171
+
172
+ - `SDTK-WIKI` (memory)
173
+ - project knowledge graph, docs view, and grounded `sdtk-wiki ask`
174
+ - any lane may read from it for recall; build with `sdtk-wiki atlas build`
175
+ - `SDTK-AGENT` (orchestration)
176
+ - a durable, file-driven DAG controller that sits above `sdtk-code` agent-team; it does not own a phase, it chains steps across lanes
177
+ - surface: `sdtk-agent run start|continue|status|report`, `gate approve|reject`, `workflow validate`, `adapter hermes-kanban plan`
178
+ - use only when a workflow has 3+ dependent steps, needs human gates between steps, or must survive a pause; otherwise route straight to a lane
179
+ - opt-in and token-aware: always propose-then-confirm before dispatch (see the orchestration cost gate in section 5)
180
+ - the CLI is runtime-neutral and installs no skills; the engine is Free; the hermes-kanban adapter defaults to dry-run and live dispatch stays fail-closed behind explicit configuration plus per-run confirmation
181
+
141
182
  If the current project only has `SDTK-SPEC` runtime assets installed:
142
183
  - keep `/dev` bounded to planning and `CODE_HANDOFF`
143
184
  - do not overclaim that SDTK-CODE or SDTK-OPS runtime assets are already installed
@@ -156,6 +197,8 @@ If the current project only has `SDTK-SPEC` runtime assets installed:
156
197
  - For SDTK-SPEC-only installs: keep `/dev` bounded to planning and `CODE_HANDOFF`; do not claim SDTK-CODE or SDTK-OPS are installed.
157
198
  - For Codex runtimes: project-local skills require the explicit local `CODEX_HOME=<project>/.codex` contract; native `.codex/skills` auto-discovery is not claimed.
158
199
  - Use `ops-parallel` or `code-parallel` only for truly independent slices. If parallel dispatch is unavailable in the active runtime, execute them sequentially in one controller session.
200
+ - `SDTK-AGENT` is runtime-neutral: it installs no skills and behaves identically on Claude and Codex. It is CLI-only, so do not invent a slash command for it.
201
+ - The `sdtk-agent` hermes-kanban adapter defaults to dry-run. Live dispatch exists but is fail-closed behind explicit adapter configuration (`mode: live` plus `live_ack`) and a per-run `--confirm`, and it remains an attended, validation-gated capability. Never claim, enable, or attempt live dispatch on the user's behalf.
159
202
 
160
203
  ## 11) Discovery And PM Readiness
161
204
  - PM initiation starts only after `docs/discovery/REQUIREMENT_[FEATURE_KEY].md` is marked `READY_FOR_PM_INITIATION`.
@@ -1,6 +1,39 @@
1
1
  {
2
- "toolkit": "SDTK-OPS",
3
- "version": "1.0.0",
4
- "skills_path": "toolkit/skills",
5
- "skill_prefix": "ops-"
2
+ "schemaVersion": 1,
3
+ "docs": {
4
+ "artifactsLanguage": "EN",
5
+ "guidanceLanguage": "EN",
6
+ "preserveOriginalInput": true,
7
+ "appendixIncludeEnglishTranslation": true,
8
+ "aiPeerReviewAllowed": true
9
+ },
10
+ "orchestration": {
11
+ "apiDesignDetailMode": "auto",
12
+ "testCaseSpecMode": "auto"
13
+ },
14
+ "stack": {
15
+ "backend": "Set your backend stack (example: Python Django REST Framework)",
16
+ "frontend": "Set your frontend stack (example: React + Vite)",
17
+ "mobile": "N/A",
18
+ "database": "Set your database (example: PostgreSQL 15)",
19
+ "auth": "Set your auth strategy (example: JWT/OAuth2)",
20
+ "detection": {
21
+ "language": null,
22
+ "framework": null,
23
+ "frameworkVersion": null,
24
+ "packageManager": null,
25
+ "confidence": "low",
26
+ "evidence": [],
27
+ "detectedAt": null,
28
+ "method": "static"
29
+ }
30
+ },
31
+ "commands": {
32
+ "backendTests": "UPDATE_ME: set backend test command",
33
+ "backendTypecheck": "UPDATE_ME: set backend typecheck command",
34
+ "backendLint": "UPDATE_ME: set backend lint command",
35
+ "frontendTests": "UPDATE_ME: set frontend test command",
36
+ "frontendLint": "UPDATE_ME: set frontend lint command",
37
+ "e2eTests": "UPDATE_ME: set e2e test command"
38
+ }
6
39
  }
@@ -1,12 +1,71 @@
1
1
  {
2
- "$comment": "Example profiles config for SDTK-OPS. Copy to sdtk-spec.config.profiles.json and customize for your runtime targets.",
3
2
  "profiles": {
4
- "default": {
3
+ "php-laravel": {
4
+ "orchestration": {
5
+ "apiDesignDetailMode": "auto",
6
+ "testCaseSpecMode": "auto"
7
+ },
5
8
  "stack": {
6
- "backend": "UPDATE_ME",
7
- "frontend": "UPDATE_ME",
8
- "database": "UPDATE_ME"
9
+ "backend": "PHP 8.3 + Laravel 11",
10
+ "frontend": "Blade + Vite (or Livewire)",
11
+ "mobile": "N/A",
12
+ "database": "MySQL 8",
13
+ "auth": "Laravel Sanctum"
14
+ },
15
+ "commands": {
16
+ "backendTests": "php artisan test",
17
+ "backendTypecheck": "vendor/bin/phpstan analyse",
18
+ "backendLint": "vendor/bin/pint --test",
19
+ "frontendTests": "npm run test",
20
+ "frontendLint": "npm run lint",
21
+ "e2eTests": "npm run e2e"
22
+ }
23
+ },
24
+ "django-react": {
25
+ "orchestration": {
26
+ "apiDesignDetailMode": "auto",
27
+ "testCaseSpecMode": "auto"
28
+ },
29
+ "stack": {
30
+ "backend": "Python 3.11 + Django 4.x + Django REST Framework",
31
+ "frontend": "React 18 + Vite",
32
+ "mobile": "N/A",
33
+ "database": "PostgreSQL 15",
34
+ "auth": "JWT"
35
+ },
36
+ "commands": {
37
+ "backendTests": "python -m pytest",
38
+ "backendTypecheck": "python -m mypy src/backend",
39
+ "backendLint": "python -m ruff check src/backend",
40
+ "frontendTests": "npm run test",
41
+ "frontendLint": "npm run lint",
42
+ "e2eTests": "npm run e2e"
43
+ }
44
+ },
45
+ "node-nextjs": {
46
+ "orchestration": {
47
+ "apiDesignDetailMode": "auto",
48
+ "testCaseSpecMode": "auto"
49
+ },
50
+ "stack": {
51
+ "backend": "Node.js 20 + Express/Fastify",
52
+ "frontend": "Next.js 14",
53
+ "mobile": "N/A",
54
+ "database": "PostgreSQL 15",
55
+ "auth": "OAuth2 + JWT"
56
+ },
57
+ "commands": {
58
+ "backendTests": "npm run test:api",
59
+ "backendTypecheck": "npm run typecheck:api",
60
+ "backendLint": "npm run lint:api",
61
+ "frontendTests": "npm run test:web",
62
+ "frontendLint": "npm run lint:web",
63
+ "e2eTests": "npm run test:e2e"
9
64
  }
10
65
  }
11
- }
66
+ },
67
+ "notes": [
68
+ "Copy one profile into sdtk-spec.config.json and adjust for your project.",
69
+ "Do not keep UPDATE_ME placeholders before running real delivery gates."
70
+ ]
12
71
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "sdtk-ops-kit",
3
- "version": "0.2.5",
3
+ "version": "0.2.8",
4
4
  "description": "Skill-driven operations toolkit for deployment, verification, monitoring, incident response, backup, security, compliance, and cost discipline.",
5
5
  "bin": {
6
6
  "sdtk-ops": "bin/sdtk-ops.js"