Update sub-agent task-description template to require explicit auth-refresh as step (0) for any external-API task
completedAgent: carson-engineer
Priority: 2
Per LEARNINGS 2026-05-31 04:10 UTC Action Item #4.
Root cause documented in tonight's reflection: on 2026-05-30 both default-action sub-agents (0d7441fb Sergey SSO Option A, e92169c1 #11190 close) blocked on unauthenticated gh because their task descriptions did not include the token-refresh step. The sub-agent runtime does not inherit my cron's authenticated environment.
DoD steps:
(0) eval $(~/bin/gh-fleet-token.sh) — MANDATORY first step.
(a) cd /home/agent/agents/carson-engineer && git fetch origin main && git checkout -b kai/sub-agent-template-auth-step
(b) Edit /home/agent/agents/carson-engineer/AGENTS.md (or create /home/agent/agents/carson-engineer/PLAYBOOKS.md if a dedicated playbook file is more discoverable — judgment call, document which one was chosen) to add a 'Sub-agent task description template' section. Required content:
- Any sub-agent task whose DoD touches gh, git push, Linear API, or any external API MUST include explicit step (0): `eval $(~/bin/gh-fleet-token.sh)` and (where Linear is touched) `export LINEAR_API_KEY=$(cat /home/agent/agents/carson-engineer/.linear-token)`.
- This applies to: direct-ask execution tasks (1a7f201a-style #11281 template), faeef93a-style executable-default tasks, recovery tasks, and any standup/heartbeat task that calls gh for final-refresh.
- Precedent: 2026-05-30/05-31 LEARNINGS entries — both Sergey SSO Option A and #11190 close defaults blocked on missing auth despite final-DM-read gates working correctly.
- Failure mode if step (0) is missing: sub-agent blocks honestly with result.reason='gh unauthenticated' (good — no false shipped claims) but the default action does not execute and recovery requires a follow-up cron.
(c) Also update the 1a7f201a direct-ask template reference (currently described in LEARNINGS 2026-05-29 as 'the new template for direct-ask tasks') to include the same step (0) requirement. If the template lives in a separate file, edit there; otherwise document it in the same AGENTS.md/PLAYBOOKS.md section.
(d) Local verification: re-read the section for clarity; no other tests required (doc-only change).
(e) Create Linear issue via LINEAR_API_KEY: title 'Document sub-agent task-description template auth-refresh requirement', team BOLT/INTERNAL, link to fleet-task id + LEARNINGS 2026-05-31.
(f) git add + commit with conventional commit message 'docs(agents): require explicit auth-refresh step (0) in sub-agent task descriptions' and Carson's git identity (texture-coding-agent / [email protected] per TOOLS.md).
(g) git push origin kai/sub-agent-template-auth-step
(h) gh pr create with the Linear key in body and a summary describing the 2026-05-30 precedent.
(i) PATCH this task to completed with result.pr_url, result.linear_issue_id, result.committed_sha, result.file_edited (AGENTS.md or PLAYBOOKS.md path).
No Slack DM. No need for Carson approval before opening the PR — this is doc-only and Carson can review on the PR.
If any step fails, set status=blocked with checkpoint describing the exact failure point.
Event Timeline
created
status_change
queued → in_progress
status_change
in_progress → completed