P1: Apply commenting style guide to packages/AgentCore/Sources/AgentOrchestrator/AgentOrchestrator.swift #66

New Issue

2026-05-12T19:21:00Z

KofTwentyTwo commented

2026-05-12 19:21:00 +00:00

(Migrated from github.com)

Goal

Bring packages/AgentCore/Sources/AgentOrchestrator/AgentOrchestrator.swift up to the standard in .planning/code-commenting-guide.md. Load-bearing actor — agent loop, tool-call orchestration, streaming, cache-hint accounting.

Constraints

ONE atomic commit. No code behavior changes — comments + docstrings only.
18/18 boundary gates green.
Apply the guide's 5 comment shapes:
- 5-line opener at top of file (WHY this orchestrator exists, threading model, who emits/consumes)
- Type-level /// docstring with Overview + Topics + Threading + See Also
- Method-level docstrings on public + key private methods (turn loop, tool dispatch, recovery paths)
- ASCII diagram of turn lifecycle (request → stream → tool-use → resume → message_stop)
- "Before you edit" invariants block (single consumer of orchestrator events, tool-choice discipline on recovery calls, recent-turns threading, cache-hint emission rules)
- MARK dividers as a table of contents

Anti-patterns to remove

Plan-ID-only comments — rewrite WHY-first with audit IDs as parenthetical footnotes.
Stale references to closed Plan IDs or removed types.
Bare TODO: / FIXME: without issue link.

Follow the canonical pattern

Use the AppDelegate.swift P0 rewrite (#65) as the canonical applied pattern.

Parent epic

#64

Source

.planning/code-commenting-guide.md → Migration plan → P1

## Goal Bring `packages/AgentCore/Sources/AgentOrchestrator/AgentOrchestrator.swift` up to the standard in `.planning/code-commenting-guide.md`. Load-bearing actor — agent loop, tool-call orchestration, streaming, cache-hint accounting. ## Constraints - ONE atomic commit. No code behavior changes — comments + docstrings only. - 18/18 boundary gates green. - Apply the guide's 5 comment shapes: - 5-line opener at top of file (WHY this orchestrator exists, threading model, who emits/consumes) - Type-level `///` docstring with Overview + Topics + Threading + See Also - Method-level docstrings on public + key private methods (turn loop, tool dispatch, recovery paths) - ASCII diagram of turn lifecycle (request → stream → tool-use → resume → message_stop) - "Before you edit" invariants block (single consumer of orchestrator events, tool-choice discipline on recovery calls, recent-turns threading, cache-hint emission rules) - MARK dividers as a table of contents ## Anti-patterns to remove - Plan-ID-only comments — rewrite WHY-first with audit IDs as parenthetical footnotes. - Stale references to closed Plan IDs or removed types. - Bare `TODO:` / `FIXME:` without issue link. ## Follow the canonical pattern Use the AppDelegate.swift P0 rewrite (#65) as the canonical applied pattern. ## Parent epic #64 ## Source .planning/code-commenting-guide.md → Migration plan → P1

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: KofTwentyTwo/Jarvis#66