feat(agentic-harness): tracker-advisor skill, generalized advisor gate, version-sync CI (v0.7.0)

.claude-plugin/marketplace.json

@@ -13,10 +13,10 @@
     {
       "name": "agentic-harness",
       "source": "./agentic-harness",
-      "description": "Stand up, assess, and maintain an agentic harness in an existing repo — generate project-specific agent teams and the skills they use, then assess how effectively they are used",
-      "version": "0.5.0",
+      "description": "Stand up, assess, and maintain an agentic harness in an existing repo — generate project-specific agent teams and the skills they use, assess how effectively they are used, and advise on spec-driven development systems and agent-suited issue trackers",
+      "version": "0.7.0",
       "category": "engineering",
-      "tags": ["harness", "agents", "skills", "scaffolding", "orchestration", "multi-agent", "meta-skill"]
+      "tags": ["harness", "agents", "skills", "scaffolding", "orchestration", "multi-agent", "meta-skill", "issue-tracker", "spec-driven-development"]
     },
     {
       "name": "developer-tools",

agentic-harness/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agentic-harness",
-  "version": "0.6.0",
-  "description": "Stand up, assess, and maintain an agentic harness in an existing repo. A meta-tool that generates project-specific agent teams and the skills they use, then assesses how effectively they are used. When a spec-driven development system is present, the generated orchestrator coordinates with it — activating the spec workflow and resuming on hand-back. Three skills: harness-setup (build, extend, maintain), harness-review (read-only assessment), and spec-advisor (advise and delegate setup of a spec-driven development system).",
+  "version": "0.7.0",
+  "description": "Stand up, assess, and maintain an agentic harness in an existing repo. A meta-tool that generates project-specific agent teams and the skills they use, then assesses how effectively they are used. When a spec-driven development system or an issue tracker is present, the generated orchestrator coordinates with it — activating the spec workflow and resuming on hand-back, pulling ready work and writing status back. Four skills: harness-setup (build, extend, maintain), harness-review (read-only assessment), spec-advisor (advise and delegate setup of a spec-driven development system), and tracker-advisor (advise and delegate setup of an agent-suited issue tracker).",
   "author": {
     "name": "MrBogomips",
     "url": "https://github.com/MrBogomips"
@@ -18,6 +18,7 @@
     "scaffolding",
     "agent-scaffolding",
     "multi-agent",
+    "issue-tracker",
     "claude-code-plugin"
   ]
 }

agentic-harness/README.md

@@ -4,15 +4,16 @@ Stand up, assess, and maintain an **agentic harness** inside an existing reposit
 
 This plugin does not do your domain work. It builds and maintains the agents and skills that do.
 
-## The three skills
+## The four skills
 
 - **`harness-setup`** — the writer. Analyzes the project, designs an agent team and the skills they use, generates them into `.claude/`, builds an orchestrator, and registers a pointer in `CLAUDE.md` that makes the orchestrator the repo's entry point — a hard gate routing every prompt through it. Also extends an existing harness, applies a review context, and records every change.
 - **`harness-review`** — read-only. Inventories the harness, detects drift, and assesses how effectively the skills and agents are actually used (from project memory, the `CLAUDE.md` pointer, and the `.claude/` inventory), then produces a prioritized *review context* that `harness-setup` can act on.
 - **`spec-advisor`** — detects whether a software project lacks a spec-driven development system and, if so, advises the best-fit option (GitHub Spec Kit, OpenSpec, BMAD-METHOD, Agent OS, Taskmaster, AWS Kiro, ADR tooling) and delegates setup to that system's own installer. Offline-first; scans first and stays out if a system is already present; never authors specs itself.
+- **`tracker-advisor`** — detects whether a software project lacks an issue tracker suited to agentic work and, if so, advises the best-fit option (Beads, Backlog.md, git-bug, git-issues, Beans, or GitHub Issues / Linear / Jira via their official access paths) and delegates setup to that system's own installer. Same posture as `spec-advisor`: offline-first, scans first and stays out, never authors issues.
 
-When a project **already has** a spec system, `harness-setup` makes the generated orchestrator coordinate with it rather than run beside it: the orchestrator activates the spec workflow with a contextual prompt, the spec system runs its owned segment, and the orchestrator resumes on a clean hand-back — one owner per phase, no duplicated artifacts. The detection signatures and the per-system coordination map are shared knowledge under `shared/` (`detection-signatures.md`, `sdd-coordination.md`).
+When a project **already has** a spec system or an issue tracker, `harness-setup` makes the generated orchestrator coordinate with it rather than run beside it: the orchestrator activates the spec workflow with a contextual prompt and resumes on a clean hand-back, and it pulls ready work from the tracker at intake and writes status back at integrate — one owner per phase and per concern, no duplicated artifacts. The detection signatures, the coordination protocol, and the per-system coordination maps are shared knowledge under `shared/` (`detection-signatures.md`, `coordination-protocol.md`, `sdd-coordination.md`, `tracker-coordination.md`).
 
-The harness loop: **review → setup → review again.** `spec-advisor` is offered alongside it when a software project has no spec system yet.
+The harness loop: **review → setup → review again.** The advisors are offered alongside it when a software project lacks the matching process layer. Keeping a repo-native tracker in sync with a human-oriented one (Jira, Linear) is planned for a future release.
 
 ## Skills, not commands
 

agentic-harness/shared/claude-md-pointer.md

@@ -8,14 +8,17 @@ wrong place for anything the file system already holds.
 
 After a harness is built or changed, write (or update) one short section in the target
 project's `CLAUDE.md`. It carries three things — plus, when the project has an installed
-spec-driven development (SDD) system, one line recording how the orchestrator coordinates with it:
+process layer (an SDD system, an issue tracker), one line per layer recording how the
+orchestrator coordinates with it:
 
 1. The harness's **goal**, in one line.
 2. The **entry-point directive** — a hard gate making the orchestrator skill the single entry
    point for the repo: every prompt is routed through it before any response.
 3. A **change-history** table.
 4. *(only when an SDD system is present)* a **spec-process** line — which system, and the segment
    the orchestrator hands to it.
+5. *(only when an issue tracker is present)* an **issue-tracking** line — which tracker, and how
+   the orchestrator pulls ready work and writes status back.
 
 This is enough for a fresh session: the entry-point directive gates every prompt to the
 orchestrator, and the orchestrator triages and handles the rest from the files under `.claude/`.
@@ -32,6 +35,9 @@ instruction layer, so it does not depend on the skill description triggering on
 **Spec process:** {system} ({version}) — orchestrator activates it for {owned segment};
 hand-back via {contract}. *(omit this line entirely when no SDD system is present)*
 
+**Issue tracking:** {tracker} ({version}) — orchestrator pulls ready work via {ready-work query};
+status written back via {write-back convention}. *(omit this line entirely when no tracker is present)*
+
 **Entry point — applies to every prompt in this repo:** You MUST invoke the
 `{orchestrator-skill-name}` skill *before* responding to any request — new work, a follow-up, a
 re-run, a question, or a change to a previous result. It is the single entry point; do not craft a
@@ -50,17 +56,20 @@ orchestrator's first phase, so a trivial or off-domain prompt still routes throu
 and is answered quickly there. This keeps the orchestrator the reliable entry point without spinning
 up a team for every message.
 
-The spec-process line records the **coordination relationship**, not the spec contents — the
-requirements, plan, and tasks stay in the SDD system's own files. The full coordination model is in
-`${CLAUDE_PLUGIN_ROOT}/shared/sdd-coordination.md`.
+The spec-process and issue-tracking lines record the **coordination relationship**, not the
+contents — the requirements, plan, and tasks stay in the SDD system's own files, and the issues
+stay in the tracker's own store. The coordination protocol is in
+`${CLAUDE_PLUGIN_ROOT}/shared/coordination-protocol.md`, with the per-area instances in
+`${CLAUDE_PLUGIN_ROOT}/shared/sdd-coordination.md` and
+`${CLAUDE_PLUGIN_ROOT}/shared/tracker-coordination.md`.
 
 ### When the repo has more than one harness
 
 Write the hard-gate sentence **once**, as a shared routing preamble above the per-domain sections —
 "Before responding to any request, invoke the orchestrator whose domain matches it; if none matches,
 answer directly" — and keep each `## Harness: {domain}` section to its goal, an **Orchestrator:**
 `{orchestrator-skill-name}` line (so the preamble can resolve domain → orchestrator), its
-spec-process line, and change history. Do not repeat "invoke *this* orchestrator before any prompt"
+spec-process and issue-tracking lines, and change history. Do not repeat "invoke *this* orchestrator before any prompt"
 in every section: N such directives contradict each other. One preamble routes by domain; each
 section just names the orchestrator it routes to.
 
@@ -75,6 +84,8 @@ Leave these out of `CLAUDE.md`:
 - Detailed execution rules — they belong in the skills and the orchestrator.
 - The spec contents — the spec-process line names the system and the coordinated segment only; the
   requirements/plan/tasks live in the SDD system's own files, the single source of truth.
+- The issue contents — the issue-tracking line names the tracker and the touchpoints only; the
+  issues live in the tracker's own store, the single source of truth for work state.
 
 The pointer is a signpost, not a manifest. Keep it small enough that it stays correct.
 

agentic-harness/shared/coordination-protocol.md

@@ -0,0 +1,63 @@
+# Coordination protocol
+
+When a project has a **process layer** installed — a spec-driven development (SDD) system, an
+issue tracker — the harness does not run beside it: the two **work coordinated**. This file
+defines the generic protocol every coordination follows; the per-area instance files apply it
+to concrete systems:
+
+- `${CLAUDE_PLUGIN_ROOT}/shared/sdd-coordination.md` — the spec process (SDD systems)
+- `${CLAUDE_PLUGIN_ROOT}/shared/tracker-coordination.md` — issue tracking
+
+A future process area adds an **instance file** with its per-system map; it does not add new
+protocol prose here. `harness-setup` reads the protocol and the instance maps at generation
+time; the generated orchestrator cannot read these files at runtime, so the relevant values
+are **inlined** when the orchestrator is generated.
+
+A harness is the *who/how/when* of the work — agents, skills, order. A process layer is part of
+the *project process* the work follows — what to build, what work is ready and in what state.
+They are different layers, so they compose cleanly once the boundary is drawn. Detection of
+which system is present is a separate concern: see
+`${CLAUDE_PLUGIN_ROOT}/shared/detection-signatures.md`.
+
+## The coordination model
+
+A coordinated system owns a **bounded segment or concern** of the workflow — for an SDD system,
+usually the spec/plan/decompose front-end; for a tracker, the work state. The orchestrator stays
+the driver and coordinates that segment through a **two-way handoff**, the same shape for every
+system:
+
+1. **Activate (hand-in).** At the boundary the system owns, the orchestrator composes a
+   **contextual prompt** from what it already holds — the goal, the constraints, the context it
+   has gathered — and activates the system's entry point so it starts cleanly without
+   re-gathering:
+   - *Auto-invokable* (a CLI or MCP entry point) → the orchestrator invokes it directly with the
+     contextual prompt.
+   - *Human-gated* (an IDE, a SaaS UI, or a workflow with an approval step) → the orchestrator
+     emits the contextual prompt for the user, **pauses**, and resumes when the user confirms
+     the step is done.
+2. **The system runs its owned segment.** The orchestrator does **not** duplicate it — it never
+   re-derives requirements an SDD owns, and never keeps a parallel status file beside a tracker.
+3. **Hand-back (return).** The system signals completion; its artifacts — a spec, a plan, a task
+   graph, an issue with its state — are the **contract**. The orchestrator detects completion
+   (the artifact is present, a flag is set, or the user confirms) and resumes.
+4. **The orchestrator resumes its owned segment** — parallel execution, integration,
+   cross-boundary QA — reading the system's artifacts as its input and **writing status and
+   decisions back** in the system's own conventions. The final deliverable still goes to the
+   user's target path.
+
+### Two rules that keep it clean
+
+- **One owner per phase, one owner per concern.** Mark each orchestrator phase as either
+  delegated (`→ {system}`) or orchestrator-owned, and give each concern (requirements, task
+  decomposition, work state) exactly one owning system. A phase or concern a system owns is not
+  re-done by an agent, and vice versa. This is what prevents the parallel-and-conflicting flow
+  the coordination exists to avoid.
+- **One source of truth per artifact.** The system's artifacts are **referenced**, never copied
+  into `_agents_workspace/`. The orchestrator reads them in place and writes status back in
+  place. Copying a spec or an issue into the workspace creates a second copy that drifts — the
+  same anti-pattern the `CLAUDE.md` pointer avoids by not duplicating the file system.
+
+Friction is minimised by the two ends of the handoff: the **contextual prompt** on hand-in means
+the system does not re-ask what the orchestrator already knows, and the
+**artifact-as-contract** on hand-back means the orchestrator does not re-derive what the system
+already settled.