Profile Lifecycle and Runtime Stacks

Profiles define the role and its operating boundaries, not a second approval system around every tool call. Keep runtime instructions short enough to read as one coherent policy; command help and focused documentation own detailed procedures.

Role and lifecycle

• One-shot workers deliver assigned work and call caco agent complete through the effective project policy. A PR accepted with auto-merge armed parks the runtime; the confirmed merge owns closeout.
• Persistent implementation workers publish with caco agent reintegrate and continue after accepted handoff. Use validated post-landing bead closeout only where the configured lifecycle does not already perform it.
• Controllers and observers keep their coordination or observation role even when composed with persistent or worker-helper mixins. Persistence does not grant backlog-draining authority; specialists retain their declared lane.
• Interactive profiles follow operator direction rather than treating an open backlog as an assignment.
• Mixins add a particular capability or behavior. The raw profile table describes frontmatter, not the fully resolved stack; inspect composition before inferring effective lifecycle or authorization.

Self-retirement is separate from delivery: when permitted, caco agent retire --reason preserves work and sessions without requiring delivery evidence. It does not close unfinished work or cancel a keep-running instruction.

Autonomy without invented gates

Ordinary engineering initiative is the shared default for every model. Within the assigned role and task, investigation, source changes, proportional tests, PR submission, and supported recovery need no additional controller approval or manual receipt packet. Accepted first-party operations are authoritative; tools enforce their own required identities, capabilities, leases, and receipt persistence.

Ask for consequential ambiguity, missing authority, unapproved destructive action, credential access, or production impact. An existing applicable operator instruction is sufficient approval for its stated action. A pending choice blocks only the dependent operation, and no response or an expired choice is not approval.

Current evidence takes precedence over old observations, not over genuine instructions. Refresh the particular bead, PR, operation, or runtime when its state matters; do not turn old summaries, terminal CI results, idle timestamps, or stale aggregate health into permanent prohibitions. An indeterminate write must be reconciled before retrying, whereas a PR accepted with auto-merge armed needs no repeated verification ceremony.

Preserve actual scoped operator holds, secrets, foreign/dirty work, daemon-owned state, required CI, and the configured delivery actor. Prompt simplification does not widen typed authorization or permit forcing past a refused lease.

Composition and maintenance

The shared instruction layer owns tool discovery, ownership, validation, recovery, communication, and preservation. One-shot and persistent worker layers add their distinct lifecycle; controller scopes receive common guidance plus their own role body. Avoid restating shared procedures in every profile or generated goal.

Use focused development diagnostics and cover acceptance criteria missing from hosted CI; do not repeat a final gate that required CI already owns. Fix regressions caused by the change, and track unrelated failures without making the whole backlog a prerequisite to submission.

Keep incident stories, recovery recipes, and detailed checklists out of always-loaded prompts. When a rare procedure is needed, point to the current command help or its dedicated guide, such as reintegration policy or restart windows.

Keep the repository AGENTS.md role-neutral: opening a checkout does not assign board work or select a managed lifecycle. Never commit runtime-injected prompt blocks or previous-session summaries into project documentation.

Regenerate the profile table with just docs-profiles-build-source-light or cargo run -p caco-profile --bin caco-docs-gen. For shared instructions or wrapped role changes, regenerate Claude wrappers with cargo run -p caco-profile --bin regen-plugin-agents. The profile tests check representative composed prompt budgets and retained boundaries; just profile-lifecycle-audit checks lifecycle contradictions and conflict markers.

One automatic wake and delivery path

Daemon-native direct delivery and configured heartbeat own routine messages and wakeups, including Pi Daemon sessions. The speech enforcer, checkout Bash wrapper, self-ops commands, independent inbox poller, self-nudge, after-tool reminders, and post-compaction/idle resume prompts are retired. Speech is advisory; /inbox remains an explicit inspection command; pi-loop is for distinct recurring tasks rather than duplicate heartbeat or inbox checks.

Old profile names remain inert for declaration compatibility, even when loaded from an older checkout. Refresh removes known retired entrypoints from real generated .pi-agent directories, and Pi Daemon excludes them from its explicit resource list. pi-home-override remains intentional; operator-home files, unrelated resources, settings and sessions are preserved. Typed authorization, required CI, genuine operator pauses, and runtime readiness/terminal/on-demand status reporting remain in place.

Inspecting and refreshing a live stack

caco profile compose --agent <declaration> --dry-run --show-prompt
caco agent introspect --id <agent-id> --show profile
caco agent refresh --help

Composition renders current source; introspection identifies the running agent's profile stack. Inspect the materialized system-prompt.txt on its owning node when auditing the actual runtime artifact. A source edit or refreshed file alone does not prove an already-running model has reloaded its system context.

Use the supported refresh/reload path when adopting changes and preserve sessions and unfinished work. Do not recreate healthy agents just to obtain a shorter prompt. Use daemon heartbeat and direct delivery for routine monitoring; do not add duplicate loops, inbox polling, or startup proof rituals.

Return to Agent Profiles for the schema and shipped-profile inventory.