Repository navigation
docs: update issue service PRD for workspace addressing and nightshift - #25
Merged
Merged
Conversation
Refine the issue service proposal so it can be built against hub as it
actually exists.
Consumers (§4): nightshift is the only consumer. Drop the af-issue skill,
af-spec and the hub web UI here and everywhere else in the document, and
record nightshift's real deployment shape -- one agent per workspace,
authenticating with a workspace-scoped PAT that gains issues:read and
issues:write alongside its existing audit:write and sessions:write.
Concepts (§5): hub has no "project". Replace it with the workspace, hub's
single central entity, addressed by its globally unique immutable slug.
Issue collections become a workspace sub-resource rather than a new
addressable entity, and workspace lifecycle (active/archived) is stated
against issue reads and writes.
API specification (§6): every path moves from /projects/{project} to
/workspaces/{slug}, served at /api/v1/workspaces/{slug}/... alongside
patches, merges, secrets and runs. Drop the proposed project listing in
favour of hub's existing GET /api/v1/workspaces. Rename project_not_found
to workspace_not_found and add workspace_mismatch and workspace_archived,
matching hub's existing error_type vocabulary.
Capability model (§7): split into issue capabilities, which gate endpoints
in this contract, and workspace capabilities, which advertise the rest of
the workspace -- carry_patch, merge_queue, upstream_sync, git_hosting,
secrets, variables, sessions, audit. Each is derived from state hub already
keeps (carry_patch from workspace_mode, upstream_sync from sync_mode,
git_hosting from hub_url) rather than from a new stored flag, and narrowed
by the caller's scopes. The map is open so adding a capability is not a
breaking change.
Record three conflicts with hub's implemented conventions as open questions
rather than silently resolving them: the Idempotency-Key header (Q-6), the
error envelope shape (Q-7), and whether the capability endpoint belongs in
this contract at all (Q-8).
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CGbu4pJZBZshA5QdMhiRwY
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
Update the issue service PRD to reflect the final design decisions: workspace-addressed endpoints (not project-based), single consumer (
nightshift), and integration with hub's existing workspace and capability model.Key Changes
/projects/{project}/to/workspaces/{slug}/endpoints, aligning with hub's existing workspace sub-resource pattern (patches,merges,secrets,runs)nightshiftis the sole consumer; removed references to hypothetical future consumers (af-issueskill,af-spec, hub web UI)409 workspace_archivedon writes) and clarified thatclone_status/sync_statusdo not gate issue operationsworkspace_mismatcherror when a workspace-scoped PAT addresses a different workspaceworkspace_not_found,workspace_archived,workspace_mismatch)internal/issuespackage,RegisterIssueRoutes,IssuesPermissions)Notable Details
{slug}immutabilitynightshift" for consistencyhttps://claude.ai/code/session_01CGbu4pJZBZshA5QdMhiRwY