ultra-builder-pro-cli 0.10.0 → 0.11.0

package/skills/ultra-init/SKILL.md

@@ -1,151 +1,70 @@
 ---
 name: ultra-init
-description: "Initialize Ultra Builder Pro project: detect context, confirm with user, scaffold .ultra/ via task.init_project, set up git."
-user-invocable: true
-runtime: all
-mcp_tools_required:
-  - task.init_project
-cli_fallback: "task init-project"
+description: Initialize an Ultra Builder Pro project with authoritative state, baseline specification files, and optional Git setup. Use when a repository has not yet been initialized for the Ultra workflow.
 ---
 
-# ultra-init — Phase 3.1
+# Initialize an Ultra project
 
-把当前工作目录（或 `--target-dir`）初始化为一个 Ultra Builder Pro 项目：拉起
-`.ultra/` 骨架、初始化权威 `state.db`、建立持续变更目录、写入 `tasks.json`
-初始元数据，并按需配置 git。
+Create the project-local Ultra runtime without inventing product requirements or
+business tasks.
 
-真实的目录搭建 + 模板拷贝 + tasks.json 注入统一由 **MCP tool `task.init_project`** 完成；
-MCP 不可达时回退 `ultra-tools task init-project`。
+## Inputs
 
-## 设计要点（对比 pre-Phase-3 行为）
+Use the current working directory unless the user names another target. Inspect
+existing project manifests to infer:
 
-- **无 Claude 独占依赖**：`task.init_project` + `ultra-tools init-project` 两条路径
-  都不调 Claude 原生工具，Claude Code、OpenCode、Codex 三个 runtime 都能走通。
-- **模板内置**：`.ultra/` 骨架来自仓内 `templates/.ultra/`；不再依赖 `~/.claude/.ultra-template/`。
-- **幂等**：二次 init 默认拒绝，`--overwrite` 才会备份旧 `.ultra/` 为
-  `.ultra.backup.<ts>` 后重建。
+- project name;
+- project type;
+- primary technologies;
+- whether Git and `.ultra/` already exist.
+
+Ask only about unresolved ambiguity, optional Git initialization, or permission to
+replace an existing `.ultra/` directory. Never infer permission to overwrite it.
 
 ## Workflow
 
-### Step 0: 状态检测（skill 调用方做）
-
-在调 `task.init_project` 之前，调用方（Claude / CLI / SDK）需要先判断：
-
-- `target_dir/.ultra/` 是否已存在 → 决定是否需要 `overwrite=true`
-- `target_dir/.git/` 是否已存在 → 影响 Step 3 的分支
-- 读 `package.json` / `Cargo.toml` / `pyproject.toml` / `go.mod` 推断项目类型和栈
-- 如果调用方是 Claude，可在此用 `TaskCreate` 跟踪 Step 0–4 的 session 内进度
-  （这是 runtime 的 session-local 跟踪，不走 MCP）
-
-### Step 1: 补全参数
-
-入参不足时补：
-
-| 字段 | 缺省 |
-|------|------|
-| `project_name` | 当前目录名（`path.basename(target_dir)`） |
-| `project_type` | Step 0 识别结果；多技术栈 → `fullstack` |
-| `stack` | Step 0 识别到的依赖（逗号分隔多值，如 `react,express,postgres`） |
-| `git_init` | `.git/` 不存在 → 询问用户 |
-
-### Step 1.5: 交互确认（仅当检测到模糊或重入）
-
-触发条件：
-- `target_dir/.ultra/` 已存在（重入）
-- 识别到多项目类型（Web + API）
-- 显式 `--interactive` 标志
-
-交互渠道：
-- **Claude runtime**：调 `AskUserQuestion`（原生）
-- **其他 runtime**：使用 Host 原生提问界面；若当前表面不支持交互，
-  要求用户通过显式命令行参数选择
-
-确认 4 个问题：
-1. 项目类型（可多选，`detected` 标签打在识别项）
-2. 技术栈（可多选）
-3. 已有 `.git/` → 保留 / 重置备份 / 不用 git
-4. 已有 `.ultra/` → 覆盖（备份） / 保留 / 取消
-
-### Step 2: 调 `task.init_project` 拉起骨架
-
-**MCP 主路径**：
-```jsonc
-// call: task.init_project
-{
-  "target_dir": "/abs/path/to/project",
-  "project_name": "my-app",
-  "project_type": "fullstack",
-  "stack": "react,express,postgres",
-  "overwrite": false
-}
-// response
-{
-  "created_path": "/abs/path/to/project/.ultra",
-  "status": "created",
-  "copied_files": [
-    "specs/discovery.md", "specs/product.md", "specs/architecture.md",
-    "tasks/tasks.json", "tasks/contexts/TEMPLATE.md",
-    "changes/active/.gitkeep", "changes/archive/.gitkeep",
-    "docs/research/README.md",
-    "test-report.json", "delivery-report.json"
-  ],
-  "state_db_path": "/abs/path/to/project/.ultra/state.db"
-}
-```
-
-**CLI 回退路径**（`UBP_MCP=off` 或 MCP 调用返回网络错）：
-```bash
-ultra-tools task init-project \
-  --target-dir "$TARGET" \
-  --project-name "$NAME" \
-  --project-type "$TYPE" \
-  --stack "$STACK" \
-  $([ "$OVERWRITE" = "1" ] && echo --overwrite)
-```
-CLI 最后一行是 `{ "ok": true, "data": { ... } }`（见 spec/cli-protocol.md §2）。
-
-**错误处理**：
-- `ULTRA_DIR_EXISTS` → Step 1.5 重新询问是否 overwrite
-- `TEMPLATE_MISSING` → 致命；提示检查 `templates/.ultra/` 是否被 gitignore 吞了
-- `TARGET_NOT_DIR` / `VALIDATION_ERROR` → 返回调用方，修参数
-- `IO_ERROR` → retriable=true；最多重试 2 次
-
-### Step 3: Git 集成
-
-根据 Step 1.5 结果：
-
-- **初始化新仓**：`git init` + 写 `.gitignore`（排除 `.ultra/backups/`、`node_modules/`、
-  敏感文件等项目通用规则）+ 写基础 `README.md`（若不存在）。
-- **保留现有 `.git/`**：仅追加 `.gitignore` 里的 `.ultra/backups/` 一行（若缺失）。
-- **不用 git**：跳过。
-
-提示建议第一个 commit：`git add . && git commit -m "feat: initialize Ultra Builder Pro"`，
-但不代为执行（commit 是用户决策）。
-
-### Step 4: 成功总结 + 下一步
-
-用中文输出：
-- ✅ `.ultra/` 骨架（specs / tasks / changes / docs / reports）
-- ✅ `.ultra/state.db` 已初始化为当前 schema，后续不再依赖第一次写操作懒创建
-- ✅ tasks.json 注入元数据（name / type / stack / created / updated）
-- ✅ git 状态（按选择）
-- ⚠️ **下一步**：跑 `/ultra-research` 做 17 步 discovery 填 spec；不要跳过直接 `/ultra-plan`
-
-## 调用方式（按 runtime）
-
-| Runtime | 调用形态 |
-|---------|----------|
-| Claude  | `/ultra-init [name] [type] [stack] [git]` — 命令薄壳拉起此 skill |
-| OpenCode | `/ultra-init …` 同上（agent frontmatter 小写化） |
-| Codex   | `codex exec "run /ultra-init …"`（Phase 4.4 adapter 接） |
-
-## 输出锚点
-
-- `target_dir/.ultra/tasks/tasks.json` — project.name / project.type / project.stack 已注入
-- `target_dir/.ultra/specs/{discovery,product,architecture}.md` — 带 `[NEEDS CLARIFICATION]` 标记
-- 若 `overwrite=true`：`target_dir/.ultra.backup.<ts>/` 保存旧骨架
-
-## 不做的事
-
-- **不**创建业务 task（业务 task 由 `/ultra-plan` 在 spec 填完后批量创建）
-- **不**调 web：离线可执行
+1. Resolve the absolute target directory and verify that it exists.
+2. Derive the project metadata from repository evidence. Treat user-provided values
+   as authoritative when they conflict with inference.
+3. If `.ultra/` exists, stop and ask whether to keep it, cancel, or recreate it with
+   `overwrite: true`. Explain that recreation first preserves a timestamped backup.
+4. Call `task.init_project` with the smallest complete input:
+
+   ```json
+   {
+     "target_dir": "/absolute/project/path",
+     "project_name": "example",
+     "project_type": "fullstack",
+     "stack": "react,node,postgres",
+     "overwrite": false
+   }
+   ```
+
+5. Verify the returned `.ultra` path, `state_db_path`, status, and copied-file list.
+   Confirm that the returned state database and baseline specification files exist.
+6. If the user requested Git setup, initialize Git only when needed and add narrowly
+   scoped ignore rules. Do not stage or commit without explicit authorization.
+
+If the MCP server cannot start, use the installed
+`ultra-tools task init-project` command only when it is available. The CLI and MCP
+must use the same initializer. Do not simulate initialization by creating projection
+files manually.
+
+## Failure handling
+
+- `ULTRA_DIR_EXISTS`: return to the overwrite decision; do not retry automatically.
+- `TEMPLATE_MISSING`: stop and report an installation/package integrity failure.
+- `TARGET_NOT_DIR` or `VALIDATION_ERROR`: correct the input and retry once.
+- `IO_ERROR`: report the affected path and preserve any backup or partial evidence.
+
+## Authority and output
+
+`.ultra/state.db` is the durable Ultra authority. Generated JSON and Markdown are
+projections or workflow artifacts and must not be edited to create state.
+
+Report the initialized path, state database path, backup path when present, Git
+action, and one next action. Route incomplete product intent to `ultra-research`;
+route an already validated baseline to `ultra-plan`.
+
+Do not create business tasks, browse the web, or rewrite an existing README as part
+of initialization.

package/skills/ultra-plan/SKILL.md

@@ -1,109 +1,69 @@
 ---
 name: ultra-plan
-description: "Turn a validated baseline, active delta, or approved PRD into fresh-context vertical slices with public seams and exact verification contracts."
-user-invocable: true
-runtime: all
-mcp_tools_required:
-  - task.create
-  - task.parse_prd
-  - task.dependency_topo
-  - plan.export
-  - plan.get
-  - change.get
-  - change.context
-  - change.breadcrumb
+description: Convert a validated baseline, active delta, or approved PRD into dependency-valid vertical slices with bounded context and exact verification. Use when requirements are ready to become authoritative Ultra tasks.
 ---
 
-# ultra-plan — Fresh-Context Execution Planning
+# Plan fresh-context execution
 
-Produce a dependency-valid plan whose tasks can be executed in isolated contexts.
-`.ultra/state.db` is authoritative; the projector owns task JSON and context
-frontmatter.
+Produce a task graph whose slices can be completed independently and verified through
+live product seams. `.ultra/state.db` remains authoritative; task JSON and context
+Markdown are generated projections.
 
-## Failure boundary
+## Entry gate
 
-Start with a state-backed MCP read. On `LEGACY_STATE_MIGRATION_REQUIRED`, stop and
-instruct:
+Start with a state-backed MCP read. If state or schema health blocks access, stop and
+route to `ultra-doctor`. Never read or write `.ultra/tasks/tasks.json` as a fallback.
 
-```bash
-ultra-tools migrate --from=4.4 --to=4.5 --source-dir <project-root>
-```
+Choose one input:
 
-Never read or write `.ultra/tasks/tasks.json` as authority. If task MCP mutation is
-unavailable, stop; there is no task-creation CLI fallback.
+- validated baseline specifications;
+- one active change packet;
+- a raw PRD through the approval-gated mode below.
 
-## Inputs
+Ask only for product, scope, cost, or risk decisions that cannot be derived from
+current evidence. A material unresolved assumption blocks persistence.
 
-Choose exactly one:
-
-- validated baseline specs under `.ultra/specs/`;
-- one active change packet (`intent.md`, `delta/`, `plan.md`);
-- raw PRD using the approval-gated direct mode below.
+## Planning rules
 
-Ask only for a product or risk decision that cannot be derived from current evidence.
-Record assumptions explicitly; unresolved material assumptions block planning.
+1. Trace acceptance through an entry point, domain behavior, side effects, and a
+   user-observable or public seam.
+2. Prefer a walking skeleton or `tracer_bullet` before horizontal layers.
+3. Give each task one outcome, bounded ownership, explicit dependencies, required
+   references, and one deterministic verification command.
+4. Use the context budget returned by the current Ultra contract. Widen it only when
+   an approved slice cannot be split without losing correctness.
+5. Add integration checkpoints at actual boundaries, not after arbitrary task counts.
+6. Put validation, errors, recovery, documentation, and migrations in the task that
+   owns the behavior.
+7. Reject scaffolding with no reachable consumer.
 
-## Planning rules
+Every persisted task must include its slice kind, public seam, verification command,
+acceptance evidence, ownership, dependencies, documentation impact, and linked change
+id when applicable.
 
-1. Trace acceptance through a live entry point, domain behavior, side effects, and a
-   user-observable/public seam.
-2. Prefer a walking skeleton / `tracer_bullet` before horizontal layers.
-3. Make each task completable in a fresh context: one outcome, bounded references,
-   explicit dependencies, and one deterministic verification command.
-4. Keep the default context packet at or below 12 files, 12k approximate tokens, and
-   40% of the fresh context budget.
-5. Use `expand_contract` only when a wider change is approved and cannot be split
-   without losing correctness.
-6. Create integration checkpoints at real seams, not after arbitrary task counts.
-7. Include error, recovery, documentation, and migration work in the task that owns
-   the behavior; do not create unreachable scaffolding tasks.
-
-## Task contract
-
-Every `task.create` must carry or be paired with:
-
-- outcome and acceptance assertions;
-- priority, complexity, dependencies, and ownership paths;
-- linked `change_id` when planning a delta;
-- `slice_kind`: `tracer_bullet`, `expand_contract`, or `integration_checkpoint`;
-- `public_seam`;
-- exact `verification_command`;
-- required context references and their reasons;
-- expected red/green signal for fixes and incidents;
-- documentation impact.
-
-After each task is persisted, compile `change.context` with `role=plan` and
-`gate=planning` when it belongs to a change. A blocked readiness result must be fixed
-before the task is called executable.
-
-## Spec mode / change mode
+## Baseline or change mode
 
 1. Read the smallest authoritative references that define acceptance.
-2. Build a task DAG in memory and check file-ownership conflicts.
-3. Present the outcome, order, cost/risk concentration, and walking-skeleton seam.
-4. Obtain approval when the plan materially changes scope or cost.
-5. Persist tasks through `task.create`.
-6. Call `task.dependency_topo`; cycles or missing dependencies are blocking.
-7. Call `plan.export`, then verify it with `plan.get` rather than reparsing the file.
-8. For an active change, call `change.breadcrumb` and report its one next action.
-
-## PRD direct mode
+2. Build the task DAG in memory and check dependency and ownership conflicts.
+3. Present the proposed outcome, execution order, risk concentration, and first live
+   seam. Obtain approval if scope, cost, or delivery semantics change materially.
+4. Persist approved tasks with `task.create`.
+5. For change-linked tasks, compile `change.context` with the planning role and gate.
+   Resolve every readiness blocker before calling a task executable.
+6. Call `task.dependency_topo`; cycles and missing dependencies block completion.
+7. Call `plan.export`, then verify the persisted result with `plan.get`.
+8. Call `change.breadcrumb` when a change is active and return one next action.
+
+## PRD mode
 
 1. Call `task.parse_prd` with `dry_run: true`.
-2. Show the proposed vertical slices, topology, conflict surface, and estimated cost.
-3. Require explicit approval. Rejection performs no state write.
-4. On approval, repeat the same parse with `dry_run: false`, then `plan.export`.
-5. Verify dry-run and persisted task ids match; mismatch is a deterministic failure.
-
-## Context body
-
-Human-readable task context may explain intent, acceptance, seam, red/green signal,
-and relevant references. It must not duplicate entire specs, provider memory, or a
-static codebase tour. The next worker should be able to begin from the manifest and
-verify the slice without recovering the planner's full conversation.
+2. Show the proposed slices, topology, conflict surface, and cost estimate.
+3. Require explicit approval; rejection performs no state write.
+4. On approval, repeat with `dry_run: false`, export the plan, and verify that the
+   dry-run and persisted task identities agree.
 
 ## Completion gate
 
-Planning is complete only when the DAG is valid, every task is reachable through a
-public seam, every command is executable, every change-linked task has a ready Context
-Manifest v2 snapshot, and no required documentation or decision is unknown.
+Planning is complete only when the DAG is valid, each task reaches a public seam, each
+verification command is executable, every change-linked context is ready, and no
+required documentation or decision remains unknown.

package/skills/ultra-research/SKILL.md

@@ -1,156 +1,63 @@
 ---
 name: ultra-research
-description: "Think-Driven Interactive Discovery - Deep research with step-file architecture for high-density output"
-user-invocable: true
+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.
 ---
 
-# Ultra Research v2 — Step-File Architecture
-
-## Overview
-
-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.
-
-**Philosophy**: Research is collaborative. Each decision validated with user before proceeding. All findings must have 90%+ confidence. Every claim needs a source.
-
-## WORKFLOW ARCHITECTURE
-
-### Core Principles
-
-- **Step-File Design**: Each step is a self-contained .md file with full execution instructions
-- **Just-In-Time Loading**: Only the current step file is in context — never load future steps
-- **Sequential Enforcement**: Steps must be completed in order, no skipping
-- **Write-Immediately**: Every step writes its output to the spec file BEFORE presenting to user
-- **User Gate**: User must explicitly confirm [C] Continue before proceeding to next step
-- **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`.
-- **Web-First**: Every analysis step REQUIRES web search with citations. No search = no proceed.
-
-### Step Processing Rules
-
-1. **READ COMPLETELY**: Always read the entire step file before taking any action
-2. **FOLLOW SEQUENCE**: Execute all numbered sections in order
-3. **SEARCH FIRST**: Execute web searches BEFORE generating analysis
-4. **WRITE IMMEDIATELY**: Append content to spec file as soon as analysis is complete
-5. **WAIT FOR INPUT**: Present [C] Continue — halt and wait for user selection
-6. **LOAD NEXT**: When user confirms, Read the next step file and follow it
-
-### Critical Rules (NO EXCEPTIONS)
-
-- NEVER load multiple step files simultaneously
-- ALWAYS read entire step file before execution
-- NEVER skip steps or optimize the sequence
-- ALWAYS write output to spec file before presenting to user
-- ALWAYS halt at [C] Continue and wait for user input
-- NEVER proceed without user confirmation
-- NEVER rely solely on training data — web search is mandatory for factual claims
-
-## STEP SEQUENCE
-
-### Round 0: Product Discovery & Strategy
-
-| Step | File | Focus | Output |
-|------|------|-------|--------|
-| 00 | `step-00-problem-validation.md` | Validate the problem is real and worth solving | discovery.md §0 |
-| 01 | `step-01-opportunity-discovery.md` | Opportunity Solution Tree (Teresa Torres) | discovery.md §1 |
-| 02 | `step-02-market-assessment.md` | TAM/SAM/SOM with dual approach | discovery.md §2 |
-| 03 | `step-03-competitive-landscape.md` | Competitors + Porter's Five Forces | discovery.md §3 |
-| 04 | `step-04-product-strategy.md` | Vision, segments, value prop, trade-offs | discovery.md §4 |
-| 05 | `step-05-assumptions-validation.md` | Risk assumptions + experiment design | discovery.md §5 |
-
-### Round 1: User & Scenario Discovery
-
-| Step | File | Focus | Output |
-|------|------|-------|--------|
-| 10 | `step-10-user-personas.md` | 2-3 personas with goals, pain points, context | product.md §1-2 |
-| 11 | `step-11-user-scenarios.md` | 3-5 user scenarios with trigger/flow/outcome | product.md §3 |
-
-### Round 2: Feature Definition
-
-| Step | File | Focus | Output |
-|------|------|-------|--------|
-| 20 | `step-20-user-stories.md` | User stories with acceptance criteria | product.md §4 |
-| 21 | `step-21-features-scope.md` | Feature prioritization + explicit exclusions | product.md §5 |
-| 22 | `step-22-success-metrics.md` | Business + user metrics with targets | product.md §6 |
-
-### Round 3: Architecture Design
-
-| Step | File | Focus | Output |
-|------|------|-------|--------|
-| 30 | `step-30-architecture-context.md` | Quality goals, constraints, system context | architecture.md §1-3 |
-| 31 | `step-31-solution-strategy.md` | Tech stack selection with rationale | architecture.md §4 |
-| 32 | `step-32-building-blocks.md` | Module decomposition + runtime scenarios | architecture.md §5-6 |
-
-### Round 4: Quality & Deployment
-
-| Step | File | Focus | Output |
-|------|------|-------|--------|
-| 40 | `step-40-deployment.md` | Infrastructure, environments, CI/CD | architecture.md §7-9 |
-| 41 | `step-41-quality-risks.md` | Quality scenarios, risks, tech debt | architecture.md §10-12 |
-
-### Synthesis
-
-| Step | File | Focus | Output |
-|------|------|-------|--------|
-| 99 | `step-99-synthesis.md` | Distillate + validation + quality summary | research-distillate.md |
-
-## ACTIVATION
-
-When invoked, follow this sequence:
-
-### 1. Pre-Research Check
-
-- If `.ultra/specs/product.md` has [NEEDS CLARIFICATION] → proceed with research
-- If `.ultra/specs/` doesn't exist → suggest `/ultra-init` first
-- If specs 100% complete → suggest skip to `/ultra-plan`
-
-### 2. Project Type Detection
-
-Ask user to determine research scope:
-
-| Type | Steps | Focus |
-|------|-------|-------|
-| Full Project | 00-99 | All rounds |
-| Product Only | 00-22 | Discovery + product |
-| Feature Only | 10-22 | User scenarios + features (skip discovery) |
-| Architecture Change | 30-41 | Architecture + deployment |
-| Custom | User selects | Specific steps |
-
-**Round 0 skip conditions**: Skip if user provides existing market research, validated strategy docs, or explicitly states "I already know the market".
-
-### 3. Begin Step Execution
-
-Read the first applicable step file:
-```
-Read: skills/ultra-research/steps/step-{NN}-{name}.md
-```
-
-Follow every instruction in that file. When the step is complete and user confirms [C], read the next step file.
-
-### 4. Output Files
-
-| File | Content |
-|------|---------|
-| `.ultra/specs/discovery.md` | §0-5: Problem, Opportunities, Market, Competition, Strategy, Assumptions |
-| `.ultra/specs/product.md` | §1-6: Problem, Personas, Scenarios, Stories, Scope, Metrics |
-| `.ultra/specs/architecture.md` | §1-12: arc42 structure |
-| `.ultra/specs/research-distillate.md` | Token-efficient summary for /ultra-plan consumption |
-| `.ultra/docs/research/*.md` | Per-round research reports |
-
-## QUALITY STANDARDS
-
-| Element | Requirement |
-|---------|-------------|
-| Sources | Every factual claim has URL citation |
-| Confidence | 90%+ for recommendations |
-| Code | Production-ready (no TODO/demo) |
-| Trade-offs | Quantified pros/cons |
-| Next steps | Specific, actionable items |
-
-## COMPLETION
-
-Research is complete when:
-- All selected steps have [C] confirmed by user
-- All spec files have no [NEEDS CLARIFICATION] markers
-- Research distillate generated
-- All recommendations have 90%+ confidence
-
-**Next**: Run `/ultra-plan` to generate task breakdown from complete specs.
+# Build a validated baseline
+
+Research only the uncertainty that blocks a durable product, architecture, or delivery
+decision. Do not force a fixed discovery ceremony onto a well-defined change.
+
+## Preflight
+
+1. Require an initialized `.ultra/specs/` directory. Route to `ultra-init` when it is
+   absent.
+2. Read the current specification files and repository evidence before asking the
+   user to repeat known facts.
+3. Define the intended deliverable, unresolved decisions, and evidence standard.
+4. Select only the research lanes that the uncertainty requires:
+   - problem and product: `references/problem-product.md`;
+   - users and scope: `references/users-scope.md`;
+   - architecture: `references/architecture.md`;
+   - quality and delivery: `references/quality-delivery.md`;
+   - final traceability: `references/synthesis.md`.
+
+Read a reference completely only when its lane is selected. Do not load all lanes by
+default.
+
+## Evidence discipline
+
+- Prefer the current checkout and existing project artifacts for repository facts.
+- Browse only when a claim is external, unstable, or requires primary-source support.
+- Prefer official and primary sources; cite each consequential external claim near the
+  statement it supports.
+- Separate observed facts, evidence-backed inferences, user decisions, and unresolved
+  assumptions.
+- Do not manufacture confidence percentages, market numbers, personas, competitors,
+  or options when evidence does not support them.
+
+## Workflow
+
+1. Build a short research agenda from the selected lanes and the decisions they must
+   unlock.
+2. Gather evidence before recommending a direction. Ask one concise question when a
+   user decision is load-bearing; batch independent low-impact questions only when it
+   improves flow.
+3. Present material tradeoffs before recording a decision. Comparisons are appropriate
+   only when real alternatives share meaningful criteria.
+4. Update the relevant baseline specification sections. Preserve source links,
+   decisions, rejected alternatives when useful, acceptance criteria, and explicit
+   open questions. Do not duplicate the same narrative across several files.
+5. Validate cross-document consistency and trace each required behavior from problem
+   or constraint to acceptance and architecture.
+6. Use `references/synthesis.md` for the completion check and report one next action.
+
+## Completion gate
+
+Research is complete when the selected scope has enough evidence for planning, every
+material decision is recorded, required acceptance is testable, architecture respects
+known constraints, and unresolved items are either blocking or explicitly outside the
+accepted scope.
+
+Route a validated baseline to `ultra-plan`. Do not create business tasks, write Ultra
+state, or maintain a second condensed specification that can drift from the baseline.

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

@@ -0,0 +1,38 @@
+# Architecture research
+
+Read this reference when the system boundary, quality attributes, integration seams,
+technology choice, or implementation constraints are unresolved.
+
+## Current system evidence
+
+Start from the current checkout:
+
+- entry points and external interfaces;
+- domain boundaries and authoritative state;
+- data flows and side effects;
+- existing dependencies and deployment topology;
+- failure, recovery, authorization, and observability paths.
+
+Do not design a replacement architecture before identifying the live path and the
+constraint that requires change.
+
+## Decision method
+
+For each material architecture decision:
+
+1. state the required capability and quality constraints;
+2. identify credible options already compatible with the system when possible;
+3. use official primary documentation for library or platform behavior;
+4. evaluate integration cost, operability, failure modes, migration, and rollback;
+5. record the selected option, rejected alternatives that may recur, and the evidence
+   that would reopen the decision.
+
+Do not compare technologies for ceremony. A single established repository pattern is
+the default when it satisfies the contract.
+
+## Record the result
+
+Update the architecture specification with system context, boundaries, building
+blocks, runtime flow, authoritative state, external contracts, quality scenarios,
+deployment constraints, and accepted decisions. Connect each required behavior to a
+reachable public seam and a verification approach.