Summary

Traced every current place that creates or edits a subagent document, prompted by a review question on the when_to_use/model retirement PR. documents.description is a separate, generic top-level column (used by generic document-listing routes like documents.ts/kb.ts , not the agent-specific UI/dispatch surfaces, which all read frontmatter fresh) that writeDocument only updates when a caller explicitly passes it. Neither of the two real, active agent-creation paths did:

• author-subagent.ts's authorSubagentDoc , the single writeDocumentGuarded call site (handles both create and edit) is used by agent-create.ts (the primary create-agent entrypoint) and the repair/edit flow. Now passes the effective description parsed fresh from the content actually being saved.
• seed-playbook.ts's migrateToPlaybook , all three subagent-doc writes (default system agents, the no-instructions placeholder, and the full custom-agent write) now pass description too.

Confirmed empirically against production: 845 of 854 real subagent docs have this column out of sync with their actual frontmatter description.

Backfill

New backfill-agent-description-column.ts, DRY_RUN-verified against production: 845 to sync, 8 already in sync, 1 skipped (a malformed doc with no frontmatter description at all , correctly reported rather than guessed at, since writeDocument's description param has no way to explicitly clear a stale column value, only to leave it alone). Not run for real yet , flagging for an explicit decision given the scale.

Self-caught during review

My first-pass comment in author-subagent.ts claimed the verification gate "requires" a description to be present before this write. Traced into verify-subagent-doc.ts and found description_present is only a warning-severity check, not an error one , dryReport.ok does not actually guarantee that. Fixed the comment to describe the real (still safe) behavior instead of a false guarantee.

Verified

• pnpm --filter @zero/server run types , clean.
• oxlint --deny-warnings , clean on all 6 files.
• deps:check , clean (1774 modules).
• Full playbook/agent-workspace test directories plus the new test file , 1364 tests, all pass.
• DRY_RUN=1 BACKFILL_ALL=1 against the real production database (confirmed on primary via pg_is_in_recovery()).
• Thermo-reviewed , 🔴 Blocking: none.

Known gap, not fixed here

migrateToPlaybook's three write-call fixes have no new dedicated test coverage , this legacy migration function has no existing test file to extend (confirmed by search), and the fix is mechanically identical to the pattern tested thoroughly in author-subagent.test.ts/agent-create.test.ts. Flagging rather than claiming coverage that isn't there.

🤖 Generated with Claude Code

https://claude.ai/code/session_01E3AhwqADAFeqe9wEhz6Mk7

Greptile Summary

This PR propagates agent frontmatter descriptions into the generic documents.description column, adds a bulk synchronization script, and expands tests around the primary authoring path.

• New-agent and migration writes now supply a top-level description.
• The backfill plans synchronization against the column's 200-character stored representation.
• Existing-agent edits still lose the description argument in the guarded patch layer.
• The backfill can trigger broader subagent reconciliation than its description-only contract suggests.

Confidence Score: 4/5

The PR is not yet safe to merge because existing-agent edits still leave documents.description stale, and the explicit assertion rule must also be satisfied.

The new argument reaches the guarded-write boundary but is omitted from the actual patch sent to writeDocument, leaving the principal edit path functionally incomplete; the bulk backfill also needs protection against unintended reconciliation side effects.

**Files Ne