pal-e-docs

Phase 8d: SDK Sprints Mixin

phase-postgres-8d-sdk-sprints Phase

Project
Goal: Add typed SDK methods for all sprint API endpoints, enabling the Phase 8f MCP rewrite to cover sprint management -- Betty Sue's primary daily workflow.
Owner: Dev agent
Repo: forgejo_admin/pal-e-docs-sdk
Depends on: 8a (SDK core)

Why

Sprint management is Betty Sue's most frequent workflow. Every session starts with checking the board, every phase completion moves items. The current MCP tools (10 tools in pal-e-docs-mcp/tools/sprints.py) use raw httpx. Without SDK coverage, the Phase 8f MCP rewrite can't cover sprints, leaving an inconsistent architecture and no integration test coverage for sprint operations.

Agent Workflows This Enables

Workflow When SDK Methods Used
Sprint planning Start of sprint <code>create_sprint</code>, <code>add_sprint_item</code> × N
Session check-in Every session start <code>list_sprints(status=)</code>, <code>get_sprint_board(item_type=, column=)</code>
Work tracking During session <code>move_sprint_item</code>, <code>update_sprint_item</code>
Backlog grooming Between sprints <code>get_backlog</code>, <code>add_sprint_item</code>, <code>remove_sprint_item</code>
Sprint close End of sprint <code>update_sprint(status=completed)</code>, <code>bulk_move_items</code>

API → SDK → MCP Mapping

# API Endpoint SDK Method MCP Tool (8f)
1 <code>GET /sprints</code> <code>list_sprints(status=)</code> <code>list_sprints</code>
2 <code>POST /sprints</code> <code>create_sprint(...)</code> <code>create_sprint</code>
3 <code>GET /sprints/{slug}</code> <code>get_sprint(slug)</code> <code>get_sprint</code>
4 <code>PATCH /sprints/{slug}</code> <code>update_sprint(slug, ...)</code> <code>update_sprint</code>
5 <code>DELETE /sprints/{slug}</code> <code>delete_sprint(slug)</code> None (destructive, no MCP by design)
6 <code>GET /sprints/backlog/items</code> <code>get_backlog(item_type=)</code> <code>get_backlog</code>
7 <code>GET /sprints/{slug}/items</code> <code>list_sprint_items(slug, item_type=, column=)</code> <code>get_sprint_board</code>
8 <code>POST /sprints/{slug}/items</code> <code>add_sprint_item(slug, ...)</code> <code>add_sprint_item</code>
9 <code>PATCH /sprints/{slug}/items/{id}</code> <code>update_sprint_item(slug, item_id, ...)</code> <code>move_sprint_item</code> (subset)
10 <code>DELETE /sprints/{slug}/items/{id}</code> <code>delete_sprint_item(slug, item_id)</code> <code>remove_sprint_item</code>
11 <code>PATCH /sprints/{slug}/items/bulk</code> <code>bulk_move_items(slug, items)</code> <code>bulk_move_items</code>

Implementation Notes

  • update_sprint uses PATCH (not PUT like notes) -- only send non-None fields
  • update_sprint_item uses PATCH with explicit null handling for points and labels (server uses model_fields_set)
  • delete_sprint and delete_sprint_item return None (204)
  • create_sprint has required fields: name, slug, status. Optional: goal, start_date, end_date
  • add_sprint_item has validation: plan/phase/todo require note_slug, issue requires forgejo_issue_url

Deliverables

  • src/pal_e_docs_sdk/sprints.py -- SprintsMixin with 11 methods
  • tests/test_sprints.py -- httpx-mocked unit tests covering all methods
  • client.py updated -- SprintsMixin in PalEDocsClient MRO
  • plan-2026-03-01-pal-e-sprints -- the sprint backend plan
  • phase-postgres-8-mcp-optimization -- parent phase (SDK + MCP Rewrite)
  • plan-2026-03-03-sprint-workflow-automation -- agent behavior built on sprint backend