sdtk-ops-kit 0.2.3 → 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.
- package/README.md +1 -0
- package/assets/manifest/toolkit-bundle.manifest.json +186 -186
- package/assets/manifest/toolkit-bundle.sha256.txt +4 -4
- package/assets/toolkit/toolkit/AGENTS.md +163 -93
- package/assets/toolkit/toolkit/SDTKOPS_TOOLKIT.md +203 -203
- package/assets/toolkit/toolkit/install.ps1 +37 -0
- package/assets/toolkit/toolkit/sdtk-spec.config.profiles.example.json +12 -12
- package/package.json +3 -3
- package/src/commands/help.js +90 -88
- package/src/commands/init.js +3 -0
- package/src/commands/update.js +11 -11
- package/src/index.js +68 -68
- package/src/lib/project-target-guard.js +53 -0
- package/src/lib/update.js +344 -337
|
@@ -1,93 +1,163 @@
|
|
|
1
|
-
# SDTK
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
- `
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
-
|
|
15
|
-
-
|
|
16
|
-
-
|
|
17
|
-
-
|
|
18
|
-
-
|
|
19
|
-
-
|
|
20
|
-
-
|
|
21
|
-
- `
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
`
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
-
|
|
40
|
-
-
|
|
41
|
-
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
-
|
|
45
|
-
-
|
|
46
|
-
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
|
55
|
-
|
|
56
|
-
|
|
|
57
|
-
|
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
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.
|