docs: sync with today's sprint merges (#46, #48, #51–#55)#56
Merged
Conversation
Update all docs to reflect today's merged changes: - Capability count: 66 → 69 (3 composite cards added in #55) - operation-cards.md: fix per-domain counts, update capability names to post-naming-overhaul IDs, add composite field to schema table, add Composite Capabilities section documenting batch.ts/builders.ts path - adapters.md: clarify CLI covers 66 atomic caps; composites are GraphQL-only - system-design.md: replace deleted agent-interface/tools/ source ref, update Current Scope section with accurate domain breakdown - architecture/README.md: remove deleted agent.ts ref → index.ts - repository-structure.md: add gql/batch.ts, gql/builders.ts, gql/capability-registry.ts, core/execute/composite.ts, core/registry/schema-utils.ts; fix archive/ → plans/ in dir tree - setup-for-agents.md: fix broken agent-interface.md link (deleted in #51) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
📝 WalkthroughWalkthroughDocumentation and architecture updates across 13 files to introduce three composite capabilities (69 total: 66 atomic + 3 composite). Changes add composite metadata and docs, mark composites as GraphQL-only (batch path), and document new modules for composite expansion, builders, and GraphQL batching. Changes
Sequence Diagram(s)sequenceDiagram
participant Agent as Agent/Client
participant Registry as Operation Registry
participant Expander as core/execute/composite
participant Builders as gql/builders.ts
participant Batch as gql/batch.ts
participant GQL as GitHub GraphQL
participant Merger as ResultEnvelope
Agent->>Registry: request composite capability (e.g., pr.threads.composite)
Registry->>Expander: expand composite steps
Expander->>Builders: build per-capability mutations
Builders->>Batch: assemble batch mutation
Batch->>GQL: single GraphQL round-trip (batch)
GQL-->>Batch: batched responses
Batch->>Merger: map & merge responses
Merger-->>Agent: unified ResultEnvelope
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 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: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
docs/getting-started/first-task.md (1)
341-345:⚠️ Potential issue | 🟡 MinorDeprecated underscore capability IDs in "Or workflows" example — one doesn't exist.
Lines 343–344 use incorrect forms:
workflow_dispatch.run→ should beworkflow.dispatch.runworkflow_run.logs.get→ doesn't exist; the correct ID isworkflow.job.logs.getCopying these commands will fail. The second one uses both the deprecated
workflow_run.*prefix and the wrong resource name (runinstead ofjob).📝 Proposed fix
-npx ghx capabilities explain workflow_dispatch.run -npx ghx capabilities explain workflow_run.logs.get +npx ghx capabilities explain workflow.dispatch.run +npx ghx capabilities explain workflow.job.logs.getBased on learnings: "Adopt dotted capability names (domain.resource.action) consistently in both docs and code. For workflows, prefer
workflow.run.*andworkflow.job.*; do not use deprecated underscore formsworkflow_run.*orworkflow_job.*."🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/getting-started/first-task.md` around lines 341 - 345, Update the example capability IDs to use the dotted domain.resource.action format and correct resource names: replace `workflow_dispatch.run` with `workflow.dispatch.run`, and replace the invalid `workflow_run.logs.get` with the correct `workflow.job.logs.get`; ensure any other occurrences avoid deprecated underscore forms like `workflow_run.*` or `workflow_job.*` and prefer `workflow.run.*` / `workflow.job.*` consistently in the "Or workflows" example and surrounding text.docs/capabilities/README.md (1)
84-95:⚠️ Potential issue | 🔴 CriticalUpdate table header from "(12)" to "(11)" and align capability names with implementation.
The Workflows table header and Mermaid diagram incorrectly claim 12 capabilities, but only 11 are listed. Additionally, the detailed documentation in
docs/capabilities/workflows.mduses deprecated underscore naming (e.g.,workflow_dispatch.run,workflow_runs.list,workflow_run.view,workflow_job.logs.get) which conflicts with the implementation and preferred dotted naming convention. The table should also referenceworkflow.job.logs.rawconsistently, notworkflow_job.logs.analyze.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/capabilities/README.md` around lines 84 - 95, Update the Workflows table header from "(12)" to "(11)" and make the capability names match the implementation and preferred dotted convention: replace deprecated underscores (e.g., workflow_dispatch.run → workflow.dispatch.run, workflow_runs.list → workflow.runs.list, workflow_run.view → workflow.run.view, workflow_job.logs.get → workflow.job.logs.get) and ensure the table uses workflow.job.logs.raw (not workflow_job.logs.analyze); also update the accompanying Mermaid diagram to reflect the same 11 capabilities and the dotted names so the docs and diagram are consistent with the code.docs/architecture/adapters.md (1)
120-120:⚠️ Potential issue | 🟡 MinorStale capability count in GraphQL Features section.
Line 120 (unchanged) still reads "28 capabilities support GraphQL routes" while the overview table at Line 12 now shows "~28 atomic + 3 composite". Both are in the same
## GraphQL Adaptersection, creating a visible contradiction.✏️ Proposed fix
-- **Selective coverage**: 28 capabilities support GraphQL routes (typically read-heavy operations) +- **Selective coverage**: ~28 atomic + 3 composite capabilities use GraphQL routes🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/architecture/adapters.md` at line 120, Update the stale sentence "28 capabilities support GraphQL routes" in the "## GraphQL Adapter" section to match the overview table by replacing it with a phrasing that reflects "~28 atomic + 3 composite" (e.g., "Approximately 28 atomic and 3 composite capabilities support GraphQL routes") so the GraphQL Features line and the overview table are consistent.
🧹 Nitpick comments (1)
docs/architecture/operation-cards.md (1)
7-45:OperationCardclass diagram is now out of sync with the Card Contents table.The Mermaid
classDiagramstill shows onlycli?: CLIMetadataandgraphql?: GraphQLMetadata, while the updated Card Contents table below it documentscompositeas a third optional field. A reader consulting the diagram alone will not know the composite field exists.♻️ Proposed diagram update
class OperationCard { capability_id: string version: string description: string input_schema: JSONSchema output_schema: JSONSchema routing: RoutingPolicy cli?: CLIMetadata graphql?: GraphQLMetadata + composite?: CompositeMetadata } class CLIMetadata { command: string args?: CliArg[] output_format?: string } class GraphQLMetadata { operation?: string field_mapping?: Record } + class CompositeMetadata { + steps: CompositeStep[] + output_strategy: string + } + class Route { name: string } OperationCard --> RoutingPolicy OperationCard --> CLIMetadata OperationCard --> GraphQLMetadata + OperationCard --> CompositeMetadata RoutingPolicy --> Route🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/architecture/operation-cards.md` around lines 7 - 45, The classDiagram is missing the new optional composite field on OperationCard; update the Mermaid diagram by adding "composite?: CompositeMetadata" to the OperationCard class, add a new "CompositeMetadata" class with relevant properties (e.g., type, components, mapping or whatever matches the Card Contents table), and create an association line "OperationCard --> CompositeMetadata" (and any relationships from CompositeMetadata to other classes like Route or a Component class if specified) so the diagram matches the Card Contents table.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/capabilities/README.md`:
- Line 3: Update the written total or the Mermaid domain counts so they match
the cards registry: locate the phrase "These 69 capabilities" and the Mermaid
diagram listing domain counts (19, 22, 5, 12, 3, 6, 1) and reconcile the
mismatch (68 vs 69) by either correcting the header number to 68 or adjusting
the diagram counts to reflect the registry; ensure the same correction is
applied to the repeated section spanning lines 11-29 so the document and the
cards registry are consistent.
In `@docs/getting-started/README.md`:
- Line 73: The sample CLI output in the README's "See all 69 capabilities"
section shows outdated counts for two categories; update the displayed strings
"Issues (18)" to "Issues (19)" and "Pull Requests (21)" to "Pull Requests (22)"
in the sample CLI output block so the example matches the actual capability
counts referenced elsewhere.
In `@docs/guides/cli-usage.md`:
- Line 35: Update the sentence "Returns a JSON array of all 69 capabilities with
descriptions:" in docs/guides/cli-usage.md to clarify that the total includes
three composite capabilities that are only executable via GraphQL and not via
the CLI; reference the command ghx capabilities list and adapters.md wording to
ensure it explicitly states that 66 are CLI-executable atomic capabilities and 3
are composite-only (GraphQL) so readers aren’t confused.
---
Outside diff comments:
In `@docs/architecture/adapters.md`:
- Line 120: Update the stale sentence "28 capabilities support GraphQL routes"
in the "## GraphQL Adapter" section to match the overview table by replacing it
with a phrasing that reflects "~28 atomic + 3 composite" (e.g., "Approximately
28 atomic and 3 composite capabilities support GraphQL routes") so the GraphQL
Features line and the overview table are consistent.
In `@docs/capabilities/README.md`:
- Around line 84-95: Update the Workflows table header from "(12)" to "(11)" and
make the capability names match the implementation and preferred dotted
convention: replace deprecated underscores (e.g., workflow_dispatch.run →
workflow.dispatch.run, workflow_runs.list → workflow.runs.list,
workflow_run.view → workflow.run.view, workflow_job.logs.get →
workflow.job.logs.get) and ensure the table uses workflow.job.logs.raw (not
workflow_job.logs.analyze); also update the accompanying Mermaid diagram to
reflect the same 11 capabilities and the dotted names so the docs and diagram
are consistent with the code.
In `@docs/getting-started/first-task.md`:
- Around line 341-345: Update the example capability IDs to use the dotted
domain.resource.action format and correct resource names: replace
`workflow_dispatch.run` with `workflow.dispatch.run`, and replace the invalid
`workflow_run.logs.get` with the correct `workflow.job.logs.get`; ensure any
other occurrences avoid deprecated underscore forms like `workflow_run.*` or
`workflow_job.*` and prefer `workflow.run.*` / `workflow.job.*` consistently in
the "Or workflows" example and surrounding text.
---
Duplicate comments:
In `@docs/guides/README.md`:
- Line 12: The "List all 69 capabilities" description for the CLI command `npx
ghx capabilities list` is ambiguous; run `npx ghx capabilities list` (or inspect
the implementation that powers it) to confirm whether it returns 69 entries
including composite capabilities or only 66 atomic capabilities, then update the
text to accurately state what the command returns (e.g., "List all 69
capabilities (including X composite capabilities)" or "List all 66 atomic
capabilities") and ensure the same wording is reconciled with the corresponding
note in the other README that references this count.
---
Nitpick comments:
In `@docs/architecture/operation-cards.md`:
- Around line 7-45: The classDiagram is missing the new optional composite field
on OperationCard; update the Mermaid diagram by adding "composite?:
CompositeMetadata" to the OperationCard class, add a new "CompositeMetadata"
class with relevant properties (e.g., type, components, mapping or whatever
matches the Card Contents table), and create an association line "OperationCard
--> CompositeMetadata" (and any relationships from CompositeMetadata to other
classes like Route or a Component class if specified) so the diagram matches the
Card Contents table.
- capabilities/README.md: update Issues Mermaid/table to 21 (add issue.triage.composite, issue.update.composite); update Workflows Mermaid/table to 11; replace all pre-overhaul PR IDs with current dotted names (pr.merge, pr.thread.*, pr.review.submit, pr.diff.files, pr.checks.*, pr.merge.status, pr.threads.composite, pr.create, pr.update) - getting-started/README.md: fix sample output counts (18→21, 21→22) and pr.merge.execute → pr.merge - getting-started/first-task.md: fix deprecated IDs in examples (pr.merge.execute→pr.merge, pr.review.submit_approve→pr.review.submit, workflow_dispatch.run→workflow.dispatch.run, workflow_run.logs.get→workflow.job.logs.get) - architecture/adapters.md: update GraphQL coverage sentence to include composite capabilities - architecture/operation-cards.md: add CompositeMetadata class to Mermaid class diagram Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
There was a problem hiding this comment.
🧹 Nitpick comments (2)
docs/architecture/operation-cards.md (1)
10-19:OperationCardclass body omitscomposite?andCompositeStepis undefined in the diagram.Two minor documentation inconsistencies:
cli?andgraphql?are listed as explicit optional fields in theOperationCardclass body, butcomposite?is not — it only appears as a relationship arrow. Addingcomposite?: CompositeMetadatato the class body would match the established pattern.
CompositeMetadata.stepsreferencesCompositeStep[], but unlikeRoute(which is defined forRoutingPolicy),CompositeStephas no corresponding class in the diagram.♻️ Proposed additions
class OperationCard { capability_id: string version: string description: string input_schema: JSONSchema output_schema: JSONSchema routing: RoutingPolicy cli?: CLIMetadata graphql?: GraphQLMetadata + composite?: CompositeMetadata }class CompositeMetadata { steps: CompositeStep[] output_strategy: string } + +class CompositeStep { + capability_id: string + params_map: Record +}Also applies to: 37-50
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/architecture/operation-cards.md` around lines 10 - 19, Update the diagram and class body to include the missing optional composite field and define the referenced step type: add composite?: CompositeMetadata to the OperationCard class definition so it matches cli? and graphql?, and add a class/definition for CompositeStep used by CompositeMetadata.steps (analogous to how Route is defined for RoutingPolicy) to remove the undefined reference; update any labels/relationships to reference CompositeMetadata and CompositeStep consistently (symbols: OperationCard, composite, CompositeMetadata, CompositeStep, RoutingPolicy, Route).docs/capabilities/README.md (1)
35-35: MD056 lint violations on domain group-header rows (changed lines).
| **Issues (21)** |and| **Workflows (11)** |are single-cell rows inside a 3-column table, triggeringMD056/table-column-countin the static analysis. The same pattern exists on unchanged lines 57 and 80, so this is pre-existing — but the changed lines still surface the warning in CI.Fix with empty trailing cells or inline suppression:
♻️ Option A — pad with empty cells
-| **Issues (21)** | +| **Issues (21)** | | |-| **Workflows (11)** | +| **Workflows (11)** | | |(Apply the same pattern to the unchanged lines 57 and 80 while you're here.)
♻️ Option B — suppress with inline markdownlint comment
-| **Issues (21)** | +| **Issues (21)** | <!-- markdownlint-disable-line MD056 -->Also applies to: 86-86
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/capabilities/README.md` at line 35, The single-cell table header rows like "| **Issues (21)** |" and "| **Workflows (11)** |" trigger MD056; fix by expanding those rows to match the table's 3-column layout (e.g., "| **Issues (21)** | | |") or by adding an inline markdownlint suppression comment (e.g., append "<!-- markdownlint-disable-line MD056 -->"); apply the same change to the other occurrences in the same table (the remaining single-cell rows such as the ones currently at the other changed/unchanged locations).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@docs/architecture/operation-cards.md`:
- Around line 10-19: Update the diagram and class body to include the missing
optional composite field and define the referenced step type: add composite?:
CompositeMetadata to the OperationCard class definition so it matches cli? and
graphql?, and add a class/definition for CompositeStep used by
CompositeMetadata.steps (analogous to how Route is defined for RoutingPolicy) to
remove the undefined reference; update any labels/relationships to reference
CompositeMetadata and CompositeStep consistently (symbols: OperationCard,
composite, CompositeMetadata, CompositeStep, RoutingPolicy, Route).
In `@docs/capabilities/README.md`:
- Line 35: The single-cell table header rows like "| **Issues (21)** |" and "|
**Workflows (11)** |" trigger MD056; fix by expanding those rows to match the
table's 3-column layout (e.g., "| **Issues (21)** | | |") or by adding an
inline markdownlint suppression comment (e.g., append "<!--
markdownlint-disable-line MD056 -->"); apply the same change to the other
occurrences in the same table (the remaining single-cell rows such as the ones
currently at the other changed/unchanged locations).
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
1 participant
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
issue.triage.composite,issue.update.composite,pr.threads.composite)operation-cards.md: fix per-domain counts and capability names (post-naming-overhaul), addcompositefield to schema table, add Composite Capabilities sectionadapters.md: clarify CLI covers 66 atomic capabilities; composites are GraphQL-onlysystem-design.md: replace deletedagent-interface/tools/source ref; update Current Scopearchitecture/README.md: remove deletedagent.tsref →index.tsrepository-structure.md: addgql/batch.ts,gql/builders.ts,gql/capability-registry.ts,core/execute/composite.ts,core/registry/schema-utils.ts; fixarchive/→plans/in dir treesetup-for-agents.md: fix broken link to deletedagent-interface.mdTest plan
packages/core/src/core/registry/cards/🤖 Generated with Claude Code
Summary by CodeRabbit
New Features
Documentation