From 4cb56b7f6c37c292a99af3d4f8bab6a0963798c3 Mon Sep 17 00:00:00 2001 From: Giovanni Costagliola Date: Tue, 9 Jun 2026 17:19:12 +0200 Subject: [PATCH] feat(agentic-harness): coordinate generated orchestrator with installed SDD (v0.5.0) When a spec-driven development (SDD) system is present, the generated orchestrator now coordinates with it via a two-way handoff instead of ignoring it: the orchestrator stays the driver, activates the SDD's owned segment with a contextual prompt (auto-invokable CLI/MCP, or prompt-and-pause for human-gated IDE/approval flows), the SDD hands back its artifacts as the contract, and the orchestrator resumes (execute, integrate, cross-boundary QA), writing status back in the SDD's conventions. Two invariants hold: one owner per phase, and one source of truth per artifact (SDD artifacts referenced in place, never copied into _agents_workspace/). - New shared/sdd-coordination.md: the handoff protocol and the per-system coordination map (owned segment, activation, hand-back contract, write-back). - Move detection-signatures.md from spec-advisor/references/ to shared/ so both spec-advisor and harness-setup read one source; update spec-advisor paths. - harness-setup: Step 0 detects an installed SDD and records a coordination context; Step 2 settles delegated vs owned phases with the user; Step 5 splices the SDD-coordination addenda into the orchestrator with concrete paths inlined; checklist updated. - orchestrator-template.md: new "SDD coordination" section (three addenda, Spec Kit and Kiro worked snippets, defer-heavy note) for templates A/B/C. - claude-md-pointer.md: optional "Spec process" line recording the relationship. - Bump plugin.json 0.4.0 -> 0.5.0 and refresh description/README; correct the stale marketplace.json version (0.3.1 -> 0.5.0). Scope is "core only": harness-review SDD-drift checks and a spec-advisor post-install hand-back offer are deferred. Structural suite and `claude plugin validate ./agentic-harness --strict` both pass. --- .claude-plugin/marketplace.json | 2 +- agentic-harness/.claude-plugin/plugin.json | 4 +- agentic-harness/README.md | 2 + agentic-harness/shared/claude-md-pointer.md | 14 ++- .../detection-signatures.md | 0 agentic-harness/shared/sdd-coordination.md | 93 +++++++++++++++++++ agentic-harness/skills/harness-setup/SKILL.md | 48 ++++++++-- .../references/orchestrator-template.md | 93 +++++++++++++++++++ agentic-harness/skills/spec-advisor/SKILL.md | 15 +-- .../spec-advisor/references/spec-systems.md | 7 +- 10 files changed, 258 insertions(+), 20 deletions(-) rename agentic-harness/{skills/spec-advisor/references => shared}/detection-signatures.md (100%) create mode 100644 agentic-harness/shared/sdd-coordination.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 76c87f0..2397820 100644 --- a/.claude-plugin/marketplace.json +++ b/.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"] }, diff --git a/agentic-harness/.claude-plugin/plugin.json b/agentic-harness/.claude-plugin/plugin.json index 511a1b0..eb311ed 100644 --- a/agentic-harness/.claude-plugin/plugin.json +++ b/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" diff --git a/agentic-harness/README.md b/agentic-harness/README.md index e377407..c76aa38 100644 --- a/agentic-harness/README.md +++ b/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 diff --git a/agentic-harness/shared/claude-md-pointer.md b/agentic-harness/shared/claude-md-pointer.md index d3cdf53..6a9f75b 100644 --- a/agentic-harness/shared/claude-md-pointer.md +++ b/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. diff --git a/agentic-harness/skills/spec-advisor/references/detection-signatures.md b/agentic-harness/shared/detection-signatures.md similarity index 100% rename from agentic-harness/skills/spec-advisor/references/detection-signatures.md rename to agentic-harness/shared/detection-signatures.md diff --git a/agentic-harness/shared/sdd-coordination.md b/agentic-harness/shared/sdd-coordination.md new file mode 100644 index 0000000..420042b --- /dev/null +++ b/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//` from the contextual prompt | semi (CLI scaffolds; content authored) | `specs//{spec,plan,tasks}.md` present and complete | tick task checkboxes in `tasks.md` | +| **OpenSpec** | the change proposal | author `openspec/changes//` 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//{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`. diff --git a/agentic-harness/skills/harness-setup/SKILL.md b/agentic-harness/skills/harness-setup/SKILL.md index c33a054..7cd3dc2 100644 --- a/agentic-harness/skills/harness-setup/SKILL.md +++ b/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. diff --git a/agentic-harness/skills/harness-setup/references/orchestrator-template.md b/agentic-harness/skills/harness-setup/references/orchestrator-template.md index d610a82..4abbacf 100644 --- a/agentic-harness/skills/harness-setup/references/orchestrator-template.md +++ b/agentic-harness/skills/harness-setup/references/orchestrator-template.md @@ -11,6 +11,7 @@ state the mode per phase. - [Template A — agent team (default)](#template-a--agent-team-default) - [Template B — subagent (fallback / lightweight)](#template-b--subagent-fallback--lightweight) - [Template C — hybrid](#template-c--hybrid) + - [SDD coordination](#sdd-coordination) - [Authoring rules](#authoring-rules) - [Follow-up keywords](#follow-up-keywords) @@ -21,6 +22,10 @@ state the mode per phase. The first choice when two or more agents need to talk while they work. Build the team with `TeamCreate`; coordinate over a shared task list and `SendMessage`. +> If the project has an installed SDD system, also splice in the [SDD coordination](#sdd-coordination) +> addenda (phase 0, prepare, integrate) so the orchestrator hands work to the spec process and +> resumes on hand-back. + ````markdown --- name: {domain}-orchestrator @@ -108,6 +113,9 @@ nudges or reassigns a stuck member, and checks state with `TaskGet`. When team communication is unnecessary, or the team tools are unavailable. Spawn each agent with the `Agent` tool and collect return values. +> If the project has an installed SDD system, also splice in the [SDD coordination](#sdd-coordination) +> addenda (phase 0, prepare, integrate). + ````markdown --- name: {domain}-orchestrator @@ -156,6 +164,10 @@ Keep `_agents_workspace/`; report a summary. A different mode per phase. State `**Execution mode:** {team | subagent}` at the top of each phase. +> If the project has an installed SDD system, the [SDD coordination](#sdd-coordination) addenda +> attach to whichever phases own the context check, the prepare step, and the integrate step — +> regardless of each phase's execution mode. + ````markdown --- name: {domain}-orchestrator @@ -188,6 +200,85 @@ One QA subagent reads `_agents_workspace/03_integrated.md` and writes a verifica team: pass the subagent's file outputs to members as read paths. Team → team: tear down the old team before the next `TeamCreate` (only one team is active per session). +## SDD coordination + +Use this when the project has an installed spec-driven development (SDD) system. The model — the +two-way handoff, the one-owner-per-phase rule, and the per-system coordination map — is in +`${CLAUDE_PLUGIN_ROOT}/shared/sdd-coordination.md`. This section turns it into three **addenda** +you splice into whichever template you picked (A / B / C). The generated orchestrator cannot read +that shared file at runtime, so **inline the concrete values** from the detected system's +coordination row: `{system}`, `{owned-segment}`, `{ACTIVATE}` (its entry point), auto-invokable or +human-gated, `{HANDBACK_CONTRACT}` (the artifact paths that mark completion), and +`{WRITEBACK_RULE}`. + +Mark every phase as either delegated (`→ SDD: {system}`) or orchestrator-owned, so no phase is done +twice. Reference the SDD's artifacts in place — never copy them into `_agents_workspace/`. + +### Addendum 1 — phase 0 (context check): locate, then activate the spec +Add to the context-check phase, before going to prepare: + +``` +- If the active spec for this request does not yet exist under `{HANDBACK_CONTRACT}`, the SDD + owns the next step. Activate it (hand-in): + - Auto-invokable: invoke `{ACTIVATE}` with a contextual prompt built from the goal and the + constraints this orchestrator already holds, so {system} starts without re-gathering. + - Human-gated: emit that contextual prompt to the user, state how to run {system}'s step, and + **pause** until the user confirms it is done. +- If the spec already exists, go straight to prepare and treat it as the input contract. +``` + +### Addendum 2 — prepare: read the contract, do not restate it +Add to the prepare phase: + +``` +- Read `{HANDBACK_CONTRACT}` as the authoritative input — requirements, design, tasks. Agents + treat it as the source of truth; they do not re-derive requirements the SDD owns. +- Reference these artifacts by path; do not copy them into `_agents_workspace/`. +``` + +### Addendum 3 — integrate / finish: write status back in {system}'s conventions +Add to the integrate (team) or finish (subagent) phase: + +``` +- The final deliverable goes to the user's target path as usual. +- Write status and decisions back into {system}: {WRITEBACK_RULE}. Never overwrite human-authored + spec prose — the spec owns intent, the harness owns execution. +``` + +### Worked snippet — Spec Kit (auto-invokable) +- **owned-segment:** spec → plan → tasks · **ACTIVATE:** the specify flow / author `specs//` +- **HANDBACK_CONTRACT:** `specs//{spec,plan,tasks}.md` complete · **WRITEBACK_RULE:** tick the + task checkboxes in `tasks.md` + +``` +### Phase 0: context check → SDD: GitHub Spec Kit +... existing initial/follow-up/partial branch ... +- If `specs//tasks.md` for this request is absent, hand in to Spec Kit: run its specify flow + with a contextual prompt from the goal + constraints; proceed once spec/plan/tasks exist. +### Phase 1: prepare +- Read `specs//{spec,plan,tasks}.md` as the contract; reference in place. +### Phase 4: integrate +- Write the deliverable; tick the completed checkboxes in `specs//tasks.md`. +``` + +### Worked snippet — AWS Kiro (human-gated, IDE) +- **ACTIVATE:** the user authors in the Kiro IDE · **HANDBACK_CONTRACT:** + `.kiro/specs//{requirements,design,tasks}.md` + +``` +### Phase 0: context check → SDD: AWS Kiro +- If `.kiro/specs//` is absent, emit a contextual prompt (goal + constraints + the EARS + requirements to capture), tell the user to author it in Kiro, and **pause**. Resume when the + files exist. +``` + +### Defer-heavy systems (BMAD, spec-workflow-mcp, Taskmaster) +These own a larger segment, but the protocol is identical — there is no "step aside" mode. Activate +the SDD's own flow with a contextual prompt, let it run its owned segment (personas, approval gate, +task loop), and have the orchestrator own only what the SDD does not: typically execution, +integration, and a cross-boundary QA pass over the SDD's output. When Taskmaster pairs with a spec +system, anchor requirements to the spec and route **task status** through `.taskmaster/tasks/tasks.json`. + ## Authoring rules 1. State the execution mode at the top. For hybrid, a per-phase mode table is required. @@ -199,6 +290,8 @@ old team before the next `TeamCreate` (only one team is active per session). call out the transition points. 6. Make error handling realistic — do not assume everything succeeds. 7. Include at least one normal and one error test scenario. +8. When an SDD system is present, splice in the [SDD coordination](#sdd-coordination) addenda with + the system's concrete values inlined, and mark each phase as delegated or orchestrator-owned. ## Follow-up keywords diff --git a/agentic-harness/skills/spec-advisor/SKILL.md b/agentic-harness/skills/spec-advisor/SKILL.md index e8a344c..73d57ef 100644 --- a/agentic-harness/skills/spec-advisor/SKILL.md +++ b/agentic-harness/skills/spec-advisor/SKILL.md @@ -13,8 +13,8 @@ nothing of its own except by running the chosen system's installer, and only aft approval. It is offline-first. Everything needed to scan, recommend, and name an install command is in the -two curated references; the network is reached only with the user's say-so (see the online policy -in `references/spec-systems.md`). +curated reference and the shared detection signatures; the network is reached only with the user's +say-so (see the online policy in `references/spec-systems.md`). ## What this skill is not — and which skill to use instead @@ -51,7 +51,7 @@ data, ops config with no codebase), explain briefly that an SDD system is not th ### Step 1 — Scan first: is a spec system already present? -Using `references/detection-signatures.md`, scan for any existing spec system **or** ADR registry. +Using `${CLAUDE_PLUGIN_ROOT}/shared/detection-signatures.md`, scan for any existing spec system **or** ADR registry. **If one is found, report what is present and where, then stop.** Do not push a second system on top of one already in use — an existing process is the user's decision, and stacking a second SDD system creates exactly the duplication this skill exists to avoid. This is a read-only report; the @@ -112,8 +112,8 @@ the user at the official source (kiro.dev), and stop. Do not run an installer or - **Offline, or a search stalls** — fall back to the curated data; never block on the network. The offline path is complete on its own. - **Detection ambiguity** — resolve the shared `requirements/design/tasks` triple by parent - directory first (per `references/detection-signatures.md`); if still ambiguous, report exactly - what was found and ask, rather than guessing the system. + directory first (per `${CLAUDE_PLUGIN_ROOT}/shared/detection-signatures.md`); if still ambiguous, + report exactly what was found and ask, rather than guessing the system. - **Installer failure** — report the failure and point the user at the system's official troubleshooting source. Do not partially hand-roll the setup; a half-installed system is worse than a clean failure the user can retry. @@ -122,8 +122,9 @@ the user at the official source (kiro.dev), and stop. Do not run an installer or ## References -- `references/detection-signatures.md` — the scan-first knowledge: the consolidated path→system - table and the disambiguation rules (triple-by-parent-dir, BMAD v4/v6, ADR signals). +- `${CLAUDE_PLUGIN_ROOT}/shared/detection-signatures.md` — the scan-first knowledge: the + consolidated path→system table and the disambiguation rules (triple-by-parent-dir, BMAD v4/v6, + ADR signals). Shared with `harness-setup`, which reads it to detect an installed system. - `references/spec-systems.md` — the per-system profiles (official repo/docs URL, install command, philosophy, Claude Code affinity, maturity, best-fit), the selection decision tree, the Kiro/IDE caveat, and the online policy. diff --git a/agentic-harness/skills/spec-advisor/references/spec-systems.md b/agentic-harness/skills/spec-advisor/references/spec-systems.md index 75a2b7f..5339034 100644 --- a/agentic-harness/skills/spec-advisor/references/spec-systems.md +++ b/agentic-harness/skills/spec-advisor/references/spec-systems.md @@ -8,6 +8,11 @@ load-bearing: when a system is **selected** (not before), the official-repo fetc is what confirms the current command — these values are the offline baseline and the source of the URL to fetch. +For how a generated orchestrator coordinates with each of these systems once it is installed (the +hand-in / hand-back protocol and the per-system owned segment), see +`${CLAUDE_PLUGIN_ROOT}/shared/sdd-coordination.md` — that is `harness-setup`'s concern, not this +skill's. + ## Per-system profiles ### GitHub Spec Kit @@ -34,7 +39,7 @@ the URL to fetch. - **On-disk artifacts:** **v6** `_bmad/` + `_bmad-output/`; **v4** `.bmad-core/` + `docs/{prd,architecture,stories}/` - **Philosophy / stages:** a heavy agile pipeline with named agent personas (analyst, PM, architect, scrum master, dev) producing PRD → architecture → sharded stories. - **Claude Code affinity:** high, but opinionated — it brings its own multi-agent process. -- **Maturity:** mature and feature-rich; note the v4/v6 layout split (see `detection-signatures.md`). +- **Maturity:** mature and feature-rich; note the v4/v6 layout split (see `${CLAUDE_PLUGIN_ROOT}/shared/detection-signatures.md`). - **Best-fit:** teams that want a full, ceremony-rich agile workflow; greenfield-leaning. ### Agent OS