docs: add composable agents design page - #11
Merged
equationalapplications merged 17 commits intoAug 11, 2026
Conversation
Design for a new docs/12-composable-agents.md page reframing the tutorial's Lambda as one instance of a hierarchical, heartbeat-driven, delegate-and-message-back agent pattern. Conceptual only — no code. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Rung 6 maps rung 4's "central memory" onto core-llm-wiki's entityId namespacing, tierWeights, per-entity ontology, and scoped access as an illustrative (non-adopted) extension. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Six fixes from spec review, all clarifications rather than scope changes; Status stays "Approved — ready for writing-plans". - Correct section count: six sections -> eight (intro, six rungs, closing). - Rung 4 now explicitly introduces the term "central memory", which rung 6 had been calling back to without it ever being named. - Rewrite the rung 1 statelessness bullet: /tmp is not simply disposable. 01-architecture.md:10 leans on warm-container reuse for the status reader and 02-rehydration.md:91 notes it survives until redeploy, so the claim is that no *durable* state lives there, not that it vanishes. - Reword the "no new terminology" non-goal to "no *parallel* vocabulary", since the ladder does legitimately introduce heartbeat/rung/to-do list/ sub-agent/central memory. - Expand Placement: index table only (leave prose links alone), row format, and that the 12- row goes above the unnumbered bedrock-model-comparison row. - Add a Length and format section (120-180 lines, diagrams sparingly). Also add a "verify before drafting" note to rung 6: it cites a lot of external core-llm-wiki API surface and links a repo name that differs from the package name, so that README needs fetching before the doc is written. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…ing, escape-hatch clarity
|
Warning Review limit reachedYou’ve reached a temporary PR review limit under our Fair Usage Limits Policy. Next review available in: 47 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (3)
📝 WalkthroughSummary by CodeRabbit
WalkthroughThe change adds a composable-agents documentation page, its design specification and implementation plan, and a README index entry. The page documents the existing fetch Lambda as rung 1 and describes rungs 2–6 as conceptual. ChangesComposable agents documentation
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
🧹 Nitpick comments (1)
docs/superpowers/specs/2026-08-11-composable-agents-design.md (1)
190-198: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winReplace the pre-drafting verification block with its completed result.
The specification is marked
Implemented, and the implementation plan records verification on August 11, 2026. Leaving “Verify before drafting” and “unconfirmed” makes the specification appear unfinished. Record the completed verification and the corrected entity-ID semantics, or remove this block.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/superpowers/specs/2026-08-11-composable-agents-design.md` around lines 190 - 198, Replace the “Verify before drafting” block with a completed verification note reflecting the August 11, 2026 verification. Confirm the external API names and repository/package URL, and document the corrected entity-ID semantics; otherwise remove the block so the Implemented specification no longer presents these details as unconfirmed.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/12-composable-agents.md`:
- Around line 3-6: Define statelessness consistently as independence from
durable in-memory state rather than literal absence of memory state. Update
docs/12-composable-agents.md lines 3-6,
docs/superpowers/specs/2026-08-11-composable-agents-design.md lines 71-74, and
docs/superpowers/plans/2026-08-11-composable-agents-doc.md lines 92-95 to
replace the absolute wording and acknowledge reusable warm /tmp contents and
cached status-reader handles.
- Around line 121-125: Update the follow-up task design to use the Rung 4 intent
contract: in docs/12-composable-agents.md lines 121-125, replace the sub-agent’s
direct to-do-list write with an intent request; apply the same
coordinator-created-item contract in
docs/superpowers/specs/2026-08-11-composable-agents-design.md lines 145-148 and
update the corresponding implementation steps in
docs/superpowers/plans/2026-08-11-composable-agents-doc.md lines 279-283.
- Around line 38-45: Narrow the composability claims across the three documented
sites: in docs/12-composable-agents.md lines 38-45, replace the “any number”
guarantee with the storage-only guarantee and document possible duplicate
Bedrock/Discord side effects plus queue/rebase requirements; in
docs/superpowers/specs/2026-08-11-composable-agents-design.md lines 93-97,
describe the conditional write as S3 storage protection rather than general
multi-agent coordination; in
docs/superpowers/plans/2026-08-11-composable-agents-doc.md lines 29-33, state
that reservedConcurrentExecutions: 1 is a tutorial default scoped to a single
Lambda function.
In `@docs/superpowers/plans/2026-08-11-composable-agents-doc.md`:
- Around line 54-59: Resolve the contradiction in the “Not touched” rule and
Task 6: either explicitly exempt this approved specification from the
prohibition on rewriting files under docs/superpowers/specs/, or remove Task 6’s
instruction to update the specification status. Keep the file-scope guidance
consistent with the selected approach.
In `@docs/superpowers/specs/2026-08-11-composable-agents-design.md`:
- Around line 164-172: Update the “Tiered memory” description to identify
tier_wisdom, tier_fact, and tier_working as ordinary entity IDs/namespaces whose
names represent tiers, with tierWeights assigning their weights; remove wording
that presents them as built-in tier names. Preserve the surrounding explanation
of durable versus working memory.
- Around line 143-145: Update the Rung 5 section heading description to remove
the claim that it closes the ladder, and instead describe handling work that
exceeds a single invocation. Preserve the surrounding explanation and
acknowledge that Rung 6 follows immediately.
---
Nitpick comments:
In `@docs/superpowers/specs/2026-08-11-composable-agents-design.md`:
- Around line 190-198: Replace the “Verify before drafting” block with a
completed verification note reflecting the August 11, 2026 verification. Confirm
the external API names and repository/package URL, and document the corrected
entity-ID semantics; otherwise remove the block so the Implemented specification
no longer presents these details as unconfirmed.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: dd4020a4-b425-49c6-aab9-dbf3f39358df
📒 Files selected for processing (4)
README.mddocs/12-composable-agents.mddocs/superpowers/plans/2026-08-11-composable-agents-doc.mddocs/superpowers/specs/2026-08-11-composable-agents-design.md
Six actionable findings plus one nitpick, all docs-only: - Statelessness: opener now reads "carries no state in memory that has to outlive an invocation" instead of the absolute "no state is held in memory between runs"; aligned across docs/12, the spec, and the plan. - Composability: "any number of these can exist" replaced with the storage- only guarantee. Documented that the conditional write does not serialize separate Lambda functions or make pre-publish Bedrock/Discord side effects idempotent, and that reservedConcurrentExecutions: 1 is the tutorial default, function-scoped and overridable via RESERVED_CONCURRENCY. - Rung 5 follow-ups: sub-agent now emits an intent and the coordinator applies it to create the to-do item, matching Rung 4's read-only sub-agent contract. - Spec Rung 5: "Closes the ladder" replaced with "handles work that exceeds a single invocation; rung 6 follows immediately." - Tiered memory: tier_wisdom / tier_fact / tier_working reframed as ordinary entity ids with naming-convention tiers; tierWeights described as a per-entity multiplier. - Plan "Not touched" rule: explicit exception added for the one-line Status flip this plan makes in Task 6. - Spec "Verify before drafting" block: replaced with a 2026-08-11 verification record so an Implemented spec no longer reads as unconfirmed. Co-Authored-By: Claude <noreply@anthropic.com>
Owner
Author
/fix-pr follow-upCommit: Review resolution
Verification
No typecheck / lint / tests apply — this PR is docs-only. |
…ifics Per a follow-up note that the doc is conceptual, not about a Discord bot. My new "Why composable" paragraph in docs/12 and the matching spec text spoke in terms of "Bedrock calls and Discord posts"; replaced with general language about side-effecting operations. Pre-existing rung 1 paragraph still mentions Bedrock/Discord as concrete examples of the fetch tick — left in place; will check with the author on whether those should be generalized too. Co-Authored-By: Claude <noreply@anthropic.com>
…example Per follow-up that the doc is conceptual, not about a Discord bot. Rung 1's "Spin up, work, go away" paragraph and the spec's matching description referred to "call Bedrock twice, post to Discord" specifically; replaced with "do the agent's scoped work". The doc and spec no longer name a specific external service anywhere; the conceptual pattern stands on its own. Co-Authored-By: Claude <noreply@anthropic.com>
Owner
Author
/fix-pr follow-up — generalizationCommit: The doc is conceptual, not about a Discord bot — applied two more commits to remove the last concrete-service references:
Co-Authored-By: Claude noreply@anthropic.com |
equationalapplications
deleted the
docs/composable-agents-spec-revisions
branch
August 11, 2026 20:51
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Spec: docs/superpowers/specs/2026-08-11-composable-agents-design.md
docs/12-composable-agents.md: names this tutorial's scheduled Lambda as a lightweight composable cloud agent, then climbs a six-rung ladder from it (to-do list, delegation, intent queue, follow-up tasks/EC2 escape hatch, tiered memory) toward hierarchical orchestration. Conceptual only — no code, tables, or infrastructure changes.Test plan
01-architecture.md,02-rehydration.md,05-from-tutorial-to-prod.md,10-concurrency.md)10-concurrency.md#high-contention-the-single-writer-queueanchor verified against the actual heading slugcore-llm-wikiREADME fetched and every cited API name (WikiMemory,entityId,tierWeights, ontology modes, etc.) verified against itdocs/12-composable-agents.mdcross-checked againstsrc/,infra/stack.ts, and sibling docs for factual accuracy (EventBridge input, Bedrock call count, reserved concurrency,/tmpsemantics, table count)docs/andREADME.md