From d5df87dafdbb1d555fe8155b543d80b2ef5ec825 Mon Sep 17 00:00:00 2001 From: CREDO23 Date: Tue, 30 Jun 2026 23:54:11 +0200 Subject: [PATCH] docs(revamp): rename primitive to Tracker, subagent to intelligence_agent --- plans/backend/revamp/00-overview.md | 28 +++++++-------- plans/backend/revamp/02-access.md | 4 +-- plans/backend/revamp/03-intelligence.md | 28 +++++++-------- plans/backend/revamp/04-timeline.md | 18 +++++----- plans/backend/revamp/05-triggers.md | 20 +++++------ plans/backend/revamp/06-orchestration.md | 43 ++++++++++++------------ 6 files changed, 70 insertions(+), 71 deletions(-) diff --git a/plans/backend/revamp/00-overview.md b/plans/backend/revamp/00-overview.md index 36dd05d2c..92bed3b4d 100644 --- a/plans/backend/revamp/00-overview.md +++ b/plans/backend/revamp/00-overview.md @@ -12,7 +12,7 @@ PRODUCT A — stateless utility ① Capabilities + ② Access call a verb → get data → bill. Nothing persists. PRODUCT B — decision-grounded CI ③ Intelligence + ④ Timeline (+ ⑤ Triggers to drive it) - a Lens accumulates structured signal over time. The Timeline is the moat. + a Tracker accumulates structured signal over time. The Timeline is the moat. ``` ## The domain map @@ -22,7 +22,7 @@ PRODUCT B — decision-grounded CI ③ Intelligence + ④ Timeline (+ ⑤ Tri ┌─────────────────────────────────┐ ┌──────────────────────────────────────────────┐ │ Acquisition │ │ ① Capabilities typed verbs over Acquisition │ │ proprietary/web_crawler │◄──┤ ② Access chat · REST · MCP doors │ - │ CrawlOutcome · billing (03c) │ │ ③ Intelligence Lens · schema · hot loop │ + │ CrawlOutcome · billing (03c) │ │ ③ Intelligence Tracker · schema · hot loop │ │ │ │ ④ Timeline 3-store delta state (moat) │ │ │ │ ⑤ Triggers pluggable refresh clock │ │ │ │ ⑥ Orchestration CI-expert subagent + tools │ @@ -34,10 +34,10 @@ PRODUCT B — decision-grounded CI ③ Intelligence + ④ Timeline (+ ⑤ Tri |---|--------|----------|-----| | ① | Capabilities | Acquisition → typed callable verbs (`web.scrape`, `web.discover`, `maps.*`) | `01-capabilities.md` | | ② | Access | expose verbs to callers, authed + metered (chat / REST / MCP) | `02-access.md` | -| ③ | Intelligence | the Lens, agent-designed locked schema, hot loop (agent judges, code computes) | `03-intelligence.md` | +| ③ | Intelligence | the Tracker, agent-designed locked schema, hot loop (agent judges, code computes) | `03-intelligence.md` | | ④ | Timeline | durable time-shaped truth; deltas not snapshots; no change → no row | `04-timeline.md` | -| ⑤ | Triggers | when a Lens refreshes; `refresh(lens)` callers; recurrence+delivery = optional CI action on automations | `05-triggers.md` | -| ⑥ | Orchestration | the human-facing CI-expert subagent (intent routing, verb chains, Lens crafting) + its tools | `06-orchestration.md` | +| ⑤ | Triggers | when a Tracker refreshes; `refresh(tracker)` callers; recurrence+delivery = optional CI action on automations | `05-triggers.md` | +| ⑥ | Orchestration | the human-facing CI-expert subagent (intent routing, verb chains, Tracker crafting) + its tools | `06-orchestration.md` | ## Reconciliation with the old plans @@ -45,7 +45,7 @@ PRODUCT B — decision-grounded CI ③ Intelligence + ④ Timeline (+ ⑤ Tri |----------|------|---------------| | `04a-connector-category.md` | **demoted to hygiene** | the genuine MCP-routing fix survives in ② (consume-user-MCP); the taxonomy work is not core | | `04b-source-discovery.md` | **absorbed** | becomes the `web.discover` capability in ① | -| `05-pipelines-model.md` | **dissolved** | the "pipeline" concept → the `Lens` (③) + Timeline tables (④); no `pipeline`/`pipeline_runs` | +| `05-pipelines-model.md` | **dissolved** | the "pipeline" concept → the `Tracker` (③) + Timeline tables (④); no `pipeline`/`pipeline_runs` | | `06-pipelines-exec.md` | **dissolved** | execution → the hot loop (③); scheduling/runs/delivery → **reuse automations** via a CI action (⑤) — its selector + `AutomationRun`, **not** a rebuilt cron | | `07-upload-pipeline-kb.md` | **dropped (crawl→KB + uploads-as-pipeline audit)** | "don't index *crawled* data" holds. **User file-upload-to-KB remains a pre-existing, untouched feature** (uploads still become indexed KB Documents). For CI, uploads are routed to a dedicated **folder** and may feed the judge (`03`, F) | @@ -60,16 +60,16 @@ out; *user uploads* still work (and gain a CI context-folder role). 4. **③ Intelligence** — schema-design agent + hot loop + materiality evaluator. 5. **⑤ Triggers** — manual/agent/external-cron; then the CI **automation action** (recurrence + delivery) reusing the automations selector + `AutomationRun`. -6. **⑥ Orchestration** — the `analyst` CI-expert subagent + tools + prompt (the human-facing seam; +6. **⑥ Orchestration** — the `intelligence_agent` CI-expert subagent + tools + prompt (the human-facing seam; built atop ①–④, can grow alongside them). ## Consolidated open forks (need your call) -1. Primitive **name** — using `Lens` as a working label; confirm or replace. -2. Schema **review-&-lock** UX before frontend exists — pure-chat confirmation for MVP? -3. Timeline ORM home — `app/db.py` vs dedicated `app/timeline/`. -4. Recurrence = CI **action** on automations (default) vs a thin CI automation **shape** (fallback). +1. Schema **review-&-lock** UX before frontend exists — pure-chat confirmation for MVP? +2. Timeline ORM home — `app/db.py` vs dedicated `app/timeline/`. +3. Recurrence = CI **action** on automations (default) vs a thin CI automation **shape** (fallback). +*(Resolved: primitive **name** = `Tracker`, subagent = `intelligence_agent` (Intelligence Agent).)* *(Resolved: the "built-in scheduler tick" fork — we reuse the automations schedule selector via a CI action instead of building a tick. See `05`.)* @@ -84,10 +84,10 @@ action instead of building a tick. See `05`.)* - **Don't index** crawled data into the KB; the Timeline (deltas) is the only persisted CI state. - CI is **decoupled from automations** (automations = one optional Trigger adapter). - Intelligence: **agent-designed schema** (sample-grounded, human-locked, versioned) in MVP; single - entity per Lens; materiality = code thresholds (numeric/clear) + agent on ambiguous; content-hash + entity per Tracker; materiality = code thresholds (numeric/clear) + agent on ambiguous; content-hash pre-check before LLM spend. -- Orchestration is a first-class deliverable: a **net-new CI-expert subagent** (`analyst`, working - name) on the existing chat runtime, with registry-backed verb tools + Lens/Timeline tools; intent +- Orchestration is a first-class deliverable: a **net-new CI-expert subagent** (`intelligence_agent`, working + name) on the existing chat runtime, with registry-backed verb tools + Tracker/Timeline tools; intent routing lives in its prompt, the headless logic stays in ③/④. - **Recurrence + alert delivery = a CI *action* on the existing automations** (not a new scheduler, not a new shape): reuses the hardened schedule selector, `AutomationRun` (audit + idempotency), and diff --git a/plans/backend/revamp/02-access.md b/plans/backend/revamp/02-access.md index ad8d165af..69d5cec60 100644 --- a/plans/backend/revamp/02-access.md +++ b/plans/backend/revamp/02-access.md @@ -60,12 +60,12 @@ user never has to: ``` "compare / find / what is / pull / summarize / right now" → ONE-SHOT → call verbs, answer (Product A, stateless) -"watch / track / notify me when / every week / keep an eye / over time" → STANDING → start the Lens setup flow (Product B, stateful → ③) +"watch / track / notify me when / every week / keep an eye / over time" → STANDING → start the Tracker setup flow (Product B, stateful → ③) ``` - **One-shot** → orchestrate verbs now, synthesize an answer; nothing persists beyond chat. - **Standing concern** → hand off to the Intelligence setup flow (`03`): sample-fetch → agent proposes - schema/thresholds/identity → user validates & locks → Lens runs on a trigger. + schema/thresholds/identity → user validates & locks → Tracker runs on a trigger. - **Ambiguous** → ask exactly **one** clarifying question — *"just this once, or should I keep watching it for you?"* — which is the entire A-vs-B decision expressed in human terms. diff --git a/plans/backend/revamp/03-intelligence.md b/plans/backend/revamp/03-intelligence.md index b3789ec66..f37d4c8cb 100644 --- a/plans/backend/revamp/03-intelligence.md +++ b/plans/backend/revamp/03-intelligence.md @@ -3,7 +3,7 @@ > **WIP design doc.** Part of the Phase 4 → end revamp. Pairs with `04-timeline.md` (the state it writes). > **Scope guardrail:** Phases 1–3 SHIPPED/FIXED. This is net-new and is **not** the KB and **not** > the automations subsystem. -> **Working name:** the standing-concern primitive is called a **Lens** (provisional — easily renamed). +> **Name:** the standing-concern primitive is the **Tracker**. ## The stateless / stateful line @@ -20,7 +20,7 @@ below the Access→Intelligence boundary stays pure functions. Turn repeated capability calls into **decision-relevant structured signal**. The motto: **the agent judges, code computes.** This replaces the old "pipeline" as the *standing concern*. -## The primitive — `Lens` +## The primitive — `Tracker` A saved, decision-grounded subject that accumulates structured signal over time: @@ -31,7 +31,7 @@ A saved, decision-grounded subject that accumulates structured signal over time: | `definition` (locked, versioned) | `{ field_schema, identity_rule, materiality }` — the agent-drafted, human-locked contract | | `status` | `draft` → `locked`/`active` | -One **entity per Lens for MVP** (one place / one URL). Multi-entity (`maps.search → many`) is deferred +One **entity per Tracker for MVP** (one place / one URL). Multi-entity (`maps.search → many`) is deferred (the Timeline model stays multi-entity-ready so it's additive). ## Setup (once) — the agent-designed schema flow (IN MVP) @@ -52,7 +52,7 @@ no UI needed): 5. **Versioned** — a locked `definition` is a snapshot; edits create a new version (mirrors how `automations` snapshots `definition`). -## The hot loop (per refresh) — `refresh(lens)` +## The hot loop (per refresh) — `refresh(tracker)` 1. **Crawl** — call the bound capability (Domain ①) → raw data. 2. **Cheap pre-check** — content hash via the existing @@ -84,12 +84,12 @@ description reworded → code: no rule → ASK AGENT → NOISE - New **Apache-2** package `app/intelligence/` (the schema-design agent, the hot loop, the materiality evaluator). Calls capability `executor`s directly (not through a door). -- Exposes **`refresh(lens)`**. *Who* calls it (manual / agent / external cron / optional automation) is +- Exposes **`refresh(tracker)`**. *Who* calls it (manual / agent / external cron / optional automation) is the **Triggers** domain's concern — Intelligence has **no dependency** on any scheduler. ## Refresh execution & idempotency — ride the invoking surface (no new run table) -`refresh(lens)` is a **headless unit of work**; the **run/audit record + idempotency live on whatever +`refresh(tracker)` is a **headless unit of work**; the **run/audit record + idempotency live on whatever surface invoked it**, so we do *not* rebuild old Phase-6 `pipeline_runs`: - **Recurring (in-app):** invoked by the **CI automation action** (`05`) → the existing @@ -112,7 +112,7 @@ into the **KB as normal** — uploads create `Document`s and are indexed/embedde **(The "don't index" rule applies only to *crawled* data, not to user uploads.)** The CI-specific part is purely **organization + use**: -- **Routed to a dedicated folder** for that CI chat/Lens (reuse the existing folder-upload / +- **Routed to a dedicated folder** for that CI chat/Tracker (reuse the existing folder-upload / `destination_folder` machinery), so the chat's reference files are scoped together. - **The judge step (5) may consult them** — retrieved from the KB, scoped to that folder — when ruling materiality: @@ -129,21 +129,21 @@ works without it); design the seam now so the judge can read the folder later. ## MVP cut vs north star - **MVP:** agent-designed-schema flow (conversational, sample-grounded, human-locked) · single entity - per Lens · the hot loop with content-hash pre-check + code-threshold + agent-on-ambiguous · - `refresh(lens)` fired manually / by agent / by external cron. + per Tracker · the hot loop with content-hash pre-check + code-threshold + agent-on-ambiguous · + `refresh(tracker)` fired manually / by agent / by external cron. - **North star (deferred):** schema **auto-evolution** from recurring `notable_signals` · multi-entity - Lenses (`maps.search`) · backward-replay reconstruction · coverage-confidence · full + Trackers (`maps.search`) · backward-replay reconstruction · coverage-confidence · full provenance/explainability · the resale/data-product stage. ## Locked decisions -1. `Lens` (provisional name) is the standing-concern primitive; replaces "pipeline". +1. `Tracker` is the standing-concern primitive; replaces "pipeline". 2. Stateless (①②/Product A) vs stateful (③④/Product B) is the Access→Intelligence boundary. 3. **Agent-designed schema flow is in MVP** (not hand-authored) — sample-grounded, human-locked, versioned. -4. Single entity per Lens for MVP. +4. Single entity per Tracker for MVP. 5. Materiality = deterministic numeric/clear rules in code + agent only on ambiguous. 6. Content-hash pre-check short-circuits unchanged pages before any LLM spend. -7. `app/intelligence/` Apache-2; `refresh(lens)` is trigger-agnostic. +7. `app/intelligence/` Apache-2; `refresh(tracker)` is trigger-agnostic. 8. **No new run table** — refresh audit/idempotency ride `AutomationRun` (recurring) or the chat job record; billing idempotency is per-capability-call + the content-hash gate. Only Timeline (`04`) is new state. @@ -157,4 +157,4 @@ works without it); design the seam now so the judge can read the folder later. confirmation for MVP?). - Versioning policy on re-lock (new version vs in-place) — lean new version. - Where the schema-design agent itself runs (a setup capability? a chat sub-flow?). -- Context-folder → judge wiring (how much of the folder to load; per-Lens vs per-chat scope). +- Context-folder → judge wiring (how much of the folder to load; per-Tracker vs per-chat scope). diff --git a/plans/backend/revamp/04-timeline.md b/plans/backend/revamp/04-timeline.md index f515f5327..d66bc23e6 100644 --- a/plans/backend/revamp/04-timeline.md +++ b/plans/backend/revamp/04-timeline.md @@ -7,7 +7,7 @@ ## Purpose -Durably store the **time-shaped truth** for each Lens. This is the asset: **time is the moat** — +Durably store the **time-shaped truth** for each Tracker. This is the asset: **time is the moat** — accumulated history a later entrant cannot re-create. Design rule: **store deltas, not snapshots — no change, no row.** Storage grows with the *rate of change*, not the number of runs. @@ -21,7 +21,7 @@ without running the loop**. That separation is the reason Timeline is its own do | Store | Role | Write pattern | |-------|------|---------------| -| `tracked_entities` | stable identity per tracked thing (the Lens's `identity_rule` → `entity_key`) | written **once** | +| `tracked_entities` | stable identity per tracked thing (the Tracker's `identity_rule` → `entity_key`) | written **once** | | `entity_current_state` | latest values + `content_hash` + `last_checked_at` per entity | **overwritten** each run | | `entity_changes` (the change log) | append-only material deltas | **appended**, never overwritten | @@ -32,16 +32,16 @@ replay deltas backward (north-star tooling; not built in MVP — we just *store* ``` tracked_entities - id · workspace_id · lens_id (FK) · entity_key (unique per lens) · first_seen_at - # MVP: exactly one row per Lens (single-entity). Table stays multi-entity-ready. + id · workspace_id · tracker_id (FK) · entity_key (unique per tracker) · first_seen_at + # MVP: exactly one row per Tracker (single-entity). Table stays multi-entity-ready. entity_current_state - entity_id (FK, unique) · lens_id · fields JSONB (latest, conforms to locked field_schema) + entity_id (FK, unique) · tracker_id · fields JSONB (latest, conforms to locked field_schema) · content_hash · last_checked_at · updated_at # overwritten each material run; content_hash powers the hot-loop cheap pre-check (03 step 2) entity_changes # the append-only change log - id · entity_id (FK) · lens_id · captured_at + id · entity_id (FK) · tracker_id · captured_at · delta JSONB # { field: { from, to } } · materiality # material | notable(=notable_signals-sourced) · decided_by # code | agent (audit of the materiality split) @@ -70,7 +70,7 @@ entity_changes # the append-only change log ## MVP cut vs north star -- **MVP:** the three stores · single entity per Lens · deltas with `decided_by`/`source_ref` · +- **MVP:** the three stores · single entity per Tracker · deltas with `decided_by`/`source_ref` · `content_hash` pre-check support. - **North star (deferred):** backward-replay reconstruction queries · trend/series read APIs · coverage-confidence metadata · multi-entity scale · the resale/data-product surface. @@ -82,11 +82,11 @@ entity_changes # the append-only change log 3. CI-owned new tables; **not** KB, **not** `automation_runs`. 4. `content_hash` on current state powers the hot-loop cheap pre-check. 5. `decided_by` on changes records the code-vs-agent materiality provenance. -6. Single entity per Lens for MVP; schema stays multi-entity-ready (additive later). +6. Single entity per Tracker for MVP; schema stays multi-entity-ready (additive later). ## Open questions (carry forward) - ORM home: `app/db.py` vs a dedicated `app/timeline/` package. -- Whether `entity_current_state.fields` should be validated against the Lens's locked `field_schema` +- Whether `entity_current_state.fields` should be validated against the Tracker's locked `field_schema` at write time (lean: yes, cheap integrity guard). - Retention / archival policy for very high-velocity entities (deferred). diff --git a/plans/backend/revamp/05-triggers.md b/plans/backend/revamp/05-triggers.md index 5818e43bd..087724143 100644 --- a/plans/backend/revamp/05-triggers.md +++ b/plans/backend/revamp/05-triggers.md @@ -6,13 +6,13 @@ ## Purpose -Decide **when** a Lens refreshes. Intelligence exposes a single entry point — **`refresh(lens)`** — +Decide **when** a Tracker refreshes. Intelligence exposes a single entry point — **`refresh(tracker)`** — and every trigger is just a caller. Intelligence never knows which trigger fired; remove any trigger and the engine still works. This replaces Phase 6's cron scheduler — and the resolution is **not** to rebuild a scheduler at all, but to **reuse the automations subsystem** for the in-app recurring path (it already has a hardened -clock + run record + delivery). A trigger only ever calls `refresh(lens)`. +clock + run record + delivery). A trigger only ever calls `refresh(tracker)`. ## The adapters @@ -20,8 +20,8 @@ clock + run record + delivery). A trigger only ever calls `refresh(lens)`. |---------|----------|------| | **Manual** | user "refresh now" (chat tool / REST) | ✅ | | **Agent** | the in-app agent calls `refresh` as a tool | ✅ | -| **External cron** | the user's own scheduler hits `POST /v1/lenses/{id}/refresh` | ✅ (zero infra on us) | -| **CI automation action** | a **CI action on the existing automations** — its schedule trigger fires `refresh(lens)` **and delivers** the material changes | ✅ (the in-app recurrence + alert path) | +| **External cron** | the user's own scheduler hits `POST /v1/trackers/{id}/refresh` | ✅ (zero infra on us) | +| **CI automation action** | a **CI action on the existing automations** — its schedule trigger fires `refresh(tracker)` **and delivers** the material changes | ✅ (the in-app recurrence + alert path) | ## Recurrence + delivery — a CI action on existing automations (NOT a new scheduler, NOT a new shape) @@ -38,25 +38,25 @@ to the existing automations subsystem**: the user. **(closes the old Gap E — alert delivery.)** **Why a CI *action*, not a new automation shape:** a new shape would duplicate triggers, runs, and -delivery that already exist. A single `refresh_lens` action reuses all of it. (If implementation finds +delivery that already exist. A single `refresh_tracker` action reuses all of it. (If implementation finds the action too constraining, a thin CI-specific shape is the fallback — but the action is the default.) ### Decoupling is preserved (automations is still optional) -CI **core** — `refresh(lens)` + Timeline (`03`/`04`) — has **zero** automations dependency and runs via +CI **core** — `refresh(tracker)` + Timeline (`03`/`04`) — has **zero** automations dependency and runs via manual / agent / external-cron. Automations is the **optional adapter** that adds recurrence + delivery + audit for in-app users. So we honor "don't glue CI to automations" *and* get its machinery for free. ## Where it lives / decoupling -- The **CI action** lives with automations (its action registry); it imports `refresh(lens)` from +- The **CI action** lives with automations (its action registry); it imports `refresh(tracker)` from `app/intelligence/`. No new scheduler/Beat task. - The **external-cron** and **REST manual** paths are just Access-door routes (`POST - /v1/lenses/{id}/refresh`) — Domain ② plumbing. + /v1/trackers/{id}/refresh`) — Domain ② plumbing. ## Locked decisions -1. Intelligence exposes `refresh(lens)`; all triggers are callers. Fully decoupled. +1. Intelligence exposes `refresh(tracker)`; all triggers are callers. Fully decoupled. 2. Adapters: manual · agent · external-cron · **CI automation action** (recurrence + delivery). 3. **No bespoke scheduler and no new run table** — the recurring path reuses the automations schedule selector + `AutomationRun`; delivery reuses automations' output. (Closes old Gaps A/B/E.) @@ -68,5 +68,5 @@ manual / agent / external-cron. Automations is the **optional adapter** that add - CI **action** vs a thin CI-specific automation **shape** (default: action; shape is the fallback). - What the delivered payload looks like (the material `entity_changes` since last fire — summarized by the agent, or raw deltas). -- Concurrency: skip a refresh if the Lens already has one in flight (per-Lens lock, like the connector +- Concurrency: skip a refresh if the Tracker already has one in flight (per-Tracker lock, like the connector indexing lock) — even with the automation run-gate, belt-and-suspenders. diff --git a/plans/backend/revamp/06-orchestration.md b/plans/backend/revamp/06-orchestration.md index abc8c1f9e..81116a591 100644 --- a/plans/backend/revamp/06-orchestration.md +++ b/plans/backend/revamp/06-orchestration.md @@ -8,7 +8,7 @@ ## Why this is a first-class deliverable -The intent router + verb-composition + Lens-crafting are where "user-friendly" is won or lost. Treating +The intent router + verb-composition + Tracker-crafting are where "user-friendly" is won or lost. Treating the agent prompt/tooling as plumbing would make the product feel rigid. So the orchestration layer gets designed, not assumed. @@ -27,9 +27,9 @@ billing** shape: it calls `WebCrawlerConnector.crawl_url`, bills via the turn ac (`get_current_accumulator()` + `WebCrawlCreditService`), returns a typed dict. Our capability/CI tools follow this exactly. -## What's new — the `analyst` subagent (CI expert) +## What's new — the `intelligence_agent` subagent (CI expert) -A new builtin `subagents/builtins/analyst/` (working name — the competitive-intelligence specialist), +A new builtin `subagents/builtins/intelligence_agent/` (the competitive-intelligence specialist), peer to `research`/`deliverables`. The **main agent delegates** to it whenever the request is CI-flavored (research a competitor, watch something, analyze a place's reviews); `description.md` is what makes that routing happen. @@ -41,7 +41,7 @@ It owns the **CI playbook** in `system_prompt.md`: ambiguous → ask the single clarifying question. 2. **Verb composition** — the chains: `web.discover → web.scrape`, `maps.search → maps.place → maps.reviews`; infer URLs/queries/locations from context so the user never supplies them by hand. -3. **Lens crafting** (the "crafting" you flagged) — the conversational schema-design flow from `03`: +3. **Tracker crafting** (the "crafting" you flagged) — the conversational schema-design flow from `03`: sample-fetch → propose `field_schema` + materiality + identity → user validates & locks → versioned. 4. **Decision-grounded answering** — read the Timeline (`04`) to answer "what changed / is X pulling ahead?" from stored deltas, not by re-deriving from chat history. @@ -51,21 +51,21 @@ It owns the **CI playbook** in `system_prompt.md`: | Tool | Wraps | Mode | Billing | |------|-------|------|---------| | capability verbs (`web.scrape`, `web.discover`, `maps.search`, `maps.place`, `maps.reviews`) | Domain ① executors | inline-or-job (slow → `deliverable_wait`) | `03c` turn accumulator (as `scrape_webpage` already does) | -| `craft_lens(decision, binding)` | `03` schema-design agent | inline (does the sample-fetch + proposes) | sample crawl billed | -| `lock_lens(draft)` / `update_lens` | `03` Lens persistence | inline | — | -| `refresh_lens(lens_id)` | `03` `refresh(lens)` | job → `deliverable_wait` | per capability call | -| `query_timeline(lens_id, …)` | `04` read API | inline | — | -| `list_lenses()` | `04`/`03` read | inline | — | +| `craft_tracker(decision, binding)` | `03` schema-design agent | inline (does the sample-fetch + proposes) | sample crawl billed | +| `lock_tracker(draft)` / `update_tracker` | `03` Tracker persistence | inline | — | +| `refresh_tracker(tracker_id)` | `03` `refresh(tracker)` | job → `deliverable_wait` | per capability call | +| `query_timeline(tracker_id, …)` | `04` read API | inline | — | +| `list_trackers()` | `04`/`03` read | inline | — | - **Capability verbs are a shared tool module** (generated from the Domain ① registry) — `research` - can load the same ones; the `analyst` additionally loads the Lens/Timeline tools + the CI prompt. + can load the same ones; the `intelligence_agent` additionally loads the Tracker/Timeline tools + the CI prompt. (`scrape_webpage` is the seed; generalize it into the registry-backed set.) -- **Slow verbs** (`maps.search`, multi-URL `web.scrape`, `refresh_lens`) dispatch a job and use the +- **Slow verbs** (`maps.search`, multi-URL `web.scrape`, `refresh_tracker`) dispatch a job and use the existing `deliverable_wait` poll-until-terminal + live-card path (`02-access.md`). ## Boundaries -- **Orchestration ≠ Intelligence.** The `analyst` *drives* `03`/`04` via tools; the hot loop, +- **Orchestration ≠ Intelligence.** The `intelligence_agent` *drives* `03`/`04` via tools; the hot loop, materiality, and Timeline writes live in `03`/`04`, callable headless (so REST/MCP and Triggers reach the same logic with no agent in the loop). - **Humans get the agent; machines get raw verbs.** REST/MCP callers (devs/external agents) skip this @@ -73,24 +73,23 @@ It owns the **CI playbook** in `system_prompt.md`: ## MVP cut vs north star -- **MVP:** the `analyst` subagent + description/prompt · capability verb tools (registry-backed) · - `craft_lens`/`lock_lens`/`refresh_lens`/`query_timeline`/`list_lenses` · intent routing in-prompt. -- **North star (deferred):** richer multi-step CI playbooks (auto competitor discovery → multi-Lens - setup), proactive "you should watch this" suggestions, cross-Lens synthesis. +- **MVP:** the `intelligence_agent` subagent + description/prompt · capability verb tools (registry-backed) · + `craft_tracker`/`lock_tracker`/`refresh_tracker`/`query_timeline`/`list_trackers` · intent routing in-prompt. +- **North star (deferred):** richer multi-step CI playbooks (auto competitor discovery → multi-Tracker + setup), proactive "you should watch this" suggestions, cross-Tracker synthesis. ## Locked decisions -1. CI orchestration is a **net-new builtin subagent** (`analyst`, working name) on the existing +1. CI orchestration is a **net-new builtin subagent** (`intelligence_agent`) on the existing runtime — not a runtime rebuild. 2. Tools follow the `scrape_webpage` shape: capability executor + access door + `03c` billing. -3. Capability verbs are a **shared, registry-generated** tool module; the `analyst` adds Lens/Timeline +3. Capability verbs are a **shared, registry-generated** tool module; the `intelligence_agent` adds Tracker/Timeline tools + the CI prompt. 4. Intent routing (A vs B) lives **in the subagent prompt**; the headless logic stays in `03`/`04`. 5. Slow verbs reuse `deliverable_wait`; nothing new for chat-async. ## Open questions (carry forward) -- Subagent **name/persona** (`analyst`? `intelligence`? `scout`?). -- Does CI one-shot scraping stay in `research`, or does the `analyst` own all CI-flavored calls (lean: - shared verb tools, `analyst` owns the *CI playbook*). -- How `craft_lens`'s "review & lock" renders pre-frontend (pure-chat confirmation — ties to `03`'s open Q). +- Does CI one-shot scraping stay in `research`, or does the `intelligence_agent` own all CI-flavored calls (lean: + shared verb tools, `intelligence_agent` owns the *CI playbook*). +- How `craft_tracker`'s "review & lock" renders pre-frontend (pure-chat confirmation — ties to `03`'s open Q).