Skip to content

create-agent / create-playbook: document that background work does not survive a Trinity execution (inline-only rule) #4

Description

@romainability

Bug Description

Agents scaffolded by the create-agent and agent-dev plugins get no warning that on Trinity, anything launched in the background (Workflow tool, subagents, background tasks) is killed when the execution ends. Platform team has confirmed this is expected behavior: "Background work doesn't survive the end of a task. When the agent finishes its turn, anything it launched gets killed, so everything has to run inline in one go." That constraint is currently not documented anywhere in the plugins.

Observed Behavior

  • agent-dev create-playbook (1.3.6): no mention of background tasks, inline-only execution, or work not surviving a run.
  • It actively points the other way: the frontmatter reference documents context: fork + agent: ("run the skill in a subagent") as a normal option, with no Trinity warning.
  • create-agent (1.7.2) create / custom / adjust: no mention of the constraint in the scaffolds or generated CLAUDE.md template.
  • trinity plugin (2.5.4) onboard / sync / loop: also silent on it.

Expected Behavior

Every playbook generated for a Trinity-deployed agent should inherit the constraint, so teams don't rediscover it via data loss. Concretely:

  1. create-playbook: an execution-constraint note in the skill template, and a warning on context: fork that it must not be used in skills that run on Trinity.
  2. create-agent scaffold: the rule in the generated CLAUDE.md guidelines.
  3. Suggested battle-tested wording (from an agent that hit this in production):

Execution constraint (Trinity): inline only. Never use the Workflow tool, subagents, or background tasks — they do not survive the end of a Trinity execution. Long tasks work sequentially and checkpoint: commit and push each completed unit before starting the next; re-runs skip committed units.

Steps to Reproduce

grep -rniE "inline|subagent|background|survive" <plugin-cache>/agent-dev/1.3.6/skills/create-playbook/SKILL.md
# -> only hits are the `context: fork` option and unrelated uses of "workflow"

Environment

  • agent-dev 1.3.6, create-agent 1.7.2, trinity 2.5.4 (marketplace: Abilityai/abilities)

Additional Context

Motivating incident (2026-08-12): a deployed production agent ran a long ingest via a background workflow; the execution ended and ~15 minutes of work was silently lost. The agent's repo now carries the inline-only rule and a per-unit commit/push checkpoint pattern in every skill — that wording is offered above as a starting point.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions