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,77 +1,62 @@
1
1
  ---
2
2
  name: ultra-status
3
- description: "Route the project from its authoritative Ultra breadcrumb, readiness gates, task state, and current verification evidence."
4
- user-invocable: true
5
- runtime: all
6
- mcp_tools_required:
7
- - change.breadcrumb
8
- - change.list
9
- - task.list
10
- - task.get
11
- - session.list
12
- - system.doctor
13
- cli_fallback: "status --cost --json"
3
+ description: Report authoritative Ultra health, position, readiness, evidence freshness, and one deterministic next action. Use when the user asks where an Ultra project stands or what should happen next.
14
4
  ---
15
5
 
16
- # ultra-status — One Router, One Next Action
6
+ # Route from authoritative status
17
7
 
18
- Use this workflow to answer “where are we?” and “what should happen next?” without
19
- reconstructing project state from prose. `.ultra/state.db` is authoritative; reports
20
- and Markdown are evidence or projections.
8
+ Answer status questions without reconstructing state from prose. `.ultra/state.db` is
9
+ authoritative; reports and Markdown are evidence or projections.
21
10
 
22
11
  ## Read order
23
12
 
24
- 1. Call `system.doctor { repair: false }`. If authority is unhealthy, route only to
13
+ 1. Call `system.doctor` in read-only mode. If authority is unhealthy, route only to
25
14
  `ultra-doctor` and include the blocking diagnostic.
26
- 2. Call `change.breadcrumb`. It returns the active change, task, role, gate,
27
- readiness, blockers, stale status, and one deterministic next action.
28
- 3. Call `task.list` and `session.list` for counts and active execution detail.
29
- 4. Read `.ultra/test-report.json` and `.ultra/delivery-report.json` only when they
30
- exist. Treat a report from a different HEAD as stale.
31
- 5. Read git branch, HEAD, and worktree status. Do not mutate anything.
32
-
33
- Never fall back to `.ultra/tasks/tasks.json`, context Markdown frontmatter, or raw
34
- SQLite when MCP task state is unavailable. Label that panel unavailable.
35
-
36
- ## Routing rules
37
-
38
- The breadcrumb owns the primary route. Do not print a menu of every Ultra command.
39
-
40
- | State | Route |
41
- |---|---|
42
- | doctor unhealthy | `ultra-doctor` |
43
- | no Ultra project | `ultra-init` |
44
- | no baseline specs or tasks | `ultra-research` or `ultra-plan`, matching the missing artifact |
45
- | readiness blocked or context stale | recompile through `ultra-change`, `ultra-plan`, or `ultra-dev` as named by the breadcrumb |
46
- | implementation task ready | `ultra-dev <task-id>` |
47
- | all scoped tasks complete, test report missing/stale | `ultra-test` |
48
- | review or convergence incomplete | `ultra-review all` or `ultra-deliver`, matching the gate |
49
- | ready change | `ultra-deliver` |
50
- | archived change and clean HEAD | report complete; do not invent more work |
51
-
52
- When there is no active change, derive a single baseline route from tasks and reports.
53
- If several changes are active or blocked, report ambiguity and require an explicit
54
- change id instead of guessing.
15
+ 2. Call `baseline.get` for mode, lifecycle status, repository revision, specification
16
+ digest health, known warnings, and adoption blockers.
17
+ 3. Call `change.breadcrumb` for the active change, task, role, gate, readiness,
18
+ blockers, advisory warnings, staleness, and next action.
19
+ 4. Call `task.list` and `session.list` for progress and active execution details.
20
+ 5. Read test and delivery reports only when present, and mark a report stale when its
21
+ HEAD differs from the current checkout.
22
+ 6. Read Git branch, HEAD, and worktree status without mutation.
23
+
24
+ If MCP task or change state is unavailable, label that panel unavailable. Never fall
25
+ back to generated task JSON, context frontmatter, or raw SQLite.
26
+
27
+ ## Routing
28
+
29
+ Follow the breadcrumb's primary route and return one action, not a menu:
30
+
31
+ - unhealthy authority: `ultra-doctor`;
32
+ - missing Ultra project: `ultra-init`;
33
+ - missing baseline evidence with no active change: `ultra-init`, then
34
+ `ultra-research` or `ultra-plan` according to the gap;
35
+ - baseline or context-budget warning during an active change: keep the current route
36
+ and surface the warning; do not turn it into a refusal;
37
+ - blocked or stale context: the workflow named by the breadcrumb;
38
+ - ready implementation task: `ultra-dev <task-id>`;
39
+ - completed tasks with missing or stale test evidence: `ultra-test`;
40
+ - incomplete review or convergence: `ultra-review` or `ultra-deliver`;
41
+ - ready change: `ultra-deliver`;
42
+ - archived change with fresh evidence: report completion without inventing more work.
43
+
44
+ Require an explicit change id when several active changes make the route ambiguous.
55
45
 
56
46
  ## Output
57
47
 
58
- Keep the answer compact:
48
+ Use a compact shape:
59
49
 
60
50
  ```text
61
51
  Ultra: <healthy|degraded> · <branch>@<head> · worktree <clean|dirty>
62
52
  Position: change=<id|none> task=<id|none> role=<role> gate=<gate>
53
+ Baseline: <greenfield|brownfield|migrated>/<status> revision=<revision|none>
63
54
  Readiness: <ready|blocked|stale> — <blockers or none>
55
+ Warnings: <advisory conditions or none>
64
56
  Progress: <completed>/<total>; sessions=<active count>
65
57
  Evidence: tests=<fresh|stale|missing>; delivery=<fresh|stale|missing>
66
- Next: <exactly one action, including the task/change id when known>
58
+ Next: <one exact action>
67
59
  ```
68
60
 
69
- Separate verified facts from unavailable panels. Do not hide a stale context or stale
70
- test report behind an overall “healthy” label.
71
-
72
- ## Boundaries
73
-
74
- - Read-only: this workflow does not repair, compile context, update tasks, or release.
75
- - Cost data may use the declared CLI fallback, but task/change authority may not.
76
- - External memory and code graph providers are optional metadata references; their
77
- absence does not change Ultra authority.
61
+ This workflow is read-only. It does not repair state, compile context, update tasks, or
62
+ release software.
@@ -1,94 +1,59 @@
1
1
  ---
2
2
  name: ultra-test
3
- description: "Run the pre-delivery check gate from a fresh role context and record exact feedback-loop, wiring, recovery, and acceptance evidence."
4
- user-invocable: true
5
- runtime: all
6
- mcp_tools_required:
7
- - task.list
8
- - change.list
9
- - change.context
10
- - change.breadcrumb
3
+ description: Run an independent pre-delivery verification gate and record exact feedback-loop, reachability, recovery, and acceptance evidence. Use when scoped implementation tasks are complete and delivery readiness must be established.
11
4
  ---
12
5
 
13
- # ultra-test — Independent Check Context
6
+ # Verify delivery readiness
14
7
 
15
- This is the project/change pre-delivery gate, not a replacement for the task-level TDD
16
- loop. It produces `.ultra/test-report.json`; task and change authority remain in
17
- `.ultra/state.db`.
8
+ Run this gate from a fresh checking context. It complements task-level development
9
+ tests and writes `.ultra/test-report.json`; it does not replace authoritative task or
10
+ change state.
18
11
 
19
12
  ## Entry gate
20
13
 
21
- 1. Call `task.list`; require at least one completed task in scope.
22
- 2. Call `change.list` and bind to exactly one relevant active/blocked/ready change, or
23
- explicitly record `change_id: null` for an initial baseline.
24
- 3. For a change, compile `change.context` with `role=check`, `gate=verification`, only
25
- the tests/specs/source seams needed to verify it, and the same execution contract.
14
+ 1. Call `task.list` and require at least one completed task in scope.
15
+ 2. Call `change.list` and bind exactly one relevant change, or record a null change id
16
+ for an initial baseline.
17
+ 3. For a change, compile `change.context` for the checking role and verification gate
18
+ with only the specifications, tests, and source seams needed for acceptance.
26
19
  4. Call `change.breadcrumb`; stop when context is stale or readiness is blocked.
27
20
 
28
- Never fall back to `.ultra/tasks/tasks.json`. Do not reuse the implementer's full
21
+ Never use generated task JSON as authority or reuse the implementer's full
29
22
  conversation as test context.
30
23
 
31
- ## Verification matrix
24
+ ## Evidence matrix
32
25
 
33
- Build a matrix from acceptance claims to observable evidence:
26
+ Map each acceptance claim to observable evidence:
34
27
 
35
- | Check | Required evidence | Blocking condition |
28
+ | Check | Evidence | Blocking result |
36
29
  |---|---|---|
37
- | Feedback loop | exact command and observed green | command fails or no prior red for fix/incident |
38
- | Public seam | reachable entry-to-consumer path | orphan/stub/unwired behavior |
39
- | Regression | focused and adjacent suites | failure or meaningful skipped assertion |
40
- | Build/static | typecheck/lint/build as applicable | non-zero result |
41
- | Error/recovery | failure mode and recovery path | silent/swallowed/unrecoverable critical path |
42
- | Security | input/auth/secrets/dependency checks in scope | high-severity issue |
43
- | Docs/spec | delivered behavior matches declared delta | drift or unknown impact |
44
-
45
- Use repository-native commands and real boundaries where practical. Test doubles are
46
- acceptable only at costly or nondeterministic external boundaries and must be named.
47
-
48
- ## Quality checks
49
-
50
- - Detect tautologies, empty tests, weakened assertions, and core-domain over-mocking.
51
- - Find changed exports without meaningful test coverage.
52
- - Trace changed source into non-test consumers; flag orphan modules and placeholder
53
- handlers/components.
54
- - Exercise key API/UI/CLI flows when the project exposes them.
55
- - Inspect error handling, authorization, migrations, idempotency, and rollback in the
56
- affected risk surface.
57
- - Compare current HEAD and context digests with the implementation evidence.
58
-
59
- Do not mechanically require every possible test category. Mark a check
60
- `not_applicable` only with a concrete scope reason.
30
+ | Feedback loop | exact command and observed result | failure or missing baseline signal for a fix |
31
+ | Public seam | reachable entry-to-consumer path | orphan, stub, or unwired behavior |
32
+ | Regression | focused and adjacent suites | failure or weakened assertion |
33
+ | Static/build | applicable type, lint, and build commands | non-zero result |
34
+ | Error/recovery | exercised failure and recovery path | silent or unrecoverable critical path |
35
+ | Security | relevant input, authorization, secret, and dependency checks | high-impact exploitable issue |
36
+ | Docs/spec | delivered behavior matches the declared baseline or delta | drift or unknown impact |
37
+
38
+ Use repository-native commands and real boundaries when practical. Use test doubles
39
+ only at costly or nondeterministic external boundaries, and state why they preserve
40
+ the contract being tested.
41
+
42
+ Inspect tests for tautologies, empty assertions, hidden skips, excessive boundary
43
+ mocking, changed exports without behavioral coverage, and code with no non-test
44
+ consumer. Apply checks by risk and scope rather than forcing every category.
61
45
 
62
46
  ## Report contract
63
47
 
64
- Write `.ultra/test-report.json` atomically with at least:
65
-
66
- ```json
67
- {
68
- "schema_version": "2.0",
69
- "change_id": "<id-or-null>",
70
- "git_commit": "<full-head>",
71
- "context_manifest_hash": "<hash-or-null>",
72
- "passed": true,
73
- "feedback_loop": {
74
- "command": "<exact command>",
75
- "expected_red": "<failure contract or not-applicable reason>",
76
- "observed_red": true,
77
- "observed_green": true,
78
- "deterministic": true
79
- },
80
- "public_seams": ["<verified seam>"],
81
- "checks": [],
82
- "blocking_issues": [],
83
- "commands": []
84
- }
85
- ```
48
+ Write the report atomically with the current full HEAD, change id, context manifest
49
+ hash, exact commands, baseline and final signals, verified public seams, checks, and
50
+ blocking issues. Preserve concise failure excerpts instead of full logs.
86
51
 
87
- Set `passed=true` only when every required check passes, the report HEAD is current,
88
- and at least one public seam is verified. Preserve exact commands, exit results, and
89
- concise failure excerpts; do not paste full logs.
52
+ Set `passed: true` only when every required check passes, the report HEAD is current,
53
+ and at least one declared public seam is verified. A not-applicable check needs a
54
+ specific scope reason.
90
55
 
91
56
  ## Exit
92
57
 
93
- Call `change.breadcrumb` and route one next action: fix a named blocker, run
94
- `/ultra-review all`, or run `/ultra-deliver`. A stale report never routes to delivery.
58
+ Call `change.breadcrumb` and return one next action: fix a named blocker, run
59
+ `ultra-review`, or run `ultra-deliver`. A stale report never routes to delivery.
@@ -1,110 +1,51 @@
1
1
  ---
2
2
  name: ultra-think
3
- description: "Deep analysis with adversarial reasoning — Evidence-First + Multi-Perspective + Steel-Man + Pre-Mortem + Sensitivity. Produces a recommendation with confidence bounds."
4
- user-invocable: true
5
- runtime: all
6
- cli_fallback: "direct user interaction"
3
+ description: Produce an evidence-bounded recommendation or diagnosis for a consequential technical or product question. Use when the decision has material tradeoffs, uncertainty, or failure risk that benefits from explicit stress testing.
7
4
  ---
8
5
 
9
- # ultra-think — Phase 3.6
6
+ # Analyze a consequential question
10
7
 
11
- Reasoning harness for complex decisions / diagnostics / architecture calls.
12
- Enforces Evidence-First labelling and adversarial stress-tests before issuing
13
- a recommendation with explicit confidence.
8
+ Use the smallest reasoning structure that resolves the user's actual decision. Answer
9
+ simple questions directly; do not turn every request into a framework exercise.
14
10
 
15
11
  ## Workflow
16
12
 
17
- ### Step 1 — Scope Check
18
-
19
- If the problem is ambiguous / underspecified, ask up to **3** clarifying
20
- questions through the current Host's native user-interaction surface.
21
- If the problem is simple, **skip the framework**, answer concisely, and mark
22
- downstream steps `completed` with note `"skipped: simple answer path"`.
23
-
24
- ### Step 2 — Evidence Gathering
25
-
26
- Every factual claim about tech/API/best-practices must be verified via:
27
- - Repo source (Read/Grep)
28
- - Official docs (Context7 MCP: `mcp__context7__query-docs`)
29
- - Community (Exa MCP: `mcp__exa__web_search_exa`)
30
- - Web search (fallback)
31
-
32
- Label each assertion:
33
- - **Fact** — verified, cite source (URL / file path)
34
- - **Inference** — deduced from facts (show the derivation chain)
35
- - **Speculation** — unverified; list verification steps the user can run
36
-
37
- **Iron law**: never trade accuracy for speed. Wrong-with-confidence > "I don't know + here's how to check".
38
-
39
- ### Step 3 — Multi-Perspective Analysis
40
-
41
- Generate **≥3 distinct approaches**. For each, apply whichever lenses are relevant:
42
- - **Technical** — feasibility, scalability, security, maintainability
43
- - **Business** — value, cost, time-to-market, competitive advantage
44
- - **User** — needs, experience, edge cases, accessibility
45
- - **System** — integration, dependencies, emergent behaviors
46
-
47
- ### Step 4 — Adversarial Stress-Testing
48
-
49
- Apply all four techniques:
50
-
51
- | Technique | Question |
52
- |-----------|----------|
53
- | **Steel Man** | For the option you're inclined to REJECT, build its strongest possible case. What do you discover? |
54
- | **Pre-Mortem** | Assume the recommended option has failed in 6 months. List the 3 most likely causes. |
55
- | **Sensitivity** | Which single assumption, if wrong, would reverse your recommendation? |
56
- | **Second-Order** | What new problems does the recommendation create 6-12 months out? |
57
-
58
- ### Step 5 — Synthesis
59
-
60
- Recommendation with quantified confidence (0-100%) and explicit uncertainty bounds.
61
-
62
- ## Output Structure (adapt to problem type)
63
-
64
- ### Problem Statement
65
- 1-2 sentences: core decision + key constraints.
66
-
67
- ### Analysis
68
- Deep analysis using relevant lenses from Step 3.
69
-
70
- ### Options Comparison (skip for diagnostic/investigative problems)
71
- | Criterion | Weight | Option A | Option B | Option C |
72
- |-----------|-------:|----------|----------|----------|
73
- Quantified where possible.
74
-
75
- ### Adversarial Findings
76
- - **Strongest counter-argument** (steel man for rejected option)
77
- - **Pre-mortem top risk** (most likely failure + mitigation)
78
- - **Assumption sensitivity** (load-bearing assumption)
79
-
80
- ### Recommendation
81
- - **Choice**: <option>
82
- - **Confidence**: <X>% because <rationale>
83
- - **Key Assumptions**: what must be true
84
- - **What would change my mind**: specific evidence / outcome
85
-
86
- ### Verification Plan
87
- Concrete steps to validate the decision — metrics, tests, time-boxed experiments.
88
-
89
- ### Next Steps
90
- Ordered, actionable items.
91
-
92
- ## MCP → CLI fallback matrix
93
-
94
- | Purpose | MCP tool | CLI fallback |
95
- |---------|----------|--------------|
96
- | Clarifying questions | none | current Host's native user-interaction surface |
97
-
98
- ## What this skill DOES NOT do
99
-
100
- - Does NOT modify state.db or project files
101
- - Does NOT implement the recommendation (that's `/ultra-dev` after `/ultra-plan`)
102
- - Does NOT replace independent review — output is one model's analysis
103
-
104
- ## Integration
105
-
106
- | | |
107
- |---|---|
108
- | **Input** | the problem statement in `$ARGUMENTS`, optional repo context via Read/Grep, docs via Context7/Exa |
109
- | **Output** | structured Markdown report (Chinese per project rule) |
110
- | **Feeds** | decisions captured in `.ultra/specs/architecture.md` via Dual-Write Mode of `/ultra-dev` |
13
+ 1. State the decision, observed symptom, or disputed claim and the constraints that
14
+ could change the answer. Ask only for missing information that materially affects
15
+ the result.
16
+ 2. Gather evidence from the most authoritative available source:
17
+ - current checkout and runtime for repository claims;
18
+ - official primary documentation for product or API behavior;
19
+ - current web sources for unstable external facts.
20
+ 3. Separate verified facts, evidence-backed inferences, and unresolved assumptions.
21
+ Cite the supporting file, command, runtime result, or source near each consequential
22
+ claim.
23
+ 4. For a decision, compare only credible alternatives. Do not invent a fixed number of
24
+ options or assign arbitrary numeric scores. Name the criteria that actually drive
25
+ the choice and explain the tradeoffs.
26
+ 5. For a diagnosis, form falsifiable hypotheses and identify the smallest observation
27
+ that distinguishes them. Do not recommend implementation before the earliest
28
+ incorrect state is supported by evidence.
29
+ 6. Stress-test the leading conclusion with the techniques that fit the problem:
30
+ - strongest counterargument;
31
+ - likely failure scenario and recovery;
32
+ - load-bearing assumption;
33
+ - meaningful second-order effect.
34
+ 7. Return the recommendation or diagnosis, evidence, uncertainty, what would change
35
+ the conclusion, and the smallest verification step.
36
+
37
+ ## Output
38
+
39
+ Adapt the response to the question. Include:
40
+
41
+ - the conclusion first;
42
+ - the decisive evidence and tradeoffs;
43
+ - unresolved uncertainty without false precision;
44
+ - one concrete verification or follow-up action.
45
+
46
+ Use a comparison table only when several alternatives share the same decision
47
+ criteria. Comparisons are an analysis tool, not a required output section.
48
+
49
+ This skill is read-only unless the user separately authorizes writing an analysis
50
+ artifact. It does not update Ultra state, implement the recommendation, or replace an
51
+ independent review.
@@ -1,92 +1,52 @@
1
1
  ---
2
2
  name: ultra-verify
3
- description: Run independent two-model verification with the current host as primary and a read-only Codex advisor, then verify and synthesize the evidence.
3
+ description: Run independent two-model verification with the current host as primary and a read-only external advisor, then verify and synthesize both evidence sets. Use only when the user explicitly requests cross-model verification.
4
4
  ---
5
5
 
6
- # Ultra Verify — Independent Two-Model Verification
6
+ # Run independent cross-model verification
7
7
 
8
- Claude Code remains primary. It writes the first independent analysis, verifies consequential
9
- claims, and owns the final answer. Codex is an untrusted read-only advisor. Use this workflow only
10
- when the user explicitly asks for cross-model verification.
8
+ Claude Code writes the first analysis, verifies consequential claims, and owns the
9
+ final answer. Codex is an untrusted read-only advisor.
11
10
 
12
11
  ## Modes
13
12
 
14
- - `decision <question>`: architecture or product decision.
15
- - `diagnose <symptoms>`: independent root-cause hypotheses.
16
- - `audit <scope>`: evidence-backed findings.
17
- - `estimate <task>`: estimates with explicit assumptions.
18
-
19
- ## Preconditions
20
-
21
- 1. Confirm `codex --version` plus authentication.
22
- 2. Define the exact workspace, question, evidence standard, and response shape.
23
- 3. Do not send secrets, unrelated files, or an unbounded home directory.
24
- 4. Track four steps in the current host plan: primary analysis, advisor launch, completion wait,
25
- and verified synthesis.
26
-
27
- ## 1. Create the session and write the primary view
28
-
29
- ```bash
30
- SESSION_ID="$(date +%Y%m%d-%H%M%S)-verify-<mode>"
31
- SESSION_PATH=".ultra/collab/${SESSION_ID}"
32
- mkdir -p "${SESSION_PATH}"
33
- ```
34
-
35
- Write Claude Code's evidence-backed analysis to `${SESSION_PATH}/claude-analysis.md` before
36
- reading the advisor output. Record the mode, checkout, scope, and evidence boundary.
37
-
38
- ## 2. Launch the advisor read-only
39
-
40
- Give the advisor the bounded raw question and evidence without the primary conclusion.
41
-
42
- ```bash
43
- codex exec -s read-only \
44
- -o "${SESSION_PATH}/codex-output.md" \
45
- "<bounded prompt>" \
46
- 2> "${SESSION_PATH}/codex-error.log"
47
- ```
48
-
49
- Never enable write-capable automation, danger-full-access, or permission bypass for the advisor.
50
-
51
- ## 3. Wait for completed output
52
-
53
- Run the bundled waiter in an asynchronous or yielded shell session and poll it at bounded
54
- intervals; never hold one blocking tool call longer than 60 seconds.
55
-
56
- ```bash
57
- python3 "$CLAUDE_PLUGIN_ROOT/skills/ultra-verify/scripts/verify_wait.py" \
58
- "${SESSION_PATH}" --timeout 1200
59
- ```
60
-
61
- The waiter reports the advisor as `complete`, `failed`, `empty`, or `pending`. Read the output only
62
- after its status is `complete` and the file is non-empty. Preserve the error log when it fails.
63
-
64
- ## 4. Verify and synthesize
65
-
66
- Compare `claude-analysis.md` with `codex-output.md`:
67
-
68
- 1. Verify claims against the current checkout, tests, runtime, or primary documentation.
69
- 2. Separate verified agreement, useful dissent, and unsupported assertions.
70
- 3. Explain scope, version, and assumption differences before judging the result.
71
- 4. Write `synthesis.md` and `metadata.json`, then return one Claude Code-owned conclusion.
72
-
73
- Use `references/confidence-system.md` for evidence-based confidence and
74
- `references/cross-verify-modes.md` for mode-specific expectations. Model agreement never overrides
75
- failing tests or authoritative runtime evidence.
76
-
77
- ## Degraded operation
78
-
79
- - Advisor failure: return the primary analysis with an explicit single-source warning.
80
- - Never block the underlying user task solely because the advisor is absent, unauthenticated, or
81
- slow.
82
-
83
- ## Session files
84
-
85
- ```text
86
- .ultra/collab/<SESSION_ID>/
87
- claude-analysis.md
88
- codex-output.md
89
- codex-error.log
90
- metadata.json
91
- synthesis.md
92
- ```
13
+ - `decision`: one consequential architecture or product choice;
14
+ - `diagnose`: independent root-cause hypotheses;
15
+ - `audit`: evidence-backed findings over a bounded scope;
16
+ - `estimate`: an estimate with explicit assumptions and uncertainty.
17
+
18
+ ## Workflow
19
+
20
+ 1. Confirm the advisor CLI and authentication. Define the exact workspace, question,
21
+ evidence standard, and response shape. Exclude secrets and unrelated files.
22
+ 2. Create `.ultra/collab/<session-id>/` and write the primary host's evidence-backed
23
+ analysis to `claude-analysis.md` before reading advisor output.
24
+ 3. Launch Codex with the raw bounded question and evidence in a read-only sandbox. Do
25
+ not include the primary conclusion when independence matters:
26
+
27
+ ```bash
28
+ codex exec -s read-only \
29
+ -a never \
30
+ --ephemeral \
31
+ --ignore-user-config \
32
+ --ignore-rules \
33
+ -o "${SESSION_PATH}/codex-output.md" \
34
+ "<bounded prompt>" \
35
+ 2> "${SESSION_PATH}/codex-error.log"
36
+ ```
37
+ 4. Run `scripts/verify_wait.py` resolved relative to this skill directory. Use a
38
+ yielded or asynchronous shell session and poll at bounded intervals; do not hold a
39
+ blocking tool call longer than one minute.
40
+ 5. Read advisor output only after the waiter reports a complete, non-empty file.
41
+ 6. Verify both analyses against the current checkout, tests, runtime, or primary
42
+ documentation. Explain scope, version, evidence, and assumption differences before
43
+ judging disagreement.
44
+ 7. Write session metadata and a synthesis artifact, then return one host-owned
45
+ conclusion.
46
+
47
+ Read `references/cross-verify-modes.md` for mode-specific evidence and
48
+ `references/confidence-system.md` when confidence language is useful. Model agreement
49
+ never overrides failing tests or authoritative runtime evidence.
50
+
51
+ Advisor failure degrades to the primary analysis with a single-source warning. It does
52
+ not block the user's underlying task.
@@ -2,47 +2,44 @@
2
2
  "skill_name": "ultra-verify",
3
3
  "evals": [
4
4
  {
5
- "id": 1,
6
- "prompt": "/ultra-verify decision 'Should we use PostgreSQL or MongoDB for our new microservice?'",
7
- "expected_output": "Claude writes its analysis first, launches Codex read-only, verifies both analyses, and returns one evidence-backed synthesis",
5
+ "id": "explicit-decision",
6
+ "prompt": "Run independent cross-model verification on the database choice, with the current host writing its view before the advisor.",
7
+ "should_trigger": true,
8
8
  "assertions": [
9
- "Claude writes its own analysis before reading advisor output",
10
- "Launches Codex with a read-only sandbox",
11
- "Creates a session directory under .ultra/collab/",
9
+ "Writes the primary analysis before reading advisor output",
10
+ "Launches the advisor in a read-only sandbox",
11
+ "Uses a bounded session directory and completion waiter",
12
12
  "Verifies consequential claims against authoritative evidence",
13
- "Separates verified agreement, useful dissent, and unsupported assertions"
13
+ "Returns one host-owned synthesis"
14
14
  ]
15
15
  },
16
16
  {
17
- "id": 2,
18
- "prompt": "/ultra-verify diagnose 'API returns 500 intermittently under load'",
19
- "expected_output": "Independent hypotheses are reconciled through discriminating checks and evidence strength",
17
+ "id": "explicit-diagnosis",
18
+ "prompt": "Use two independent models to diagnose the intermittent 500 response and reconcile their hypotheses with discriminating checks.",
19
+ "should_trigger": true,
20
20
  "assertions": [
21
- "Both analyses provide ranked hypotheses",
22
- "Duplicate hypotheses are merged by root cause",
23
- "Each retained hypothesis includes a verification step",
24
- "Investigation order follows evidence strength and verification cost"
21
+ "Keeps both initial hypotheses independent",
22
+ "Deduplicates by root cause after both outputs complete",
23
+ "Orders verification by evidence and diagnostic value",
24
+ "Does not decide by model vote"
25
25
  ]
26
26
  },
27
27
  {
28
- "id": 3,
29
- "prompt": "/ultra-verify audit",
30
- "expected_output": "Findings are deduplicated and verified against the current checkout without vote-based severity",
28
+ "id": "ordinary-analysis-negative",
29
+ "prompt": "Should this service use PostgreSQL or MongoDB?",
30
+ "should_trigger": false,
31
31
  "assertions": [
32
- "Uses the same scope and severity model for both analyses",
33
- "Verifies every reported location",
34
- "Retains uniquely reported findings when source evidence confirms them",
35
- "Severity does not depend on model agreement"
32
+ "Answers with the ordinary analysis workflow",
33
+ "Does not launch an external advisor without explicit cross-model intent"
36
34
  ]
37
35
  },
38
36
  {
39
- "id": 4,
40
- "prompt": "/ultra-verify estimate 'Implement OAuth2 login with two providers'",
41
- "expected_output": "Two estimates are reconciled by scope, assumptions, dependencies, and risk",
37
+ "id": "ordinary-review-negative",
38
+ "prompt": "Review these changes before I commit.",
39
+ "should_trigger": false,
42
40
  "assertions": [
43
- "Both analyses include work breakdowns and assumptions",
44
- "Large differences are explained rather than averaged mechanically",
45
- "Final range is supported by the reconciled work breakdown"
41
+ "Uses the standard review workflow",
42
+ "Does not substitute cross-model verification for native review"
46
43
  ]
47
44
  }
48
45
  ]