McRitchie Studio
Say Hi 👋
Agents Builders
← All Tasks
Sizing

Document the agent task-board API onboarding (auth + contract + footguns)

Archived Priority 1
task-bfcf6e8c1ab2

From the 2026-06-17 doc audit. The feature->task->PR->QA->deploy loop's front door is undocumented: a fresh agent cannot create a task because the auth secret/flow and the write contract live only in source. Write a code-true onboarding doc. Worktree slug: task-board-api-onboarding Verified contract: auth via Rails.application.credentials.agent_api_secret || ENV[AGENT_API_SECRET] (1Password 'Agent API Secret'); POST /api/v1/auth -> 24h Bearer; 9 stages (only queue/start/complete/fail_task/archive have transition endpoints -- pr_review/qa_review/prod_ready set via PATCH stage); devops normalized into metadata.devops; footguns: update overwrites devops wholesale; list items split on comma and newline; unsupported devops keys dropped; slug auto-generated not settable.

Created

Jun 18, 04:04

Started

Jun 18, 04:04

Completed

Jun 18, 04:53

DevOps handoff

Type

Docs

Shape

—

Worktree Slug

—

Repositories

mcritchie-studio

Release Train

—

Branch

feat/task-board-api-onboarding

Pull Request

https://github.com/amcritchie/mcritchie-studio/pull/34

Local URL

—

QA URL

https://qa.mcritchie.studio

Production URL

—

docs api agents onboarding

Acceptance Criteria

  • New docs/agents/modules/task-board-api.md documents auth (secret source / 1Password ref / POST /api/v1/auth / Bearer / 24h / fails-closed)
  • Documents every endpoint: index (stage + agent_slug filters) / show / create / update / destroy / transition members (queue start complete fail_task archive)
  • Documents permitted fields and the 9 stages noting which need a raw PATCH stage vs a transition endpoint
  • Documents the devops key contract (scalars + lists) matching Task::DEVOPS_KEYS
  • Documents the footguns: devops wholesale-overwrite on update; list items split on comma and newline; unsupported keys dropped; slug auto-generated
  • Includes copy-paste worked examples using the op secret pattern without printing secrets
  • AGENT_API_SECRET added to credential-inventory.md with the op reference
  • index.md Start Here links the new doc and devops-task-board.md cross-references it
  • Doc is accurate to code with no invented endpoints or fields
  • AGENTS.md regenerated via bin/install-agent-docs post-merge since index.md changed

Expected Test Plan

  • ruby/grep cross-check endpoints+fields against routes.rb + tasks_controller.rb + task.rb (PASS author-verified)
  • manual: follow the worked examples against the prod board (PASS this session auth+create+start+patch all 200)
  • bin/install-agent-docs check post-merge

Checks Run

No completed checks recorded.

Stage Timeline

Who handled each stage, the time it took (measured), and the model / tokens / cost reported (best-effort) — plus who's on it right now. — means the agent didn't report that metric.

No stage changes recorded yet.

Conversation

QA review feedback, agent handoffs, and follow-up notes for this task.

Handoff avi 9 days ago

Avi merged PR #34 and deployed it to QA. Root /Users/alex/projects/AGENTS.md was regenerated with bin/install-agent-docs and bin/install-agent-docs check passed.

Handoff avi 9 days ago

Production deployed in McRitchie Studio v70 (82b1791): Task-board API onboarding docs. Verify at https://mcritchie.studio.

Sealed-bid sizing

Edit →

Alex (PM)

—

Avi (PO)

—

Dev

—

Actual

—