01-projects/phdata/competitive-intel/managed-agent-handoff

Phased build plan - Claude partner CI agent

2026-10-22

Build plan

Doc references are files in the claude-api skill's shared/ folder.

Phase 0: Prerequisites (you do these by hand, 30-45 min)

Done when: ant auth status shows the ci-agent workspace, and the session has read the pack.

Phase 1: One manual debrief, as an outcome (1-2 hours)

Learn: agent, environment, session, outcome and rubric, web allowlists.

  1. Run /claude-api managed-agents-onboard field-monitor. Adapt agent.md to [[BRIEF-SPEC]]. Write environment.yaml with limited networking, the [[DECISIONS]] host list, and allow_mcp_servers: true (needed once the Notion server is declared, or session create fails with a 400); enable web_search and web_fetch with matching allowed_domains. Apply after the dry run.
  2. Upload the seed CSV (Files API) and attach it as a file resource with mount_path: /data/partners-index.csv; the agent sees /mnt/session/uploads/data/partners-index.csv (managed-agents-environments.md -> Resources).
  3. session.yaml: budget "500" ($5.00); initial_events = a user.message naming the week and files, then a user.define_outcome with [[RUBRIC]] as the rubric, max_iterations: 3 (managed-agents-outcomes.md).
  4. Watch in the Console session viewer (Managed Agents -> Sessions; the session prints its link). ant beta:sessions connect needs an interactive terminal, so use it only from your own laptop. Read each span.outcome_evaluation_end result and explanation.
  5. Download the brief from session outputs and grade it yourself.

Done when: a spec-following brief is in /mnt/session/outputs/, the grader said satisfied (or you know why not), and you know the run's list cost from usage.

Watch for (likely): the directory is a JavaScript app; a 2026-10-22 Playwright scrape needed about 52 "View more" clicks. Before writing the brief, the agent fetches the directory and one profile page and logs what came back. If it cannot read them, the header says "Directory readable: no", and sections (a) and (b) say "Directory not readable this run; tier data from snapshot YYYY-MM-DD", never "no change". Pick a refresh route ([[DECISIONS]] item 9) before Phase 2.

Phase 2: Memory, so the agent compares weeks (about 1 hour)

Learn: memory stores, access modes, seeding, memory versions.

Done when: run 2 reports real differences (or "nothing changed") and memory versions show the agent's writes.

Phase 3: Delivery (45-90 min)

Learn: MCP servers, vaults, permission policies. Two options that the docs support:

A. Notion page (template default) B. Email through an email API
How The field-monitor template already declares the Notion MCP server. The agent writes a dated page to a "CI Debriefs" database. An environment_variable vault credential (for example an email API key) with allowed_hosts set to that API's host. The agent calls it with curl from bash.
Setup Connect Notion with OAuth in the Console (Vaults). No keys, and the token refreshes automatically. An email provider account and a verified sender domain. Add the host to both credential and environment allowlists. Header-only injection.
Gets to you You open Notion (or subscribe to the database). It arrives in your inbox.
Risk The OAuth grant covers whatever pages you share with it. Share one database only. The key can send to anyone. A malicious page could try to steer the agent into emailing someone else.

Recommendation (Ray's guess): A. The template's own path, fewest new parts, no secret you handle, and it teaches vaults and MCP cleanly. Move to B if you find you do not open Notion.

Permission policy: the onboarding recommends auto for unattended runs that read outsider text and write somewhere. But an auto call it cannot judge pauses the run with nobody to approve. If that happens, narrow the Notion toolset to the page-create tool with always_allow (exact name from Notion's docs; a wrong name silently disables it).

Done when: a manual session puts the brief in your chosen destination, with no approval pauses.

Phase 4: Scheduled deployment (30 min)

Learn: deployments, deployment runs, pause and unpause (managed-agents-scheduled-deployments.md).

Done when: schedule.upcoming_runs_at shows Mondays, the manual run succeeded, and ant beta:deployment-runs list shows no errors.

Phase 5: Tuning (30 min a week for 3 weeks)