PRD: Manager Console orchestration for delegated Project Threads #15

Problem Statement

The current h-code workflow still depends too heavily on the human to coordinate delegable work. A human can identify work in an epic, Jira set, or todo list that should be parallelised across coding agents, but today they still need to manually shape prompts, choose the right Project, create Threads, check progress across Threads, answer follow-up questions, and push status back to systems of record.

This creates three problems:

1. Work that could be delegated stays idle when the human is preoccupied with other work.
2. Worker Threads receive uneven prompt quality because the human acts as the prompt shaper under time pressure.
3. Ongoing supervision still requires too much manual polling, context switching, and bookkeeping.

The product opportunity is to add a manager-style coordination layer that can accept seeded work, classify it, refine it when needed, spawn Worker Threads in the correct Projects, consume worker blockers/questions, respond when possible, escalate to the human when necessary, and write progress back to Jira or todo systems without hiding the underlying Threads.

Solution

Introduce a single Manager Console in a dedicated Manager Workspace that acts as the control plane for delegated work. The human seeds the manager with an epic, Jira set, or todo list. The manager performs Delegation Intake on each work item, classifies its Work Readiness, and then routes the item through one of three paths:

• ready-for-worker: create a project-bound Worker Thread
• needs-refinement: create a project-bound Refiner Thread that runs a human-in-the-loop refinement workflow, typically via grill-with-docs
• human-owned or blocked-on-context: keep the item in the Manager Console for the human

A Refiner Thread produces a Refinement Handoff containing the refined problem statement, behavioral or functional acceptance criteria, and target Project. The manager appends that refined context back to the originating Jira/todo item, re-evaluates readiness, and automatically spawns a Worker Thread when the item is clearly ready.

A Worker Thread is a normal first-class Thread inside its owning Project, typically using a worktree. It is visibly marked with a Delegation Badge and can emit structured Worker Escalations such as questions, blockers, review requests, or completion notices. Each Worker Escalation creates a linked Manager Queue Item in the Manager Console. The Manager Queue Discipline for v1 is FIFO, while queue items still retain categories for handling semantics.

Manager-to-worker communication is visible. When the manager responds to a worker, the Worker Thread shows a distinct visible manager-instruction row styled similarly to a human message but visually differentiated. Worker questions and blockers remain visible in the Worker Thread and also surface into the Manager Console as linked queue items.

The v1 manager runtime should favor token efficiency and reliability over a continuously running hidden session. The Manager Console remains a single logical conversation for the user, but underlying manager executions should be short-lived and resume on demand using durable files in the Manager Workspace plus the current queue state. Worker runtime continuity can remain thread-local and provider-native.

User Stories

1. As a human operator, I want to seed the Manager Console with an epic and its underlying Jira issues, so that delegable work can begin without me manually creating every Thread.
2. As a human operator, I want to seed the Manager Console with a todo list, so that informal work can be managed with the same delegation flow as tracked work.
3. As a human operator, I want the manager to perform Delegation Intake before spawning workers, so that vague work is not blindly delegated.
4. As a human operator, I want each seeded work item to receive a Work Readiness classification, so that I can see what is ready, what needs refinement, and what still belongs with me.
5. As a human operator, I want the manager to classify items as ready-for-worker, so that work with sufficient clarity can begin immediately.
6. As a human operator, I want the manager to classify items as needs-refinement, so that incomplete work is sharpened before delegation.
7. As a human operator, I want the manager to classify items as human-owned or blocked on missing context, so that unsuitable work is not delegated prematurely.
8. As a human operator, I want needs-refinement items to spawn a Refiner Thread, so that I can refine the task in a dedicated conversation instead of overloading the manager transcript.
9. As a human operator, I want each Refiner Thread to be tied to a specific Project, so that grill-with-docs can use the correct CONTEXT.md and ADRs.
10. As a human operator, I want the Refiner Thread to focus on the problem statement and acceptance criteria rather than implementation file paths, so that delegated work stays grounded without steering workers into the wrong directory.
11. As a human operator, I want at most one active Refiner Thread per work item, so that refinement does not fork into conflicting conversations.
12. As a human operator, I want a completed Refiner Thread to produce a Refinement Handoff, so that the manager can act on structured output instead of rereading the whole transcript.
13. As a human operator, I want the Refinement Handoff to include the refined problem statement, so that the downstream worker receives a legible task definition.
14. As a human operator, I want the Refinement Handoff to include behavioral or functional acceptance criteria, so that worker success is testable.
15. As a human operator, I want the Refinement Handoff to include the target Project, so that the manager can delegate into the correct repo.
16. As a human operator, I want the manager to append refined notes back to Jira or todo systems, so that systems of record reflect the clarified work without overwriting the original description.
17. As a human operator, I want Jira updates to be append-only comments or notes in v1, so that the original issue body remains intact.
18. As a human operator, I want the manager to automatically spawn a Worker Thread after successful refinement when readiness is clear, so that I do not need to manually re-trigger delegation.
19. As a human operator, I want each Worker Thread to live inside its owning Project, so that branch, worktree, and repo-local context remain coherent.
20. As a human operator, I want a Worker Thread to be visibly distinguished from ad hoc Threads, so that I can quickly tell which work is manager-delegated.
21. As a human operator, I want delegated worker Threads to retain the original Jira/todo text as provenance, so that source context is never lost.
22. As a human operator, I want delegated worker Threads to receive the Refinement Handoff as the primary brief, so that prompt quality is improved before implementation starts.
23. As a human operator, I want the manager to transform rough human prompts into stronger worker prompts, so that agent execution quality is less dependent on my phrasing.
24. As a human operator, I want the manager to choose the right Project for a worker, so that repo routing becomes part of delegation instead of a manual step.
25. As a human operator, I want the manager to favor worktrees for delegated execution when appropriate, so that worker activity stays isolated from other active work.
26. As a human operator, I want workers to surface blockers and questions back to the manager automatically, so that I do not have to poll every worker transcript.
27. As a human operator, I want worker blockers to create linked Manager Queue Items, so that unresolved work returns to the manager control plane.
28. As a human operator, I want worker questions to create linked Manager Queue Items, so that the manager can answer or escalate them.
29. As a human operator, I want worker completion notices to create linked Manager Queue Items, so that the manager can update Jira and decide what happens next.
30. As a human operator, I want each worker escalation to remain visible in the Worker Thread, so that execution history stays auditable in place.
31. As a human operator, I want the manager queue to use FIFO in v1, so that coordination stays simple while the product proves the model.
32. As a human operator, I want queue items to still carry categories, so that the manager can apply different handling semantics without adding scheduling complexity.
33. As a human operator, I want the manager to always write back to the Worker Thread when resolving a worker-facing queue item, so that there is no hidden split between manager state and worker instructions.
34. As a human operator, I want manager instructions to appear in the Worker Thread as distinct visible rows, so that I can see what the manager told the worker.
35. As a human operator, I want the manager-instruction row to look close to a human message but with distinct styling, so that authorship is legible without inventing a totally separate visual language.
36. As a human operator, I want worker replies to continue looking like ordinary agent replies, so that only the manager-specific affordances need new UI.
37. As a human operator, I want the Manager Console to live in a dedicated Manager Workspace, so that it can persist context in files outside any specific Project checkout.
38. As a human operator, I want the Manager Console to remain a single unified visible conversation, so that coordination work does not fragment into many manager-facing chats.
39. As a human operator, I want the manager runtime to be token-efficient, so that coordination overhead does not dominate the usefulness of the system.
40. As a human operator, I want the manager runtime to be reliable under interruptions and restarts, so that the control plane is not flaky.
41. As a human operator, I want the manager to reconstruct its working context from durable manager files and queue state, so that it does not rely entirely on ever-growing conversational history.
42. As a human operator, I want worker continuity to stay thread-local and provider-native, so that implementation work can keep benefiting from project-specific session history.
43. As a human operator, I want the manager to answer worker questions when it has sufficient context, so that I am only interrupted when truly necessary.
44. As a human operator, I want unresolved manager questions to surface clearly to me, so that I can provide input only where it adds value.
45. As a human operator, I want the manager to learn my preferences over time through durable workspace context, so that fewer future escalations need my direct involvement.
46. As a human operator, I want the manager to supervise multiple Projects from one place, so that cross-repo work can still be delegated coherently.
47. As a human operator, I want to inspect worker conversations the manager created, so that delegated work remains transparent.
48. As a human operator, I want the manager to update Jira as worker progress changes, so that external systems stay in sync without manual copying.
49. As a human operator, I want the manager to leave comments instead of silently mutating tickets, so that stakeholders can see what happened.
50. As a human operator, I want this flow to preserve h-code’s existing Thread semantics wherever possible, so that the new capability does not create a second hidden conversation model.

Implementation Decisions

• Introduce one Manager Console as a first-class control-plane conversation in a dedicated Manager Workspace. The manager is a single persistent user-facing coordination surface, even if its runtime executes in short-lived bursts.
• Add a Manager Inbox section to the sidebar that presents the Manager Console separately from project-owned Threads.
• Treat Worker Thread and Refiner Thread as first-class Thread variants rather than inventing hidden internal sessions. This preserves inspectability, reuse of existing Thread infrastructure, and the current product mental model.
• Keep Worker Threads project-bound. A Worker Thread belongs to exactly one Project and can belong to at most one Manager Console.
• Keep Refiner Threads project-bound. Refiner Threads exist because refinement uses repo-local context such as CONTEXT.md and ADRs via grill-with-docs.
• Restrict v1 to one active Refiner Thread per seeded work item.
• Add a Delegation Intake stage to the manager flow before any worker creation. This stage classifies each seeded work item by Work Readiness.
• Support at least these v1 readiness outcomes: ready-for-worker, needs-refinement, human-owned, and blocked-on-context.
• When readiness is needs-refinement, the manager creates a project-bound Refiner Thread instead of trying to refine the task inline in the Manager Console.
• A completed Refiner Thread must produce a Refinement Handoff with the minimum structured fields needed for downstream delegation: refined problem statement, behavioral or functional acceptance criteria, and target Project.
• The manager should append the Refinement Handoff back to the originating Jira/todo record as notes or comments, rather than overwriting the original description.
• When readiness becomes clearly ready-for-worker after refinement, the manager should automatically create the Worker Thread and surface that action in the Manager Console.
• Worker delegation input should include both the original Jira/todo text and the Refinement Handoff, with the handoff treated as the primary brief and the original text preserved as provenance.
• Add explicit Worker Escalation support inside the h-code orchestration runtime rather than heuristic transcript scanning. Escalations should be structured runtime events that the system can route reliably.
• Each Worker Escalation should create exactly one linked Manager Queue Item in the Manager Console.
• The Manager Queue Discipline in v1 is FIFO. Queue item category affects handling semantics and presentation, but not scheduling order.
• Support v1 queue categories that cover at least questions, blockers, review requests, and work completion.
• Require manager responses to worker-facing queue items to always write back into the Worker Thread. Manager-only resolution should be reserved for pure internal bookkeeping.
• Render manager-to-worker communication as a distinct visible manager-instruction row in the Worker Thread, styled similarly to a human message but visually differentiated.
• Preserve the existing assistant rendering model for worker agent responses rather than redesigning all thread history around fully general multi-party chat authorship.
• Extend the orchestration/event model to represent manager-specific visible rows and worker-specific escalations as first-class events or activities emitted from the h-code runtime.
• Prefer a deep module for manager orchestration state and routing logic instead of scattering manager behavior across sidebar, transport, and provider glue code.
• Introduce a deep module for queue state and queue-item lifecycle so FIFO selection, linkage to worker/refiner Threads, and Jira write-back can be tested independently of the UI.
• Introduce a deep module for seeded work-item classification and readiness transitions so Delegation Intake, Refinement Handoff, and automatic worker creation remain deterministic.
• Introduce a deep module for manager workspace persistence so the manager can store durable files such as notes, preference summaries, active work-item snapshots, and queue state without tying behavior to conversational history alone.
• Favor short-lived manager executions that reconstruct context from Manager Workspace files plus current queue state, rather than relying on a forever-resumed hidden CLI session. This is a deliberate token-efficiency and reliability tradeoff.
• Keep worker execution continuity aligned with existing thread-local provider sessions so project implementation work can still use provider-native resume behavior.
• Defer autonomous Jira intake. In v1, the human explicitly seeds the manager with the relevant epic, Jira set, or todo list, while manager-side Jira interactions are limited to append-only write-back.
• This work likely warrants an ADR because it establishes hard-to-reverse architecture around conversation types, queue semantics, manager runtime strategy, and cross-thread supervision.

Testing Decisions

• Good tests should assert external behavior and state transitions, not internal implementation details. The tests should validate what queue items are created, which Threads are spawned, what gets written back to worker Threads or Jira-facing adapters, and how readiness changes over time.
• Test the manager orchestration module with scenario-driven state tests: seeded intake, readiness classification, refiner creation, handoff completion, worker auto-spawn, escalation handling, and write-back behavior.
• Test the queue module independently for FIFO behavior, category preservation, linkage between Manager Queue Items and source Worker Escalations, and idempotent handling of duplicate events.
• Test the refinement lifecycle independently: one active Refiner Thread per work item, correct Refinement Handoff capture, and correct manager transition from needs-refinement to ready-for-worker.
• Test the worker escalation path at the orchestration boundary: a structured worker escalation should create both a visible worker-side row and a manager-side queue item.
• Test sidebar projection and UI rendering for the Manager Inbox, Delegation Badge, manager-instruction rows, and linked navigation between manager items and project-bound Threads.
• Test Jira/todo write-back through adapter-level contract tests that verify append-only comments/notes rather than destructive mutation.
• Reuse prior art from the existing orchestration decider, projector, and WebSocket stream tests already present in the codebase. Similar event-driven tests exist around thread turn start, plan capture, activity projection, and runtime ingestion.

Out of Scope

• Autonomous Jira discovery or polling without explicit human seeding.
• Priority-based queue scheduling beyond FIFO.
• Multiple Manager Console instances.
• Multiple simultaneous active Refiner Threads for one work item.
• Overwriting Jira issue descriptions in place.
• File-path-level implementation plans in the Refinement Handoff.
• A fully general multi-party message model for all thread history.
• Hidden background transcript scanners that infer blockers from punctuation or free text.
• A full long-lived daemon-style always-on manager runtime.
• Rich optimization of manager memory or custom provider compaction strategies beyond the initial manager-workspace persistence model.
• Advanced human-routing toggles such as choosing whether a message in a worker thread goes to the human or the manager on the fly.

Further Notes

• This PRD intentionally preserves h-code’s existing Thread mental model. The new capability comes from adding control-plane relationships and new Thread variants rather than replacing the core object model.
• The design assumes that visibility is a product requirement, not just a debugging convenience. The human should be able to inspect the manager-created Worker Threads and Refiner Threads directly.
• The design is intentionally token-conscious. The manager should act as a prompt shaper and coordinator, but its runtime should remain lean by depending on durable manager workspace state instead of ever-growing conversational baggage.
• The manager’s value is not only automatic spawning. It is also prompt shaping, supervision, escalation handling, and write-back coordination.
• An ADR should capture the reasoning behind the single Manager Console, project-bound Refiner Threads, explicit Worker Escalations, append-only Jira write-back, and hybrid manager runtime strategy.