ultra-builder-pro-cli 0.14.0 → 0.15.0

package/skills/ultra-research/references/00-problem-validation.md

@@ -0,0 +1,36 @@
+# Problem validation
+
+Use for workflow step `00-problem-validation`.
+
+## Objective
+
+Establish the problem, affected actor, current workaround, consequence, and available
+demand evidence. In brownfield adoption, describe the behavior the current system
+already serves before discussing future intent.
+
+## Evidence
+
+- Inspect existing product documents, user-facing entry points, support evidence, and
+  runtime behavior before asking the owner for facts already present.
+- Treat an owner statement as a decision or claim, not as observed user evidence.
+- Record absent evidence as `Unknown`; do not invent demand, urgency, or a target user.
+- Use external research only when a consequential claim depends on current facts.
+
+## Record
+
+Update `discovery.md` with `Observed`, `Verified`, `Decided`, and `Unknown` entries for:
+
+- problem and affected actor;
+- current workaround and consequence;
+- demand or usage evidence;
+- the narrowest owner-approved problem boundary;
+- unresolved validation needs.
+
+Link the updated specification anchor from the immutable step report required by the
+orchestrator. A missing load-bearing fact becomes a blocker or baseline gap, not a
+guessed answer.
+
+## Semantic record
+
+Use kind `problem`. Record `actor`, `current_workaround`, `consequence`, and
+`evidence_status`.

package/skills/ultra-research/references/01-opportunity-discovery.md

@@ -0,0 +1,33 @@
+# Opportunity discovery
+
+Use for workflow step `01-opportunity-discovery`.
+
+## Objective
+
+Connect the validated problem to desired outcomes and evidence-backed opportunities.
+Describe opportunities from the actor's perspective rather than as a feature list.
+
+## Evidence
+
+- Derive current outcomes from observed workflows, existing behavior, interviews, or
+  owner decisions.
+- Preserve causal links between a problem, an unmet outcome, and its evidence.
+- Do not force rankings, solution brainstorming, or a fixed number of opportunities.
+- Record opportunities that lack evidence as unknown or future research.
+
+## Record
+
+Update `discovery.md` with:
+
+- desired outcomes and their evidence;
+- opportunity statements and affected actors;
+- constraints or dependencies;
+- owner-decided priority when one exists;
+- rejected or deferred opportunities only when that decision is durable.
+
+Complete the step with the evidence used and the updated output path.
+
+## Semantic record
+
+Use kind `opportunity`. Record `actor`, `desired_outcome`, and `evidence_status`. Link
+the record to its problem when that relation is established.

package/skills/ultra-research/references/02-market-assessment.md

@@ -0,0 +1,30 @@
+# Market assessment
+
+Use for workflow step `02-market-assessment`.
+
+## Objective
+
+Record only market facts that materially affect product scope, economics, regulation,
+or delivery. For an internal tool or a brownfield system with no market decision, state
+that boundary and retain the evidence supporting it.
+
+## Evidence
+
+- Prefer current primary sources, filings, official statistics, and directly observed
+  commercial data.
+- Preserve source date, geography, segment definition, and calculation assumptions.
+- Do not manufacture TAM, growth rates, pricing, or false numeric precision.
+- Separate externally verified facts from owner targets and estimates.
+
+## Record
+
+Update `discovery.md` with relevant segment boundaries, commercial or operational
+constraints, source-backed measurements, assumptions, and unknowns. Include a sizing
+model only when the decision genuinely depends on one and the inputs are defensible.
+
+Link source references and the updated specification anchor from the immutable step
+report required by the orchestrator.
+
+## Semantic record
+
+Use kind `market_constraint`. Record `constraint`, `decision_impact`, and `freshness`.

package/skills/ultra-research/references/03-competitive-landscape.md

@@ -0,0 +1,31 @@
+# Competitive landscape
+
+Use for workflow step `03-competitive-landscape`.
+
+## Objective
+
+Identify the alternatives actors actually use and the consequences for strategy.
+Alternatives may include direct products, adjacent tools, manual workflows, or doing
+nothing.
+
+## Evidence
+
+- Use current product documentation, pricing, repositories, filings, or observed user
+  workflows.
+- Evaluate only criteria that change the decision at hand.
+- Do not create a ceremonial matrix, fixed competitor count, or unsupported claim of
+  superiority.
+- Distinguish a verified capability from marketing language and inference.
+
+## Record
+
+Update `discovery.md` with the relevant alternatives, evidence, meaningful differences,
+switching constraints, and durable strategy implications. Record an unknown when a
+credible alternative cannot be verified.
+
+Complete the step with evidence references and the updated output path.
+
+## Semantic record
+
+Use kind `alternative`. Record `category`, `switching_constraint`, and
+`strategy_implication`.

package/skills/ultra-research/references/04-product-strategy.md

@@ -0,0 +1,32 @@
+# Product strategy
+
+Use for workflow step `04-product-strategy`.
+
+## Objective
+
+Turn accepted evidence into a product direction, target boundary, value proposition,
+and explicit tradeoffs.
+
+## Evidence and decisions
+
+- Derive constraints from prior research and current system behavior.
+- Ask the owner when a scope, customer, business, or risk decision is load-bearing.
+- Do not infer an MVP, reduced scope, release phase, or commercial posture.
+- Record exclusions only when the owner or an accepted constraint establishes them.
+
+## Record
+
+Update `discovery.md` with:
+
+- product direction and intended actors;
+- value delivered through observable behavior;
+- chosen tradeoffs and their rationale;
+- constraints, exclusions, and unresolved decisions;
+- any defensibility claim with its supporting evidence.
+
+Complete the step with decision and evidence references plus the updated output path.
+
+## Semantic record
+
+Use kind `strategy_decision`. Record `tradeoff` and `rationale`, then link the decision
+to the problems, opportunities, or constraints that support it.

package/skills/ultra-research/references/05-assumptions-validation.md

@@ -0,0 +1,31 @@
+# Assumptions and validation
+
+Use for workflow step `05-assumptions-validation`.
+
+## Objective
+
+Make load-bearing assumptions visible and define the smallest credible evidence needed
+to confirm or reject them.
+
+## Method
+
+- Extract assumptions from problem, opportunity, market, alternative, and strategy
+  claims.
+- Separate already verified facts from assumptions and owner decisions.
+- Prioritize by consequence and uncertainty only when prioritization affects the next
+  action; do not assign arbitrary scores.
+- Define a validation signal, evidence source, decision rule, owner, and recovery path.
+
+## Record
+
+Update `discovery.md` with the assumption ledger and validation state. Map unresolved
+load-bearing assumptions to blocking unknowns or gaps. Keep non-blocking future work
+out of the implementation task graph until the owner selects it.
+
+Link evidence and the updated specification anchor from the immutable step report
+required by the orchestrator.
+
+## Semantic record
+
+Use kind `assumption`. Record `category`, `consequence`, `validation_signal`,
+`success_rule`, `failure_rule`, and `ambiguous_rule`.

package/skills/ultra-research/references/10-user-personas.md

@@ -0,0 +1,29 @@
+# Actors and jobs
+
+Use for workflow step `10-user-personas`.
+
+## Objective
+
+Describe evidence-backed actors, their jobs, operating context, goals, constraints, and
+adoption barriers. A role or actor model is sufficient; do not invent demographic
+personas.
+
+## Evidence
+
+- Prefer observed workflows, access roles, support evidence, usage data, and owner
+  decisions.
+- Link each actor to a real entry point or intended behavior.
+- Mark unverified motivations and pain points as unknown.
+- In brownfield adoption, document the actors represented by current code and runtime,
+  even when product research is incomplete.
+
+## Record
+
+Update `product.md` with actor identity, job, context, current workflow, desired outcome,
+constraints, and evidence. Record priority only when it is an accepted decision.
+
+Complete the step with evidence references and the updated output path.
+
+## Semantic record
+
+Use kind `actor`. Record `job`, `current_workflow`, `goal`, and `constraint`.

package/skills/ultra-research/references/11-user-scenarios.md

@@ -0,0 +1,28 @@
+# User scenarios
+
+Use for workflow step `11-user-scenarios`.
+
+## Objective
+
+Trace the important current and intended journeys from trigger through outcome,
+including failure and recovery.
+
+## Method
+
+- Bind each scenario to an evidence-backed actor and entry point.
+- Describe the current path before proposing a changed path in brownfield adoption.
+- Include state changes, external systems, permissions, and observable outcomes.
+- Do not force a fixed scenario count or emotional narrative.
+
+## Record
+
+Update `product.md` with scenario id, actor, trigger, preconditions, current or intended
+flow, success outcome, failure outcome, recovery, and evidence. Mark gaps where runtime
+behavior and documentation disagree.
+
+Complete the step with evidence references and the updated output path.
+
+## Semantic record
+
+Use kind `scenario`. Record `actor_id`, `trigger`, `preconditions`, `flow`, `success`,
+`failure`, and `recovery`.

package/skills/ultra-research/references/20-user-stories.md

@@ -0,0 +1,30 @@
+# Behavioral requirements and acceptance
+
+Use for workflow step `20-user-stories`.
+
+## Objective
+
+Translate accepted scenarios into testable behavior without prematurely designing the
+implementation.
+
+## Method
+
+- Use stable requirement identifiers.
+- State preconditions, action, observable result, error behavior, and recovery where
+  relevant.
+- Trace every requirement to a scenario, constraint, or owner decision.
+- Preserve current delivered behavior separately from proposed behavior.
+- Do not use priority labels as a substitute for explicit scope decisions.
+
+## Record
+
+Update `product.md` with requirements and acceptance criteria that can map to an
+executable check or deliberate manual evidence. Record unknown behavior instead of
+writing vague acceptance.
+
+Complete the step with evidence references and the updated output path.
+
+## Semantic record
+
+Use kind `requirement`. Record `preconditions`, `action`, `observable_result`,
+`error_recovery`, and `verification`. Link it to its accepted scenario or decision.

package/skills/ultra-research/references/21-features-scope.md

@@ -0,0 +1,29 @@
+# Capability and scope boundary
+
+Use for workflow step `21-features-scope`.
+
+## Objective
+
+Group accepted behavior into coherent capabilities and record what is included,
+excluded, deferred, or unresolved.
+
+## Rules
+
+- Preserve the owner's stated product and release posture.
+- Never infer an MVP, reduced version, phase label, or omission from implementation
+  convenience.
+- Trace included capabilities to requirements and observable outcomes.
+- Record dependencies, migrations, compatibility, and operational obligations inside
+  the capability that owns them.
+- Keep speculative future ideas outside the active scope unless selected.
+
+## Record
+
+Update `product.md` with capability boundaries, included requirements, explicit
+exclusions and rationale, dependencies, and unresolved scope decisions.
+
+Complete the step with decision evidence and the updated output path.
+
+## Semantic record
+
+Use kind `capability`. Record `requirement_ids`, `scope_status`, and `rationale`.

package/skills/ultra-research/references/22-success-metrics.md

@@ -0,0 +1,28 @@
+# Outcomes and measurements
+
+Use for workflow step `22-success-metrics`.
+
+## Objective
+
+Define how the owner will know the accepted behavior and product outcome are working,
+including signals that would reveal harmful optimization.
+
+## Method
+
+- Derive measurements from accepted outcomes and available instrumentation.
+- State definition, source, observation window, owner, and decision use.
+- Separate current measurements, target decisions, and unavailable telemetry.
+- Do not invent baselines, targets, or a single north-star metric.
+
+## Record
+
+Update `product.md` with outcome measures, operational measures, guardrails, evidence
+availability, and unresolved instrumentation needs. A metric that cannot be observed
+must be recorded as a gap or explicit future change.
+
+Complete the step with evidence references and the updated output path.
+
+## Semantic record
+
+Use kind `metric`. Record `definition`, `source`, `window`, `owner`, and
+`decision_use`.

package/skills/ultra-research/references/30-architecture-context.md

@@ -0,0 +1,30 @@
+# Architecture context
+
+Use for workflow step `30-architecture-context`.
+
+## Objective
+
+Establish current system boundaries, quality goals, constraints, actors, external
+systems, and data flows.
+
+## Evidence
+
+- Inspect code entry points, configuration, schemas, deployment assets, tests, and
+  runtime evidence.
+- Separate observed architecture from intended architecture.
+- Record permissions, data sensitivity, compliance, and organizational constraints
+  when they affect the design.
+- Do not infer a greenfield architecture over an existing system.
+
+## Record
+
+Update `architecture.md` with system context, external dependencies, trust boundaries,
+data flows, quality goals, constraints, and evidence. Record documentation drift when
+the current checkout contradicts an existing diagram or claim.
+
+Complete the step with source or runtime evidence and the updated output path.
+
+## Semantic record
+
+Use kind `architecture_context`. Record `boundary`, `inputs_outputs`,
+`trust_authority`, and `consumers`.

package/skills/ultra-research/references/31-solution-strategy.md

@@ -0,0 +1,28 @@
+# Solution strategy
+
+Use for workflow step `31-solution-strategy`.
+
+## Objective
+
+Record architecture decisions that satisfy accepted behavior and constraints while
+preserving current repository patterns where they remain valid.
+
+## Method
+
+- Search for existing implementations and dependencies before proposing new ones.
+- Evaluate alternatives only when more than one credible choice remains and the choice
+  materially affects the contract.
+- Record decision drivers, chosen direction, consequences, compatibility, and recovery.
+- Do not force a new stack, fixed option count, scoring model, or arbitrary preference.
+
+## Record
+
+Update `architecture.md` with accepted strategy decisions and their evidence. Preserve
+unresolved decisions as blockers rather than selecting on the owner's behalf.
+
+Complete the step with decision evidence and the updated output path.
+
+## Semantic record
+
+Use kind `architecture_decision`. Record `drivers`, `direction`, `consequences`,
+`compatibility`, and `recovery`.

package/skills/ultra-research/references/32-building-blocks.md

@@ -0,0 +1,28 @@
+# Building blocks and runtime paths
+
+Use for workflow step `32-building-blocks`.
+
+## Objective
+
+Map responsibilities, contracts, data ownership, consumers, and runtime behavior across
+the current or accepted architecture.
+
+## Method
+
+- Start from real modules and live entry points in brownfield adoption.
+- Define boundaries by responsibility and authority, not by an imposed layer diagram.
+- Trace key scenarios through validation, domain behavior, persistence, integrations,
+  observable output, failure, and recovery.
+- Identify unreachable scaffolding, duplicate authority, and undocumented coupling.
+
+## Record
+
+Update `architecture.md` with building blocks, public contracts, ownership, dependencies,
+runtime paths, error paths, and evidence. Link each proposed block to a consumer.
+
+Complete the step with source evidence and the updated output path.
+
+## Semantic record
+
+Use kind `runtime_path`. Record `entry_point`, `state_side_effects`,
+`observable_result`, `failure_recovery`, and `consumers`.

package/skills/ultra-research/references/40-deployment.md

@@ -0,0 +1,29 @@
+# Deployment and operations
+
+Use for workflow step `40-deployment`.
+
+## Objective
+
+Record how the system is built, configured, migrated, deployed, observed, recovered,
+and rolled back across its actual environments.
+
+## Evidence
+
+- Inspect repository-native build and deployment configuration, environment contracts,
+  migrations, health checks, and operational documentation.
+- Use current provider documentation only when repository evidence is insufficient.
+- Separate verified deployment behavior from intended delivery design.
+- Never record secrets or fabricate infrastructure that has not been selected.
+
+## Record
+
+Update `architecture.md` with environments, topology, CI/CD entry points, configuration,
+migrations, observability, rollback, recovery, cost constraints when relevant, and
+unknowns.
+
+Complete the step with file, runtime, or provider evidence and the updated output path.
+
+## Semantic record
+
+Use kind `deployment`. Record `environment`, `entry_point`, `config_migration`,
+`observation`, and `rollback_recovery`.

package/skills/ultra-research/references/41-quality-risks.md

@@ -0,0 +1,28 @@
+# Quality scenarios and risks
+
+Use for workflow step `41-quality-risks`.
+
+## Objective
+
+Turn quality goals and known failure modes into observable scenarios, mitigations,
+recovery expectations, and a durable risk ledger.
+
+## Method
+
+- Cover only qualities material to the accepted system: correctness, availability,
+  security, performance, privacy, maintainability, or others supported by evidence.
+- State trigger, operating condition, expected response, measurement, and recovery.
+- Separate known defect, technical debt, uncertain risk, and accepted constraint.
+- Do not assign arbitrary probability or confidence scores.
+
+## Record
+
+Update `architecture.md` with quality scenarios, risk evidence, mitigation, owner,
+verification, recovery, technical debt, and architecture decisions where needed.
+
+Complete the step with evidence references and the updated output path.
+
+## Semantic record
+
+Use kind `risk`. Record `trigger_condition`, `expected_response`, `measurement`,
+`mitigation`, `recovery`, and `owner`.

package/skills/ultra-research/references/99-synthesis.md

@@ -0,0 +1,35 @@
+# Research synthesis
+
+Use for workflow step `99-synthesis`.
+
+## Objective
+
+Verify that research artifacts form one traceable, planning-ready baseline without
+creating a second condensed authority.
+
+## Validate
+
+- Every consequential claim is marked `Observed`, `Verified`, `Decided`, or `Unknown`.
+- Product behavior traces from problem or constraint through actor, scenario,
+  requirement, acceptance, architecture, quality, and delivery evidence.
+- Current behavior and proposed behavior are not silently merged.
+- Scope reflects owner decisions and never an inferred MVP or reduction.
+- Documentation conflicts, known failures, and load-bearing unknowns are in the gap
+  ledger with owners or explicit decisions.
+- Verification commands and observed results are current.
+
+## Record
+
+Write `research-distillate.md` as a navigation and traceability artifact containing
+baseline ids, source document anchors, accepted decisions, blockers, gaps, verification
+evidence, and the exact planning entry. Do not duplicate the specifications' prose.
+
+Write the immutable `99-synthesis` step report, then complete the step with that report,
+all three baseline specification paths, the distillate path, and the evidence used for
+the synthesis. Read the completed workflow back before baseline convergence.
+
+## Semantic record
+
+Use kind `synthesis_trace`. Record one verified chain through `problem_id`,
+`scenario_id`, `requirement_ids`, `architecture_path_ids`, and `verification_refs`.
+Every referenced id must exist in an earlier selected step.