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.
- package/README.md +1 -0
- package/assets/manifest/toolkit-bundle.manifest.json +186 -186
- package/assets/manifest/toolkit-bundle.sha256.txt +5 -5
- package/assets/toolkit/toolkit/AGENTS.md +194 -93
- package/assets/toolkit/toolkit/SDTKOPS_TOOLKIT.md +203 -203
- package/assets/toolkit/toolkit/install.ps1 +168 -168
- package/assets/toolkit/toolkit/sdtk-spec.config.json +36 -4
- package/assets/toolkit/toolkit/sdtk-spec.config.profiles.example.json +50 -12
- package/package.json +46 -46
- package/src/commands/help.js +90 -90
- package/src/commands/init.js +98 -98
- package/src/commands/update.js +11 -11
- package/src/index.js +68 -68
- package/src/lib/project-target-guard.js +53 -53
- package/src/lib/update.js +344 -344
|
@@ -1,93 +1,194 @@
|
|
|
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
|
+
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.
|
|
36
|
+
|
|
37
|
+
## 3) Orchestrator-First Intake Protocol
|
|
38
|
+
For every unprefixed user request:
|
|
39
|
+
1. Classify the request intent before selecting PM/BA/ARCH/DEV/QA or a downstream product lane.
|
|
40
|
+
2. Route to the smallest sufficient workflow:
|
|
41
|
+
- unclear idea or early concept -> brainstorm / requirement clarification, then create or update `docs/discovery/REQUIREMENT_[FEATURE_KEY].md`
|
|
42
|
+
- formal feature discovery or planning -> SDTK-SPEC pipeline
|
|
43
|
+
- implementation, bug fix, refactor, verification, or ship-ready code -> SDTK-CODE
|
|
44
|
+
- deploy, release, infrastructure, CI/CD, monitoring, incident, backup, security-infra, or ops verification -> SDTK-OPS
|
|
45
|
+
- documentation graph or Atlas viewer -> `sdtk-spec atlas` compatibility workflow, or `sdtk-wiki` for canonical SDTK-WIKI work
|
|
46
|
+
- SDTK-WIKI Ask -> native `sdtk-wiki ask` when `.sdtk/wiki/graph` and `wiki.ask` entitlement/runtime preconditions are present
|
|
47
|
+
- project ingest, project refresh, or project audit -> the matching project command or workflow
|
|
48
|
+
- review or release decision -> review/QA workflow
|
|
49
|
+
3. Ask focused questions only when missing information blocks safe routing.
|
|
50
|
+
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`.
|
|
51
|
+
5. When routing creates artifacts, record decisions and open questions in the correct SDTK artifact.
|
|
52
|
+
|
|
53
|
+
## 4) Intent-To-Skill Routing Matrix
|
|
54
|
+
Use this compact matrix during intake so the agent picks the smallest sufficient workflow instead of defaulting everything to PM:
|
|
55
|
+
|
|
56
|
+
| User intent | Primary route | Output expectation |
|
|
57
|
+
|---|---|---|
|
|
58
|
+
| Raw idea | Brainstorm / requirement clarification | `docs/discovery/REQUIREMENT_[FEATURE_KEY].md` with clarified problem, scope, assumptions, open questions, and readiness |
|
|
59
|
+
| Approved idea ready for product planning | `SDTK-SPEC` PM initiation | `REQUIREMENT_[FEATURE_KEY]` marked `READY_FOR_PM_INITIATION`, then `PROJECT_INITIATION` kickoff |
|
|
60
|
+
| Formal feature delivery | `SDTK-SPEC` pipeline | PM -> BA -> ARCH -> DEV planning -> CODE handoff -> QA |
|
|
61
|
+
| Build, fix, or refactor implementation | `SDTK-CODE` | code-brainstorm (when slice is ambiguous) -> start -> plan -> build -> verify -> ship |
|
|
62
|
+
| Debug failure or unexpected behavior | `SDTK-CODE` debug | Root cause, bounded fix, regression verification |
|
|
63
|
+
| Deployment, release, infra, or CI/CD work | `SDTK-OPS` | ops-plan -> ops-deploy/ops-incident/ops-monitor -> ops-verify |
|
|
64
|
+
| Code review or spec review | Review / QA workflow | Findings, risks, blockers, acceptance signal |
|
|
65
|
+
| 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 |
|
|
66
|
+
| SDTK-WIKI Ask | `sdtk-wiki ask` | Grounded answer when `.sdtk/wiki/graph` plus `wiki.ask` entitlement/runtime preconditions are present, otherwise explicit blocker |
|
|
67
|
+
| Existing project scan: project ingest, project refresh, or project audit | Matching premium project workflow | Project-local foundation, refresh, or audit result without overclaiming entitlement |
|
|
68
|
+
| 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` |
|
|
69
|
+
| "what should we do next" | Orchestrator state review | Recommended next action with rationale and lane choice |
|
|
70
|
+
|
|
71
|
+
Guardrails:
|
|
72
|
+
- Explicit user role prefix wins unless safety or missing critical inputs block execution.
|
|
73
|
+
- 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.
|
|
74
|
+
- 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.
|
|
75
|
+
- 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.
|
|
76
|
+
|
|
77
|
+
## 5) Proceed-Vs-Ask Decision Rules
|
|
78
|
+
Ask clarification when:
|
|
79
|
+
1. the requested outcome is ambiguous
|
|
80
|
+
2. safety, security, or release impact is unclear
|
|
81
|
+
3. the target repo, project, or path is missing
|
|
82
|
+
4. implementation is requested without an acceptance boundary
|
|
83
|
+
5. the next command could mutate external state
|
|
84
|
+
6. the next step would spawn multiple sub-agents or incur significant token cost, such as dispatching an `sdtk-agent` run
|
|
85
|
+
|
|
86
|
+
Proceed when:
|
|
87
|
+
1. the intent and target are clear
|
|
88
|
+
2. the task is read-only analysis
|
|
89
|
+
3. the user already approved the relevant plan or spec
|
|
90
|
+
4. the requested change is bounded and verifiable
|
|
91
|
+
|
|
92
|
+
### 5.1) Orchestration Cost Gate (sdtk-agent)
|
|
93
|
+
`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:
|
|
94
|
+
|
|
95
|
+
1. Never auto-start an `sdtk-agent` run on the user's behalf. Only propose it.
|
|
96
|
+
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.
|
|
97
|
+
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:
|
|
98
|
+
> 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)
|
|
99
|
+
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.
|
|
100
|
+
5. Honor `.sdtk/agent-runtime/config.json` `orchestration.confirmationMode` (`always` by default): no mode ever allows dispatch without at least one confirmation per run.
|
|
101
|
+
|
|
102
|
+
## 6) Clarification Protocol
|
|
103
|
+
Apply for all roles (`/pm`, `/ba`, `/arch`, `/dev`, `/qa`):
|
|
104
|
+
1. If there is ambiguity or missing data, log `Open Questions` as `OQ-xx` in the current phase artifact.
|
|
105
|
+
2. Do not guess for behavior, API contracts, UI/UX, data model, security, or release criteria.
|
|
106
|
+
3. Escalate unresolved items to PM with question ID and file reference.
|
|
107
|
+
4. PM resolves by:
|
|
108
|
+
- using available docs and making a clear decision, or
|
|
109
|
+
- asking the user if source information is still missing.
|
|
110
|
+
5. Record decisions in PRD (`Decision Log`) and update the originating `OQ-xx` with resolution.
|
|
111
|
+
|
|
112
|
+
For raw ideas before PM initiation:
|
|
113
|
+
1. Use `docs/discovery/REQUIREMENT_[FEATURE_KEY].md` as the canonical clarification artifact.
|
|
114
|
+
2. Record scope, non-goals, assumptions, constraints, open questions, and readiness there before opening `PROJECT_INITIATION`.
|
|
115
|
+
3. Treat the discovery artifact as a bridge into PM initiation, not as a PRD replacement.
|
|
116
|
+
|
|
117
|
+
## 7) Role Selection In One Message
|
|
118
|
+
When the user prefixes a message, execute that role:
|
|
119
|
+
- `/orchestrator` (default intake + routing)
|
|
120
|
+
- `/pm` (formal product initiation + planning)
|
|
121
|
+
- `/ba`
|
|
122
|
+
- `/arch`
|
|
123
|
+
- `/dev`
|
|
124
|
+
- `/qa`
|
|
125
|
+
- `/engineer` (escalation for technical blockers)
|
|
126
|
+
|
|
127
|
+
Notes:
|
|
128
|
+
- Supported delivery roles are PM/BA/ARCH/DEV/QA.
|
|
129
|
+
- There is no separate `/tester` role. Test-case design belongs to QA with `sdtk-test-case-spec`.
|
|
130
|
+
|
|
131
|
+
## 8) Suite Product Routing
|
|
132
|
+
Use the suite products according to task intent:
|
|
133
|
+
|
|
134
|
+
- `SDTK-SPEC`
|
|
135
|
+
- feature discovery
|
|
136
|
+
- requirements, BA, PRD, backlog, architecture, QA artifacts
|
|
137
|
+
- handoff generation and release-gate traceability
|
|
138
|
+
- entry: `/orchestrator` (recommended), `/pm`, `/ba`, `/arch`, `/dev`, `/qa`
|
|
139
|
+
- `SDTK-DESIGN`
|
|
140
|
+
- screen/layout design, visual tokens, prototype evidence, design handoff before coding
|
|
141
|
+
- use before `SDTK-CODE` when implementation needs reviewable screens or a design handoff
|
|
142
|
+
- `SDTK-CODE`
|
|
143
|
+
- build a feature
|
|
144
|
+
- fix a bug
|
|
145
|
+
- refactor implementation
|
|
146
|
+
- run implementation verification
|
|
147
|
+
- ship code changes
|
|
148
|
+
- workflow: `start -> plan -> build -> verify -> ship`
|
|
149
|
+
- entry point for ambiguous slices: `code-brainstorm`
|
|
150
|
+
- 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)
|
|
151
|
+
- `SDTK-OPS`
|
|
152
|
+
- deploy or release
|
|
153
|
+
- infrastructure and environment setup
|
|
154
|
+
- CI/CD changes
|
|
155
|
+
- monitoring, incident response, security-infra, backup, compliance
|
|
156
|
+
- entry: `ops-discover` (when boundary is unclear), `ops-plan`, `ops-deploy`, `ops-incident`, `ops-monitor`, `ops-backup`, `ops-verify`, `ops-debug`
|
|
157
|
+
|
|
158
|
+
Cross-cutting capabilities (not a linear lane; usable across every phase):
|
|
159
|
+
|
|
160
|
+
- `SDTK-WIKI` (memory)
|
|
161
|
+
- project knowledge graph, docs view, and grounded `sdtk-wiki ask`
|
|
162
|
+
- any lane may read from it for recall; build with `sdtk-wiki atlas build`
|
|
163
|
+
- `SDTK-AGENT` (orchestration)
|
|
164
|
+
- a durable, file-driven DAG controller that sits above `sdtk-code` agent-team; it does not own a phase, it chains steps across lanes
|
|
165
|
+
- surface: `sdtk-agent run start|continue|status|report`, `gate approve|reject`, `workflow validate`, `adapter hermes-kanban plan`
|
|
166
|
+
- 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
|
|
167
|
+
- opt-in and token-aware: always propose-then-confirm before dispatch (see the orchestration cost gate in section 5)
|
|
168
|
+
- the CLI is runtime-neutral and installs no skills; the engine is Free, and live external dispatch is not part of this release (hermes-kanban is dry-run only)
|
|
169
|
+
|
|
170
|
+
If the current project only has `SDTK-SPEC` runtime assets installed:
|
|
171
|
+
- keep `/dev` bounded to planning and `CODE_HANDOFF`
|
|
172
|
+
- do not overclaim that SDTK-CODE or SDTK-OPS runtime assets are already installed
|
|
173
|
+
- still describe the correct downstream suite path in guidance and handoffs
|
|
174
|
+
|
|
175
|
+
## 9) Shared State And Quality Gates
|
|
176
|
+
- `SHARED_PLANNING.md`: phase status, owners, artifacts, blockers, handoff notes.
|
|
177
|
+
- `QUALITY_CHECKLIST.md`: gate checklist by phase.
|
|
178
|
+
- No handoff to next phase while current gate is not PASS.
|
|
179
|
+
- QA cannot start until downstream implementation evidence exists, normally from SDTK-CODE.
|
|
180
|
+
- QA cannot approve until `OPS_HANDOFF` and downstream OPS evidence are present and aligned.
|
|
181
|
+
- QA accepts downstream implementation evidence from SDTK-CODE as the default handoff bridge, plus `OPS_HANDOFF + OPS evidence` in the current formal suite flow.
|
|
182
|
+
|
|
183
|
+
## 10) Runtime Availability Rules
|
|
184
|
+
- Route only to products whose runtime assets are installed; do not overclaim.
|
|
185
|
+
- For SDTK-SPEC-only installs: keep `/dev` bounded to planning and `CODE_HANDOFF`; do not claim SDTK-CODE or SDTK-OPS are installed.
|
|
186
|
+
- For Codex runtimes: project-local skills require the explicit local `CODEX_HOME=<project>/.codex` contract; native `.codex/skills` auto-discovery is not claimed.
|
|
187
|
+
- 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.
|
|
188
|
+
- `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.
|
|
189
|
+
- The `sdtk-agent` hermes-kanban adapter is dry-run only in this release; it never calls a live gateway or creates a real card. Live dispatch is a future Pro capability, so do not claim it.
|
|
190
|
+
|
|
191
|
+
## 11) Discovery And PM Readiness
|
|
192
|
+
- PM initiation starts only after `docs/discovery/REQUIREMENT_[FEATURE_KEY].md` is marked `READY_FOR_PM_INITIATION`.
|
|
193
|
+
- Use `NEEDS_MORE_DISCOVERY` or `NOT_ACTIONABLE_YET` when the request is not ready.
|
|
194
|
+
- The discovery artifact is a pre-PM clarification bridge, not a PRD or BA replacement.
|