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.
Files changed (137) hide show
  1. package/.ultra-template/specs/architecture.md +54 -223
  2. package/.ultra-template/specs/discovery.md +34 -231
  3. package/.ultra-template/specs/product.md +44 -200
  4. package/.ultra-template/tasks/contexts/TEMPLATE.md +36 -0
  5. package/.ultra-template/tasks/tasks.json +6 -0
  6. package/CHANGELOG.md +86 -1
  7. package/README.md +21 -9
  8. package/adapters/_shared/codex-assets.cjs +24 -342
  9. package/adapters/_shared/handbook.cjs +4 -3
  10. package/adapters/_shared/runtime-assets.cjs +24 -0
  11. package/adapters/_shared/tests/handbook.test.cjs +4 -0
  12. package/adapters/_shared/tests/runtime-assets.test.cjs +11 -4
  13. package/adapters/claude.js +28 -5
  14. package/adapters/kimi.js +15 -138
  15. package/adapters/opencode.js +22 -49
  16. package/adapters/tests/claude.test.cjs +22 -8
  17. package/adapters/tests/codex.test.cjs +21 -8
  18. package/adapters/tests/kimi-hook.test.cjs +1 -1
  19. package/adapters/tests/kimi.test.cjs +11 -11
  20. package/adapters/tests/opencode.test.cjs +47 -8
  21. package/agents/code-reviewer.md +24 -85
  22. package/agents/debugger.md +30 -132
  23. package/agents/review-code.md +24 -104
  24. package/agents/review-comments.md +20 -83
  25. package/agents/review-coordinator.md +40 -137
  26. package/agents/review-design.md +21 -118
  27. package/agents/review-errors.md +22 -70
  28. package/agents/review-spec.md +36 -0
  29. package/agents/review-tests.md +20 -76
  30. package/agents/tdd-runner.md +26 -84
  31. package/commands/learn.md +5 -36
  32. package/commands/ultra-change.md +5 -43
  33. package/commands/ultra-deliver.md +4 -46
  34. package/commands/ultra-dev.md +4 -48
  35. package/commands/ultra-doctor.md +4 -30
  36. package/commands/ultra-init.md +5 -47
  37. package/commands/ultra-plan.md +5 -48
  38. package/commands/ultra-research.md +5 -54
  39. package/commands/ultra-status.md +5 -44
  40. package/commands/ultra-test.md +5 -45
  41. package/commands/ultra-think.md +5 -40
  42. package/docs/AGENT-CONTEXT.md +16 -8
  43. package/docs/ARCHITECTURE.md +32 -5
  44. package/docs/PLAN.zh-CN.md +8 -6
  45. package/docs/ROADMAP.md +5 -3
  46. package/docs/RUNTIME-COMPAT-MATRIX.md +8 -5
  47. package/docs/SKILL-AUTHORING.md +75 -0
  48. package/docs/STATE-DB-ACCESS-POLICY.md +17 -11
  49. package/docs/USER-HANDBOOK-CONTRACT.md +8 -5
  50. package/hooks/README.md +4 -3
  51. package/hooks/adapters/codex.py +1 -1
  52. package/hooks/adapters/kimi.py +1 -1
  53. package/hooks/context_spine.py +120 -16
  54. package/hooks/health_check.py +11 -0
  55. package/hooks/pre_stop_check.py +6 -5
  56. package/mcp-server/lib/baseline-workflow.cjs +415 -0
  57. package/mcp-server/lib/baseline-workflow.test.cjs +225 -0
  58. package/mcp-server/lib/change-workflow.cjs +24 -27
  59. package/mcp-server/lib/change-workflow.test.cjs +202 -6
  60. package/mcp-server/lib/context-spine.cjs +74 -9
  61. package/mcp-server/lib/context-spine.test.cjs +15 -0
  62. package/mcp-server/lib/doctor.cjs +14 -0
  63. package/mcp-server/lib/doctor.test.cjs +25 -1
  64. package/mcp-server/lib/init-project.cjs +49 -14
  65. package/mcp-server/lib/provider-refs.cjs +42 -0
  66. package/mcp-server/lib/spec-learning.test.cjs +5 -0
  67. package/mcp-server/lib/state-db.cjs +63 -4
  68. package/mcp-server/lib/state-db.test.cjs +8 -3
  69. package/mcp-server/server.cjs +48 -3
  70. package/mcp-server/tests/init-project.test.cjs +54 -8
  71. package/mcp-server/tests/server-contract.test.cjs +99 -2
  72. package/mcp-server/tests/state-db.test.cjs +11 -2
  73. package/package.json +3 -2
  74. package/skills/cc-collab/SKILL.md +16 -18
  75. package/skills/code-review-expert/SKILL.md +39 -114
  76. package/skills/code-review-expert/references/correctness-reliability.md +30 -0
  77. package/skills/code-review-expert/references/design-boundaries.md +26 -0
  78. package/skills/code-review-expert/references/removal-plan.md +17 -45
  79. package/skills/codex-collab/SKILL.md +23 -28
  80. package/skills/codex-collab/evals/evals.json +18 -23
  81. package/skills/integration-rules/SKILL.md +28 -67
  82. package/skills/learn/SKILL.md +46 -106
  83. package/skills/security-rules/SKILL.md +34 -56
  84. package/skills/testing-rules/SKILL.md +28 -52
  85. package/skills/ultra-change/SKILL.md +68 -114
  86. package/skills/ultra-deliver/SKILL.md +58 -86
  87. package/skills/ultra-dev/SKILL.md +46 -105
  88. package/skills/ultra-doctor/SKILL.md +45 -72
  89. package/skills/ultra-init/SKILL.md +62 -147
  90. package/skills/ultra-init/references/brownfield-adoption.md +65 -0
  91. package/skills/ultra-plan/SKILL.md +56 -89
  92. package/skills/ultra-research/SKILL.md +64 -152
  93. package/skills/ultra-research/references/architecture.md +38 -0
  94. package/skills/ultra-research/references/problem-product.md +39 -0
  95. package/skills/ultra-research/references/quality-delivery.md +34 -0
  96. package/skills/ultra-research/references/synthesis.md +38 -0
  97. package/skills/ultra-research/references/users-scope.md +40 -0
  98. package/skills/ultra-review/SKILL.md +54 -98
  99. package/skills/ultra-review/references/unified-schema.md +76 -101
  100. package/skills/ultra-review/scripts/review_wait.py +242 -77
  101. package/skills/ultra-status/SKILL.md +41 -56
  102. package/skills/ultra-test/SKILL.md +37 -72
  103. package/skills/ultra-think/SKILL.md +43 -102
  104. package/skills/ultra-verify/SKILL.md +44 -84
  105. package/skills/ultra-verify/evals/evals.json +24 -27
  106. package/spec/cli-protocol.md +4 -0
  107. package/spec/mcp-tools.yaml +223 -4
  108. package/spec/schemas/command-manifest.schema.json +7 -25
  109. package/spec/schemas/mcp-tools.schema.json +1 -1
  110. package/spec/schemas/skill-manifest.schema.json +9 -79
  111. package/spec/schemas/state-db.sql +33 -2
  112. package/ultra-tools/commands/status.cjs +20 -2
  113. package/ultra-tools/commands/task.cjs +4 -1
  114. package/ultra-tools/status-command.test.cjs +20 -0
  115. package/ultra-tools/system-command.test.cjs +5 -0
  116. package/skills/code-review-expert/references/code-quality-checklist.md +0 -112
  117. package/skills/code-review-expert/references/integration-checklist.md +0 -46
  118. package/skills/code-review-expert/references/security-checklist.md +0 -100
  119. package/skills/code-review-expert/references/solid-checklist.md +0 -65
  120. package/skills/ultra-research/steps/step-00-problem-validation.md +0 -154
  121. package/skills/ultra-research/steps/step-01-opportunity-discovery.md +0 -172
  122. package/skills/ultra-research/steps/step-02-market-assessment.md +0 -195
  123. package/skills/ultra-research/steps/step-03-competitive-landscape.md +0 -197
  124. package/skills/ultra-research/steps/step-04-product-strategy.md +0 -196
  125. package/skills/ultra-research/steps/step-05-assumptions-validation.md +0 -234
  126. package/skills/ultra-research/steps/step-10-user-personas.md +0 -169
  127. package/skills/ultra-research/steps/step-11-user-scenarios.md +0 -181
  128. package/skills/ultra-research/steps/step-20-user-stories.md +0 -156
  129. package/skills/ultra-research/steps/step-21-features-scope.md +0 -157
  130. package/skills/ultra-research/steps/step-22-success-metrics.md +0 -195
  131. package/skills/ultra-research/steps/step-30-architecture-context.md +0 -154
  132. package/skills/ultra-research/steps/step-31-solution-strategy.md +0 -172
  133. package/skills/ultra-research/steps/step-32-building-blocks.md +0 -188
  134. package/skills/ultra-research/steps/step-40-deployment.md +0 -123
  135. package/skills/ultra-research/steps/step-41-quality-risks.md +0 -135
  136. package/skills/ultra-research/steps/step-99-synthesis.md +0 -188
  137. package/skills/ultra-review/scripts/review_verdict_update.py +0 -99
@@ -1,156 +1,68 @@
1
1
  ---
2
2
  name: ultra-research
3
- description: "Think-Driven Interactive Discovery - Deep research with step-file architecture for high-density output"
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
- # Ultra Research v2 — Step-File Architecture
8
-
9
- ## Overview
10
-
11
- Transform vague ideas into complete, high-confidence specifications through progressive interactive discovery. Each research step is a self-contained instruction file loaded just-in-time for maximum LLM attention density.
12
-
13
- **Philosophy**: Research is collaborative. Each decision validated with user before proceeding. All findings must have 90%+ confidence. Every claim needs a source.
14
-
15
- ## WORKFLOW ARCHITECTURE
16
-
17
- ### Core Principles
18
-
19
- - **Step-File Design**: Each step is a self-contained .md file with full execution instructions
20
- - **Just-In-Time Loading**: Only the current step file is in context — never load future steps
21
- - **Sequential Enforcement**: Steps must be completed in order, no skipping
22
- - **Write-Immediately**: Every step writes its output to the spec file BEFORE presenting to user
23
- - **User Gate**: User must explicitly confirm [C] Continue before proceeding to next step
24
- - **State Tracking**: Track per-session progress via the runtime's native TaskCreate/TaskUpdate (session-local). Research does NOT write business tasks to state.db — it only emits spec files. Business tasks are created later by `/ultra-plan` via MCP `task.create`.
25
- - **Web-First**: Every analysis step REQUIRES web search with citations. No search = no proceed.
26
-
27
- ### Step Processing Rules
28
-
29
- 1. **READ COMPLETELY**: Always read the entire step file before taking any action
30
- 2. **FOLLOW SEQUENCE**: Execute all numbered sections in order
31
- 3. **SEARCH FIRST**: Execute web searches BEFORE generating analysis
32
- 4. **WRITE IMMEDIATELY**: Append content to spec file as soon as analysis is complete
33
- 5. **WAIT FOR INPUT**: Present [C] Continue — halt and wait for user selection
34
- 6. **LOAD NEXT**: When user confirms, Read the next step file and follow it
35
-
36
- ### Critical Rules (NO EXCEPTIONS)
37
-
38
- - NEVER load multiple step files simultaneously
39
- - ALWAYS read entire step file before execution
40
- - NEVER skip steps or optimize the sequence
41
- - ALWAYS write output to spec file before presenting to user
42
- - ALWAYS halt at [C] Continue and wait for user input
43
- - NEVER proceed without user confirmation
44
- - NEVER rely solely on training data — web search is mandatory for factual claims
45
-
46
- ## STEP SEQUENCE
47
-
48
- ### Round 0: Product Discovery & Strategy
49
-
50
- | Step | File | Focus | Output |
51
- |------|------|-------|--------|
52
- | 00 | `step-00-problem-validation.md` | Validate the problem is real and worth solving | discovery.md §0 |
53
- | 01 | `step-01-opportunity-discovery.md` | Opportunity Solution Tree (Teresa Torres) | discovery.md §1 |
54
- | 02 | `step-02-market-assessment.md` | TAM/SAM/SOM with dual approach | discovery.md §2 |
55
- | 03 | `step-03-competitive-landscape.md` | Competitors + Porter's Five Forces | discovery.md §3 |
56
- | 04 | `step-04-product-strategy.md` | Vision, segments, value prop, trade-offs | discovery.md §4 |
57
- | 05 | `step-05-assumptions-validation.md` | Risk assumptions + experiment design | discovery.md §5 |
58
-
59
- ### Round 1: User & Scenario Discovery
60
-
61
- | Step | File | Focus | Output |
62
- |------|------|-------|--------|
63
- | 10 | `step-10-user-personas.md` | 2-3 personas with goals, pain points, context | product.md §1-2 |
64
- | 11 | `step-11-user-scenarios.md` | 3-5 user scenarios with trigger/flow/outcome | product.md §3 |
65
-
66
- ### Round 2: Feature Definition
67
-
68
- | Step | File | Focus | Output |
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: "Run two independent review axes over one current diff, using bounded specialist workers and file-based evidence without context pollution."
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
- # /ultra-review - Ultra Review System
6
+ # Review one current diff
15
7
 
16
- Review one explicit diff at the current HEAD. The top-level gates are independent:
8
+ Keep two verdict axes independent:
17
9
 
18
- 1. `spec_fidelity`: does the implementation satisfy intent, acceptance, delta,
19
- documentation impact, and public seam?
20
- 2. `engineering_standards`: is the implementation correct, safe, maintainable,
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. The coordinator may deduplicate the same
24
- root cause but must preserve each source finding's severity, confidence, file/line,
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
- ## Usage
17
+ ## Scope and context
28
18
 
29
- ```text
30
- /ultra-review # applicable specialists
31
- /ultra-review all # all five specialists; delivery gate
32
- /ultra-review quick # review-code only
33
- /ultra-review security # review-code + review-errors
34
- /ultra-review tests # review-tests only
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>/` and an index entry with reviewed HEAD,
50
- change id, mode, range, and `verdict=pending`.
26
+ 5. Create `.ultra/reviews/<session-id>/` with the reviewed HEAD, range, change id,
27
+ selected workers, and a pending verdict.
51
28
 
52
- The spec-fidelity axis reads only the bounded intent/delta/baseline/acceptance packet;
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
- ## Phase 2: Specialist Selection
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
- Five engineering specialists feed the two-axis result:
36
+ ## Select engineering specialists
59
37
 
60
- | Worker | Scope |
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
- `all` always runs all five. Other modes may skip a worker only when its scope is
69
- provably absent, and the skip reason is written to the session. Spec fidelity is never
70
- skipped for a change-linked review.
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
- ## Phase 3: Background Execution (Zero Context Pollution)
46
+ Record why any engineering specialist is skipped. The independent specification
47
+ worker is required for every change-linked review.
73
48
 
74
- Launch selected workers in background mode using multiple Task tool calls in a single
75
- message when the current host supports it. Each bounded worker must:
49
+ ## Execute bounded workers
76
50
 
77
- 1. read its installed worker instructions;
78
- 2. inspect only `DIFF_FILES`, `DIFF_RANGE`, and supplied role context;
79
- 3. write `{SESSION_PATH}/{worker}.json` following
80
- `$CLAUDE_PLUGIN_ROOT/skills/ultra-review/references/unified-schema.md`;
81
- 4. return at most 12 findings with confidence >= 75, ordered by its own severity;
82
- 5. output only a one-line file acknowledgement after the artifact exists.
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
- Do not copy worker transcripts into the parent context. Findings flow through files.
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 "$CLAUDE_PLUGIN_ROOT/skills/ultra-review/scripts/review_wait.py" {SESSION_PATH} agents {AGENT_COUNT}
63
+ python3 scripts/review_wait.py <session-path> agents spec-fidelity review-code review-tests
92
64
  ```
93
65
 
94
- Then run the installed `review-coordinator` over valid artifacts plus the independent
95
- spec-fidelity assessment. It writes `SUMMARY.json` and `SUMMARY.md`. Validate:
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
- - session/change id, reviewed HEAD/range, workers run/skipped;
110
- - `axes.spec_fidelity` and `axes.engineering_standards`, each with its own verdict and
111
- evidence refs;
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 the two axis verdicts first, then P0/P1 findings and the report path. Fixes are a
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
- ## Convergence handoff
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, recompile `change.context` with `role=review` and a next action of
123
- `Converge and deliver the verified change`. The delivery workflow must submit two
124
- separate `review` evidence rows: one with `axis=spec_fidelity`, one with
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.