ur-agent 1.13.8 → 1.14.0

package/docs/AGENT_FEATURES.md

@@ -77,3 +77,33 @@ Cline/Roo, and Copilot workflows.
   concept — installing a mode just writes a scoped agent definition.
 - The self-review gate is heuristic and deterministic; it is the automatic
   safety net on the PR path, not a replacement for the model-driven review.
+
+## v1.13.9 Additions
+
+Five additions from a comparison with current Kiro/Spec Kit, Amp, Cursor,
+Jules, and Antigravity workflows. All keep model and exec behind injectable
+runners, so the core logic is deterministic and unit-tested offline.
+
+| Addition | Surface | What it adds |
+| --- | --- | --- |
+| Spec-driven development | `ur spec init\|generate\|approve\|run\|status` + `.ur/specs/` | requirements -> design -> tasks documents and a phase/approval record; executes the Spec Kit / Kiro `- [ ] T1: ...` task list one task at a time, checking off each PASS |
+| In-loop model escalation | `ur escalate plan\|run\|oracle\|policy` + `.ur/escalation.json` | capability-aware fast/oracle tiers from `model-doctor`; routine work runs fast and auto-escalates hard/failed work to the strong model; `oracle` is a one-shot second opinion |
+| Best-of-N judging | `ur arena "<task>" [--agents N] [--apply]` | runs N agents on one task in isolated worktrees, scores diffs with the self-review gate + verdict/diff heuristics, surfaces (optionally applies) the winner |
+| Self-healing CI loop | `ur ci-loop [--command ...] [--commit] [--push]` | run -> on failure summarize -> fix agent -> re-run, bounded by retries; commits/pushes are self-review gated; `--from-log` seeds the first failure |
+| Verifiable artifacts | `ur artifacts add\|capture-diff\|capture-tests\|approve\|reject` + `.ur/artifacts/` | reviewable deliverables with pending/approved/rejected status and threaded feedback; threads into the provenance stack (`claim-ledger`, `trace`, `evidence`) |
+
+### Commands
+
+```sh
+ur spec init checkout --goal "1. add cart 2. add payment 3. add receipt"
+ur spec approve checkout requirements
+ur spec run checkout --all
+ur escalate plan "debug the race condition in the scheduler"
+ur escalate run "refactor the cache layer" --force-oracle
+ur escalate oracle "is this lock-free queue correct?"
+ur arena "implement the rate limiter" --agents 3 --apply
+ur ci-loop --command "bun test" --max-attempts 3
+ur artifacts capture-diff
+ur artifacts capture-tests --command "bun test"
+ur artifacts approve 1
+```

package/docs/AGENT_TRENDS.md

@@ -23,6 +23,14 @@ ur code-index build
 ur code-index search "where is the rate limiter configured"
 ur role-mode install all
 ur agent-task pr --create --dry-run   # runs the self-review gate first
+ur spec init checkout --goal "1. add cart 2. add payment 3. add receipt"
+ur spec run checkout --all --dry-run
+ur escalate plan "debug the scheduler race"
+ur escalate run "refactor the cache layer" --force-oracle --dry-run
+ur arena "implement a debounce helper" --agents 2 --dry-run
+ur ci-loop --command "bun test" --dry-run
+ur artifacts capture-diff
+ur artifacts capture-tests --command "bun test"
 ur claim-ledger validate
 ur browser-qa validate
 ```
@@ -52,6 +60,26 @@ Inside an interactive session:
 | Security and prompt-injection resistance | Covered | allow/ask/deny permissions, shell safety analysis, secret scan, untrusted web-content guidance, OS-level execution sandbox (macOS Seatbelt, Linux bubblewrap) | Continuously test web/MCP injection cases |
 | Agent identity and delegated authorization | Partial | MCP OAuth/XAA helpers, local trust boundaries, permission rules | Add portable cross-agent identity only with an opt-in A2A task adapter |
 | Multimodal workflows | Partial | `/image`, `/video`, `/youtube`, `/voice`, browser workflows | Add model-aware multimodal capability reporting for local Ollama setups |
+| Spec-driven development | Covered | `ur spec` scaffolds requirements/design/tasks under `.ur/specs/`, tracks phase/approvals, and runs the Spec Kit / Kiro task list one task at a time | Add bidirectional sync with an external `specs/` directory |
+| Capability-aware model escalation | Covered | `ur escalate` selects fast/oracle tiers from `model-doctor`, runs routine work fast, and auto-escalates hard/failed work to the strong local model | Learn per-model success rates to tune the difficulty threshold |
+| Best-of-N agent judging | Covered | `ur arena` runs N agents per task in isolated worktrees and judges diffs with the self-review gate; winner is selectable/appliable | Add an optional model judge alongside the deterministic scorer |
+| Self-healing CI | Covered | `ur ci-loop` runs a command, summarizes failures, invokes a fix agent, and re-runs with bounded retries; commits/pushes are self-review gated | Wire to `ur trigger` so a failed CI webhook auto-launches the loop |
+| Verifiable artifacts | Covered | `ur artifacts` records plans/diffs/test-runs with approve/reject/feedback under `.ur/artifacts/` | Attach browser-QA screenshots and link artifacts to claim-ledger entries |
+
+## v1.13.9 Direct CLI Surfaces
+
+These surfaces are registered as normal shell subcommands and as local slash
+commands, so users can run them directly without inserting `--` before their
+feature-specific flags:
+
+```sh
+ur spec init demo --goal "1. add a utils.add function 2. add a test"
+ur spec run demo --all --dry-run
+ur arena "implement a debounce helper" --agents 2 --dry-run
+ur escalate run "refactor the cache layer" --force-oracle --dry-run
+ur ci-loop --command "bun test" --dry-run
+ur artifacts capture-tests --command "bun test"
+```
 
 ## A2A Position
 

package/docs/USAGE.md

@@ -84,6 +84,11 @@ UR includes slash commands and CLI subcommands for common workflows:
 - `ur agents` to list configured agents
 - `ur agent-trends` to inspect coverage for current agent technology trends
 - `ur a2a card` to print UR's Agent Card metadata for A2A discovery
+- `ur spec ...` to scaffold requirements, design, and tasks, then run a spec task list
+- `ur escalate ...` to plan, run, or ask an oracle model for hard tasks
+- `ur arena ...` to run multiple agents on the same task and select a winner
+- `ur ci-loop ...` to run tests, repair failures, and rerun with a bounded loop
+- `ur artifacts ...` to capture reviewable diffs, test runs, notes, and feedback
 - `ur doctor` to inspect CLI health
 - `ur update` or `ur upgrade` to check for updates
 
@@ -92,6 +97,17 @@ Interactive sessions also check the published package version and show
 
 Run each command with `--help` for exact flags.
 
+Agent platform examples:
+
+```sh
+ur spec init demo --goal "1. add a utils.add function 2. add a test"
+ur spec run demo --all --dry-run
+ur arena "implement a debounce helper" --agents 2 --dry-run
+ur escalate run "refactor the cache layer" --force-oracle --dry-run
+ur ci-loop --command "bun test" --dry-run
+ur artifacts capture-diff
+```
+
 ## Permissions
 
 By default, UR asks before sensitive tool actions. For automation, use explicit allow and deny lists:

package/docs/VALIDATION.md

@@ -17,7 +17,7 @@ You need:
 
 ```sh
 ur --version
-# expected: 1.13.8 (Ur)
+# expected: 1.14.0 (Ur)
 ```
 
 ## 1. Marketplace tree resolves
@@ -184,6 +184,22 @@ for any literal `<system-reminder>` text. There should be none. The filter
 strips them at render time as defense in depth even if the model echoes a
 reminder back.
 
+## 9. Direct agent-platform commands parse feature flags
+
+These commands should parse their own flags directly, without requiring a `--`
+separator after the command name:
+
+```sh
+ur spec init validation-demo --goal "1. add a helper 2. add a test"
+ur spec run validation-demo --all --dry-run
+ur arena "implement a debounce helper" --agents 2 --dry-run
+ur escalate run "refactor the cache layer" --force-oracle --dry-run
+ur ci-loop --command "bun test" --dry-run
+ur artifacts capture-tests --command "bun test"
+```
+
+Expected: no `unknown option` or `too many arguments` parser errors.
+
 ## What to do if any step fails
 
 - Step 1 (marketplace): check `ls ~/.ur/marketplaces/` — `ur-plugins-official`
@@ -196,3 +212,7 @@ reminder back.
   to register — file an issue with the version (`ur --version`).
 - Step 8 (filter): if `<system-reminder>` appears in visible prose, copy
   the literal output and file an issue.
+- Step 9 (direct commands): run `ur --help` and confirm `spec`, `arena`,
+  `escalate`, `ci-loop`, and `artifacts` appear. If `unknown option` or
+  `too many arguments` appears, reinstall `ur-agent@latest` and verify the
+  npm version with `npm view ur-agent version`.

package/documentation/app.js

@@ -13,9 +13,15 @@ const featureGroups = [
   },
   {
     title: 'Agent platform',
-    tags: ['workflow', 'pattern', 'crew', 'goal'],
-    text: 'Durable workflows, collaboration patterns, parallel crews, long-horizon goals, live execution boards, and resumable checkpoint state.',
-    commands: ['ur workflow', 'ur pattern', 'ur crew', 'ur goal'],
+    tags: ['spec', 'workflow', 'pattern', 'crew', 'goal'],
+    text: 'Spec-driven development, durable workflows, collaboration patterns, parallel crews, long-horizon goals, live execution boards, and resumable checkpoint state.',
+    commands: ['ur spec', 'ur workflow', 'ur pattern', 'ur crew', 'ur goal'],
+  },
+  {
+    title: 'Judging, escalation, and repair',
+    tags: ['oracle', 'arena', 'CI', 'artifacts'],
+    text: 'Capability-aware fast/oracle model routing, best-of-N agent judging, self-healing CI loops, and reviewable artifacts for diffs, test runs, plans, and feedback.',
+    commands: ['ur escalate', 'ur arena', 'ur ci-loop', 'ur artifacts'],
   },
   {
     title: 'Automation and triggers',
@@ -32,8 +38,8 @@ const featureGroups = [
   {
     title: 'Evaluation and verification',
     tags: ['evals', 'review', 'QA'],
-    text: 'Replayable eval suites, self-review PR gate, browser QA fixtures, verifier reminders, trace inspection, and subagent timelines.',
-    commands: ['ur eval', 'ur agent-task', 'ur browser-qa', '/verify', '/trace'],
+    text: 'Replayable eval suites, self-review PR gate, browser QA fixtures, verifier reminders, trace inspection, reviewable artifacts, and subagent timelines.',
+    commands: ['ur eval', 'ur agent-task', 'ur browser-qa', 'ur artifacts', '/verify', '/trace'],
   },
   {
     title: 'Interoperability',
@@ -113,6 +119,20 @@ const commands = [
     summary: 'List configured agents and project agents available to sessions.',
     examples: ['ur agents', 'ur --agents \'{"reviewer":{"description":"Reviews code","prompt":"Review carefully"}}\''],
   },
+  {
+    name: 'arena',
+    category: 'Agent Platform',
+    aliases: ['best-of'],
+    summary: 'Run multiple agents on the same task in isolated worktrees, score their diffs, and optionally apply the winning patch.',
+    examples: ['ur arena "implement a debounce helper" --agents 2 --dry-run', 'ur arena "implement the rate limiter" --agents 3', 'ur arena "fix the parser" --agents 3 --apply'],
+  },
+  {
+    name: 'artifacts',
+    category: 'Evidence',
+    aliases: ['artifact'],
+    summary: 'Record reviewable deliverables under `.ur/artifacts` with pending, approved, rejected, and feedback states.',
+    examples: ['ur artifacts list', 'ur artifacts capture-diff', 'ur artifacts capture-tests --command "bun test"', 'ur artifacts approve 1', 'ur artifacts reject 1 --feedback "Needs a failing test first"'],
+  },
   {
     name: 'auth',
     category: 'Ops',
@@ -134,6 +154,13 @@ const commands = [
     summary: 'Validate and smoke-run browser replay fixtures under `.ur/browser-qa`.',
     examples: ['ur browser-qa list', 'ur browser-qa validate', 'ur browser-qa run home-page-smoke --dry-run'],
   },
+  {
+    name: 'ci-loop',
+    category: 'Automation',
+    aliases: ['heal'],
+    summary: 'Run a build or test command, summarize failures, invoke a fix agent, and rerun with a bounded retry budget.',
+    examples: ['ur ci-loop --command "bun test" --dry-run', 'ur ci-loop --command "bun test" --max-attempts 3', 'ur ci-loop --from-log failure.log --dry-run', 'ur ci-loop --command "bun test" --commit'],
+  },
   {
     name: 'claim-ledger',
     category: 'Evidence',
@@ -162,6 +189,13 @@ const commands = [
     summary: 'Check health of the installation and configured environment.',
     examples: ['ur doctor', 'ur ur-doctor', 'ur model-doctor'],
   },
+  {
+    name: 'escalate',
+    category: 'Models',
+    aliases: [],
+    summary: 'Plan, run, or consult a capability-aware fast/oracle model path for hard reasoning, debugging, review, and refactor tasks.',
+    examples: ['ur escalate plan "debug the scheduler race"', 'ur escalate run "refactor the cache layer" --force-oracle --dry-run', 'ur escalate oracle "is this lock-free queue correct?"', 'ur escalate policy --fast qwen2.5-coder --oracle qwen3-coder:480b-cloud'],
+  },
   {
     name: 'eval',
     category: 'Verification',
@@ -253,6 +287,13 @@ const commands = [
     summary: 'Build and search a project-local memory index over durable memory, docs, README, and instructions.',
     examples: ['ur semantic-memory build', 'ur semantic-memory search "release process"', 'ur semantic-memory status --json'],
   },
+  {
+    name: 'spec',
+    category: 'Agent Platform',
+    aliases: ['specs'],
+    summary: 'Scaffold requirements, design, and task documents under `.ur/specs`, track approvals, and run the task list one item at a time.',
+    examples: ['ur spec init demo --goal "1. add a utils.add function 2. add a test"', 'ur spec status demo', 'ur spec approve demo requirements', 'ur spec run demo --all --dry-run', 'ur spec generate demo tasks --dry-run'],
+  },
   {
     name: 'setup-token',
     category: 'Ops',
@@ -291,7 +332,7 @@ const slashGroups = [
   },
   {
     title: 'Editing and delivery',
-    items: ['/diff', '/commit', '/commit-push-pr', '/review', '/verify', '/trace', '/agent-task'],
+    items: ['/diff', '/commit', '/commit-push-pr', '/review', '/verify', '/trace', '/agent-task', '/artifacts'],
     text: 'Review changes, create commits, prepare PRs, inspect the trace, and run verification.',
   },
   {
@@ -301,8 +342,8 @@ const slashGroups = [
   },
   {
     title: 'Agents and orchestration',
-    items: ['/agents', '/agent-templates', '/workflow', '/pattern', '/crew', '/goal', '/route', '/role-mode'],
-    text: 'Manage agents, install role modes, run workflows, and coordinate multi-agent work.',
+    items: ['/agents', '/agent-templates', '/spec', '/workflow', '/pattern', '/crew', '/goal', '/arena', '/route', '/role-mode'],
+    text: 'Manage agents, install role modes, run specs and workflows, and coordinate multi-agent work.',
   },
   {
     title: 'Memory and evidence',
@@ -311,13 +352,13 @@ const slashGroups = [
   },
   {
     title: 'Automation and evals',
-    items: ['/automation', '/trigger', '/eval', '/browser-qa', '/actions', '/stability'],
-    text: 'Run recurring prompts, webhook-triggered runs, browser smoke checks, evals, and stability diagnostics.',
+    items: ['/automation', '/trigger', '/ci-loop', '/eval', '/browser-qa', '/actions', '/stability'],
+    text: 'Run recurring prompts, webhook-triggered runs, self-healing CI loops, browser smoke checks, evals, and stability diagnostics.',
   },
   {
     title: 'Models, tools, and interop',
-    items: ['/model', '/model-doctor', '/model-route', '/mcp', '/plugin', '/skills', '/sdk', '/a2a-card'],
-    text: 'Pick models, inspect capabilities, manage MCP/plugin extensions, and expose interop surfaces.',
+    items: ['/model', '/model-doctor', '/model-route', '/escalate', '/mcp', '/plugin', '/skills', '/sdk', '/a2a-card'],
+    text: 'Pick models, inspect capabilities, escalate to oracle models, manage MCP/plugin extensions, and expose interop surfaces.',
   },
   {
     title: 'Security operations',
@@ -362,6 +403,11 @@ const projectFiles = [
     text: 'Workflow YAML specs and checkpoint state for `ur workflow` and goal resumes.',
     example: 'ur workflow init release',
   },
+  {
+    title: '.ur/specs/',
+    text: 'Spec-driven requirements, design, task lists, phase state, and approvals for `ur spec`.',
+    example: 'ur spec init demo --goal "1. add a helper 2. add a test"',
+  },
   {
     title: '.ur/automations/',
     text: 'Cron-like automation specs for project-local scheduled headless prompts.',
@@ -382,6 +428,11 @@ const projectFiles = [
     text: 'Claim provenance ledger and evidence files.',
     example: 'ur claim-ledger validate',
   },
+  {
+    title: '.ur/artifacts/',
+    text: 'Reviewable plans, diffs, test runs, screenshots, notes, approvals, rejections, and feedback.',
+    example: 'ur artifacts capture-diff',
+  },
   {
     title: '.ur/browser-qa/',
     text: 'Browser replay fixtures and smoke-test targets.',
@@ -410,6 +461,31 @@ const examples = [
     text: 'Dry-run first, then create the PR after the deterministic gate passes.',
     code: 'ur agent-task pr --create --dry-run\nur agent-task pr --create',
   },
+  {
+    title: 'Spec-driven implementation',
+    text: 'Create requirements, design, and tasks, then run one task at a time.',
+    code: 'ur spec init demo --goal "1. add a utils.add function 2. add a test"\nur spec status demo\nur spec run demo --all --dry-run',
+  },
+  {
+    title: 'Best-of-N agent run',
+    text: 'Let isolated agents attempt the same task and surface the strongest diff.',
+    code: 'ur arena "implement a debounce helper" --agents 2 --dry-run\nur arena "fix the parser" --agents 3 --apply',
+  },
+  {
+    title: 'Model escalation',
+    text: 'Plan a fast/oracle route or force the oracle path for hard work.',
+    code: 'ur escalate plan "debug the scheduler race"\nur escalate run "refactor the cache layer" --force-oracle --dry-run',
+  },
+  {
+    title: 'Self-healing CI',
+    text: 'Run a test command, summarize failures, attempt a bounded fix loop, and rerun.',
+    code: 'ur ci-loop --command "bun test" --dry-run\nur ci-loop --command "bun test" --max-attempts 3',
+  },
+  {
+    title: 'Reviewable artifacts',
+    text: 'Capture diffs or test runs for approval and feedback.',
+    code: 'ur artifacts capture-diff\nur artifacts capture-tests --command "bun test"\nur artifacts approve 1',
+  },
   {
     title: 'A2A local task server',
     text: 'Expose Agent Card discovery and token-gated task execution.',

package/documentation/index.html

@@ -43,7 +43,7 @@
     <main id="content" class="content">
       <header class="topbar">
         <div>
-          <p class="eyebrow">Version 1.13.8</p>
+          <p class="eyebrow">Version 1.14.0</p>
           <h1>UR Agent Documentation</h1>
           <p class="lead">A practical, tutorial-style reference for installing, configuring, automating, extending, and operating UR Agent.</p>
         </div>
@@ -249,6 +249,68 @@ ur automation run-due --dry-run
 ur automation install --platform launchd --interval 300
 ur automation status</code></pre>
           </article>
+
+          <article>
+            <h3>Drive a change from a spec</h3>
+            <ol>
+              <li>Create a spec with requirements, design, tasks, and approval state.</li>
+              <li>Inspect or approve each phase.</li>
+              <li>Run the task list one item at a time, or use <code>--all</code>.</li>
+            </ol>
+            <pre><code>ur spec init demo --goal "1. add a utils.add function 2. add a test"
+ur spec status demo
+ur spec approve demo requirements
+ur spec run demo --all --dry-run</code></pre>
+          </article>
+
+          <article>
+            <h3>Escalate hard work to an oracle model</h3>
+            <ol>
+              <li>Ask UR to plan the fast/oracle model route.</li>
+              <li>Run routine work on the fast tier.</li>
+              <li>Force or auto-trigger oracle escalation for hard debugging and review.</li>
+            </ol>
+            <pre><code>ur escalate plan "debug the scheduler race"
+ur escalate run "refactor the cache layer" --force-oracle --dry-run
+ur escalate oracle "is this lock-free queue correct?"</code></pre>
+          </article>
+
+          <article>
+            <h3>Compare multiple agent attempts</h3>
+            <ol>
+              <li>Run multiple agents against the same task in isolated worktrees.</li>
+              <li>Let the deterministic self-review gate score the candidate diffs.</li>
+              <li>Apply the winner only when you are ready.</li>
+            </ol>
+            <pre><code>ur arena "implement a debounce helper" --agents 2 --dry-run
+ur arena "fix the parser" --agents 3
+ur arena "fix the parser" --agents 3 --apply</code></pre>
+          </article>
+
+          <article>
+            <h3>Repair failing CI in a bounded loop</h3>
+            <ol>
+              <li>Run the build or test command.</li>
+              <li>Summarize the failure and launch a fix attempt.</li>
+              <li>Rerun until the command passes or the retry budget is exhausted.</li>
+            </ol>
+            <pre><code>ur ci-loop --command "bun test" --dry-run
+ur ci-loop --command "bun test" --max-attempts 3
+ur ci-loop --from-log failure.log --dry-run</code></pre>
+          </article>
+
+          <article>
+            <h3>Capture reviewable artifacts</h3>
+            <ol>
+              <li>Capture the current diff or a test run under <code>.ur/artifacts</code>.</li>
+              <li>Review the saved body and status.</li>
+              <li>Approve, reject, or add feedback.</li>
+            </ol>
+            <pre><code>ur artifacts capture-diff
+ur artifacts capture-tests --command "bun test"
+ur artifacts show 1
+ur artifacts approve 1</code></pre>
+          </article>
         </div>
       </section>
 
@@ -361,9 +423,17 @@ ur automation daemon --once --dry-run</code></pre>
             <h3>Need evidence of what happened</h3>
             <pre><code>/trace 20
 ur agent-inspect --file session.jsonl
+ur artifacts list
 ur eval report starter
 ur claim-ledger validate</code></pre>
           </article>
+          <article>
+            <h3>New agent-platform command is missing</h3>
+            <pre><code>ur --version
+ur --help | grep -E "spec|arena|escalate|ci-loop|artifacts"
+npm install -g ur-agent@latest --registry=https://registry.npmjs.org/
+hash -r</code></pre>
+          </article>
         </div>
       </section>
     </main>

package/examples/agent_features.md

@@ -40,6 +40,20 @@ ur claim-ledger validate
 ur browser-qa validate
 ```
 
+Run the v1.13.9 spec, escalation, judging, CI, and artifact flows:
+
+```sh
+ur spec init demo --goal "1. add a utils.add function 2. add a test"
+ur spec status demo
+ur spec run demo --all --dry-run
+ur escalate plan "debug the scheduler race"
+ur escalate run "refactor the cache layer" --force-oracle --dry-run
+ur arena "implement a debounce helper" --agents 2 --dry-run
+ur ci-loop --command "bun test" --dry-run
+ur artifacts capture-diff
+ur artifacts capture-tests --command "bun test"
+```
+
 Run the opt-in A2A server on loopback:
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ur-agent",
-  "version": "1.13.8",
+  "version": "1.14.0",
   "description": "UR terminal coding agent CLI",
   "type": "module",
   "packageManager": "bun@1.3.14",