sdtk-ops-kit 0.2.1 → 0.2.3

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.
Files changed (43) hide show
  1. package/README.md +95 -8
  2. package/assets/manifest/toolkit-bundle.manifest.json +66 -66
  3. package/assets/manifest/toolkit-bundle.sha256.txt +32 -32
  4. package/assets/toolkit/toolkit/AGENTS.md +30 -2
  5. package/assets/toolkit/toolkit/SDTKOPS_TOOLKIT.md +203 -166
  6. package/assets/toolkit/toolkit/install.ps1 +1 -8
  7. package/assets/toolkit/toolkit/scripts/install-codex-skills.ps1 +30 -7
  8. package/assets/toolkit/toolkit/scripts/uninstall-codex-skills.ps1 +31 -2
  9. package/assets/toolkit/toolkit/sdtk-spec.config.profiles.example.json +12 -12
  10. package/assets/toolkit/toolkit/skills/ops-backup/SKILL.md +0 -2
  11. package/assets/toolkit/toolkit/skills/ops-backup/references/backup-script-patterns.md +0 -2
  12. package/assets/toolkit/toolkit/skills/ops-ci-cd/SKILL.md +0 -2
  13. package/assets/toolkit/toolkit/skills/ops-ci-cd/references/pipeline-examples.md +0 -2
  14. package/assets/toolkit/toolkit/skills/ops-container/SKILL.md +0 -2
  15. package/assets/toolkit/toolkit/skills/ops-container/references/k8s-manifest-patterns.md +0 -2
  16. package/assets/toolkit/toolkit/skills/ops-cost/SKILL.md +0 -2
  17. package/assets/toolkit/toolkit/skills/ops-debug/SKILL.md +0 -1
  18. package/assets/toolkit/toolkit/skills/ops-debug/references/root-cause-tracing.md +0 -1
  19. package/assets/toolkit/toolkit/skills/ops-deploy/SKILL.md +0 -2
  20. package/assets/toolkit/toolkit/skills/ops-discover/SKILL.md +21 -0
  21. package/assets/toolkit/toolkit/skills/ops-incident/SKILL.md +0 -2
  22. package/assets/toolkit/toolkit/skills/ops-incident/references/communication-templates.md +0 -2
  23. package/assets/toolkit/toolkit/skills/ops-incident/references/postmortem-template.md +0 -2
  24. package/assets/toolkit/toolkit/skills/ops-incident/references/runbook-template.md +0 -2
  25. package/assets/toolkit/toolkit/skills/ops-infra-plan/SKILL.md +1 -3
  26. package/assets/toolkit/toolkit/skills/ops-infra-plan/references/iac-patterns.md +0 -2
  27. package/assets/toolkit/toolkit/skills/ops-monitor/SKILL.md +0 -2
  28. package/assets/toolkit/toolkit/skills/ops-monitor/references/alert-rules.md +0 -2
  29. package/assets/toolkit/toolkit/skills/ops-monitor/references/slo-templates.md +0 -2
  30. package/assets/toolkit/toolkit/skills/ops-parallel/SKILL.md +22 -5
  31. package/assets/toolkit/toolkit/skills/ops-plan/SKILL.md +33 -1
  32. package/assets/toolkit/toolkit/skills/ops-security-infra/SKILL.md +1 -3
  33. package/assets/toolkit/toolkit/skills/ops-security-infra/references/cicd-security-pipeline.md +0 -2
  34. package/assets/toolkit/toolkit/skills/ops-security-infra/references/security-headers.md +0 -2
  35. package/assets/toolkit/toolkit/skills/ops-verify/SKILL.md +16 -1
  36. package/package.json +1 -1
  37. package/src/commands/help.js +88 -53
  38. package/src/commands/init.js +10 -1
  39. package/src/commands/runtime.js +29 -7
  40. package/src/commands/update.js +11 -0
  41. package/src/index.js +68 -65
  42. package/src/lib/scope.js +19 -2
  43. package/src/lib/update.js +337 -0
@@ -16,6 +16,25 @@ Use for:
16
16
  - unclear routing between planning, debugging, deployment, monitoring, or security
17
17
  - deciding which skill chain should run first
18
18
 
19
+ ## OPS_HANDOFF Intake
20
+
21
+ If `DEV-Run` starts from `docs/dev/OPS_HANDOFF_[FEATURE_KEY].json`, inspect the handoff before choosing the first skill.
22
+
23
+ Read these fields first:
24
+ - `handoff_status`
25
+ - `suggested_next_ops_path`
26
+ - `open_blockers`
27
+ - `code_evidence_refs`
28
+
29
+ Routing rules:
30
+ - if `handoff_status` is `READY_FOR_SDTK_OPS`, default to `suggested_next_ops_path.start_with`
31
+ - treat `suggested_next_ops_path.suggested_chain` as the default chain unless fresh evidence requires a bounded reroute
32
+ - if `handoff_status` is `BLOCKED_FOR_SDTK_OPS`, the handoff is still inspectable but not a normal ready-path execution input
33
+ - blocked handoffs should route to bounded triage or clarification only; do not silently reinterpret them as deployment-ready
34
+
35
+ `SDTK-OPS` consumes the frozen handoff contract.
36
+ It does not redefine schema fields or invent alternate handoff names or locations.
37
+
19
38
  ## Priority Order
20
39
 
21
40
  Choose in this order:
@@ -71,6 +90,8 @@ Use `ops-parallel` only when the work can safely split after the primary skill c
71
90
 
72
91
  | Situation | Suggested Chain |
73
92
  |-----------|-----------------|
93
+ | READY `OPS_HANDOFF` intake | `suggested_next_ops_path.start_with` -> `suggested_next_ops_path.suggested_chain` -> `ops-verify` |
94
+ | BLOCKED `OPS_HANDOFF` intake | inspect `open_blockers` -> bounded triage or clarification -> `ops-verify` only if a legal scoped OPS action actually runs |
74
95
  | New service rollout | `ops-infra-plan` -> `ops-container` -> `ops-ci-cd` -> `ops-deploy` -> `ops-monitor` -> `ops-verify` |
75
96
  | Production incident | `ops-incident` -> `ops-debug` -> `ops-deploy` -> `ops-verify` |
76
97
  | Backup hardening | `ops-backup` -> `ops-infra-plan` -> `ops-monitor` -> `ops-verify` |
@@ -1,4 +1,3 @@
1
- <!-- Based on agency-agents by AgentLand Contributors (MIT License, 2025). Adapted for SDTK-OPS. -->
2
1
  ---
3
2
  name: ops-incident
4
3
  description: Incident response and management. Use when a production incident occurs or when establishing incident response procedures -- covers severity classification, response coordination, post-mortem facilitation, and on-call design.
@@ -110,4 +109,3 @@ During incident response:
110
109
  - use `ops-debug` for diagnosis
111
110
  - use `ops-monitor` to confirm recovery against live signals
112
111
  - use `ops-verify` before declaring the system stable
113
-
@@ -1,4 +1,3 @@
1
- <!-- Based on agency-agents by AgentLand Contributors (MIT License, 2025). Adapted for SDTK-OPS. -->
2
1
 
3
2
  # Communication Templates
4
3
 
@@ -31,4 +30,3 @@
31
30
  **Impact Summary**: [who was affected and how]
32
31
  **Follow-up**: Post-mortem scheduled for [date]. Action items will be tracked in [link].
33
32
  ```
34
-
@@ -1,4 +1,3 @@
1
- <!-- Based on agency-agents by AgentLand Contributors (MIT License, 2025). Adapted for SDTK-OPS. -->
2
1
 
3
2
  # Postmortem Template
4
3
 
@@ -66,4 +65,3 @@
66
65
  ## Lessons Learned
67
66
  [Key takeaways that should change design, monitoring, or procedure]
68
67
  ```
69
-
@@ -1,4 +1,3 @@
1
- <!-- Based on agency-agents by AgentLand Contributors (MIT License, 2025). Adapted for SDTK-OPS. -->
2
1
 
3
2
  # Incident Runbook Template
4
3
 
@@ -66,4 +65,3 @@
66
65
  - External: [status page or customer update path]
67
66
  - Follow-up: Create post-mortem within 48 hours
68
67
  ```
69
-
@@ -1,4 +1,3 @@
1
- <!-- Based on agency-agents by AgentLand Contributors (MIT License, 2025) and gstack by Garry Tan (MIT License, 2026). Adapted for SDTK-OPS. -->
2
1
  ---
3
2
  name: ops-infra-plan
4
3
  description: Infrastructure architecture planning. Use when designing cloud resources, networking, security groups, IAM policies, or IaC modules -- produces a reviewable infrastructure plan before provisioning.
@@ -83,7 +82,7 @@ Prefer reusable modules and explicit inputs over hand-built resources. Common pa
83
82
  - alarms and dashboards defined in the same plan as the resource they guard
84
83
  - environment-specific values separated from reusable module logic
85
84
 
86
- Use `./references/iac-patterns.md` for concrete Terraform-style examples adapted from the source material.
85
+ Use `./references/iac-patterns.md` for concrete Terraform-style examples.
87
86
 
88
87
  ## Review Checklist
89
88
 
@@ -120,4 +119,3 @@ After the plan is approved:
120
119
  - provision in dependency order
121
120
  - verify each applied layer before moving forward
122
121
  - use `ops-verify` before marking any provisioning step complete
123
-
@@ -1,4 +1,3 @@
1
- <!-- Based on agency-agents by AgentLand Contributors (MIT License, 2025) and gstack by Garry Tan (MIT License, 2026). Adapted for SDTK-OPS. -->
2
1
 
3
2
  # IaC Patterns
4
3
 
@@ -138,4 +137,3 @@ Before applying an IaC change, confirm:
138
137
  - network, identity, and secret dependencies are listed
139
138
  - rollback covers both failed create and partial update
140
139
  - health checks, alarms, and backups are defined with the resource
141
-
@@ -1,4 +1,3 @@
1
- <!-- Based on agency-agents by AgentLand Contributors (MIT License, 2025). Adapted for SDTK-OPS. -->
2
1
  ---
3
2
  name: ops-monitor
4
3
  description: Observability and monitoring setup. Use when designing monitoring, defining SLOs/SLIs, configuring alerts, or building dashboards -- covers the three pillars of observability and Golden Signals framework.
@@ -107,4 +106,3 @@ After monitoring is defined:
107
106
  - route incident handling through `ops-incident`
108
107
  - use `ops-debug` for root-cause investigation
109
108
  - use `ops-verify` before claiming monitoring coverage is complete
110
-
@@ -1,4 +1,3 @@
1
- <!-- Based on agency-agents by AgentLand Contributors (MIT License, 2025). Adapted for SDTK-OPS. -->
2
1
 
3
2
  # Alert Rules
4
3
 
@@ -77,4 +76,3 @@ groups:
77
76
  - attach a runbook to every page-worthy alert
78
77
  - use warning and critical levels where the system benefits from early warning
79
78
  - deduplicate rules that describe the same symptom
80
-
@@ -1,4 +1,3 @@
1
- <!-- Based on agency-agents by AgentLand Contributors (MIT License, 2025). Adapted for SDTK-OPS. -->
2
1
 
3
2
  # SLO Templates
4
3
 
@@ -80,4 +79,3 @@ Before approving an SLO definition, confirm:
80
79
  - the window is explicit
81
80
  - burn-rate alerts exist for fast and slow budget exhaustion
82
81
  - the team can explain what action follows each budget state
83
-
@@ -1,4 +1,3 @@
1
- <!-- Based on superpowers by Jesse Vincent (MIT License, 2025). Adapted for SDTK-OPS. -->
2
1
  ---
3
2
  name: ops-parallel
4
3
  description: Parallel operations dispatch. Use when facing 2+ independent infrastructure tasks that can be worked on without shared state or sequential dependencies.
@@ -6,13 +5,31 @@ description: Parallel operations dispatch. Use when facing 2+ independent infras
6
5
 
7
6
  # Ops Parallel
8
7
 
8
+ ## Critical Constraints
9
+
10
+ - I do not assume collaboration or subagent dispatch is available in every runtime.
11
+ - If the runtime cannot dispatch helpers in parallel, I keep the same task decomposition but execute the slices sequentially in one controller session.
12
+ - I do not describe sequential fallback as real parallel execution.
13
+
9
14
  ## Overview
10
15
 
11
- You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history. You construct exactly what they need. This also preserves your own context for coordination work.
16
+ When runtime support exists, you can delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you keep each slice focused and reviewable. When runtime support does not exist, keep the same slice boundaries and execute them sequentially instead of pretending the environment supports real parallel dispatch.
12
17
 
13
18
  When you have multiple unrelated operational problems or task slices, investigating them sequentially wastes time. Each investigation is independent and can happen in parallel.
14
19
 
15
- **Core principle:** Dispatch one agent per independent problem domain. Let them work concurrently.
20
+ **Core principle:** Keep one isolated slice per independent problem domain, then execute those slices concurrently only when the runtime actually supports it.
21
+
22
+ ## Runtime Fallback Note
23
+
24
+ Current SDTK truth treats helper-dispatch availability as environment-dependent and does not guarantee parallel helper dispatch in every environment.
25
+
26
+ If collaboration or subagent dispatch is unavailable:
27
+ - keep the same independence test
28
+ - prepare the same focused task slices
29
+ - execute those slices sequentially in one controller session
30
+ - preserve the same verification and fan-in discipline
31
+
32
+ Do not claim runtime parity or actual concurrent dispatch when the environment only supports sequential execution.
16
33
 
17
34
  ## When to Use
18
35
 
@@ -64,7 +81,7 @@ Each agent gets:
64
81
  - **Constraints:** do not change unrelated code or infrastructure
65
82
  - **Expected output:** summary of what was found and what changed
66
83
 
67
- ### 3. Dispatch in Parallel
84
+ ### 3. Dispatch or Execute the Slices
68
85
 
69
86
  ```text
70
87
  Task("Tune monitoring alerts for checkout service")
@@ -72,7 +89,7 @@ Task("Fix CI deployment gate for staging rollouts")
72
89
  Task("Update backup retention procedure and verification notes")
73
90
  ```
74
91
 
75
- All three run concurrently.
92
+ If runtime dispatch is available, all three can run concurrently. Otherwise execute the three slices sequentially with the same scope boundaries and verification plan.
76
93
 
77
94
  ### 4. Review and Integrate
78
95
 
@@ -1,4 +1,3 @@
1
- <!-- Based on superpowers by Jesse Vincent (MIT License, 2025) and gstack by Garry Tan (MIT License, 2026). Adapted for SDTK-OPS. -->
2
1
  ---
3
2
  name: ops-plan
4
3
  description: Infrastructure and operations planning. Use when planning infrastructure changes, deployment strategies, or operational procedures before execution -- numbered steps, dependency ordering, rollback strategy per step.
@@ -21,6 +20,28 @@ Challenge scope before planning:
21
20
  - What is the minimum change that achieves the goal safely?
22
21
  - Which work is required now, and which work can be deferred?
23
22
 
23
+ ## OPS_HANDOFF Intake Rules
24
+
25
+ When the work enters `DEV-Run` through `docs/dev/OPS_HANDOFF_[FEATURE_KEY].json`, consume the frozen handoff contract as-is.
26
+
27
+ Read these fields before planning:
28
+ - `handoff_status`
29
+ - `scope_slices`
30
+ - `code_evidence_refs`
31
+ - `deployment_prerequisites`
32
+ - `environment_assumptions`
33
+ - `infra_runtime_dependencies`
34
+ - `observability_requirements`
35
+ - `rollback_recovery_expectations`
36
+ - `open_blockers`
37
+ - `suggested_next_ops_path`
38
+
39
+ Planning rules:
40
+ - if `handoff_status` is `READY_FOR_SDTK_OPS`, the first planned step should normally align to `suggested_next_ops_path.start_with`
41
+ - if `handoff_status` is `BLOCKED_FOR_SDTK_OPS`, do not write a normal ready-path execution plan
42
+ - a blocked handoff may still receive a bounded triage or clarification plan, but that plan must keep the blocker state explicit
43
+ - do not redefine field names, rename the artifact, or patch the handoff schema downstream
44
+
24
45
  ## File Structure And Affected Systems
25
46
 
26
47
  Before defining tasks, map out what will be created or modified and what each item owns.
@@ -159,6 +180,17 @@ Use this shape for each task:
159
180
  | Verification only at the end | You lose the exact step where the system broke |
160
181
  | Migration plan ignores backward compatibility | Deploy succeeds but runtime traffic fails |
161
182
 
183
+ ## Minimum OPS Evidence Expectations
184
+
185
+ This wave does not define a final OPS evidence schema, but plans derived from `OPS_HANDOFF` must keep these evidence expectations explicit:
186
+ - record the consumed handoff path and `handoff_status`
187
+ - record whether the first OPS step followed or overrode `suggested_next_ops_path`, and why
188
+ - record which prerequisites, assumptions, dependencies, observability requirements, and rollback or recovery expectations were checked
189
+ - record journey-specific operational evidence for the scoped work
190
+ - record final `ops-verify` closeout evidence
191
+
192
+ Do not invent QA bridge fields or a new formal OPS artifact schema in this step.
193
+
162
194
  ## Execution Handoff
163
195
 
164
196
  After saving the plan:
@@ -1,4 +1,3 @@
1
- <!-- Based on agency-agents by AgentLand Contributors (MIT License, 2025). Adapted for SDTK-OPS. -->
2
1
  ---
3
2
  name: ops-security-infra
4
3
  description: Infrastructure security. Use when hardening infrastructure, managing secrets, defining network policies, or setting up security scanning in CI/CD -- covers STRIDE for infrastructure, secrets management, and detection-as-code.
@@ -74,7 +73,7 @@ The pipeline should scan:
74
73
  - dependency and image vulnerabilities with Trivy or equivalent
75
74
  - secret exposure with Gitleaks or equivalent
76
75
 
77
- Use `./references/cicd-security-pipeline.md` for a GitHub Actions example adapted from the source material.
76
+ Use `./references/cicd-security-pipeline.md` for a GitHub Actions example.
78
77
 
79
78
  ## Detection As Code
80
79
 
@@ -123,4 +122,3 @@ After defining the security change:
123
122
  - send infrastructure boundary changes to `ops-infra-plan`
124
123
  - route CI/CD controls through `ops-ci-cd`
125
124
  - verify the final control state with `ops-verify`
126
-
@@ -1,4 +1,3 @@
1
- <!-- Based on agency-agents by AgentLand Contributors (MIT License, 2025). Adapted for SDTK-OPS. -->
2
1
 
3
2
  # CI CD Security Pipeline
4
3
 
@@ -52,4 +51,3 @@ jobs:
52
51
  - fail the pipeline on critical findings, not just log them
53
52
  - keep secrets in the platform secret store
54
53
  - expand beyond GitHub Actions only if the team actually uses another runner
55
-
@@ -1,4 +1,3 @@
1
- <!-- Based on agency-agents by AgentLand Contributors (MIT License, 2025). Adapted for SDTK-OPS. -->
2
1
 
3
2
  # Security Headers
4
3
 
@@ -21,4 +20,3 @@ server {
21
20
  - tune CSP to the actual application surface before enforcing it
22
21
  - keep headers consistent across edge and app-serving paths
23
22
  - remove unnecessary server disclosure where the platform permits it
24
-
@@ -1,4 +1,3 @@
1
- <!-- Based on superpowers by Jesse Vincent (MIT License, 2025). Adapted for SDTK-OPS. -->
2
1
  ---
3
2
  name: ops-verify
4
3
  description: Verification before completion. Use before claiming any infrastructure change, deployment, or operational task is done -- run verification commands and confirm output, evidence before assertions.
@@ -50,6 +49,22 @@ Skip any step = lying, not verifying
50
49
  | Agent completed | VCS diff shows changes | Agent reports "success" |
51
50
  | Requirements met | Line-by-line checklist | Tests passing |
52
51
 
52
+ ## OPS_HANDOFF Closeout Checks
53
+
54
+ If the scoped OPS work came from `docs/dev/OPS_HANDOFF_[FEATURE_KEY].json`, verify against the handoff before claiming `DEV-Run` completion.
55
+
56
+ Check at minimum:
57
+ - the consumed handoff path and `handoff_status`
58
+ - whether the work followed or overrode `suggested_next_ops_path`, and why
59
+ - whether `deployment_prerequisites`, `environment_assumptions`, `infra_runtime_dependencies`, `observability_requirements`, and `rollback_recovery_expectations` were actually checked
60
+ - whether journey-specific operational evidence exists for the scoped work
61
+ - whether final closeout evidence is explicit and fresh
62
+
63
+ Blocked-state rule:
64
+ - if `handoff_status` is `BLOCKED_FOR_SDTK_OPS`, you may inspect and report the handoff
65
+ - you may verify bounded triage work if that work actually ran
66
+ - you must not claim normal ready-path operational completion from a blocked handoff
67
+
53
68
  ## Common Mistakes
54
69
 
55
70
  | Mistake | Why it fails |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "sdtk-ops-kit",
3
- "version": "0.2.1",
3
+ "version": "0.2.3",
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"
@@ -1,53 +1,88 @@
1
- "use strict";
2
-
3
- function cmdHelp() {
4
- const text = [
5
- "SDTK-OPS CLI -- skill-driven operations discipline toolkit",
6
- "",
7
- "Usage:",
8
- " sdtk-ops <command> [options]",
9
- "",
10
- "Commands:",
11
- " init Initialize SDTK-OPS files in a project",
12
- " runtime Manage runtime asset installation (install, uninstall, status)",
13
- " help Show this help message",
14
- "",
15
- "Current supported surface:",
16
- " Supported now: help, init, runtime install|status|uninstall",
17
- " Not supported: generate",
18
- " Package scope: public npm package",
19
- "",
20
- "Workflow entry:",
21
- " After init, choose a journey directly if the goal is clear.",
22
- " Canonical journeys: deployment, incident, monitoring, backup/recovery.",
23
- " If the correct path is unclear, start with the ops-discover skill.",
24
- " Close every journey with ops-verify before declaring work complete.",
25
- "",
26
- "Runtime support:",
27
- " Claude: project + user scope",
28
- " Codex: user scope only",
29
- " Gate C0: Codex project scope is rejected",
30
- "",
31
- "Global options:",
32
- " -h, --help Show this help",
33
- " -v, --version Show version",
34
- "",
35
- "Examples:",
36
- " sdtk-ops --help",
37
- " sdtk-ops --version",
38
- " sdtk-ops init --runtime claude --project-path ./my-project",
39
- " sdtk-ops runtime install --runtime claude --scope project --project-path ./my-project",
40
- " # Journey routing after init:",
41
- " # deployment -> ops-plan -> ops-infra-plan -> ops-container -> ops-ci-cd -> ops-deploy -> ops-monitor -> ops-verify",
42
- " # incident -> ops-incident -> ops-debug -> ops-monitor -> ops-verify",
43
- " # monitoring -> ops-plan -> ops-monitor -> ops-verify",
44
- " # recovery -> ops-plan -> ops-backup -> ops-verify",
45
- " sdtk-ops runtime status --runtime codex",
46
- " sdtk-ops runtime uninstall --runtime codex --scope user",
47
- ];
48
-
49
- console.log(text.join("\n"));
50
- return 0;
51
- }
52
-
53
- module.exports = { cmdHelp };
1
+ "use strict";
2
+
3
+ function cmdHelp() {
4
+ const text = [
5
+ "SDTK-OPS CLI -- skill-driven operations discipline toolkit",
6
+ "",
7
+ "Usage:",
8
+ " sdtk-ops <command> [options]",
9
+ "",
10
+ "Commands:",
11
+ " init Initialize SDTK-OPS files in a project",
12
+ " runtime Manage runtime asset installation (install, uninstall, status)",
13
+ " update Refresh the npm package and optionally re-apply managed project/runtime assets",
14
+ " help Show this help message",
15
+ "",
16
+ "Current supported surface:",
17
+ " Supported now: help, init, runtime install|status|uninstall",
18
+ " Not supported: generate",
19
+ " Package scope: public npm package",
20
+ "",
21
+ "DEV-Run intake:",
22
+ " Canonical intake artifact: docs/dev/OPS_HANDOFF_[FEATURE_KEY].json",
23
+ " READY_FOR_SDTK_OPS: start from suggested_next_ops_path or confirm it with ops-discover.",
24
+ " BLOCKED_FOR_SDTK_OPS: inspect blockers and evidence refs, but do not treat it as normal ready-path execution.",
25
+ " SDTK-OPS consumes the frozen handoff contract and does not redefine the schema.",
26
+ "",
27
+ "Workflow entry:",
28
+ " After init, choose a journey directly if the goal is clear.",
29
+ " Canonical journeys: deployment, incident, monitoring, backup/recovery.",
30
+ " If the correct path is unclear, start with the ops-discover skill.",
31
+ " ops-parallel remains valid only for independent slices; if collab/subagent dispatch is unavailable in the active runtime, keep the same split but execute sequentially.",
32
+ " Close every journey with ops-verify before declaring work complete.",
33
+ "",
34
+ "Runtime support:",
35
+ " Claude: project + user scope",
36
+ " Codex: default user scope plus bounded project scope via <project>/.codex",
37
+ " Codex project scope requires the explicit local CODEX_HOME=<project>/.codex contract",
38
+ " Native .codex/skills auto-discovery is not claimed",
39
+ "",
40
+ "Runtime commands:",
41
+ " sdtk-ops runtime install --runtime <codex|claude> [--scope <project|user>] [--project-path <path>]",
42
+ " sdtk-ops runtime uninstall --runtime <codex|claude> [--scope <project|user>] [--all] [--project-path <path>]",
43
+ " sdtk-ops runtime status --runtime <codex|claude> [--project-path <path>]",
44
+ "",
45
+ "Update options:",
46
+ " --version <latest|x.y.z> Target published npm package version (default: latest)",
47
+ " --runtime <codex|claude> Optional runtime refresh target after npm update",
48
+ " --scope <project|user> Runtime asset scope when --runtime is provided",
49
+ " --project-path <path> Target project directory for managed file refresh (default: cwd)",
50
+ " --check-only Print the planned npm/init/runtime refresh steps without making changes",
51
+ " --skip-project-files Skip sdtk-ops init --force during update",
52
+ " --skip-runtime-assets Skip sdtk-ops runtime install --force during update",
53
+ " --verbose Show detailed command output",
54
+ "",
55
+ "Uninstall behavior:",
56
+ " runtime uninstall removes only SDTK-OPS-managed skill folders for the selected runtime/scope.",
57
+ " It does not delete parent runtime roots such as .claude/, .claude/skills/, $CODEX_HOME/, or $CODEX_HOME/skills/.",
58
+ " npm uninstall -g sdtk-ops-kit removes the CLI package only. Runtime assets remain until runtime uninstall or manual cleanup.",
59
+ "",
60
+ "Global options:",
61
+ " -h, --help Show this help",
62
+ " -v, --version Show version",
63
+ "",
64
+ "Examples:",
65
+ " sdtk-ops --help",
66
+ " sdtk-ops --version",
67
+ " sdtk-ops init --runtime claude --project-path ./my-project",
68
+ " sdtk-ops update --check-only",
69
+ " sdtk-ops update --runtime claude --project-path ./my-project",
70
+ " sdtk-ops update --version 1.2.3 --runtime codex --scope user --skip-project-files",
71
+ " sdtk-ops init --runtime codex --runtime-scope project --project-path ./my-project",
72
+ " sdtk-ops runtime install --runtime claude --scope project --project-path ./my-project",
73
+ " sdtk-ops runtime install --runtime codex --scope project --project-path ./my-project",
74
+ " # Journey routing after init:",
75
+ " # deployment -> ops-plan -> ops-infra-plan -> ops-container -> ops-ci-cd -> ops-deploy -> ops-monitor -> ops-verify",
76
+ " # incident -> ops-incident -> ops-debug -> ops-monitor -> ops-verify",
77
+ " # monitoring -> ops-plan -> ops-monitor -> ops-verify",
78
+ " # recovery -> ops-plan -> ops-backup -> ops-verify",
79
+ " sdtk-ops runtime status --runtime codex",
80
+ " sdtk-ops runtime uninstall --runtime codex --scope user",
81
+ " npm uninstall -g sdtk-ops-kit",
82
+ ];
83
+
84
+ console.log(text.join("\n"));
85
+ return 0;
86
+ }
87
+
88
+ module.exports = { cmdHelp };
@@ -29,7 +29,7 @@ async function cmdInit(args) {
29
29
  validateChoice(scope, VALID_SCOPES, "runtime-scope");
30
30
  if (scope === "project" && !isProjectScopeSupported(runtime)) {
31
31
  throw new ValidationError(
32
- "Codex does not support project-local skills. Use --runtime-scope user instead."
32
+ `${runtime} does not support project-local runtime assets. Use --runtime-scope user instead.`
33
33
  );
34
34
  }
35
35
 
@@ -62,6 +62,11 @@ async function cmdInit(args) {
62
62
  console.log(` Runtime: ${runtime}`);
63
63
  console.log(` Scope: ${scope}`);
64
64
  console.log(` Project: ${projectPath}`);
65
+ if (runtime === "codex" && scope === "project") {
66
+ console.log(` Codex home contract: ${path.join(projectPath, ".codex")}`);
67
+ console.log(" Note: Launch Codex with CODEX_HOME=<project>/.codex to use project-local skills.");
68
+ console.log(" Note: This CLI does not claim native .codex/skills auto-discovery.");
69
+ }
65
70
  console.log("");
66
71
 
67
72
  const result = await runScript(installScript, params, { silent: !flags.verbose });
@@ -74,6 +79,10 @@ async function cmdInit(args) {
74
79
 
75
80
  console.log("");
76
81
  console.log("SDTK-OPS workspace initialized successfully.");
82
+ if (runtime === "codex" && scope === "project") {
83
+ console.log(`Project-local Codex skills were installed into ${path.join(projectPath, ".codex", "skills")}.`);
84
+ console.log("Launch Codex with CODEX_HOME=<project>/.codex to activate that local runtime home.");
85
+ }
77
86
  console.log("");
78
87
  console.log("Next steps:");
79
88
  console.log(" 1. Review and customize sdtk-spec.config.json for your operations environment.");
@@ -11,6 +11,8 @@ const {
11
11
  defaultScope,
12
12
  isProjectScopeSupported,
13
13
  managedSkillNames,
14
+ resolveCodexProjectHome,
15
+ resolveCodexUserHome,
14
16
  resolveSkillsDir,
15
17
  } = require("../lib/scope");
16
18
 
@@ -29,7 +31,7 @@ const SUBCOMMANDS = ["install", "uninstall", "status"];
29
31
  function validateScopeForRuntime(runtime, scope, label) {
30
32
  if (scope === "project" && !isProjectScopeSupported(runtime)) {
31
33
  throw new ValidationError(
32
- `Codex does not support project-local skills. Use --${label} user instead.`
34
+ `${runtime} does not support project-local runtime assets. Use --${label} user instead.`
33
35
  );
34
36
  }
35
37
  }
@@ -51,7 +53,7 @@ async function cmdRuntimeInstall(flags) {
51
53
  : "toolkit/scripts/install-codex-skills.ps1";
52
54
  const script = resolvePayloadFile(scriptName);
53
55
  const params = { Scope: scope };
54
- if (runtime === "claude") {
56
+ if (scope === "project") {
55
57
  params.ProjectPath = projectPath;
56
58
  }
57
59
  if (flags.force) {
@@ -64,9 +66,14 @@ async function cmdRuntimeInstall(flags) {
64
66
  console.log(`Installing ${runtime} runtime assets...`);
65
67
  console.log(` Runtime: ${runtime}`);
66
68
  console.log(` Scope: ${scope}`);
67
- if (runtime === "claude" && scope === "project") {
69
+ if (scope === "project") {
68
70
  console.log(` Project: ${projectPath}`);
69
71
  }
72
+ if (runtime === "codex" && scope === "project") {
73
+ console.log(` Codex home contract: ${resolveCodexProjectHome(projectPath)}`);
74
+ console.log(" Note: Launch Codex with CODEX_HOME=<project>/.codex to activate this project-local install.");
75
+ console.log(" Note: Native .codex/skills auto-discovery is not claimed.");
76
+ }
70
77
  console.log("");
71
78
 
72
79
  const result = await runScript(script, params, { silent: !flags.verbose });
@@ -98,11 +105,14 @@ async function cmdRuntimeUninstall(flags) {
98
105
  ? "toolkit/scripts/uninstall-claude-skills.ps1"
99
106
  : "toolkit/scripts/uninstall-codex-skills.ps1";
100
107
  const script = resolvePayloadFile(scriptName);
101
- const params = { All: true };
102
- if (runtime === "claude") {
103
- params.Scope = scope;
108
+ const params = {};
109
+ params.Scope = scope;
110
+ if (scope === "project") {
104
111
  params.ProjectPath = projectPath;
105
112
  }
113
+ if (flags.all) {
114
+ params.All = true;
115
+ }
106
116
  if (!flags.verbose) {
107
117
  params.Quiet = true;
108
118
  }
@@ -124,11 +134,20 @@ function cmdRuntimeStatus(flags) {
124
134
  validateChoice(runtime, VALID_RUNTIMES, "runtime");
125
135
 
126
136
  const projectPath = flags["project-path"] ? path.resolve(flags["project-path"]) : process.cwd();
127
- const scopes = runtime === "claude" ? ["project", "user"] : ["user"];
137
+ const scopes = ["project", "user"];
128
138
 
129
139
  console.log(`Runtime: ${runtime}`);
130
140
  console.log("");
131
141
 
142
+ if (runtime === "codex") {
143
+ console.log("Codex scope truth:");
144
+ console.log(` Project-local root: ${resolveCodexProjectHome(projectPath)}`);
145
+ console.log(` User/global root: ${resolveCodexUserHome()}`);
146
+ console.log(" Project-local Codex support requires launching Codex with CODEX_HOME=<project>/.codex.");
147
+ console.log(" Native .codex/skills auto-discovery is not claimed.");
148
+ console.log("");
149
+ }
150
+
132
151
  for (const scope of scopes) {
133
152
  const skillsDir = resolveSkillsDir(runtime, scope, projectPath);
134
153
  const managed = managedSkillNames(runtime);
@@ -158,6 +177,9 @@ function cmdRuntimeStatus(flags) {
158
177
 
159
178
  console.log(` Scope: ${scope}`);
160
179
  console.log(` Path: ${skillsDir}`);
180
+ if (runtime === "codex" && scope === "project") {
181
+ console.log(" Activation: explicit CODEX_HOME=<project>/.codex contract required");
182
+ }
161
183
  console.log(` Status: ${status}`);
162
184
  if (exists && hasManagedSkills && skillCount < managed.length) {
163
185
  const missing = managed.filter((name) => !installedNames.includes(name));
@@ -0,0 +1,11 @@
1
+ "use strict";
2
+
3
+ const { executeUpdate } = require("../lib/update");
4
+
5
+ async function cmdUpdate(args) {
6
+ return executeUpdate(args);
7
+ }
8
+
9
+ module.exports = {
10
+ cmdUpdate,
11
+ };