Jared — package task-manager orchestration (heartbeat, skills, layout)

Problem

Today the manager story is spread across scripts/ (heartbeat, dispatch, worktrees, register snapshots), tasks/tools/ (task schema/CLI), .codex/skills/ (task-manager, worktree-new, …), and .claude/commands/ (task-dispatch, pr, …). There is no single named product for operators or agents to ask for, and no clear boundary between “Jared concerns” and the rest of the repo.

We want a deliberate layout so that:

1. Humans know what to run and where to read (background heartbeat, optional manager tmux session, recovery).
2. Claude (and Codex) load a small, coherent skill set for orchestration without hiding unrelated skills.
3. Implementation stays testable in CI and does not fork into untested copies living only under .claude/.

This task is planning + scope definition for a follow-up implementation task (or initiative) once the approach is chosen.

It is not redundant with upgrade-jared-task-manager-visibility-orchestration-and-operator-ux: that task owns operator UX (visibility, escalation, tasks server direction). This task owns filesystem layout, umbrella skill, and extractability of the orchestration bundle. Implementation work (two-tier watchdog, tasks serve, etc.) is tracked in the dependency chain linked from the upgrade task.

Context

What “Jared” is (working definition)

Jared = the local, host-side orchestration layer for tasks tasks: queue/heartbeat, dispatch to worktrees, monitoring (dispatch-watch), dependency + PR CI gates, register/snapshots, and the playbook the long-lived manager agent follows. It is not the full tasks product (schema, site, initiatives) and not generic Claude skills (charts, cloud, etc.).

Implementation inventory (candidates to “belong to Jared”)

Constraints

• Single source of truth for behavior: Python/shell under scripts/ (and tasks/tools/) with pytest coverage — avoid duplicating logic inside skill markdown “bins.”
• .claude/skills/ in this repo are documentation + procedure, not a second package manager.
• Portable “install elsewhere” (another repo) is a non-goal for v1 unless explicitly scoped; extraction to libs/jared only if we need importable code reuse.

Possible Solutions

A. tasks/jared/ (docs + manifests only)

• Pros: Sits next to the plans system; good for operator runbooks, ADRs, “how to run Jared.”
• Cons: Does not naturally hold executable code; scripts would still live in scripts/.

B. libs/jared/ (Python package, like historical libs/cbox)

• Pros: Clear extract boundary; could publish or vendor later; task_manager_lib becomes jared.*.
• Cons: Migration cost, import paths, every consumer update; overkill if everything stays single-repo.

C. .codex/skills/jared/ (umbrella skill + thin wrappers; Codex-canonical)

• Pros: Agents discover one index skill; can list “read these next” (task-manager, worktree-new, qa-explorer, pr).
• Cons: Must not copy task_manager_lib.py into the skill; only link to scripts/….

D. Repo-root jared/ with bin/ or scripts/

• Pros: Very visible name.
• Cons: Another top-level directory; overlaps with scripts/; easy to drift.

Recommended (for v1): C (Codex-canonical) + A-lite

• Add .codex/skills/jared/SKILL.md as the index: goals, when to use Jared, ordered links to existing skills/commands, env vars (TASK_MANAGER_*), and canonical script paths. Per sync-skills policy, .codex/skills/ is the primary surface (no .claude/skills/ directory exists in this repo).
• Register in AGENTS.md as a top-level skill entry so agents discover it.
• Keep all executables in scripts/; optionally add a scripts/jared/ subdirectory only if we want filesystem grouping without a Python package move (purely organizational; requires updating references and tests — deferred to follow-up task).

Optional later: B if we need Jared logic in another repository or as an installable tool — then extract task_manager_lib + heartbeat entrypoints behind a stable API.

Plan

1. Decide naming in UX copy — Use Jared in skills and runbooks; keep script filenames stable (task-manager-*) unless a later task renames with compatibility shims.
2. Add umbrella skill — .codex/skills/jared/SKILL.md (Codex-canonical per sync-skills policy) describing the bundle, dependencies (gh, tmux, uv), and pointers to task-manager / worktree-new / pr / qa-explorer.
3. Register in AGENTS.md — Top-level “jared (task orchestration)” entry so agents find the skill without loading everything.
4. sync-skills — Jared skill is Codex-only (like worktree-new); no .claude/skills/ mirror needed per repo policy.
5. Spike: scripts/jared/ vs status quo — Deferred to follow-up implementation task. If the team wants a directory grouping, prototype moving only task-manager-* + task_manager_lib.py under scripts/jared/ and fix imports/tests.
6. Follow-up task (implementation) — Filed as implement-jared-layout-scripts-grouping-and-sync-skills-reconciliation.md with concrete scope for script grouping, sync-skills reconciliation, and regression tests.

Implementation Progress

• [x] Decided layout: C (Codex-canonical) + A-lite — umbrella skill in .codex/skills/jared/, registered in AGENTS.md, executables stay in scripts/.
• [x] Created .codex/skills/jared/SKILL.md — index skill with bundle members, canonical script paths, env vars, dependencies.
• [x] Registered Jared in AGENTS.md as top-level skill entry.
• [x] Follow-up implementation task created: tasks/workstreams/infra-tooling/tasks/implement-jared-layout-scripts-grouping-and-sync-skills-reconciliation.md (p3).
• [ ] (Optional) tasks operator doc or initiative stub for Jared — deferred, covered by the skill doc for now.

QA Exploration

N/A — planning / documentation task only.

• [x] QA exploration N/A (no UI)

Review Feedback

• [ ] Review cleared