PRD: os-backlog plugin — the AI's process-management surface #9
Labels
No Label
P0
P1
P2
P3
afk-ready
hitl
next
ready-for-agent
review
semi
waiting
wayfinder:grilling
wayfinder:map
wayfinder:research
wayfinder:task
No Milestone
No project
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: jared/cc-os#9
Loading…
Reference in New Issue
No description provided.
Delete Branch "%!s(<nil>)"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
PRD: os-backlog plugin — the AI's process-management surface
Phase-1 PRD deferred by the backlog pilot plan (vault:
vault-backlog-pilot-plan); plugin home decided in ADR-023. Drafted 2026-07-10.Problem Statement
Task and process state is now live in Planka (pilot gate passed 2026-07-09), but the AI has no formal surface for it. Sessions don't know where a project's tasks live (Planka board? Forgejo issues? in-repo markdown files?), don't reliably capture work discovered mid-session, and have no convention telling them how autonomously to act on a given task. The human ends up as the router: repeating "where do I look for tasks" decisions per project, manually shepherding cards, and never being sure the board reflects reality. Three trackers exist with no written boundary between them, and nothing deterministic tells a session which one is in effect for the repo it's sitting in.
Solution
A new global
os-backlogplugin that makes tracker routing deterministic and task behavior conventional:teafor private repos, GitHub for public) hold implementation specs only —/to-issues-style slices bound to a repo's code. Mixed usage is the norm for code efforts: one Planka card is the state pointer, the repo issue chain is the spec; state is never duplicated. When a Planka effort accretes significant code, it is promoted: carve a repo, move specs there, the card remains the pointer.tracker = …in the existing.cc-os/config. A new os-status check reads it deterministically — present means a session silently knows where tasks live; absent in a git project means a nudge to run the routing/migration skill once.planka-apigem binary for everything mechanical.hitl/semi/afk-ready) carried as a Planka label, issue-header field, and recurrence-manifest key, so a session reading a task knows whether to prepare-and-ask, run-then-stop-at-gates, or barrel through to Review.User Stories
trackerkey in.cc-os/configto be the single source of that routing, so that the answer is a file read, not an inference.~/dev/*vs~/clients/*), so that cards never land on the wrong board.archived--<name>), with activation automatic and archiving only on my explicit go-ahead, so that board lifecycle is safe and reversible.hitl-labeled cards never picked up autonomously by AI, so that judgment-work waits for me.hitl/semi/afk-ready) as Planka labels, so that a card tells me how to work it before I start.semi-labeled work to mean "run mechanical parts, stop at named decision gates," so that semi-autonomous tasks have a defined stopping contract.autonomykey, so that one convention spans all three tracking surfaces./to-issues, keeping the card as pointer — so that specs live next to the code they specify./to-issuesuser, I want the skill's output routed by the tracker convention (Planka cards by default; repo issues only where the config key says so), so that slicing and routing don't fight.Implementation Decisions
os-backlogunder the cc-os plugin family (ADR-023). Naming per the plugin/skill naming convention: verb-first skills invoked as/os-backlog:<verb>; noname:frontmatter; nocommands/dispatcher directories.trackerkey in.cc-os/config(the existing per-project config file os-status already reads). Value grammar:planka:<board>|forgejo:<owner>/<repo>|github:<owner>/<repo>|repo:<path>(in-repo markdown issues). Absence in a git project is the onboarding trigger..cc-os/) apply unchanged.lib/+ CLI pattern): input = repo path + config + board inventory; output = one ofuse <board>/activate <archived board>/stop-and-discuss. No live API inside the resolver.planka-apigem binary — no cross-repo source coupling (pilot-plan repo-separation decision). Board-ensure enforces uniform lists (Backlog → Next → Doing → Waiting → Review → Done) and the uniform label set (P0–P3+ autonomy labels), applies the verified Planka 2.1.1 API requirements (undocumentedtypefields on create; owner-manager visibility fix; label color whitelist), and implements the archive/activate rename convention.hitl/afk-readylabels are kept;semiis added as the third value. Same vocabulary in issue-headerType:fields and as anautonomy:key in the recurrence manifest (the manifest key is consumed by the planka gem's tick — passing it through is gem work, tracked as gem issue 13's release pass, out of this plugin's scope).hitlcards are never self-assigned.boardfield. Tick-fed population is blocked on gem issue 13 (offset expansion + versioning) — out of scope here; the board itself and manual cards are in scope.card-triage(labels/priorities raw Backlog cards) andboard-audit(drift report). Both read-mostly; any writes land as comments or label changes, never column moves past Review./to-issuesintegration: the routing skill/convention becomes the router for/to-issuesoutput — Planka by default, repo issues where the config key says so.Testing Decisions
hook_test.pysuite, same pattern as the other registry checks (env-var override for fixture paths; missing config silent outside git projects; snooze honored).lib/adr/test suite. No live-API calls in CI/tests; live verification happens once, manually, per the pilot's verified-API notes.Out of Scope
+1d/+1w/+2w), the manifestautonomykey pass-through, and gem publish/versioning — planka gem issue 13.Further Notes
os-orchestration's rubric file — a deliberate cross-plugin edit consistent with the ecosystem framing in ADR-023.Removed ready-for-agent: this is the PRD/tracking issue, not a grabbable slice. Status: slices 1–6 (#10–#15) shipped and closed; remaining are #16 (unblocked) and #17 (blocked by #16). Close this once #17 lands.
PRD scope delivered: all 31 user stories and every implementation/testing decision are built, tested (138 runs / 295 assertions / 0 failures), and live — capture/list/route skills, card-triage + board-audit agents, CLI-enforced column ownership (ADR-029), tracker key + os-status check, autonomy labels, session-start injection, /to-issues integration. Residuals tracked elsewhere: board-lookup name-collision bug (Backlog card), recurrence autonomy pass-through + tick-fed operations board (blocked on planka gem issue #13), onboard-a-second-project rollout (new Backlog card). Closing as delivered.