feat(agentic-harness): coordinate generated orchestrator with installed SDD (v0.5.0)

.claude-plugin/marketplace.json

@@ -14,7 +14,7 @@
       "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.3.1",
+      "version": "0.5.0",
       "category": "engineering",
       "tags": ["harness", "agents", "skills", "scaffolding", "orchestration", "multi-agent", "meta-skill"]
     },

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

@@ -1,7 +1,7 @@
 {
   "name": "agentic-harness",
-  "version": "0.4.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. 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.5.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).",
   "author": {
     "name": "MrBogomips",
     "url": "https://github.com/MrBogomips"

agentic-harness/README.md

@@ -10,6 +10,8 @@ This plugin does not do your domain work. It builds and maintains the agents and
 - **`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.
 
+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`).
+
 The harness loop: **review → setup → review again.** `spec-advisor` is offered alongside it when a software project has no spec system yet.
 
 ## Skills, not commands

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

@@ -7,11 +7,14 @@ wrong place for anything the file system already holds.
 ## Register a minimal pointer
 
 After a harness is built or changed, write (or update) one short section in the target
-project's `CLAUDE.md`. It carries three things and nothing more:
+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:
 
 1. The harness's **goal**, in one line.
 2. The **trigger rule** — which orchestrator skill to use, and for which kind of request.
 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.
 
 This is enough for a fresh session: the trigger rule routes domain requests to the
 orchestrator, and the orchestrator handles the rest from the files under `.claude/`.
@@ -23,6 +26,9 @@ orchestrator, and the orchestrator handles the rest from the files under `.claud
 
 **Goal:** {one line on what this harness produces}
 
+**Spec process:** {system} ({version}) — orchestrator activates it for {owned segment};
+hand-back via {contract}. *(omit this line entirely when no SDD system is present)*
+
 **Trigger:** For {domain} work, use the `{orchestrator-skill-name}` skill. Answer simple
 questions directly.
 
@@ -32,6 +38,10 @@ questions directly.
 | {YYYY-MM-DD} | Initial setup | All | — |
 ````
 
+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`.
+
 ## What not to put here
 
 Leave these out of `CLAUDE.md`:
@@ -41,6 +51,8 @@ Leave these out of `CLAUDE.md`:
   truth that drifts.
 - The directory structure — readable straight from the file system.
 - 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 pointer is a signpost, not a manifest. Keep it small enough that it stays correct.
 

agentic-harness/shared/sdd-coordination.md

@@ -0,0 +1,93 @@
+# SDD coordination
+
+When a project has a spec-driven development (SDD) system installed, the harness does not run
+beside it — the two **work coordinated**. This file defines how the generated orchestrator and an
+installed SDD system compose: who owns which part of the workflow, how the orchestrator hands work
+in, and how it picks the work back up. `harness-setup` reads this to bake the coordination into the
+orchestrator it generates; the orchestrator itself cannot read this file at runtime, so the
+relevant values are **inlined** at generation time.
+
+A harness is the *who/how/when* of the work — agents, skills, order. An SDD system is the
+*project process* the work follows — requirements, design, decomposition, decision records. 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
+
+An SDD system owns a **bounded segment** of the workflow — usually the spec/plan/decompose
+front-end, and for the heavier systems part of the build too. 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 phase boundary the SDD owns, the orchestrator composes a
+   **contextual prompt** from what it already holds — the goal, the constraints, the context it has
+   gathered — and activates the SDD's entry point so the SDD 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, 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 SDD runs its owned segment.** The orchestrator does **not** duplicate it — it never
+   re-derives the requirements or the plan the SDD owns.
+3. **Hand-back (return).** The SDD signals completion; its artifacts — the spec, plan, tasks,
+   approved design, or task graph — are the **contract**. The orchestrator detects completion (the
+   artifact is present, an approval flag is set, or the user confirms) and resumes.
+4. **The orchestrator resumes its owned segment** — parallel execution, integration, cross-boundary
+   QA — reading the SDD artifacts as its input and **writing status and decisions back** in the
+   SDD's own conventions. The final deliverable still goes to the user's target path.
+
+### Two rules that keep it clean
+
+- **One owner per phase.** Mark each orchestrator phase as either delegated (`→ SDD: {system}`) or
+  orchestrator-owned. A phase the SDD 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.** SDD artifacts are **referenced**, never copied into
+  `_agents_workspace/`. The orchestrator reads them in place and writes status back in place. Copying
+  a spec 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
+SDD 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 SDD already settled.
+
+## Per-system coordination map
+
+The owned segment, the activation entry point, the hand-back contract, and the write-back rule for
+each system in the curated shortlist. `harness-setup` looks up the detected system's row and inlines
+these concrete values into the orchestrator. Where a system spans versions (BMAD), the artifact path
+follows the detected version — see `${CLAUDE_PLUGIN_ROOT}/shared/detection-signatures.md`.
+
+| System | SDD owns | Activate (hand-in) | Auto-invokable? | Hand-back contract | Orchestrator writes back |
+|---|---|---|---|---|---|
+| **GitHub Spec Kit** | spec → plan → tasks | run the specify flow / author `specs/<NNN>/` from the contextual prompt | semi (CLI scaffolds; content authored) | `specs/<NNN>/{spec,plan,tasks}.md` present and complete | tick task checkboxes in `tasks.md` |
+| **OpenSpec** | the change proposal | author `openspec/changes/<id>/` from the context | semi | the settled change proposal | implement the change; archive to `openspec/specs/` |
+| **Agent OS** | the spec, honoring standards | produce `agent-os/specs/` per `standards/` | semi | the spec is ready | execute per spec + standards |
+| **AWS Kiro** | EARS requirements/design/tasks (IDE) | emit the contextual prompt; the user authors in the Kiro IDE; **pause** | no (IDE / human) | `.kiro/specs/<feature>/{requirements,design,tasks}.md` | status back into `tasks.md` |
+| **ADR tooling** | decision records | on a design decision, hand in "record this decision" | semi | an ADR file under `docs/adr/` | append an ADR for each decision the harness makes |
+| **BMAD-METHOD** | the agile persona pipeline | activate the BMAD flow with the contextual prompt (which epic / story) | yes (CLI; human-in-loop steps) | `_bmad-output/` (v6) or `docs/{prd,architecture,stories}/` (v4) + story status | coordinate; add only the cross-cutting QA / integration BMAD lacks; write story status back |
+| **spec-workflow-mcp** | the spec workflow + approval gate | call its MCP tools with the contextual prompt; wait on the approval gate | yes (MCP) + human approval | the approved spec under `.spec-workflow/specs/` | execute the approved spec; status back via its conventions |
+| **Taskmaster** | task decomposition + tracking | hand in the PRD / context → it parses to a task graph | yes (CLI / MCP) | `.taskmaster/tasks/tasks.json` | execute tasks; update task status via Taskmaster |
+
+The heavier systems (BMAD, spec-workflow-mcp, Taskmaster) own a **larger** segment and may be
+human-gated, but the handoff protocol is the same — there is no "step aside and let the SDD own
+everything" mode. The orchestrator always drives the parts the SDD does not own (typically
+execution, integration, and a cross-boundary QA pass), and coordinates the rest.
+
+### Taskmaster as a pairing
+
+Taskmaster decomposes and tracks tasks; it **pairs** with an upstream spec system rather than
+replacing one (it owns the task graph, not the requirements). When Taskmaster co-exists with a spec
+system, the orchestrator anchors requirements to the spec system and routes **task status** through
+Taskmaster's `tasks.json` instead of inventing its own status file — one owner per concern.
+
+## How `harness-setup` uses this
+
+1. After detecting the present system (Step 0), look up its row above and capture the **coordination
+   context**: `{system, version, owned-segment, activation, auto-invokable, hand-back contract,
+   write-back rule}`.
+2. With the user, decide which phases the orchestrator delegates vs owns, and whether activation is
+   auto or prompt-and-pause (Step 2). Fold the decision into the change manifest.
+3. Splice the **SDD-coordination block** from `harness-setup`'s `references/orchestrator-template.md`
+   into the chosen template (A / B / C), substituting the concrete values from the coordination
+   context (Step 5). The generated orchestrator must be self-contained — inline the paths and the
+   entry point; do not leave it pointing at this file.
+4. Record the relationship in the `CLAUDE.md` pointer's **Spec process** line — see
+   `${CLAUDE_PLUGIN_ROOT}/shared/claude-md-pointer.md`.

agentic-harness/skills/harness-setup/SKILL.md

@@ -49,13 +49,22 @@ plan is confirmed.
    Record the answers. Asking is the default; a "no" is a fine answer, but a silent skip is
    not. Running happens only on a yes — see Step 1b. This confirms the approach; the concrete
    list of files and tools is approved separately at Step 2b, before anything is written.
-5. **Offer `spec-advisor` when it fits.** When the project looks like software and no
-   spec-driven development system is evident, offer to run the `spec-advisor` skill — it advises
-   which SDD system fits and delegates setup to that system's own installer. A harness is the
-   *who/how/when* of the work; a spec system is the *project process* that work follows, so the
-   two are complementary, not the same job. Make the offer here and hand off — detection lives in
-   `spec-advisor`, so do not duplicate it. Offering is the default; running is gated on a yes, and
-   nothing is installed without `spec-advisor`'s own per-system approval. Record the answer.
+5. **Account for the project's spec process.** A harness is the *who/how/when* of the work; a
+   spec-driven development (SDD) system is the *project process* the work follows. They are
+   complementary, so check which case applies — scan with
+   `${CLAUDE_PLUGIN_ROOT}/shared/detection-signatures.md`:
+   - **No SDD system, project looks like software** → offer to run the `spec-advisor` skill, which
+     advises which SDD system fits and delegates setup to that system's own installer. Offering is
+     the default; running is gated on a yes, and nothing is installed without `spec-advisor`'s own
+     per-system approval. If the user installs one, fold its coordination into the plan below.
+   - **An SDD system is present** → do not re-recommend and do not install. Identify the system and
+     version, look up its row in `${CLAUDE_PLUGIN_ROOT}/shared/sdd-coordination.md`, and record a
+     **coordination context** — `{system, version, owned-segment, activation, auto-invokable,
+     hand-back contract, write-back rule}` — to carry into Step 2 and Step 5. This is the lightweight
+     read `harness-setup` needs to bake the coordination into the orchestrator; `spec-advisor` still
+     owns recommending and installing.
+
+   Record the answer either way.
 
 ## Step 1: Analyze the domain
 
@@ -113,6 +122,16 @@ covers them.
 criteria table is in `references/agent-design-patterns.md`. Prefer a few focused agents over
 many thin ones; coordination cost grows with team size.
 
+**Coordinate with the spec process.** If Step 0 recorded a coordination context (an SDD system is
+present), decide *with the user* how the orchestrator and the SDD compose — they must work together
+without overlap and with minimal friction, not run in parallel. Using
+`${CLAUDE_PLUGIN_ROOT}/shared/sdd-coordination.md`, settle: which phases the orchestrator **delegates**
+to the SDD (the spec/plan/decompose segment it owns) versus **owns** (typically execution,
+integration, and a cross-boundary QA pass); and whether activation is **auto-invokable** (the
+orchestrator calls the SDD's CLI/MCP entry point with a contextual prompt) or **human-gated** (it
+emits the prompt and pauses for the user, as with an IDE or an approval step). Fold the decision into
+the Step 2b manifest so it is approved before any write.
+
 ## Step 2b: Approve the change manifest — required before any write
 
 Before creating, updating, or deleting anything — and before installing or uninstalling any
@@ -207,6 +226,12 @@ Build into the orchestrator:
 - **The tools registry**, when tool discovery (Step 1b) has run: it lives in this
   orchestrator's `references/` directory as `tools.md`, and agents and skills reference tools
   by role from it.
+- **SDD coordination**, when Step 0 recorded a coordination context: splice the addenda from
+  `references/orchestrator-template.md` (SDD coordination section) into the orchestrator's phase 0,
+  prepare, and integrate phases, **inlining the system's concrete artifact paths and entry point** —
+  the orchestrator cannot read the shared file at runtime. Mark each phase as delegated
+  (`→ SDD: {system}`) or orchestrator-owned. The model is in
+  `${CLAUDE_PLUGIN_ROOT}/shared/sdd-coordination.md`.
 
 When extending rather than building new, modify the existing orchestrator — do not create a
 second one. Reflect a new agent in the team composition, task assignment, data flow, and
@@ -250,7 +275,11 @@ Before calling a setup or change complete:
 - [ ] Skill and orchestrator descriptions are pushy and include follow-up keywords.
 - [ ] Each SKILL.md body is within ~500 lines; overflow moved to `references/`.
 - [ ] The orchestrator's first phase does a context check (initial / follow-up / partial).
-- [ ] The `CLAUDE.md` pointer is registered (goal + trigger + change history).
+- [ ] If an SDD system is present: the orchestrator activates it via a contextual prompt and resumes
+      on hand-back, every phase has exactly one owner, and no SDD artifact is copied into
+      `_agents_workspace/`.
+- [ ] The `CLAUDE.md` pointer is registered (goal + trigger + change history; plus the spec-process
+      line when an SDD system is present).
 - [ ] The change-history table records this change.
 - [ ] The user was asked whether to run tool research (and, on an existing harness, tool
       maintenance), and the answer was recorded — whatever they chose.
@@ -274,3 +303,6 @@ Before calling a setup or change complete:
 - `${CLAUDE_PLUGIN_ROOT}/shared/harness-model.md`,
   `${CLAUDE_PLUGIN_ROOT}/shared/execution-modes.md`,
   `${CLAUDE_PLUGIN_ROOT}/shared/claude-md-pointer.md` — shared concepts.
+- `${CLAUDE_PLUGIN_ROOT}/shared/detection-signatures.md` — how to recognise an installed SDD system
+  (shared with `spec-advisor`); `${CLAUDE_PLUGIN_ROOT}/shared/sdd-coordination.md` — the
+  orchestrator↔SDD coordination model and the per-system coordination map.