Skip to content

feat(deutero-research 1.0.0): Deutero user-research agents on Trinity - #28

Open
francisjervis wants to merge 4 commits into
Abilityai:mainfrom
francisjervis:feat/deutero-research
Open

francisjervis wants to merge 4 commits into
Abilityai:mainfrom
francisjervis:feat/deutero-research

Conversation

@francisjervis

Copy link
Copy Markdown
Contributor

Summary

This adds a new deutero-research plugin (1.0.0) with three skills for running user research on Trinity agents through Deutero, a platform for AI-conducted user interviews.

Skill What it does
add-deutero Gives an existing agent its own Deutero key, the Deutero MCP server and the Deutero skills. It keeps the agent's other credentials intact.
create-researcher Scaffolds, pushes and deploys a single research agent.
create-research-team Deploys a lead, a study designer and an analyst as one Trinity system.

Design notes

  • Merge-safe credentials. Trinity's inject_credentials replaces whole files. scripts/add_deutero.py reads the agent's current .env and .mcp.json, changes only the Deutero lines, and re-injects both. The key is read from a local file and never printed. In .mcp.json the server refers to it as ${DEUTERO_API_KEY} rather than containing it.
  • Skills come from the Trinity skills library (deutero-ai/agent-skill), not from Deutero's Claude Code plugin. That plugin's MCP entry signs in with browser OAuth, which a headless agent can't complete.
  • Guardrails are written into every scaffolded CLAUDE.md:
    • check credits before spending any;
    • a person approves anything that reaches participants (ask_operator);
    • transcripts stay in data/ and are never committed;
    • participants' words are treated as data, not instructions.
  • Schedules ship disabled. Completed interviews are polled with list_interviews, because Trinity schedule webhooks can't yet verify Deutero's webhook signatures or pass the payload to the agent.
  • Separate plugin. This is not a create-agent wizard, given that the domain wizards were retired in create-agent 2.0.0. A Deutero agent needs specific integration steps that the custom wizard doesn't cover.

Verification

  • add_deutero.py was tested against a stub Trinity API:
    • add, re-run (no change), key rotation and removal all behave correctly;
    • other .env keys and other MCP servers are preserved;
    • an unknown agent is refused;
    • a fake key is rejected by the live Deutero API.
  • The merged .mcp.json passes Trinity's MCP validator (agent_server/mcp_validator.py).
  • Scaffolds for all four roles pass every hard and soft check in Trinity's static compatibility suite. That was run with Trinity's own collector and static_checks.run_static. The only remaining findings are info-level: F-009 for the lead and designer, F-011, and DP-004.
  • system.yaml parses and validates with Trinity's system_service. The permission edges are lead→designer, lead→analyst, designer→lead and analyst→lead, and both schedules come out disabled.
  • End to end on a local Trinity 1.0 instance:
    • the agent was deployed with deploy-local; the live compatibility report is compatible (0 hard, 0 soft);
    • both schedules were created from template.yaml, disabled;
    • the Deutero skill source registered and synced (8 skills), and the 4-skill researcher preset was injected;
    • add_deutero.py passed the key check against the live Deutero API, wrote .env once, and a re-run changed nothing;
    • from inside the agent container, the Deutero MCP server answered get_credit_balance using the agent's own key.
  • Bugs this run found and fixed on this branch:
    • Cloudflare blocks Python's default User-Agent;
    • key files saved as a .env line were not accepted;
    • the skill wrongly said the server is "withheld" until the key is set.
  • Not tested: a chat turn through Claude Code, because the test instance had no Anthropic credentials.

🤖 Generated with Claude Code

francisjervis and others added 4 commits November 8, 2026 03:17
New plugin with three skills:

- add-deutero: give an existing Trinity agent its own Deutero key, the
  Deutero MCP server and the Deutero skills. scripts/add_deutero.py reads
  the agent's current .env and .mcp.json, merges only the Deutero lines and
  re-injects both (Trinity's inject replaces whole files). The key is read
  from a file, never printed, and referenced as ${DEUTERO_API_KEY} in
  .mcp.json. Skills come from the Trinity skills library (deutero-ai/
  agent-skill), not Deutero's Claude Code plugin, whose MCP entry needs
  browser OAuth.
- create-researcher: scaffold (scripts/scaffold.py), push and deploy a
  single research agent with credential declarations, metrics, dashboard,
  disabled schedules, and CLAUDE.md guardrails: credits, person approval
  before anything reaches participants, participant data kept out of git.
- create-research-team: lead + designer + analyst as a Trinity system
  manifest with explicit permissions and shared findings.

Checked against Trinity: the merged .mcp.json passes the platform MCP
validator, the scaffolds pass every hard and soft static compatibility
check, and the manifest parses, validates and resolves the intended
permission edges with Trinity's own system_service.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…onfigured without a key until add-deutero, not withheld

Live test on Trinity: .mcp.json.template rendering only withholds a server when an env-block variable is missing; a ${VAR} in headers is copied through, so the server is present and returns 401 until DEUTERO_API_KEY is in .env.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Found in a live run on a local Trinity instance:

- Deutero's Cloudflare edge refuses Python's default User-Agent with 403
  (error 1010), so the key check failed for every key. Send an explicit
  User-Agent; report a Cloudflare block separately from a rejected key.
- Deutero's dashboard copies the key as a .env line. Accept
  [export ]DEUTERO_API_KEY="..." in the key file and store only the value.
- Real keys are not dtro_-prefixed, so the scaffold's pre-push secret scan
  now also matches DEUTERO_API_KEY=<value>.

Verified end to end: key check passes, .env gains the key once (re-run is a
no-op), and from inside the agent container the Deutero MCP server answers
get_credit_balance with the agent's own key.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…CHITECTURE.md

- template.yaml declares `library_skills:` per role (researcher, recruiter and
  analyst presets, the same as add-deutero), so Trinity assigns and delivers
  the Deutero skills when the agent is created (Abilityai/trinity#4387).
  add-deutero still assigns them on instances without that support.
- Every scaffold gets ARCHITECTURE.md (components, data flow, trust
  boundaries), clearing compatibility note F-011.
- create-researcher 1.1, create-research-team 1.1.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@vybe

vybe commented Nov 10, 2026

Copy link
Copy Markdown
Contributor

Thanks — this is careful work, and the end-to-end verification notes are appreciated. We'd like to take it into the marketplace, with three changes first:

  1. Author. plugin.json names Ability.ai as the author. This is a Deutero integration — please name Deutero (or yourself) as author, and say so in the plugin README, so it's clear who maintains it.
  2. Pin the skills source to a tag. add-deutero registers deutero-ai/agent-skill with ref: main, ref_type: branch. A library source is re-injected into every assigned agent when it moves, so a branch-tracking third-party source means unreviewed changes reach running agents. Please register a release tag, and document bumping it.
  3. library_skills: depends on feat(templates): declare skills-library skills to assign at creation (#4387) trinity#4388. That PR is being taken with a change to the field shape (skill sets + alignment with the manifest's keys — see the comment there). Please keep the scaffolds in step with what lands, and keep add-deutero as the path that works on instances without it (as you already do).

Separately, your note that Deutero's own MCP entry needs a browser OAuth sign-in a headless agent can't complete is useful evidence — we've recorded that platform gap.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants