sdtk-ops-kit 0.2.4 → 0.2.6

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.
@@ -1,203 +1,203 @@
1
- # Software Development Toolkit - Operations (SDTK-OPS)
2
-
3
- ## Document Role
4
- This file is the architecture and product-boundary document for `SDTK-OPS`.
5
-
6
- Use this file to understand:
7
- - how `SDTK-OPS` fits inside the `SDTK-SPEC -> SDTK-CODE -> SDTK-OPS` family
8
- - what the current skill-driven entry model owns
9
- - which journeys are canonical in the current wave
10
- - what stays outside `SDTK-OPS` scope
11
-
12
- Do not use this file as the primary install or onboarding guide.
13
-
14
- Canonical end-user guide:
15
- - `products/sdtk-ops/governance/SDTKOPS_TOOLKIT_USAGE_GUIDE.md`
16
-
17
- ## 1. Overview
18
-
19
- `SDTK-OPS` is the operations-process product in the `SDTK-SPEC -> SDTK-CODE -> SDTK-OPS` family.
20
-
21
- It is not a workflow-first CLI like `SDTK-CODE`.
22
-
23
- The truthful current CLI surface is:
24
- - `sdtk-ops help`
25
- - `sdtk-ops init`
26
- - `sdtk-ops runtime install`
27
- - `sdtk-ops runtime status`
28
- - `sdtk-ops runtime uninstall`
29
-
30
- The current public package is:
31
- - `sdtk-ops-kit`
32
- - CLI command: `sdtk-ops`
33
- - Latest published version lookup: `npm view sdtk-ops-kit version`
34
-
35
- The truthful current operational surface after `init` is skill-driven:
36
- - the 15 `ops-*` skills remain the real operating surface
37
- - `ops-discover` remains a skill, not a CLI command
38
- - `ops-verify` remains the required closing skill for every canonical journey
39
- - `generate` remains unsupported and deferred
40
-
41
- ## 2. Boundary With SDTK-SPEC And SDTK-CODE
42
-
43
- `SDTK-SPEC` is upstream and remains the docs-first specification and handoff system.
44
-
45
- `SDTK-SPEC` owns:
46
- - specification and handoff generation
47
- - PM, BA, ARCH, DEV, and QA orchestration
48
- - upstream workflow contracts and design artifacts
49
-
50
- `SDTK-CODE` owns:
51
- - coding-process execution after handoff
52
- - workflow-first build, verify, and closeout discipline
53
- - implementation evidence for the coded slice
54
-
55
- `SDTK-OPS` owns:
56
- - operational planning and deployment discipline
57
- - environment/runtime validation
58
- - monitoring, incident response, and backup or recovery execution
59
- - infrastructure security, compliance, and cost work when those are the active concern
60
-
61
- `SDTK-OPS` does not own:
62
- - upstream requirements or architecture generation
63
- - coding workflow execution
64
- - provider-specific platform packs in the current wave
65
- - broader launch marketing claims beyond the current public package
66
-
67
- ## 3. DEV-Run Intake Contract
68
-
69
- `DEV-Run` is executed via `SDTK-OPS`.
70
-
71
- When `DEV-Run` begins from coded scope, the only canonical `CODE -> OPS` bridge artifact is:
72
- - `docs/dev/OPS_HANDOFF_[FEATURE_KEY].json`
73
-
74
- `SDTK-OPS` reads that frozen contract as input.
75
- It does not redefine the schema, rename fields, move the file, or silently normalize producer output into a different contract.
76
-
77
- Ready-path intake rules:
78
- - inspect `handoff_status` first
79
- - if `handoff_status` is `READY_FOR_SDTK_OPS`, start with `suggested_next_ops_path.start_with` unless fresh evidence requires a bounded reroute
80
- - treat `suggested_next_ops_path.suggested_chain` as the default first routing sequence
81
- - close with `suggested_next_ops_path.close_with`, which should normally be `ops-verify`
82
-
83
- Blocked-path intake rules:
84
- - if `handoff_status` is `BLOCKED_FOR_SDTK_OPS`, the handoff is still inspectable
85
- - inspect `open_blockers`, `code_evidence_refs`, and the prerequisite fields before choosing any action
86
- - do not treat blocked handoff state as normal ready-path execution
87
- - use `ops-discover` to select bounded triage or clarification only when blocker text supports that path
88
-
89
- Bounded OPS evidence expectations in this wave:
90
- - record the consumed handoff path and `handoff_status`
91
- - record the selected first OPS step and whether it followed or overrode `suggested_next_ops_path`
92
- - record checked prerequisites, assumptions, dependencies, observability requirements, and rollback or recovery expectations
93
- - record journey-specific operational evidence for the scoped OPS work
94
- - record final `ops-verify` closeout evidence
95
-
96
- This wave does not define a final OPS evidence schema and does not implement QA bridge logic.
97
-
98
- ## 4. Entry And Routing Model
99
-
100
- After `sdtk-ops init`, choose a journey directly when the goal is clear.
101
-
102
- If the correct path is unclear:
103
- - start with `ops-discover`
104
-
105
- Always:
106
- - close every canonical journey with `ops-verify`
107
- - keep `generate` out of the documented command path
108
-
109
- | Journey | Start With | Suggested Chain | Close With |
110
- |---------|------------|-----------------|------------|
111
- | Deployment | `ops-plan` | `ops-plan` -> `ops-infra-plan` -> `ops-container` -> `ops-ci-cd` -> `ops-deploy` -> `ops-monitor` | `ops-verify` |
112
- | Incident | `ops-incident` | `ops-incident` -> `ops-debug` -> `ops-deploy` if a change or rollback is required -> `ops-monitor` | `ops-verify` |
113
- | Monitoring | `ops-plan` | `ops-plan` -> `ops-monitor` | `ops-verify` |
114
- | Backup or recovery | `ops-plan` | `ops-plan` -> `ops-backup` | `ops-verify` |
115
-
116
- Other valid but non-primary routed skills in this wave:
117
- - `ops-security-infra`
118
- - `ops-compliance`
119
- - `ops-cost`
120
- - `ops-parallel`
121
-
122
- ## 5. Skill Catalog
123
-
124
- ### 5.1 Core Process
125
-
126
- | Skill | Purpose |
127
- |-------|---------|
128
- | `ops-verify` | verify commands, state, and evidence before declaring work complete |
129
- | `ops-debug` | diagnose operational failures systematically and trace root cause |
130
- | `ops-plan` | write reviewable operational plans with rollback and verification steps |
131
- | `ops-parallel` | split truly independent operations tasks into parallel workstreams |
132
-
133
- ### 5.2 Deployment
134
-
135
- | Skill | Purpose |
136
- |-------|---------|
137
- | `ops-infra-plan` | design infrastructure architecture and provisioning order before apply |
138
- | `ops-deploy` | execute deployments with health gates, rollout strategy, and rollback discipline |
139
- | `ops-container` | define secure image build and container orchestration patterns |
140
- | `ops-ci-cd` | build and manage pipelines, promotion flow, artifact handling, and secret controls |
141
-
142
- ### 5.3 Operations
143
-
144
- | Skill | Purpose |
145
- |-------|---------|
146
- | `ops-monitor` | define SLOs, alerts, dashboards, logs, and traces |
147
- | `ops-incident` | coordinate incident response, stabilization, and post-mortem follow-up |
148
- | `ops-backup` | design backup, restore, and disaster recovery procedures |
149
- | `ops-cost` | review spend, identify waste, and plan safe right-sizing |
150
-
151
- ### 5.4 Security And Compliance
152
-
153
- | Skill | Purpose |
154
- |-------|---------|
155
- | `ops-security-infra` | harden infrastructure, secrets, network policy, and security scanning |
156
- | `ops-compliance` | automate audit readiness, evidence collection, retention, and policy enforcement |
157
-
158
- ### 5.5 Discovery
159
-
160
- | Skill | Purpose |
161
- |-------|---------|
162
- | `ops-discover` | choose the correct SDTK-OPS entry point and sequencing |
163
-
164
- ## 6. Runtime Truth
165
-
166
- ### Claude
167
- - supports project and user scope
168
- - default scope is project
169
- - uses the `ops-*` runtime payload after install
170
-
171
- ### Codex
172
- - defaults to user scope
173
- - default scope is user
174
- - uses collision-avoiding `sdtk-ops-*` skill directory names
175
- - supports project-local installs only through the explicit local `CODEX_HOME=<project>/.codex` contract
176
- - native `.codex/skills` auto-discovery is not claimed
177
-
178
- ## 7. Documentation Map
179
-
180
- Use these documents by role:
181
-
182
- - Canonical end-user install and usage guide:
183
- - `products/sdtk-ops/governance/SDTKOPS_TOOLKIT_USAGE_GUIDE.md`
184
- - Install-truth and smoke appendix:
185
- - `products/sdtk-ops/governance/installation-runbook.md`
186
- - Workflow-entry and reference stub:
187
- - `products/sdtk-ops/governance/usage-guide.md`
188
- - Package landing page:
189
- - `products/sdtk-ops/distribution/sdtk-ops-kit/README.md`
190
- - Runtime routing inventory:
191
- - `products/sdtk-ops/toolkit/AGENTS.md`
192
- - Release docs:
193
- - `products/sdtk-ops/governance/release-packaging.md`
194
- - `products/sdtk-ops/governance/release-evidence.md`
195
-
196
- ## 8. Scope
197
-
198
- `SDTK-OPS` v1 contains 15 core skills and stays cloud-agnostic.
199
-
200
- Not part of the current supported wave:
201
- - provider-specific packs such as AWS, GCP, or Azure variants
202
- - a workflow-first CLI command suite such as `sdtk-ops deploy`
203
- - cloud, Kubernetes, or production-topology guarantees beyond the current validated local Docker proof
1
+ # Software Development Toolkit - Operations (SDTK-OPS)
2
+
3
+ ## Document Role
4
+ This file is the architecture and product-boundary document for `SDTK-OPS`.
5
+
6
+ Use this file to understand:
7
+ - how `SDTK-OPS` fits inside the `SDTK-SPEC -> SDTK-CODE -> SDTK-OPS` family
8
+ - what the current skill-driven entry model owns
9
+ - which journeys are canonical in the current wave
10
+ - what stays outside `SDTK-OPS` scope
11
+
12
+ Do not use this file as the primary install or onboarding guide.
13
+
14
+ Canonical end-user guide:
15
+ - `products/sdtk-ops/governance/SDTKOPS_TOOLKIT_USAGE_GUIDE.md`
16
+
17
+ ## 1. Overview
18
+
19
+ `SDTK-OPS` is the operations-process product in the `SDTK-SPEC -> SDTK-CODE -> SDTK-OPS` family.
20
+
21
+ It is not a workflow-first CLI like `SDTK-CODE`.
22
+
23
+ The truthful current CLI surface is:
24
+ - `sdtk-ops help`
25
+ - `sdtk-ops init`
26
+ - `sdtk-ops runtime install`
27
+ - `sdtk-ops runtime status`
28
+ - `sdtk-ops runtime uninstall`
29
+
30
+ The current public package is:
31
+ - `sdtk-ops-kit`
32
+ - CLI command: `sdtk-ops`
33
+ - Latest published version lookup: `npm view sdtk-ops-kit version`
34
+
35
+ The truthful current operational surface after `init` is skill-driven:
36
+ - the 15 `ops-*` skills remain the real operating surface
37
+ - `ops-discover` remains a skill, not a CLI command
38
+ - `ops-verify` remains the required closing skill for every canonical journey
39
+ - `generate` remains unsupported and deferred
40
+
41
+ ## 2. Boundary With SDTK-SPEC And SDTK-CODE
42
+
43
+ `SDTK-SPEC` is upstream and remains the docs-first specification and handoff system.
44
+
45
+ `SDTK-SPEC` owns:
46
+ - specification and handoff generation
47
+ - PM, BA, ARCH, DEV, and QA orchestration
48
+ - upstream workflow contracts and design artifacts
49
+
50
+ `SDTK-CODE` owns:
51
+ - coding-process execution after handoff
52
+ - workflow-first build, verify, and closeout discipline
53
+ - implementation evidence for the coded slice
54
+
55
+ `SDTK-OPS` owns:
56
+ - operational planning and deployment discipline
57
+ - environment/runtime validation
58
+ - monitoring, incident response, and backup or recovery execution
59
+ - infrastructure security, compliance, and cost work when those are the active concern
60
+
61
+ `SDTK-OPS` does not own:
62
+ - upstream requirements or architecture generation
63
+ - coding workflow execution
64
+ - provider-specific platform packs in the current wave
65
+ - broader launch marketing claims beyond the current public package
66
+
67
+ ## 3. DEV-Run Intake Contract
68
+
69
+ `DEV-Run` is executed via `SDTK-OPS`.
70
+
71
+ When `DEV-Run` begins from coded scope, the only canonical `CODE -> OPS` bridge artifact is:
72
+ - `docs/dev/OPS_HANDOFF_[FEATURE_KEY].json`
73
+
74
+ `SDTK-OPS` reads that frozen contract as input.
75
+ It does not redefine the schema, rename fields, move the file, or silently normalize producer output into a different contract.
76
+
77
+ Ready-path intake rules:
78
+ - inspect `handoff_status` first
79
+ - if `handoff_status` is `READY_FOR_SDTK_OPS`, start with `suggested_next_ops_path.start_with` unless fresh evidence requires a bounded reroute
80
+ - treat `suggested_next_ops_path.suggested_chain` as the default first routing sequence
81
+ - close with `suggested_next_ops_path.close_with`, which should normally be `ops-verify`
82
+
83
+ Blocked-path intake rules:
84
+ - if `handoff_status` is `BLOCKED_FOR_SDTK_OPS`, the handoff is still inspectable
85
+ - inspect `open_blockers`, `code_evidence_refs`, and the prerequisite fields before choosing any action
86
+ - do not treat blocked handoff state as normal ready-path execution
87
+ - use `ops-discover` to select bounded triage or clarification only when blocker text supports that path
88
+
89
+ Bounded OPS evidence expectations in this wave:
90
+ - record the consumed handoff path and `handoff_status`
91
+ - record the selected first OPS step and whether it followed or overrode `suggested_next_ops_path`
92
+ - record checked prerequisites, assumptions, dependencies, observability requirements, and rollback or recovery expectations
93
+ - record journey-specific operational evidence for the scoped OPS work
94
+ - record final `ops-verify` closeout evidence
95
+
96
+ This wave does not define a final OPS evidence schema and does not implement QA bridge logic.
97
+
98
+ ## 4. Entry And Routing Model
99
+
100
+ After `sdtk-ops init`, choose a journey directly when the goal is clear.
101
+
102
+ If the correct path is unclear:
103
+ - start with `ops-discover`
104
+
105
+ Always:
106
+ - close every canonical journey with `ops-verify`
107
+ - keep `generate` out of the documented command path
108
+
109
+ | Journey | Start With | Suggested Chain | Close With |
110
+ |---------|------------|-----------------|------------|
111
+ | Deployment | `ops-plan` | `ops-plan` -> `ops-infra-plan` -> `ops-container` -> `ops-ci-cd` -> `ops-deploy` -> `ops-monitor` | `ops-verify` |
112
+ | Incident | `ops-incident` | `ops-incident` -> `ops-debug` -> `ops-deploy` if a change or rollback is required -> `ops-monitor` | `ops-verify` |
113
+ | Monitoring | `ops-plan` | `ops-plan` -> `ops-monitor` | `ops-verify` |
114
+ | Backup or recovery | `ops-plan` | `ops-plan` -> `ops-backup` | `ops-verify` |
115
+
116
+ Other valid but non-primary routed skills in this wave:
117
+ - `ops-security-infra`
118
+ - `ops-compliance`
119
+ - `ops-cost`
120
+ - `ops-parallel`
121
+
122
+ ## 5. Skill Catalog
123
+
124
+ ### 5.1 Core Process
125
+
126
+ | Skill | Purpose |
127
+ |-------|---------|
128
+ | `ops-verify` | verify commands, state, and evidence before declaring work complete |
129
+ | `ops-debug` | diagnose operational failures systematically and trace root cause |
130
+ | `ops-plan` | write reviewable operational plans with rollback and verification steps |
131
+ | `ops-parallel` | split truly independent operations tasks into parallel workstreams |
132
+
133
+ ### 5.2 Deployment
134
+
135
+ | Skill | Purpose |
136
+ |-------|---------|
137
+ | `ops-infra-plan` | design infrastructure architecture and provisioning order before apply |
138
+ | `ops-deploy` | execute deployments with health gates, rollout strategy, and rollback discipline |
139
+ | `ops-container` | define secure image build and container orchestration patterns |
140
+ | `ops-ci-cd` | build and manage pipelines, promotion flow, artifact handling, and secret controls |
141
+
142
+ ### 5.3 Operations
143
+
144
+ | Skill | Purpose |
145
+ |-------|---------|
146
+ | `ops-monitor` | define SLOs, alerts, dashboards, logs, and traces |
147
+ | `ops-incident` | coordinate incident response, stabilization, and post-mortem follow-up |
148
+ | `ops-backup` | design backup, restore, and disaster recovery procedures |
149
+ | `ops-cost` | review spend, identify waste, and plan safe right-sizing |
150
+
151
+ ### 5.4 Security And Compliance
152
+
153
+ | Skill | Purpose |
154
+ |-------|---------|
155
+ | `ops-security-infra` | harden infrastructure, secrets, network policy, and security scanning |
156
+ | `ops-compliance` | automate audit readiness, evidence collection, retention, and policy enforcement |
157
+
158
+ ### 5.5 Discovery
159
+
160
+ | Skill | Purpose |
161
+ |-------|---------|
162
+ | `ops-discover` | choose the correct SDTK-OPS entry point and sequencing |
163
+
164
+ ## 6. Runtime Truth
165
+
166
+ ### Claude
167
+ - supports project and user scope
168
+ - default scope is project
169
+ - uses the `ops-*` runtime payload after install
170
+
171
+ ### Codex
172
+ - defaults to user scope
173
+ - default scope is user
174
+ - uses collision-avoiding `sdtk-ops-*` skill directory names
175
+ - supports project-local installs only through the explicit local `CODEX_HOME=<project>/.codex` contract
176
+ - native `.codex/skills` auto-discovery is not claimed
177
+
178
+ ## 7. Documentation Map
179
+
180
+ Use these documents by role:
181
+
182
+ - Canonical end-user install and usage guide:
183
+ - `products/sdtk-ops/governance/SDTKOPS_TOOLKIT_USAGE_GUIDE.md`
184
+ - Install-truth and smoke appendix:
185
+ - `products/sdtk-ops/governance/installation-runbook.md`
186
+ - Workflow-entry and reference stub:
187
+ - `products/sdtk-ops/governance/usage-guide.md`
188
+ - Package landing page:
189
+ - `products/sdtk-ops/distribution/sdtk-ops-kit/README.md`
190
+ - Runtime routing inventory:
191
+ - `products/sdtk-ops/toolkit/AGENTS.md`
192
+ - Release docs:
193
+ - `products/sdtk-ops/governance/release-packaging.md`
194
+ - `products/sdtk-ops/governance/release-evidence.md`
195
+
196
+ ## 8. Scope
197
+
198
+ `SDTK-OPS` v1 contains 15 core skills and stays cloud-agnostic.
199
+
200
+ Not part of the current supported wave:
201
+ - provider-specific packs such as AWS, GCP, or Azure variants
202
+ - a workflow-first CLI command suite such as `sdtk-ops deploy`
203
+ - cloud, Kubernetes, or production-topology guarantees beyond the current validated local Docker proof