docs(context): document pluggable scope chain resolution API and write developer guide #8918

Open
opened 2026-04-14 04:03:11 +00:00 by HAL9000 · 3 comments
Owner

Background and Context

Epic #5507 (Pluggable Scope Chain Resolution — Extension Points for Context Scoping) has implemented the ScopeChainResolver protocol (#5531) and an example custom scope resolver (#5535). The final deliverable for this Epic is comprehensive developer documentation that explains how to write, register, and test custom scope resolvers.

Without clear documentation, the extension API is effectively unusable for third-party developers. The documentation must cover the protocol interface, entry-point registration, priority ordering, and include a worked example.

This issue blocks Epic #5507.

Acceptance Criteria

  • docs/reference/scope-chain-extensions.md is created with full API reference
  • Documentation covers the ScopeChainResolver protocol interface and method signatures
  • Documentation covers entry-point registration (cleveragents.scope_resolvers group)
  • Documentation covers priority ordering and how resolvers are chained
  • A worked example (end-to-end) is included showing a custom resolver from scratch
  • Documentation is linked from the main ACMS reference page
  • Documentation is reviewed and approved by a maintainer

Subtasks

  • Write docs/reference/scope-chain-extensions.md with API reference
  • Add protocol interface documentation with type signatures
  • Add entry-point registration guide with pyproject.toml example
  • Add priority ordering explanation with diagram
  • Add worked example: custom JiraIssueResolver from scratch
  • Link from docs/reference/acms.md to the new extension guide

Definition of Done

  • All acceptance criteria met
  • Tests written and passing (coverage >= 97%)
  • Code reviewed and approved
  • Documentation updated if needed
  • No regressions introduced

Metadata

  • Commit message: docs(context): document pluggable scope chain resolution API and developer guide
  • Branch name: docs/context-scope-chain-extension-guide

Automated by CleverAgents Bot
Agent: new-issue-creator

## Background and Context Epic #5507 (Pluggable Scope Chain Resolution — Extension Points for Context Scoping) has implemented the `ScopeChainResolver` protocol (#5531) and an example custom scope resolver (#5535). The final deliverable for this Epic is comprehensive developer documentation that explains how to write, register, and test custom scope resolvers. Without clear documentation, the extension API is effectively unusable for third-party developers. The documentation must cover the protocol interface, entry-point registration, priority ordering, and include a worked example. This issue blocks Epic #5507. ## Acceptance Criteria - [ ] `docs/reference/scope-chain-extensions.md` is created with full API reference - [ ] Documentation covers the `ScopeChainResolver` protocol interface and method signatures - [ ] Documentation covers entry-point registration (`cleveragents.scope_resolvers` group) - [ ] Documentation covers priority ordering and how resolvers are chained - [ ] A worked example (end-to-end) is included showing a custom resolver from scratch - [ ] Documentation is linked from the main ACMS reference page - [ ] Documentation is reviewed and approved by a maintainer ## Subtasks - [ ] Write `docs/reference/scope-chain-extensions.md` with API reference - [ ] Add protocol interface documentation with type signatures - [ ] Add entry-point registration guide with `pyproject.toml` example - [ ] Add priority ordering explanation with diagram - [ ] Add worked example: custom `JiraIssueResolver` from scratch - [ ] Link from `docs/reference/acms.md` to the new extension guide ## Definition of Done - [ ] All acceptance criteria met - [ ] Tests written and passing (coverage >= 97%) - [ ] Code reviewed and approved - [ ] Documentation updated if needed - [ ] No regressions introduced ## Metadata - **Commit message:** `docs(context): document pluggable scope chain resolution API and developer guide` - **Branch name:** `docs/context-scope-chain-extension-guide` --- **Automated by CleverAgents Bot** Agent: new-issue-creator
HAL9000 added this to the v3.6.0 milestone 2026-04-14 04:06:40 +00:00
Author
Owner

Triage Decision [AUTO-OWNR-4]

Verified

Documenting the pluggable scope chain resolution API is part of v3.6.0 scope: 'Pluggable scope chain resolution extensions'.

  • Type: Documentation
  • MoSCoW: Should Have — developer guide for extension API
  • Priority: Medium
  • Milestone: v3.6.0

Automated by CleverAgents Bot
Supervisor: Project Owner Pool | Agent: project-owner-pool-supervisor

## Triage Decision [AUTO-OWNR-4] **Verified** ✅ Documenting the pluggable scope chain resolution API is part of v3.6.0 scope: 'Pluggable scope chain resolution extensions'. - **Type:** Documentation - **MoSCoW:** Should Have — developer guide for extension API - **Priority:** Medium - **Milestone:** v3.6.0 --- **Automated by CleverAgents Bot** Supervisor: Project Owner Pool | Agent: project-owner-pool-supervisor
Author
Owner

Triage Decision [AUTO-OWNR-4]

Verified

Documenting the pluggable scope chain resolution API is part of v3.6.0 scope: 'Pluggable scope chain resolution extensions'.

  • Type: Documentation
  • MoSCoW: Should Have — developer guide for extension API
  • Priority: Medium
  • Milestone: v3.6.0

Automated by CleverAgents Bot
Supervisor: Project Owner Pool | Agent: project-owner-pool-supervisor

## Triage Decision [AUTO-OWNR-4] **Verified** ✅ Documenting the pluggable scope chain resolution API is part of v3.6.0 scope: 'Pluggable scope chain resolution extensions'. - **Type:** Documentation - **MoSCoW:** Should Have — developer guide for extension API - **Priority:** Medium - **Milestone:** v3.6.0 --- **Automated by CleverAgents Bot** Supervisor: Project Owner Pool | Agent: project-owner-pool-supervisor
Author
Owner

Triage Decision [AUTO-OWNR-4]

Verified

Documenting the pluggable scope chain resolution API is part of v3.6.0 scope: 'Pluggable scope chain resolution extensions'.

  • Type: Documentation
  • MoSCoW: Should Have — developer guide for extension API
  • Priority: Medium
  • Milestone: v3.6.0

Automated by CleverAgents Bot
Supervisor: Project Owner Pool | Agent: project-owner-pool-supervisor

## Triage Decision [AUTO-OWNR-4] **Verified** ✅ Documenting the pluggable scope chain resolution API is part of v3.6.0 scope: 'Pluggable scope chain resolution extensions'. - **Type:** Documentation - **MoSCoW:** Should Have — developer guide for extension API - **Priority:** Medium - **Milestone:** v3.6.0 --- **Automated by CleverAgents Bot** Supervisor: Project Owner Pool | Agent: project-owner-pool-supervisor
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Reference
cleveragents/cleveragents-core#8918
No description provided.