sdtk-ops-kit 0.2.4 → 0.2.5

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,93 +1,163 @@
1
- # SDTK-OPS -- Operations Discipline Toolkit
2
-
3
- Purpose: use SDTK-OPS to drive disciplined infrastructure and operations work across planning, deployment, monitoring, incident response, recovery, security hardening, and cost optimization.
4
-
5
- Canonical end-user guide:
6
- - `products/sdtk-ops/governance/SDTKOPS_TOOLKIT_USAGE_GUIDE.md`
7
-
8
- Document role:
9
- - runtime routing and skill-catalog truth after `sdtk-ops init`
10
- - not the primary install or onboarding guide
11
-
12
- ## Default Rules
13
-
14
- - If the correct entry point is unclear, start with `ops-discover`.
15
- - Use `ops-verify` before marking any operational task complete.
16
- - Use `ops-debug` for evidence-first diagnosis before proposing speculative fixes.
17
- - Use `ops-parallel` only for truly independent slices. If collab or subagent dispatch is unavailable in the active runtime, keep the same slice boundaries but execute them sequentially in one controller session.
18
- - Keep guidance cloud-agnostic unless the task explicitly requires a platform-specific example.
19
- - Do not drift into application specification or coding workflows. Those belong to SDTK-SPEC or SDTK-CODE.
20
- - `ops-discover` is a skill, not a CLI command.
21
- - `generate` remains unsupported and deferred in the current SDTK-OPS CLI surface.
22
-
23
- ## DEV-Run Intake
24
-
25
- When `DEV-Run` begins from `SDTK-CODE`, the only canonical bridge artifact is:
26
- - `docs/dev/OPS_HANDOFF_[FEATURE_KEY].json`
27
-
28
- Treat that file as the frozen suite contract input.
29
- `SDTK-OPS` consumes it, but does not redefine the schema, rename fields, or move the canonical path.
30
-
31
- Ready-path intake:
32
- - inspect `handoff_status` first
33
- - if status is `READY_FOR_SDTK_OPS`, default to `suggested_next_ops_path.start_with`
34
- - treat `suggested_next_ops_path.suggested_chain` as the default route unless fresh evidence requires a bounded reroute
35
- - close with `suggested_next_ops_path.close_with`, which should normally be `ops-verify`
36
-
37
- Blocked-path intake:
38
- - if status is `BLOCKED_FOR_SDTK_OPS`, the handoff is still inspectable
39
- - inspect `open_blockers`, `code_evidence_refs`, and prerequisite fields before choosing a next step
40
- - do not treat a blocked handoff as normal ready-path execution
41
- - use `ops-discover` only to select bounded triage or clarification, not to silently reinterpret blocked scope as deployment-ready
42
-
43
- Minimum OPS evidence expectations:
44
- - record the consumed handoff path and `handoff_status`
45
- - record whether the chosen first skill followed or overrode `suggested_next_ops_path`, and why
46
- - record which prerequisites, assumptions, dependencies, observability, and rollback items were checked
47
- - record journey-specific operational evidence for the scoped OPS work
48
- - record final `ops-verify` closeout evidence
49
-
50
- ## Primary Routing Journeys
51
-
52
- | Journey | Start With | Suggested Chain | Close With |
53
- |---------|------------|-----------------|------------|
54
- | Deployment | `ops-plan` | `ops-plan` -> `ops-infra-plan` -> `ops-container` -> `ops-ci-cd` -> `ops-deploy` -> `ops-monitor` | `ops-verify` |
55
- | Incident | `ops-incident` | `ops-incident` -> `ops-debug` -> `ops-deploy` if a change or rollback is required -> `ops-monitor` | `ops-verify` |
56
- | Monitoring | `ops-plan` | `ops-plan` -> `ops-monitor` | `ops-verify` |
57
- | Backup or recovery | `ops-plan` | `ops-plan` -> `ops-backup` | `ops-verify` |
58
-
59
- ## Other Valid Skills
60
-
61
- - `ops-security-infra`, `ops-compliance`, and `ops-cost` remain valid SDTK-OPS skills, but they are not the primary routed journeys in the current wave.
62
- - Use `ops-discover` when the correct boundary between deployment, incident, monitoring, backup or recovery, security, compliance, and cost work is unclear.
63
-
64
- ## Skill Catalog
65
-
66
- | Category | Skill | Trigger Condition |
67
- |----------|-------|-------------------|
68
- | Core Process | `ops-verify` | you need evidence before claiming an operational task is complete |
69
- | Core Process | `ops-debug` | a deployment, service, network, DNS, or runtime issue needs root-cause analysis |
70
- | Core Process | `ops-plan` | the team needs a step-by-step operational change plan |
71
- | Core Process | `ops-parallel` | two or more independent operations tasks can proceed without shared state |
72
- | Deployment | `ops-infra-plan` | you are designing infrastructure, networking, IAM, or resource topology before provisioning |
73
- | Deployment | `ops-deploy` | you are executing a rollout, promotion, cutover, or rollback |
74
- | Deployment | `ops-container` | you are building images, Dockerfiles, manifests, or container runtime patterns |
75
- | Deployment | `ops-ci-cd` | you are setting up or modifying pipelines, artifact flow, or deployment gates |
76
- | Operations | `ops-monitor` | you need SLOs, alerts, dashboards, logs, traces, or observability coverage |
77
- | Operations | `ops-incident` | a production incident is active or incident procedures need to be established |
78
- | Operations | `ops-backup` | backup, restore, disaster recovery, RTO, or RPO design is in scope |
79
- | Operations | `ops-cost` | you are reviewing spend, right-sizing, or budget controls |
80
- | Security And Compliance | `ops-security-infra` | infrastructure hardening, secrets, network policy, or security scanning is the main concern |
81
- | Security And Compliance | `ops-compliance` | audit readiness, evidence collection, retention, or policy enforcement is the main concern |
82
- | Discovery | `ops-discover` | you need help choosing among SDTK-OPS skills or sequencing them |
83
-
84
- ## Runtime Support
85
-
86
- | Runtime | Project Scope | User Scope | Default Scope | Notes |
87
- |---------|:-------------:|:----------:|---------------|-------|
88
- | Claude | true | true | project | project-local toolkit supported |
89
- | Codex | true | true | user | Project-local skill runtime is supported only through the explicit local `CODEX_HOME=<project>/.codex` contract; native `.codex/skills` auto-discovery is not claimed. |
90
-
91
- ## Verification Policy
92
-
93
- Use `ops-verify` before marking any operational task complete, including deployment, incident, monitoring, and backup or recovery journeys.
1
+ # SDTK Orchestrator Routing Contract
2
+
3
+ Goal: use the SDTK Suite as a coordinated operating model:
4
+ - `SDTK-SPEC` governs upstream discovery, planning, design, traceability, and release gates.
5
+ - `SDTK-CODE` is the default downstream system for implementation, bug fixing, refactoring, verification, and ship-ready code changes.
6
+ - `SDTK-OPS` is the downstream system for deployment, infrastructure, CI/CD, monitoring, incident handling, and operational verification.
7
+
8
+ Orchestrator Intake is the always-winning front door for every unprefixed request.
9
+
10
+ ## 1) Default Rules
11
+ - If role is not specified, default to Orchestrator Intake, not PM.
12
+ - Orchestrator first classifies the user request intent, then routes to the smallest sufficient SDTK product, role, and skill.
13
+ - PM starts only when the request is ready for formal SDTK-SPEC product initiation after discovery readiness is confirmed.
14
+ - Do not skip phases. If inputs are missing, ask focused questions before moving on.
15
+ - At the end of every SDTK-SPEC phase, update:
16
+ - `SHARED_PLANNING.md`
17
+ - `QUALITY_CHECKLIST.md`
18
+ - Artifact language under `docs/**` should default to English.
19
+ - Read stack and command configuration from `sdtk-spec.config.json` in the project root.
20
+ - For VI/JP source requirements, keep original text in an appendix and add literal English translation for traceability.
21
+ - `/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`.
23
+ - `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
+
25
+ ## 2) Session Bootstrap Protocol
26
+ When starting a new session, read context in this order when the files exist:
27
+ 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
32
+
33
+ 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
+
35
+ ## 3) Orchestrator-First Intake Protocol
36
+ For every unprefixed user request:
37
+ 1. Classify the request intent before selecting PM/BA/ARCH/DEV/QA or a downstream product lane.
38
+ 2. Route to the smallest sufficient workflow:
39
+ - unclear idea or early concept -> brainstorm / requirement clarification, then create or update `docs/discovery/REQUIREMENT_[FEATURE_KEY].md`
40
+ - formal feature discovery or planning -> SDTK-SPEC pipeline
41
+ - implementation, bug fix, refactor, verification, or ship-ready code -> SDTK-CODE
42
+ - deploy, release, infrastructure, CI/CD, monitoring, incident, backup, security-infra, or ops verification -> SDTK-OPS
43
+ - documentation graph or Atlas viewer -> `sdtk-spec atlas` compatibility workflow, or `sdtk-wiki` for canonical SDTK-WIKI work
44
+ - SDTK-WIKI Ask -> native `sdtk-wiki ask` when `.sdtk/wiki/graph` and `wiki.ask` entitlement/runtime preconditions are present
45
+ - project ingest, project refresh, or project audit -> the matching project command or workflow
46
+ - review or release decision -> review/QA workflow
47
+ 3. Ask focused questions only when missing information blocks safe routing.
48
+ 4. Do not force raw ideas directly into PM Phase 1. Clarify the requirement first in `docs/discovery/REQUIREMENT_[FEATURE_KEY].md`, then start PM initiation only after the artifact is marked `READY_FOR_PM_INITIATION`.
49
+ 5. When routing creates artifacts, record decisions and open questions in the correct SDTK artifact.
50
+
51
+ ## 4) Intent-To-Skill Routing Matrix
52
+ Use this compact matrix during intake so the agent picks the smallest sufficient workflow instead of defaulting everything to PM:
53
+
54
+ | User intent | Primary route | Output expectation |
55
+ |---|---|---|
56
+ | Raw idea | Brainstorm / requirement clarification | `docs/discovery/REQUIREMENT_[FEATURE_KEY].md` with clarified problem, scope, assumptions, open questions, and readiness |
57
+ | Approved idea ready for product planning | `SDTK-SPEC` PM initiation | `REQUIREMENT_[FEATURE_KEY]` marked `READY_FOR_PM_INITIATION`, then `PROJECT_INITIATION` kickoff |
58
+ | Formal feature delivery | `SDTK-SPEC` pipeline | PM -> BA -> ARCH -> DEV planning -> CODE handoff -> QA |
59
+ | Build, fix, or refactor implementation | `SDTK-CODE` | code-brainstorm (when slice is ambiguous) -> start -> plan -> build -> verify -> ship |
60
+ | Debug failure or unexpected behavior | `SDTK-CODE` debug | Root cause, bounded fix, regression verification |
61
+ | Deployment, release, infra, or CI/CD work | `SDTK-OPS` | ops-plan -> ops-deploy/ops-incident/ops-monitor -> ops-verify |
62
+ | Code review or spec review | Review / QA workflow | Findings, risks, blockers, acceptance signal |
63
+ | 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 |
64
+ | SDTK-WIKI Ask | `sdtk-wiki ask` | Grounded answer when `.sdtk/wiki/graph` plus `wiki.ask` entitlement/runtime preconditions are present, otherwise explicit blocker |
65
+ | Existing project scan: project ingest, project refresh, or project audit | Matching premium project workflow | Project-local foundation, refresh, or audit result without overclaiming entitlement |
66
+ | "what should we do next" | Orchestrator state review | Recommended next action with rationale and lane choice |
67
+
68
+ Guardrails:
69
+ - Explicit user role prefix wins unless safety or missing critical inputs block execution.
70
+ - Raw idea clarification should use `docs/discovery/REQUIREMENT_[FEATURE_KEY].md`; do not widen the discovery-clarification scope into generator automation, package sync, or downstream validation work.
71
+ - Do not claim SDTK-WIKI Ask, project ingest, project refresh, project audit, web discover, compile, or query-history availability unless the runtime and entitlement preconditions are actually present.
72
+ - Ambiguous intent: ask, do not guess. Cap re-routes at 2 to avoid bouncing between products. Escalate to the user when intent cannot be classified or when the re-route limit is hit.
73
+
74
+ ## 5) Proceed-Vs-Ask Decision Rules
75
+ Ask clarification when:
76
+ 1. the requested outcome is ambiguous
77
+ 2. safety, security, or release impact is unclear
78
+ 3. the target repo, project, or path is missing
79
+ 4. implementation is requested without an acceptance boundary
80
+ 5. the next command could mutate external state
81
+
82
+ Proceed when:
83
+ 1. the intent and target are clear
84
+ 2. the task is read-only analysis
85
+ 3. the user already approved the relevant plan or spec
86
+ 4. the requested change is bounded and verifiable
87
+
88
+ ## 6) Clarification Protocol
89
+ Apply for all roles (`/pm`, `/ba`, `/arch`, `/dev`, `/qa`):
90
+ 1. If there is ambiguity or missing data, log `Open Questions` as `OQ-xx` in the current phase artifact.
91
+ 2. Do not guess for behavior, API contracts, UI/UX, data model, security, or release criteria.
92
+ 3. Escalate unresolved items to PM with question ID and file reference.
93
+ 4. PM resolves by:
94
+ - using available docs and making a clear decision, or
95
+ - asking the user if source information is still missing.
96
+ 5. Record decisions in PRD (`Decision Log`) and update the originating `OQ-xx` with resolution.
97
+
98
+ For raw ideas before PM initiation:
99
+ 1. Use `docs/discovery/REQUIREMENT_[FEATURE_KEY].md` as the canonical clarification artifact.
100
+ 2. Record scope, non-goals, assumptions, constraints, open questions, and readiness there before opening `PROJECT_INITIATION`.
101
+ 3. Treat the discovery artifact as a bridge into PM initiation, not as a PRD replacement.
102
+
103
+ ## 7) Role Selection In One Message
104
+ When the user prefixes a message, execute that role:
105
+ - `/orchestrator` (default intake + routing)
106
+ - `/pm` (formal product initiation + planning)
107
+ - `/ba`
108
+ - `/arch`
109
+ - `/dev`
110
+ - `/qa`
111
+ - `/engineer` (escalation for technical blockers)
112
+
113
+ Notes:
114
+ - Supported delivery roles are PM/BA/ARCH/DEV/QA.
115
+ - There is no separate `/tester` role. Test-case design belongs to QA with `sdtk-test-case-spec`.
116
+
117
+ ## 8) Suite Product Routing
118
+ Use the suite products according to task intent:
119
+
120
+ - `SDTK-SPEC`
121
+ - feature discovery
122
+ - requirements, BA, PRD, backlog, architecture, QA artifacts
123
+ - handoff generation and release-gate traceability
124
+ - entry: `/orchestrator` (recommended), `/pm`, `/ba`, `/arch`, `/dev`, `/qa`
125
+ - `SDTK-CODE`
126
+ - build a feature
127
+ - fix a bug
128
+ - refactor implementation
129
+ - run implementation verification
130
+ - ship code changes
131
+ - workflow: `start -> plan -> build -> verify -> ship`
132
+ - entry point for ambiguous slices: `code-brainstorm`
133
+ - specialist engine: `code-plan`, `code-execute`, `code-tdd`, `code-debug`, `code-verify`, `code-review`, `code-ship`, `code-finish`, `code-worktree`, `code-discover`, `code-parallel` (sequential fallback when parallel dispatch is unavailable)
134
+ - `SDTK-OPS`
135
+ - deploy or release
136
+ - infrastructure and environment setup
137
+ - CI/CD changes
138
+ - monitoring, incident response, security-infra, backup, compliance
139
+ - entry: `ops-discover` (when boundary is unclear), `ops-plan`, `ops-deploy`, `ops-incident`, `ops-monitor`, `ops-backup`, `ops-verify`, `ops-debug`
140
+
141
+ If the current project only has `SDTK-SPEC` runtime assets installed:
142
+ - keep `/dev` bounded to planning and `CODE_HANDOFF`
143
+ - do not overclaim that SDTK-CODE or SDTK-OPS runtime assets are already installed
144
+ - still describe the correct downstream suite path in guidance and handoffs
145
+
146
+ ## 9) Shared State And Quality Gates
147
+ - `SHARED_PLANNING.md`: phase status, owners, artifacts, blockers, handoff notes.
148
+ - `QUALITY_CHECKLIST.md`: gate checklist by phase.
149
+ - No handoff to next phase while current gate is not PASS.
150
+ - QA cannot start until downstream implementation evidence exists, normally from SDTK-CODE.
151
+ - QA cannot approve until `OPS_HANDOFF` and downstream OPS evidence are present and aligned.
152
+ - QA accepts downstream implementation evidence from SDTK-CODE as the default handoff bridge, plus `OPS_HANDOFF + OPS evidence` in the current formal suite flow.
153
+
154
+ ## 10) Runtime Availability Rules
155
+ - Route only to products whose runtime assets are installed; do not overclaim.
156
+ - For SDTK-SPEC-only installs: keep `/dev` bounded to planning and `CODE_HANDOFF`; do not claim SDTK-CODE or SDTK-OPS are installed.
157
+ - For Codex runtimes: project-local skills require the explicit local `CODEX_HOME=<project>/.codex` contract; native `.codex/skills` auto-discovery is not claimed.
158
+ - 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.
159
+
160
+ ## 11) Discovery And PM Readiness
161
+ - PM initiation starts only after `docs/discovery/REQUIREMENT_[FEATURE_KEY].md` is marked `READY_FOR_PM_INITIATION`.
162
+ - Use `NEEDS_MORE_DISCOVERY` or `NOT_ACTIONABLE_YET` when the request is not ready.
163
+ - The discovery artifact is a pre-PM clarification bridge, not a PRD or BA replacement.