ultra-builder-pro-cli 0.10.0 → 0.12.1
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/.ultra-template/specs/architecture.md +54 -223
- package/.ultra-template/specs/discovery.md +34 -231
- package/.ultra-template/specs/product.md +44 -200
- package/.ultra-template/tasks/contexts/TEMPLATE.md +36 -0
- package/.ultra-template/tasks/tasks.json +6 -0
- package/CHANGELOG.md +86 -1
- package/README.md +21 -9
- package/adapters/_shared/codex-assets.cjs +24 -342
- package/adapters/_shared/handbook.cjs +4 -3
- package/adapters/_shared/runtime-assets.cjs +24 -0
- package/adapters/_shared/tests/handbook.test.cjs +4 -0
- package/adapters/_shared/tests/runtime-assets.test.cjs +11 -4
- package/adapters/claude.js +28 -5
- package/adapters/kimi.js +15 -138
- package/adapters/opencode.js +22 -49
- package/adapters/tests/claude.test.cjs +22 -8
- package/adapters/tests/codex.test.cjs +21 -8
- package/adapters/tests/kimi-hook.test.cjs +1 -1
- package/adapters/tests/kimi.test.cjs +11 -11
- package/adapters/tests/opencode.test.cjs +47 -8
- package/agents/code-reviewer.md +24 -85
- package/agents/debugger.md +30 -132
- package/agents/review-code.md +24 -104
- package/agents/review-comments.md +20 -83
- package/agents/review-coordinator.md +40 -137
- package/agents/review-design.md +21 -118
- package/agents/review-errors.md +22 -70
- package/agents/review-spec.md +36 -0
- package/agents/review-tests.md +20 -76
- package/agents/tdd-runner.md +26 -84
- package/commands/learn.md +5 -36
- package/commands/ultra-change.md +5 -43
- package/commands/ultra-deliver.md +4 -46
- package/commands/ultra-dev.md +4 -48
- package/commands/ultra-doctor.md +4 -30
- package/commands/ultra-init.md +5 -47
- package/commands/ultra-plan.md +5 -48
- package/commands/ultra-research.md +5 -54
- package/commands/ultra-status.md +5 -44
- package/commands/ultra-test.md +5 -45
- package/commands/ultra-think.md +5 -40
- package/docs/AGENT-CONTEXT.md +16 -8
- package/docs/ARCHITECTURE.md +32 -5
- package/docs/PLAN.zh-CN.md +8 -6
- package/docs/ROADMAP.md +5 -3
- package/docs/RUNTIME-COMPAT-MATRIX.md +8 -5
- package/docs/SKILL-AUTHORING.md +75 -0
- package/docs/STATE-DB-ACCESS-POLICY.md +17 -11
- package/docs/USER-HANDBOOK-CONTRACT.md +8 -5
- package/hooks/README.md +4 -3
- package/hooks/adapters/codex.py +1 -1
- package/hooks/adapters/kimi.py +1 -1
- package/hooks/context_spine.py +120 -16
- package/hooks/health_check.py +11 -0
- package/hooks/pre_stop_check.py +6 -5
- package/mcp-server/lib/baseline-workflow.cjs +415 -0
- package/mcp-server/lib/baseline-workflow.test.cjs +225 -0
- package/mcp-server/lib/change-workflow.cjs +24 -27
- package/mcp-server/lib/change-workflow.test.cjs +202 -6
- package/mcp-server/lib/context-spine.cjs +74 -9
- package/mcp-server/lib/context-spine.test.cjs +15 -0
- package/mcp-server/lib/doctor.cjs +14 -0
- package/mcp-server/lib/doctor.test.cjs +25 -1
- package/mcp-server/lib/init-project.cjs +49 -14
- package/mcp-server/lib/provider-refs.cjs +42 -0
- package/mcp-server/lib/spec-learning.test.cjs +5 -0
- package/mcp-server/lib/state-db.cjs +63 -4
- package/mcp-server/lib/state-db.test.cjs +8 -3
- package/mcp-server/server.cjs +48 -3
- package/mcp-server/tests/init-project.test.cjs +54 -8
- package/mcp-server/tests/server-contract.test.cjs +99 -2
- package/mcp-server/tests/state-db.test.cjs +11 -2
- package/package.json +3 -2
- package/skills/cc-collab/SKILL.md +16 -18
- package/skills/code-review-expert/SKILL.md +39 -114
- package/skills/code-review-expert/references/correctness-reliability.md +30 -0
- package/skills/code-review-expert/references/design-boundaries.md +26 -0
- package/skills/code-review-expert/references/removal-plan.md +17 -45
- package/skills/codex-collab/SKILL.md +23 -28
- package/skills/codex-collab/evals/evals.json +18 -23
- package/skills/integration-rules/SKILL.md +28 -67
- package/skills/learn/SKILL.md +46 -106
- package/skills/security-rules/SKILL.md +34 -56
- package/skills/testing-rules/SKILL.md +28 -52
- package/skills/ultra-change/SKILL.md +68 -114
- package/skills/ultra-deliver/SKILL.md +58 -86
- package/skills/ultra-dev/SKILL.md +46 -105
- package/skills/ultra-doctor/SKILL.md +45 -72
- package/skills/ultra-init/SKILL.md +62 -147
- package/skills/ultra-init/references/brownfield-adoption.md +65 -0
- package/skills/ultra-plan/SKILL.md +56 -89
- package/skills/ultra-research/SKILL.md +64 -152
- package/skills/ultra-research/references/architecture.md +38 -0
- package/skills/ultra-research/references/problem-product.md +39 -0
- package/skills/ultra-research/references/quality-delivery.md +34 -0
- package/skills/ultra-research/references/synthesis.md +38 -0
- package/skills/ultra-research/references/users-scope.md +40 -0
- package/skills/ultra-review/SKILL.md +54 -98
- package/skills/ultra-review/references/unified-schema.md +76 -101
- package/skills/ultra-review/scripts/review_wait.py +242 -77
- package/skills/ultra-status/SKILL.md +41 -56
- package/skills/ultra-test/SKILL.md +37 -72
- package/skills/ultra-think/SKILL.md +43 -102
- package/skills/ultra-verify/SKILL.md +44 -84
- package/skills/ultra-verify/evals/evals.json +24 -27
- package/spec/cli-protocol.md +4 -0
- package/spec/mcp-tools.yaml +223 -4
- package/spec/schemas/command-manifest.schema.json +7 -25
- package/spec/schemas/mcp-tools.schema.json +1 -1
- package/spec/schemas/skill-manifest.schema.json +9 -79
- package/spec/schemas/state-db.sql +33 -2
- package/ultra-tools/commands/status.cjs +20 -2
- package/ultra-tools/commands/task.cjs +4 -1
- package/ultra-tools/status-command.test.cjs +20 -0
- package/ultra-tools/system-command.test.cjs +5 -0
- package/skills/code-review-expert/references/code-quality-checklist.md +0 -112
- package/skills/code-review-expert/references/integration-checklist.md +0 -46
- package/skills/code-review-expert/references/security-checklist.md +0 -100
- package/skills/code-review-expert/references/solid-checklist.md +0 -65
- package/skills/ultra-research/steps/step-00-problem-validation.md +0 -154
- package/skills/ultra-research/steps/step-01-opportunity-discovery.md +0 -172
- package/skills/ultra-research/steps/step-02-market-assessment.md +0 -195
- package/skills/ultra-research/steps/step-03-competitive-landscape.md +0 -197
- package/skills/ultra-research/steps/step-04-product-strategy.md +0 -196
- package/skills/ultra-research/steps/step-05-assumptions-validation.md +0 -234
- package/skills/ultra-research/steps/step-10-user-personas.md +0 -169
- package/skills/ultra-research/steps/step-11-user-scenarios.md +0 -181
- package/skills/ultra-research/steps/step-20-user-stories.md +0 -156
- package/skills/ultra-research/steps/step-21-features-scope.md +0 -157
- package/skills/ultra-research/steps/step-22-success-metrics.md +0 -195
- package/skills/ultra-research/steps/step-30-architecture-context.md +0 -154
- package/skills/ultra-research/steps/step-31-solution-strategy.md +0 -172
- package/skills/ultra-research/steps/step-32-building-blocks.md +0 -188
- package/skills/ultra-research/steps/step-40-deployment.md +0 -123
- package/skills/ultra-research/steps/step-41-quality-risks.md +0 -135
- package/skills/ultra-research/steps/step-99-synthesis.md +0 -188
- package/skills/ultra-review/scripts/review_verdict_update.py +0 -99
|
@@ -1,156 +1,68 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: ultra-research
|
|
3
|
-
description:
|
|
4
|
-
user-invocable: true
|
|
3
|
+
description: Turn uncertain product or architecture intent into evidence-backed baseline specifications with explicit decisions and traceable acceptance. Use when an Ultra project has unresolved requirements that are not ready for planning.
|
|
5
4
|
---
|
|
6
5
|
|
|
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
|
-
| 20 | `step-20-user-stories.md` | User stories with acceptance criteria | product.md §4 |
|
|
71
|
-
| 21 | `step-21-features-scope.md` | Feature prioritization + explicit exclusions | product.md §5 |
|
|
72
|
-
| 22 | `step-22-success-metrics.md` | Business + user metrics with targets | product.md §6 |
|
|
73
|
-
|
|
74
|
-
### Round 3: Architecture Design
|
|
75
|
-
|
|
76
|
-
| Step | File | Focus | Output |
|
|
77
|
-
|------|------|-------|--------|
|
|
78
|
-
| 30 | `step-30-architecture-context.md` | Quality goals, constraints, system context | architecture.md §1-3 |
|
|
79
|
-
| 31 | `step-31-solution-strategy.md` | Tech stack selection with rationale | architecture.md §4 |
|
|
80
|
-
| 32 | `step-32-building-blocks.md` | Module decomposition + runtime scenarios | architecture.md §5-6 |
|
|
81
|
-
|
|
82
|
-
### Round 4: Quality & Deployment
|
|
83
|
-
|
|
84
|
-
| Step | File | Focus | Output |
|
|
85
|
-
|------|------|-------|--------|
|
|
86
|
-
| 40 | `step-40-deployment.md` | Infrastructure, environments, CI/CD | architecture.md §7-9 |
|
|
87
|
-
| 41 | `step-41-quality-risks.md` | Quality scenarios, risks, tech debt | architecture.md §10-12 |
|
|
88
|
-
|
|
89
|
-
### Synthesis
|
|
90
|
-
|
|
91
|
-
| Step | File | Focus | Output |
|
|
92
|
-
|------|------|-------|--------|
|
|
93
|
-
| 99 | `step-99-synthesis.md` | Distillate + validation + quality summary | research-distillate.md |
|
|
94
|
-
|
|
95
|
-
## ACTIVATION
|
|
96
|
-
|
|
97
|
-
When invoked, follow this sequence:
|
|
98
|
-
|
|
99
|
-
### 1. Pre-Research Check
|
|
100
|
-
|
|
101
|
-
- If `.ultra/specs/product.md` has [NEEDS CLARIFICATION] → proceed with research
|
|
102
|
-
- If `.ultra/specs/` doesn't exist → suggest `/ultra-init` first
|
|
103
|
-
- If specs 100% complete → suggest skip to `/ultra-plan`
|
|
104
|
-
|
|
105
|
-
### 2. Project Type Detection
|
|
106
|
-
|
|
107
|
-
Ask user to determine research scope:
|
|
108
|
-
|
|
109
|
-
| Type | Steps | Focus |
|
|
110
|
-
|------|-------|-------|
|
|
111
|
-
| Full Project | 00-99 | All rounds |
|
|
112
|
-
| Product Only | 00-22 | Discovery + product |
|
|
113
|
-
| Feature Only | 10-22 | User scenarios + features (skip discovery) |
|
|
114
|
-
| Architecture Change | 30-41 | Architecture + deployment |
|
|
115
|
-
| Custom | User selects | Specific steps |
|
|
116
|
-
|
|
117
|
-
**Round 0 skip conditions**: Skip if user provides existing market research, validated strategy docs, or explicitly states "I already know the market".
|
|
118
|
-
|
|
119
|
-
### 3. Begin Step Execution
|
|
120
|
-
|
|
121
|
-
Read the first applicable step file:
|
|
122
|
-
```
|
|
123
|
-
Read: skills/ultra-research/steps/step-{NN}-{name}.md
|
|
124
|
-
```
|
|
125
|
-
|
|
126
|
-
Follow every instruction in that file. When the step is complete and user confirms [C], read the next step file.
|
|
127
|
-
|
|
128
|
-
### 4. Output Files
|
|
129
|
-
|
|
130
|
-
| File | Content |
|
|
131
|
-
|------|---------|
|
|
132
|
-
| `.ultra/specs/discovery.md` | §0-5: Problem, Opportunities, Market, Competition, Strategy, Assumptions |
|
|
133
|
-
| `.ultra/specs/product.md` | §1-6: Problem, Personas, Scenarios, Stories, Scope, Metrics |
|
|
134
|
-
| `.ultra/specs/architecture.md` | §1-12: arc42 structure |
|
|
135
|
-
| `.ultra/specs/research-distillate.md` | Token-efficient summary for /ultra-plan consumption |
|
|
136
|
-
| `.ultra/docs/research/*.md` | Per-round research reports |
|
|
137
|
-
|
|
138
|
-
## QUALITY STANDARDS
|
|
139
|
-
|
|
140
|
-
| Element | Requirement |
|
|
141
|
-
|---------|-------------|
|
|
142
|
-
| Sources | Every factual claim has URL citation |
|
|
143
|
-
| Confidence | 90%+ for recommendations |
|
|
144
|
-
| Code | Production-ready (no TODO/demo) |
|
|
145
|
-
| Trade-offs | Quantified pros/cons |
|
|
146
|
-
| Next steps | Specific, actionable items |
|
|
147
|
-
|
|
148
|
-
## COMPLETION
|
|
149
|
-
|
|
150
|
-
Research is complete when:
|
|
151
|
-
- All selected steps have [C] confirmed by user
|
|
152
|
-
- All spec files have no [NEEDS CLARIFICATION] markers
|
|
153
|
-
- Research distillate generated
|
|
154
|
-
- All recommendations have 90%+ confidence
|
|
155
|
-
|
|
156
|
-
**Next**: Run `/ultra-plan` to generate task breakdown from complete specs.
|
|
6
|
+
# Build a validated baseline
|
|
7
|
+
|
|
8
|
+
Research only the uncertainty that blocks a durable product, architecture, or delivery
|
|
9
|
+
decision. Do not force a fixed discovery ceremony onto a well-defined change.
|
|
10
|
+
|
|
11
|
+
## Preflight
|
|
12
|
+
|
|
13
|
+
1. Require an initialized `.ultra/specs/` directory and call `baseline.get`. Route to
|
|
14
|
+
`ultra-init` when state or the baseline is absent. Preserve its mode and id.
|
|
15
|
+
2. Read the current specification files and repository evidence before asking the
|
|
16
|
+
user to repeat known facts.
|
|
17
|
+
3. Define the intended deliverable, unresolved decisions, and evidence standard.
|
|
18
|
+
4. Select only the research lanes that the uncertainty requires:
|
|
19
|
+
- problem and product: `references/problem-product.md`;
|
|
20
|
+
- users and scope: `references/users-scope.md`;
|
|
21
|
+
- architecture: `references/architecture.md`;
|
|
22
|
+
- quality and delivery: `references/quality-delivery.md`;
|
|
23
|
+
- final traceability: `references/synthesis.md`.
|
|
24
|
+
|
|
25
|
+
Read a reference completely only when its lane is selected. Do not load all lanes by
|
|
26
|
+
default.
|
|
27
|
+
|
|
28
|
+
## Evidence discipline
|
|
29
|
+
|
|
30
|
+
- Prefer the current checkout and existing project artifacts for repository facts.
|
|
31
|
+
- Browse only when a claim is external, unstable, or requires primary-source support.
|
|
32
|
+
- Prefer official and primary sources; cite each consequential external claim near the
|
|
33
|
+
statement it supports.
|
|
34
|
+
- Separate observed facts, evidence-backed inferences, user decisions, and unresolved
|
|
35
|
+
assumptions.
|
|
36
|
+
- Do not manufacture confidence percentages, market numbers, personas, competitors,
|
|
37
|
+
or options when evidence does not support them.
|
|
38
|
+
|
|
39
|
+
## Workflow
|
|
40
|
+
|
|
41
|
+
1. Build a short research agenda from the selected lanes and the decisions they must
|
|
42
|
+
unlock.
|
|
43
|
+
2. Gather evidence before recommending a direction. Ask one concise question when a
|
|
44
|
+
user decision is load-bearing; batch independent low-impact questions only when it
|
|
45
|
+
improves flow.
|
|
46
|
+
3. Present material tradeoffs before recording a decision. Comparisons are appropriate
|
|
47
|
+
only when real alternatives share meaningful criteria.
|
|
48
|
+
4. Update the relevant baseline specification sections. Preserve source links,
|
|
49
|
+
decisions, rejected alternatives when useful, acceptance criteria, and explicit
|
|
50
|
+
open questions. Do not duplicate the same narrative across several files.
|
|
51
|
+
5. Validate cross-document consistency and trace each required behavior from problem
|
|
52
|
+
or constraint to acceptance and architecture.
|
|
53
|
+
6. Use `references/synthesis.md` for the completion check.
|
|
54
|
+
7. Call `baseline.record` with the complete current specification list, bounded evidence
|
|
55
|
+
references, actual verification results, provider metadata, and explicit unknowns.
|
|
56
|
+
Use the returned repository revision for convergence.
|
|
57
|
+
8. Present the baseline and any known-red verification to the owner. After explicit
|
|
58
|
+
approval, call `baseline.converge`. Resolve deterministic blockers before routing.
|
|
59
|
+
|
|
60
|
+
## Completion gate
|
|
61
|
+
|
|
62
|
+
Research is complete when the selected scope has enough evidence for planning, every
|
|
63
|
+
material decision is recorded, required acceptance is testable, architecture respects
|
|
64
|
+
known constraints, and unresolved items are either blocking or explicitly outside the
|
|
65
|
+
accepted scope.
|
|
66
|
+
|
|
67
|
+
Route a converged baseline to `ultra-plan`. Do not create business tasks, write raw
|
|
68
|
+
SQLite, or maintain a second condensed specification that can drift from the baseline.
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
# Architecture research
|
|
2
|
+
|
|
3
|
+
Read this reference when the system boundary, quality attributes, integration seams,
|
|
4
|
+
technology choice, or implementation constraints are unresolved.
|
|
5
|
+
|
|
6
|
+
## Current system evidence
|
|
7
|
+
|
|
8
|
+
Start from the current checkout:
|
|
9
|
+
|
|
10
|
+
- entry points and external interfaces;
|
|
11
|
+
- domain boundaries and authoritative state;
|
|
12
|
+
- data flows and side effects;
|
|
13
|
+
- existing dependencies and deployment topology;
|
|
14
|
+
- failure, recovery, authorization, and observability paths.
|
|
15
|
+
|
|
16
|
+
Do not design a replacement architecture before identifying the live path and the
|
|
17
|
+
constraint that requires change.
|
|
18
|
+
|
|
19
|
+
## Decision method
|
|
20
|
+
|
|
21
|
+
For each material architecture decision:
|
|
22
|
+
|
|
23
|
+
1. state the required capability and quality constraints;
|
|
24
|
+
2. identify credible options already compatible with the system when possible;
|
|
25
|
+
3. use official primary documentation for library or platform behavior;
|
|
26
|
+
4. evaluate integration cost, operability, failure modes, migration, and rollback;
|
|
27
|
+
5. record the selected option, rejected alternatives that may recur, and the evidence
|
|
28
|
+
that would reopen the decision.
|
|
29
|
+
|
|
30
|
+
Do not compare technologies for ceremony. A single established repository pattern is
|
|
31
|
+
the default when it satisfies the contract.
|
|
32
|
+
|
|
33
|
+
## Record the result
|
|
34
|
+
|
|
35
|
+
Update the architecture specification with system context, boundaries, building
|
|
36
|
+
blocks, runtime flow, authoritative state, external contracts, quality scenarios,
|
|
37
|
+
deployment constraints, and accepted decisions. Connect each required behavior to a
|
|
38
|
+
reachable public seam and a verification approach.
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# Problem and product research
|
|
2
|
+
|
|
3
|
+
Read this reference when the problem, value, market context, or product direction is
|
|
4
|
+
uncertain.
|
|
5
|
+
|
|
6
|
+
## Establish the problem
|
|
7
|
+
|
|
8
|
+
- Identify the affected actor, current behavior, observable cost, and desired outcome.
|
|
9
|
+
- Distinguish user evidence from stakeholder belief and solution preference.
|
|
10
|
+
- Find current alternatives, including manual work or doing nothing.
|
|
11
|
+
- State what evidence would disprove the problem framing.
|
|
12
|
+
|
|
13
|
+
Use repository artifacts, support data, interviews, analytics, or primary external
|
|
14
|
+
sources that actually exist. Do not invent quotes, demand, or market size.
|
|
15
|
+
|
|
16
|
+
## Decide how much market work is needed
|
|
17
|
+
|
|
18
|
+
Market sizing and competitive research are optional. Use them only when they affect a
|
|
19
|
+
funding, positioning, pricing, or build-versus-buy decision.
|
|
20
|
+
|
|
21
|
+
When needed:
|
|
22
|
+
|
|
23
|
+
1. define the market boundary and time period;
|
|
24
|
+
2. show the calculation inputs and sources;
|
|
25
|
+
3. separate direct, adjacent, and substitute alternatives;
|
|
26
|
+
4. explain how the evidence changes the product decision.
|
|
27
|
+
|
|
28
|
+
Do not present unsourced top-down totals or call a category competitor-free.
|
|
29
|
+
|
|
30
|
+
## Record the result
|
|
31
|
+
|
|
32
|
+
Update the discovery specification with:
|
|
33
|
+
|
|
34
|
+
- problem and affected actors;
|
|
35
|
+
- observed evidence and source quality;
|
|
36
|
+
- desired outcome and non-goals;
|
|
37
|
+
- material alternatives and tradeoffs;
|
|
38
|
+
- assumptions, validation method, and blocking questions;
|
|
39
|
+
- the accepted product decision and why it follows from the evidence.
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# Quality and delivery research
|
|
2
|
+
|
|
3
|
+
Read this reference when acceptance depends on operational risk, security, migration,
|
|
4
|
+
deployment, recovery, or release constraints.
|
|
5
|
+
|
|
6
|
+
## Risk-driven quality
|
|
7
|
+
|
|
8
|
+
Identify failures that would materially affect users, data, authorization, money,
|
|
9
|
+
availability, or recoverability. For each relevant risk, record:
|
|
10
|
+
|
|
11
|
+
- trigger and affected boundary;
|
|
12
|
+
- expected behavior and observable signal;
|
|
13
|
+
- prevention, detection, and recovery;
|
|
14
|
+
- verification method and owner.
|
|
15
|
+
|
|
16
|
+
Apply security, performance, accessibility, and resilience checks according to the
|
|
17
|
+
actual product surface. Do not impose generic categories or coverage percentages when
|
|
18
|
+
they do not define acceptance.
|
|
19
|
+
|
|
20
|
+
## Delivery path
|
|
21
|
+
|
|
22
|
+
Capture the environments, configuration authority, migration order, compatibility
|
|
23
|
+
window, health and readiness checks, observability, rollout, rollback, and operator
|
|
24
|
+
actions needed for this product.
|
|
25
|
+
|
|
26
|
+
Prefer existing repository and platform workflows. Add a new service, dependency, or
|
|
27
|
+
deployment mechanism only when the accepted architecture requires it.
|
|
28
|
+
|
|
29
|
+
## Record the result
|
|
30
|
+
|
|
31
|
+
Update the architecture and product specifications with testable quality scenarios,
|
|
32
|
+
delivery constraints, failure behavior, recovery evidence, and release acceptance.
|
|
33
|
+
Keep exact volatile commands in the repository's runbook when they are operational
|
|
34
|
+
procedure rather than durable architecture.
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
# Baseline synthesis and validation
|
|
2
|
+
|
|
3
|
+
Read this reference after the selected research lanes are complete.
|
|
4
|
+
|
|
5
|
+
## Traceability check
|
|
6
|
+
|
|
7
|
+
Verify that each accepted outcome has:
|
|
8
|
+
|
|
9
|
+
1. supporting problem, user, or constraint evidence;
|
|
10
|
+
2. an explicit decision and scope boundary;
|
|
11
|
+
3. testable acceptance behavior;
|
|
12
|
+
4. a compatible architecture or delivery path;
|
|
13
|
+
5. a named unresolved blocker when any link is missing.
|
|
14
|
+
|
|
15
|
+
Check the reverse direction as well: every proposed component, dependency, and quality
|
|
16
|
+
requirement must support an accepted outcome or constraint.
|
|
17
|
+
|
|
18
|
+
## Consistency check
|
|
19
|
+
|
|
20
|
+
- Use one term for each actor, boundary, and authoritative data source.
|
|
21
|
+
- Remove duplicate narratives and stale alternatives.
|
|
22
|
+
- Keep source links next to the claims they support.
|
|
23
|
+
- Separate durable decisions from volatile external facts.
|
|
24
|
+
- Preserve explicit non-goals and rejected alternatives only when they prevent a
|
|
25
|
+
likely future mistake.
|
|
26
|
+
|
|
27
|
+
## Handoff
|
|
28
|
+
|
|
29
|
+
Report:
|
|
30
|
+
|
|
31
|
+
- validated scope and decisive evidence;
|
|
32
|
+
- specification files changed;
|
|
33
|
+
- accepted decisions and material uncertainty;
|
|
34
|
+
- blockers, or an explicit statement that none remain;
|
|
35
|
+
- one next action.
|
|
36
|
+
|
|
37
|
+
Do not create a parallel summary document solely for model consumption. The planning
|
|
38
|
+
workflow should read the smallest authoritative baseline sections it needs.
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# Users, behavior, and scope
|
|
2
|
+
|
|
3
|
+
Read this reference when actors, workflows, acceptance, boundaries, or success signals
|
|
4
|
+
are unclear.
|
|
5
|
+
|
|
6
|
+
## Actors and scenarios
|
|
7
|
+
|
|
8
|
+
Model only actors supported by evidence. Prefer roles and jobs over fictional persona
|
|
9
|
+
biographies. For each material scenario, capture:
|
|
10
|
+
|
|
11
|
+
- trigger and preconditions;
|
|
12
|
+
- actor goal;
|
|
13
|
+
- main flow and system response;
|
|
14
|
+
- important failure or recovery path;
|
|
15
|
+
- observable completion signal.
|
|
16
|
+
|
|
17
|
+
## Acceptance and scope
|
|
18
|
+
|
|
19
|
+
Turn scenarios into testable behavior. Each requirement should name the observable
|
|
20
|
+
outcome, relevant constraints, and how success can be verified.
|
|
21
|
+
|
|
22
|
+
Define:
|
|
23
|
+
|
|
24
|
+
- included behavior required for the accepted outcome;
|
|
25
|
+
- explicit non-goals;
|
|
26
|
+
- dependencies and assumptions;
|
|
27
|
+
- deferred work only when a real sequencing decision exists.
|
|
28
|
+
|
|
29
|
+
Avoid arbitrary release buckets or a fixed number of stories. Scope follows the
|
|
30
|
+
validated outcome and delivery constraint.
|
|
31
|
+
|
|
32
|
+
## Success signals
|
|
33
|
+
|
|
34
|
+
Choose metrics only when they will guide a decision. Define the event, population,
|
|
35
|
+
window, source, owner, and interpretation. Do not invent target values; record a
|
|
36
|
+
baseline, a user-approved target, or the experiment needed to establish one.
|
|
37
|
+
|
|
38
|
+
Update the product specification with actors, scenarios, acceptance, scope, non-goals,
|
|
39
|
+
and decision-relevant success signals. Keep business facts in their source system and
|
|
40
|
+
link them rather than copying volatile datasets into the specification.
|
|
@@ -1,125 +1,81 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: ultra-review
|
|
3
|
-
description:
|
|
4
|
-
user-invocable: true
|
|
5
|
-
runtime: all
|
|
6
|
-
mcp_tools_required:
|
|
7
|
-
- change.list
|
|
8
|
-
- change.get
|
|
9
|
-
- change.context
|
|
10
|
-
- change.breadcrumb
|
|
11
|
-
- task.list
|
|
3
|
+
description: Run independent specification-fidelity and engineering reviews over one current diff using bounded workers and file-based evidence. Use when implementation needs a read-only review gate before task completion or delivery.
|
|
12
4
|
---
|
|
13
5
|
|
|
14
|
-
#
|
|
6
|
+
# Review one current diff
|
|
15
7
|
|
|
16
|
-
|
|
8
|
+
Keep two verdict axes independent:
|
|
17
9
|
|
|
18
|
-
1. `spec_fidelity`:
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
tested, observable, and recoverable?
|
|
10
|
+
1. `spec_fidelity`: intent, acceptance, delta, documentation impact, and public seam;
|
|
11
|
+
2. `engineering_standards`: correctness, safety, maintainability, testing,
|
|
12
|
+
observability, and recovery.
|
|
22
13
|
|
|
23
|
-
One axis cannot compensate for the other.
|
|
24
|
-
|
|
25
|
-
and axis; it may not silently downgrade or rerank findings.
|
|
14
|
+
One axis cannot compensate for the other. Preserve each finding's source, severity,
|
|
15
|
+
file and line, and axis during coordination.
|
|
26
16
|
|
|
27
|
-
##
|
|
17
|
+
## Scope and context
|
|
28
18
|
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
/ultra-review recheck # unresolved P0/P1 scope
|
|
36
|
-
/ultra-review delta # files changed since last review
|
|
37
|
-
/ultra-review --range <range> | --pr <number>
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
## Phase 1: Scope and Context
|
|
41
|
-
|
|
42
|
-
1. Resolve one diff range and `DIFF_FILES`. Include staged and unstaged changes for
|
|
43
|
-
default working-tree review.
|
|
44
|
-
2. Bind to the single matching change through `change.list`/`task.list`; require an
|
|
45
|
-
explicit id if ambiguous.
|
|
46
|
-
3. Compile `change.context` with `role=review`, `gate=review`, spec/delta/test refs,
|
|
47
|
-
current diff paths, and the public-seam execution contract.
|
|
19
|
+
1. Resolve one explicit diff range and file set. Include staged and unstaged changes
|
|
20
|
+
for a default working-tree review.
|
|
21
|
+
2. Bind the single matching change through `change.list` and `task.list`; require an id
|
|
22
|
+
when ambiguous.
|
|
23
|
+
3. Compile `change.context` for the review role and gate with only the intent, delta,
|
|
24
|
+
acceptance, tests, diff paths, and public-seam contract needed for this review.
|
|
48
25
|
4. Stop on stale HEAD, blocked readiness, empty scope, or missing acceptance evidence.
|
|
49
|
-
5. Create `.ultra/reviews/<session-id>/`
|
|
50
|
-
|
|
26
|
+
5. Create `.ultra/reviews/<session-id>/` with the reviewed HEAD, range, change id,
|
|
27
|
+
selected workers, and a pending verdict.
|
|
51
28
|
|
|
52
|
-
|
|
53
|
-
the engineering axis reads the bounded diff and test evidence. Do not load unrelated
|
|
54
|
-
project history or external provider payloads.
|
|
29
|
+
## Run the independent fidelity axis
|
|
55
30
|
|
|
56
|
-
|
|
31
|
+
Always dispatch `review-spec` with only the accepted intent, delta, acceptance criteria,
|
|
32
|
+
public-seam context, current HEAD, and diff scope. Do not give it engineering findings
|
|
33
|
+
or an implementation rationale that is not part of the accepted contract. It writes
|
|
34
|
+
`spec-fidelity.json` with `axis: spec_fidelity`.
|
|
57
35
|
|
|
58
|
-
|
|
36
|
+
## Select engineering specialists
|
|
59
37
|
|
|
60
|
-
|
|
61
|
-
|---|---|
|
|
62
|
-
| `review-code` | correctness, security, live-path reachability |
|
|
63
|
-
| `review-tests` | meaningful coverage, mocks, red/green evidence |
|
|
64
|
-
| `review-errors` | swallowed failures, recovery, observability |
|
|
65
|
-
| `review-design` | types, boundaries, complexity, coupling |
|
|
66
|
-
| `review-comments` | stale or misleading comments/docs |
|
|
38
|
+
Use the smallest set that covers the diff. The delivery gate runs all five:
|
|
67
39
|
|
|
68
|
-
`
|
|
69
|
-
|
|
70
|
-
|
|
40
|
+
- `review-code`: correctness, security, and live-path reachability;
|
|
41
|
+
- `review-tests`: behavioral coverage and feedback-loop evidence;
|
|
42
|
+
- `review-errors`: hidden failures, recovery, and observability;
|
|
43
|
+
- `review-design`: types, boundaries, complexity, and coupling;
|
|
44
|
+
- `review-comments`: stale or misleading comments and documentation.
|
|
71
45
|
|
|
72
|
-
|
|
46
|
+
Record why any engineering specialist is skipped. The independent specification
|
|
47
|
+
worker is required for every change-linked review.
|
|
73
48
|
|
|
74
|
-
|
|
75
|
-
message when the current host supports it. Each bounded worker must:
|
|
49
|
+
## Execute bounded workers
|
|
76
50
|
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
51
|
+
Use the current host's native bounded-worker mechanism. Dispatch `review-spec` and the
|
|
52
|
+
selected engineering workers independently. Each worker must inspect only the supplied
|
|
53
|
+
diff and role context. Resolve `references/unified-schema.md` from this
|
|
54
|
+
Skill directory and pass that absolute path as `SCHEMA_PATH`; never make a worker infer
|
|
55
|
+
the plugin installation root. Each worker writes `<session>/<worker>.json` following
|
|
56
|
+
that contract, limits output to actionable findings, and returns only a short file
|
|
57
|
+
acknowledgement to the parent context.
|
|
83
58
|
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
## Phase 4: Wait & Coordinate (File-Based)
|
|
87
|
-
|
|
88
|
-
Validate worker files:
|
|
59
|
+
Resolve bundled paths relative to this skill directory. Validate the exact expected
|
|
60
|
+
artifacts before coordination:
|
|
89
61
|
|
|
90
62
|
```bash
|
|
91
|
-
python3
|
|
63
|
+
python3 scripts/review_wait.py <session-path> agents spec-fidelity review-code review-tests
|
|
92
64
|
```
|
|
93
65
|
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
```bash
|
|
98
|
-
python3 "$CLAUDE_PLUGIN_ROOT/skills/ultra-review/scripts/review_wait.py" {SESSION_PATH} summary
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
Partial worker completion is explicit. Zero valid worker files blocks the engineering
|
|
102
|
-
axis. A coordinator may merge duplicate root causes but must retain source ids and the
|
|
103
|
-
highest original severity/confidence without reinterpreting priorities.
|
|
104
|
-
|
|
105
|
-
## Phase 5: Report to User
|
|
106
|
-
|
|
107
|
-
`SUMMARY.json` must contain:
|
|
66
|
+
Pass only the engineering worker stems actually selected. Missing or invalid required
|
|
67
|
+
artifacts make the corresponding axis incomplete; a partial set is never a pass.
|
|
108
68
|
|
|
109
|
-
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
- unchanged source findings with axis/source provenance;
|
|
113
|
-
- overall verdict: `REQUEST_CHANGES` when either axis has P0/P1 or fails;
|
|
114
|
-
- incomplete/partial status and exact rerun command.
|
|
69
|
+
Run `review-coordinator` only after validation. It may merge duplicate root causes but
|
|
70
|
+
must retain source identifiers and the highest original severity.
|
|
71
|
+
Validate its summary with the same waiter.
|
|
115
72
|
|
|
116
|
-
Report
|
|
117
|
-
separate implementation action; review itself is read-only except for review artifacts.
|
|
118
|
-
After fixes, use `recheck` or `delta` rather than rerunning unrelated scope.
|
|
73
|
+
## Report and handoff
|
|
119
74
|
|
|
120
|
-
|
|
75
|
+
Report both axis verdicts first, followed by blocking findings and artifact paths.
|
|
76
|
+
Review is read-only except for review artifacts; fixes are a separate implementation
|
|
77
|
+
action. Recheck only unresolved or changed scope after fixes.
|
|
121
78
|
|
|
122
|
-
At the final HEAD,
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
`axis=engineering_standards`. A single aggregate “review passed” row is invalid.
|
|
79
|
+
At the final HEAD, compile review context with one convergence action. Delivery must
|
|
80
|
+
submit separate review evidence rows for `spec_fidelity` and
|
|
81
|
+
`engineering_standards`; a single aggregate pass is invalid.
|