diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 377f632..0b32c43 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1,30 +1,27 @@ { - "name": "mrbogomips", + "name": "mrbogomips-tools", "owner": { "name": "Mr Bogomips", "email": "giovanni.costagliola@gmail.com" }, "metadata": { "description": "A curated collection of Claude Code plugins for professional workflows", - "version": "2.0.0", + "version": "3.0.0", "license": "MIT" }, "plugins": [ - { - "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, assess how effectively they are used, advise on spec-driven development systems and agent-suited issue trackers, and generate a dual-tracker sync when a repo-native and a human tracker coexist", - "version": "0.8.0", - "category": "engineering", - "tags": ["harness", "agents", "skills", "scaffolding", "orchestration", "multi-agent", "meta-skill", "issue-tracker", "tracker-sync", "spec-driven-development"] - }, { "name": "developer-tools", "source": "./developer-tools", "description": "Developer environment tooling — devcontainer generation, stack detection, infrastructure config", "version": "2.4.0", "category": "engineering", - "tags": ["devcontainer", "docker", "infrastructure", "developer-experience"] + "tags": [ + "devcontainer", + "docker", + "infrastructure", + "developer-experience" + ] }, { "name": "human-resources", @@ -32,7 +29,14 @@ "description": "HR interview workflow — job descriptions, candidate pre-screening, interview preparation, evaluation, compliance checking, and methodology guidance", "version": "0.2.0", "category": "human-resources", - "tags": ["hr", "recruiting", "interviews", "compliance", "evaluation", "job-description"] + "tags": [ + "hr", + "recruiting", + "interviews", + "compliance", + "evaluation", + "job-description" + ] }, { "name": "kaizen", @@ -40,7 +44,15 @@ "description": "Continuous improvement loops — a generic recursive optimization engine with bundled profiles for Claude Code usage, code refactoring, and process improvement", "version": "1.0.0", "category": "engineering", - "tags": ["kaizen", "improvement", "optimization", "automation", "autoresearch", "kpi", "refactoring"] + "tags": [ + "kaizen", + "improvement", + "optimization", + "automation", + "autoresearch", + "kpi", + "refactoring" + ] }, { "name": "plantuml", @@ -48,7 +60,15 @@ "description": "Authoring, rendering, and maintenance of PlantUML diagrams — policy-driven projects with multi-target rendering, lint, validate, review, advisor, and migrate", "version": "1.0.0", "category": "documentation", - "tags": ["plantuml", "diagrams", "uml", "c4", "documentation", "rendering", "lint"] + "tags": [ + "plantuml", + "diagrams", + "uml", + "c4", + "documentation", + "rendering", + "lint" + ] }, { "name": "project-management", @@ -56,7 +76,16 @@ "description": "SOW writing, review, estimation, and PMI-compliant PERT analysis — an integrated project management pipeline", "version": "1.0.0", "category": "operations", - "tags": ["pmo", "sow", "pert", "estimation", "wbs", "risk", "planning", "review"] + "tags": [ + "pmo", + "sow", + "pert", + "estimation", + "wbs", + "risk", + "planning", + "review" + ] }, { "name": "tech-writing", @@ -64,7 +93,11 @@ "description": "Technical writing support — documentation structure, style guides, content review", "version": "0.1.0", "category": "documentation", - "tags": ["writing", "documentation", "style-guide"] + "tags": [ + "writing", + "documentation", + "style-guide" + ] } ] } diff --git a/README.md b/README.md index 5d3db18..7dfdf04 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,6 @@ A curated collection of [Claude Code](https://claude.com/claude-code) plugins fo | Plugin | Description | Category | |--------|-------------|----------| -| [agentic-harness](./agentic-harness) | Stand up, assess, and maintain an agentic harness — generate project-specific agent teams and the skills they use, then assess how effectively they are used | Engineering | | [developer-tools](./developer-tools) | Developer environment tooling — devcontainer generation, stack detection, infrastructure config | Engineering | | [human-resources](./human-resources) | HR interview workflow — job descriptions, pre-screening, interview prep, evaluation, compliance | Human Resources | | [kaizen](./kaizen) | Continuous improvement loops — recursive optimization engine with profiles for Claude Code usage, refactoring, and process improvement | Engineering | @@ -14,7 +13,7 @@ A curated collection of [Claude Code](https://claude.com/claude-code) plugins fo | [project-management](./project-management) | SOW writing, review, estimation, and PMI-compliant PERT analysis — integrated project management pipeline | Operations | | [tech-writing](./tech-writing) | Technical writing support — documentation structure, style guides, content review | Documentation | -> The [`agentic-harness`](./agentic-harness) plugin is inspired by the open-source `harness` plugin by revfactory (Apache-2.0). It is an independent reimplementation under MIT, with its own structure and prose. +> **Moved:** the `agentic-harness` plugin now lives in its own repository — [MrBogomips/agentic-harness](https://github.com/MrBogomips/agentic-harness). If you installed it from this marketplace, re-add it from there. ## Installation @@ -24,15 +23,15 @@ Add this marketplace, then install the plugins you want. # 1. Add the marketplace claude plugin marketplace add MrBogomips/claude-code -# 2. Install a plugin (the marketplace name is "mrbogomips") -claude plugin install agentic-harness@mrbogomips +# 2. Install a plugin (the marketplace name is "mrbogomips-tools") +claude plugin install kaizen@mrbogomips-tools ``` Or, inside a Claude Code session, use the slash commands: ``` /plugin marketplace add MrBogomips/claude-code -/plugin install agentic-harness@mrbogomips +/plugin install kaizen@mrbogomips-tools ``` Browse and manage everything interactively with `/plugin`. diff --git a/agentic-harness/.claude-plugin/plugin.json b/agentic-harness/.claude-plugin/plugin.json deleted file mode 100644 index 198957a..0000000 --- a/agentic-harness/.claude-plugin/plugin.json +++ /dev/null @@ -1,24 +0,0 @@ -{ - "name": "agentic-harness", - "version": "0.8.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. When a repo-native tracker and a human tracker (Jira, Linear, GitHub Issues) coexist, it generates a dual-tracker sync that keeps the SaaS as a projection of the repo-native source of truth. 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" - }, - "license": "MIT", - "homepage": "https://github.com/MrBogomips/claude-code/tree/main/agentic-harness", - "keywords": [ - "harness", - "agentic-harness", - "agent-team", - "skill-architect", - "meta-skill", - "orchestration", - "scaffolding", - "agent-scaffolding", - "multi-agent", - "issue-tracker", - "claude-code-plugin" - ] -} diff --git a/agentic-harness/README.md b/agentic-harness/README.md deleted file mode 100644 index 4f979a6..0000000 --- a/agentic-harness/README.md +++ /dev/null @@ -1,30 +0,0 @@ -# agentic-harness - -Stand up, assess, and maintain an **agentic harness** inside an existing repository — the project-local agents, skills, and orchestrator that make a repo work well with Claude Code. - -This plugin does not do your domain work. It builds and maintains the agents and skills that do. - -## 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 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`, `tracker-sync-protocol.md`). - -When a project runs **both** a repo-native tracker and a human-oriented one (Jira, Linear, GitHub Issues), `harness-setup` also offers to generate a **dual-tracker sync**: a project-local `tracker-sync` skill and agent that keep the SaaS tracker as a projection of the repo-native source of truth — continuous one-way push, one-time intake of human-created issues, and remote state changes treated as proposals rather than overwritten. Sync state lives in `.tracker-sync/` at the repo root; scheduled headless runs are read-and-report only. The model is in `shared/tracker-sync-protocol.md`; `harness-review` reads the sync state as part of its drift assessment. - -The harness loop: **review → setup → review again.** The advisors are offered alongside it when a software project lacks the matching process layer. - -## Skills, not commands - -Invoke a skill directly (`/agentic-harness:harness-setup`) or let Claude trigger it from context. This plugin ships no slash commands — Claude Code merged commands into skills. - -## Execution modes - -`harness-setup` defaults to an **agent team** and falls back to **subagents** when the experimental team tools are unavailable. See `shared/execution-modes.md`. - -## Inspired by - -The harness concept is inspired by prior work in the community; this is an independent implementation. Credit lives in the repository README. diff --git a/agentic-harness/shared/claude-md-pointer.md b/agentic-harness/shared/claude-md-pointer.md deleted file mode 100644 index 3dd308e..0000000 --- a/agentic-harness/shared/claude-md-pointer.md +++ /dev/null @@ -1,106 +0,0 @@ -# The CLAUDE.md pointer - -A target project's `CLAUDE.md` is loaded into context at the start of every session. That -makes it the right place to record that a harness exists and when it should fire — and the -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 — plus, when the project has an installed -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/`. -The directive is the lever that makes activation reliable — `CLAUDE.md` is the highest-priority -instruction layer, so it does not depend on the skill description triggering on its own. - -### Template - -````markdown -## Harness: {domain} - -**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)* - -**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 -response outside it. The orchestrator decides what happens next: it answers trivial or -out-of-{domain} requests directly and runs the full team only when the work warrants it. - -**Change history:** -| Date | Change | Target | Reason | -|------|--------|--------|--------| -| {YYYY-MM-DD} | Initial setup | All | — | -```` - -The entry-point directive is a hard gate, not a suggestion — there is no `CLAUDE.md`-level bypass. -The triage that used to live here ("answer simple questions directly") now lives *inside* the -orchestrator's first phase, so a trivial or off-domain prompt still routes through the orchestrator -and is answered quickly there. This keeps the orchestrator the reliable entry point without spinning -up a team for every message. - -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 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. - -## What not to put here - -Leave these out of `CLAUDE.md`: - -- The agent list or the skill list — they live in `.claude/agents/` and `.claude/skills/`, - and the orchestrator already knows them. Copying them here creates a second source of - 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 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. - -## The change-history table - -Every write to the harness appends a row. The columns are fixed: - -| Date | Change | Target | Reason | -|------|--------|--------|--------| -| 2026-04-05 | Initial setup | All | — | -| 2026-04-07 | Added QA agent | `agents/qa.md` | deliverable-quality gaps reported | -| 2026-04-10 | Added tone guidance | `skills/content-writer` | output read as too stiff | - -The table earns its place: it shows how the harness has evolved and why, which makes -regressions visible and gives the next reviewer a starting point. Recording history is a -required step of every harness write — not an optional courtesy. - -On periodic review this table can be pruned, preserving valuable information and keeping it readable. diff --git a/agentic-harness/shared/coordination-protocol.md b/agentic-harness/shared/coordination-protocol.md deleted file mode 100644 index 1ea2680..0000000 --- a/agentic-harness/shared/coordination-protocol.md +++ /dev/null @@ -1,63 +0,0 @@ -# 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. diff --git a/agentic-harness/shared/detection-signatures.md b/agentic-harness/shared/detection-signatures.md deleted file mode 100644 index 9ed84a1..0000000 --- a/agentic-harness/shared/detection-signatures.md +++ /dev/null @@ -1,129 +0,0 @@ -# Detection signatures - -The scan-first knowledge behind flow Step 1 of `spec-advisor` and `tracker-advisor` (and behind -`harness-setup`'s process-layers gate). This is a curated **reference of facts**, not a set of -recommendations: it tells you how to recognise a spec system, an ADR registry, or an issue -tracker that is already present, so the skill can report it and stay out. A generic search -cannot reliably re-derive these signatures each run — the on-disk layouts drift in load-bearing -ways (BMAD changed its directories between v4 and v6) and several systems share filenames — so -they live here as knowledge. - -## How to scan - -Look for the signature paths below at the repository root and one or two levels in. One -signature is **not a path**: git-bug stores issues as git objects under the `refs/bugs/` -namespace, so check it with `git for-each-ref refs/bugs` (read-only) — a filesystem scan will -silently miss it. A hit means a system of that area **already exists**. When you find one: - -- Report **what** is present and **where** (the matched path or ref), then **stop** for that - area. -- Do not push a second system on top of one that is already in use. The skills are advisory and - detection-first: an existing process is the user's decision, and stacking a second system on - top of it creates exactly the duplication the skills are built to avoid. - -This is a read-only report — the scan itself writes nothing. Each advisor scans its own area's -table; `harness-setup` scans both. - -## Spec systems and ADR registries — path → system table - -| Signature path(s) | System | Notes | -|---|---|---| -| `.specify/`, `specs//{spec,plan,tasks}.md` | GitHub Spec Kit | `specs/NNN-feature/` numbered dirs each holding `spec.md` + `plan.md` + `tasks.md`; `.specify/` is the tool's own config. | -| `openspec/` containing `changes/`, `specs/`, `config.yaml` | OpenSpec | Change-proposal layout — `changes/` holds in-flight proposals, `specs/` the settled capability specs. | -| `_bmad/` + `_bmad-output/` | BMAD-METHOD **v6** | New layout. Report the version — the installer and the flow differ from v4. | -| `.bmad-core/` + `docs/{prd,architecture,stories}/` | BMAD-METHOD **v4** | Legacy layout. The `docs/` artifacts (PRD, architecture, sharded stories) are the give-away. | -| `agent-os/` (v2) or `.agent-os/` (v1); plus `standards/`, `specs/` | Agent OS | `standards/` (governance) alongside light `specs/`. The dotted `.agent-os/` is the older v1 location. | -| `.taskmaster/` containing `docs/prd.txt`, `tasks/tasks.json` | Taskmaster | Task-decomposition tool; often **pairs** with a separate spec system rather than replacing one. | -| `.spec-workflow/` containing `specs/`, `steering/` | spec-workflow-mcp | MCP-surfaced workflow with an approval dashboard; `steering/` holds the project's steering docs. | -| `.kiro/specs//{requirements,design,tasks}.md`, `.kiro/steering/` | AWS Kiro (IDE) | EARS-style `requirements.md`. Kiro is an **IDE**, not a repo install — see the Kiro caveat in `spec-systems.md`. | -| `docs/adr/`, `doc/adr/`, `.adr-dir`, `.log4brains.yml` | ADR tooling | A *decision-record* registry, not a full spec process. `.log4brains.yml` ⇒ log4brains specifically; `.adr-dir` / `docs/adr/` ⇒ adr-tools-style. | - -## Issue trackers — path → system table - -| Signature path(s) | Tracker | Notes | -|---|---|---| -| `.beads/` (holds an embedded Dolt db and/or `issues.jsonl`) | Beads (`bd`) | Graph-based, git-synced issue db built for coding agents. | -| `backlog/` or `.backlog/` containing `config.yml` | Backlog.md | Markdown task manager. A bare `backlog/` directory **without** the config is ambiguous — see rule 4. | -| `.issues/` with YAML-frontmatter markdown files | git-issues | Minimal single-binary tracker; may also leave a generated `.agent.md`. | -| `.beans/` with `.beans.yml` | Beans | Flat-file markdown tracker with a GraphQL query CLI. | -| `refs/bugs/` ref namespace (`git for-each-ref refs/bugs`) | git-bug | Issues live as **git objects**, not files — the filesystem shows nothing. | -| `.github/ISSUE_TEMPLATE/` | GitHub Issues (weak signal) | Usage signal only — see rule 5; never conclude on it silently. | -| `.taskmaster/` | Taskmaster | **Spec-derived** task decomposition, not a general tracker — see rule 6. | - -## Human-tracker usage signals - -A human-oriented SaaS tracker (Jira, Linear, GitHub Issues) rarely leaves a config file in -the repo, so its presence is read from **usage signals** rather than signature paths. These -feed `harness-setup`'s dual-tracker sync sub-step (offered only when an agentic tracker -*and* a human tracker are both present or declared). Every one of them is a signal in the -rule-5 sense — **report what was found and ask whether the tracker is actively used; never -conclude silently**: - -| Signal | Points to | How to check | -|---|---|---| -| Jira issue keys in recent commit messages (`PROJ-123`-style) | Jira | `git log --oneline -100 \| grep -E '[A-Z][A-Z0-9]+-[0-9]+'` | -| `linear.app` links in the repo (README, docs, issue/PR templates) | Linear | `grep -rE 'linear\.app' --include='*.md' .` | -| A configured Atlassian or Linear MCP server in the local/session config | Jira / Linear | inspect the MCP configuration | -| Active `gh` auth plus `.github/ISSUE_TEMPLATE/` | GitHub Issues | `gh auth status`; stays **rule-5 weak** — templates alone prove nothing | - -A declared tracker counts too: when the user says the team works in Jira or Linear, that is -presence — record it and confirm the access path, do not demand an on-disk artifact. - -## Disambiguation rules - -Six cases need a rule because the raw signal is ambiguous. - -### 1. The shared `requirements.md + design.md + tasks.md` triple — resolve by parent directory - -More than one system writes a `requirements.md` + `design.md` + `tasks.md` triple (AWS Kiro under -`.kiro/specs//`, spec-workflow-mcp under `.spec-workflow/specs//`, and others). -The filenames alone do **not** identify the system. Resolve by the **parent directory**, not the -filenames: - -- under `.kiro/` ⇒ AWS Kiro, -- under `.spec-workflow/` ⇒ spec-workflow-mcp, -- under `specs/NNN-*/` with a sibling `.specify/` ⇒ Spec Kit. - -If the triple sits under a parent that matches none of the known roots, the result is genuinely -ambiguous: report exactly what was found and where, and ask the user which system it is rather -than guessing. - -### 2. BMAD version — `_bmad/` is v6, `.bmad-core/` is v4 - -BMAD-METHOD changed its on-disk layout between major versions. `_bmad/` (with `_bmad-output/`) -is the **v6** layout; `.bmad-core/` (with the `docs/{prd,architecture,stories}/` artifacts) is -the **v4** layout. Always report the detected version, because the installer command and the -workflow differ between them — a user on v4 and a user on v6 need different guidance. - -### 3. ADR signals mean a decision-record registry, not a spec system - -`docs/adr/`, `doc/adr/`, `.adr-dir`, or `.log4brains.yml` indicate an **Architecture Decision -Record** registry — lightweight decision logs, not a full spec-driven workflow. Report it as ADR -tooling and distinguish the tool: `.log4brains.yml` ⇒ log4brains; a plain `docs/adr/` with an -`.adr-dir` pointer ⇒ adr-tools-style. A project can hold ADRs *and* still lack a spec system — if -only ADR signals are present, say so plainly, since the user may legitimately want to add a spec -process alongside their existing decision records (offer it; do not assume it). - -### 4. A bare `backlog/` directory is not Backlog.md - -`backlog/` is an ordinary word that projects use for their own notes. Only the directory -**containing Backlog.md's `config.yml`** identifies the tool. A bare `backlog/` without the -config is genuinely ambiguous: report exactly what was found and ask, rather than concluding a -tracker is present. - -### 5. `.github/ISSUE_TEMPLATE/` is a weak signal — report and ask - -Issue templates show that GitHub Issues *has been configured at some point*, not that it is the -project's active tracker — many repos carry vestigial templates. Report "GitHub Issues appears -to be in use" and **ask** whether it is the active tracker. If yes, a tracker is present (it is -agent-reachable via `gh`) — stay out. If no, continue as if no tracker were found. Never treat -the templates alone as a silent stay-out, and never ignore them silently either. - -### 6. Taskmaster appears in both tables — it is spec-derived, not a general tracker - -`.taskmaster/` decomposes and tracks tasks **derived from a spec or PRD**; it pairs with a spec -system rather than serving general issue intake. `spec-advisor` treats it as an SDD pairing -(its own table row above). `tracker-advisor` reports it — "spec-derived task tracking is -covered by Taskmaster" — and stays out unless the user explicitly asks for a general issue -tracker alongside it. When both Taskmaster and a general tracker exist, work state needs one -owner per item — see `${CLAUDE_PLUGIN_ROOT}/shared/tracker-coordination.md`. diff --git a/agentic-harness/shared/execution-modes.md b/agentic-harness/shared/execution-modes.md deleted file mode 100644 index 3a2baa4..0000000 --- a/agentic-harness/shared/execution-modes.md +++ /dev/null @@ -1,85 +0,0 @@ -# Execution modes - -A harness coordinates more than one agent. There are three ways to run that coordination. -Pick one per harness — or, in hybrid, one per phase — and state the choice explicitly in -the orchestrator. - -## Before you choose: the team-tools caveat - -The agent-team mode depends on experimental tools: `TeamCreate`, `SendMessage`, -`TaskCreate`/`TaskUpdate`, `TeamDelete`. These are **not guaranteed to be available** in a -given Claude Code build, session, or permission setup. Treat their presence as a runtime -fact to check, not an assumption. - -Because of that, every team-mode harness must define a **subagent fallback**. The subagent -mode uses only the `Agent` tool, which is broadly available. A harness that can only run as -a team is brittle; a harness that prefers a team and falls back to subagents is not. Build -the fallback at the same time as the team path, not later. - -When the team tools are missing, do not fail — re-route to the subagent equivalent -(`Agent` with `run_in_background`) and note in the run that team coordination was -unavailable. The mapping below makes that re-route mechanical. - -## The three modes - -| Mode | Use when | Mechanism | -|------|----------|-----------| -| **Agent team** (default) | Two or more agents collaborate and benefit from real-time exchange — sharing findings, challenging each other, reconciling conflicts | Members run as peers; coordinate via `TeamCreate` + `SendMessage` + a shared task list (`TaskCreate`/`TaskUpdate`) | -| **Subagent** (fallback and lightweight default) | A single agent's work, or several independent jobs where only the result matters and inter-agent talk would be overhead | The orchestrator calls the `Agent` tool directly; parallelize with `run_in_background` and collect return values | -| **Hybrid** | Phases differ in character — e.g. independent collection, then consensus integration | Choose the mode per phase; state each phase's mode in the orchestrator | - -The team mode is the *preferred* default when agents genuinely need to talk: cross-checking -and shared discovery raise quality in a way isolated subagents cannot. But "preferred" is -conditional on the tools being present and on the work actually needing coordination. When -either is false, subagents are the right call, not a downgrade. - -## Decision order - -1. Is this a single agent? → **subagent**. One agent needs no team. -2. Two or more agents: do they need to exchange information mid-task (challenge findings, - resolve conflicts, hand off partial state)? → if yes, **agent team**; if no — only the - final results combine — **subagent** is enough and cheaper. -3. Are the team tools unavailable? → **subagent fallback**, using the mapping below. -4. Do phases differ markedly in whether coordination helps? → **hybrid**, mode stated per - phase. - -## Team-to-subagent fallback mapping - -When team mode is unavailable, translate it mechanically: - -| Team-mode mechanism | Subagent equivalent | -|---------------------|---------------------| -| `TeamCreate` + member prompts | One `Agent` call per member, each with its role prompt | -| Parallel members | `Agent` calls with `run_in_background: true`, collected after | -| `SendMessage` between members | No direct channel — members can't talk; route shared context through files the orchestrator writes and each agent reads | -| `TaskCreate`/`TaskUpdate` shared list | The orchestrator holds the task list itself and assigns work in the spawn prompts | -| Leader synthesis after team | Orchestrator reads each agent's output file/return value and integrates | - -The cost of the fallback is real: subagents cannot debate or revise each other mid-flight. -Where the team relied on that, compensate by adding an explicit integration or review step -that reconciles the independent outputs afterward. - -## Data-passing per mode - -State the data-passing method inside the orchestrator. Match it to the mode: - -| Method | How | Mode | Fits | -|--------|-----|------|------| -| Message-based | direct member-to-member via `SendMessage` | team | real-time coordination, lightweight state hand-off | -| Task-based | shared work state via `TaskCreate`/`TaskUpdate` | team | progress tracking, dependency management | -| File-based | write and read files at agreed paths | team + subagent | large or structured deliverables, audit trail | -| Return-value-based | the `Agent` tool's return message | subagent | the orchestrator collects results directly | - -- **Team mode:** task-based for coordination + file-based for deliverables + message-based - for live exchange. -- **Subagent mode:** return-value-based for results + file-based for anything large. -- **Hybrid:** apply the matching combination per phase, and check the hand-off at phase - boundaries — when a team phase feeds a subagent phase, the team's output files become the - subagent's inputs. - -### File-passing convention - -- Keep intermediate work under a `_agents_workspace/` directory in the working tree. -- Name files `{phase}_{agent}_{artifact}.{ext}` — e.g. `01_analyst_requirements.md`. -- Write only the final deliverable to the user's target path; preserve `_agents_workspace/` for - later inspection rather than deleting it. diff --git a/agentic-harness/shared/harness-model.md b/agentic-harness/shared/harness-model.md deleted file mode 100644 index 8bb8135..0000000 --- a/agentic-harness/shared/harness-model.md +++ /dev/null @@ -1,55 +0,0 @@ -# The harness model - -A *harness* is the project-local configuration that lets a repository work well with -agents. It has three parts, and keeping them separate is what makes a harness -maintainable. - -## The three parts - -| Part | Question it answers | Where it lives | -|------|---------------------|----------------| -| **Agent** | *Who* does the work | `.claude/agents/{name}.md` | -| **Skill** | *How* the work is done | `.claude/skills/{name}/SKILL.md` | -| **Orchestrator** | *When*, and *in what order*, the agents collaborate | a skill, usually `.claude/skills/{domain}-orchestrator/` | - -An **agent** is an expert role: a persona, its working principles, its input/output -contract, and — in team mode — how it communicates with other agents. An agent is small. -It says who is acting and what that actor cares about, not the step-by-step procedure. - -A **skill** is procedural knowledge: the workflow an agent follows, the format it -produces, the references it consults. A skill can be large. It says how a job is done, -independent of who does it. - -An **orchestrator** is a skill whose subject is the team itself. Where individual skills -describe one agent's job, the orchestrator describes the collaboration: which agents take -part, what each produces, how their outputs flow together, and how failures are handled. - -## Why separate who from how - -The separation is not bookkeeping. It buys three concrete things: - -- **Reuse.** A skill written for "how to review an API contract" is usable by any agent - that needs it, in this project or the next. Bind the procedure to a single named agent - and it stops being portable. -- **Independent change.** When a deliverable is weak, you revise the skill. When you need - a new kind of reviewer, you add an agent. When the workflow order is wrong, you edit the - orchestrator. Each fault has one obvious place to fix it. -- **Survival across sessions.** An agent defined only inline in a prompt vanishes when the - session ends. An agent defined as a file is there next time, with its protocol intact - and its memory. - -## The file rule - -Every agent is a file under `.claude/agents/`, even when it uses a built-in type -(`general-purpose`, `Explore`, `Plan`). Put the built-in type in the call that spawns the -agent; put the role, principles, and protocol in the file. A role written only into a -spawn prompt is not reusable and carries no collaboration contract — so it is not part of -the harness. - -## How the parts connect - -One agent uses one or more skills; a skill may be shared by several agents. The -orchestrator names the agents and points each at its skills. The pointer in the target -project's `CLAUDE.md` names only the orchestrator and its entry-point directive (the hard gate -that routes every prompt through it) — see `claude-md-pointer.md`. Nothing in the harness duplicates what the file system already -states: the agent and skill lists live in `.claude/`, not in `CLAUDE.md`. diff --git a/agentic-harness/shared/sdd-coordination.md b/agentic-harness/shared/sdd-coordination.md deleted file mode 100644 index 43ec7b4..0000000 --- a/agentic-harness/shared/sdd-coordination.md +++ /dev/null @@ -1,55 +0,0 @@ -# SDD coordination - -The spec-process instance of the harness coordination protocol. The protocol itself — the -two-way handoff (activate, owned segment, hand-back, write-back), auto-invokable vs human-gated -activation, and the two rules (**one owner per phase**, **one source of truth per artifact**) — -is in `${CLAUDE_PLUGIN_ROOT}/shared/coordination-protocol.md`; read it first. This file applies -it to spec-driven development (SDD) systems: 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 — and the per-system map below gives the concrete values `harness-setup` inlines into -the generated orchestrator. Detection of which system is present is a separate concern: see -`${CLAUDE_PLUGIN_ROOT}/shared/detection-signatures.md`. - -## 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/shared/tracker-coordination.md b/agentic-harness/shared/tracker-coordination.md deleted file mode 100644 index 0993696..0000000 --- a/agentic-harness/shared/tracker-coordination.md +++ /dev/null @@ -1,73 +0,0 @@ -# Tracker coordination - -The issue-tracking instance of the harness coordination protocol. The protocol itself — the -two-way handoff, auto-invokable vs human-gated activation, and the two rules (**one owner per -phase/concern**, **one source of truth per artifact**) — is in -`${CLAUDE_PLUGIN_ROOT}/shared/coordination-protocol.md`; read it first. This file applies it to -issue trackers: a tracker owns the **work-state concern** — what work exists, what is ready, -and what state each item is in — and the per-tracker map below gives the concrete values -`harness-setup` inlines into the generated orchestrator. Detection of which tracker is present -is a separate concern: see `${CLAUDE_PLUGIN_ROOT}/shared/detection-signatures.md`. - -## The tracker coordination model - -Unlike an SDD system, a tracker does not own a phase of the workflow — it owns a concern that -**brackets** the workflow. The orchestrator touches it at two points: - -1. **Phase 0 (intake & triage) — pull or create.** Once triage routes a request in as in-domain - work: if a matching ready item exists (`{READY_QUERY}`), claim it and carry its ID through - the run; if the work is new, create the issue (`{CREATE_CMD}`) so the tracker owns the work - state from the start. For a human-gated tracker (a SaaS UI with no configured CLI/MCP - access), emit the contextual prompt and **pause** per the protocol. -2. **Integrate / finish — write status back.** When the deliverable is written, update the - issue (`{STATUS_WRITEBACK}`) — close it or transition its state, referencing the - deliverable's path. Never delete issues and never rewrite human-authored issue prose — the - tracker owns intent and history, the harness owns execution. - -Between those two points the issue is **referenced, not copied**: agents carry the issue ID in -workspace artifact headers and read the issue in place. The orchestrator keeps no parallel -status file — work state has exactly one owner. - -## Per-tracker coordination map - -`harness-setup` looks up the detected tracker's row and inlines these concrete values into the -orchestrator. Commands are the curated baseline; confirm against the tracker's own docs if a -flag fails. - -| Tracker | Ready-work query | Create | Status write-back | Auto-invokable? | -|---|---|---|---|---| -| **Beads (`bd`)** | `bd ready --json` | `bd create "title"` | claim with `bd update {id} --claim`; close with `bd close {id} "summary"` | yes (CLI) | -| **Backlog.md** | `backlog task list` (CLI or its MCP server) | `backlog task create` | `backlog task edit` status transition | yes (CLI / MCP) | -| **git-issues** | `issues next` | author a new `.issues/` entry per its conventions | `issues claim {id}` → `issues done {id}` | yes (CLI) | -| **Beans** | `beans list` or a GraphQL query | `beans create` | `beans update` / `beans archive` | yes (CLI) | -| **git-bug** | `git bug ls` | `git bug add` | update state / comment via the `git bug` CLI | yes (CLI) | -| **GitHub Issues** | `gh issue list --json number,title,state,labels` | `gh issue create` | `gh issue close` / `gh issue comment` | yes (`gh`, authenticated) | -| **Linear** | its official MCP server (mcp.linear.app) | MCP create-issue tool | MCP update/comment tools | yes when the MCP server is configured; otherwise human-gated | -| **Jira** | the Atlassian MCP server (mcp.atlassian.com) | MCP create tool | MCP transition/comment tools | yes when the MCP server is configured; otherwise human-gated | - -For Linear and Jira without a configured MCP server, every touch is human-gated: emit the -contextual prompt (what to file or update, with the values to enter), pause, and resume on the -user's confirmation. Do not scrape or guess at SaaS state. - -### Taskmaster boundary — one owner for work state - -Taskmaster (`.taskmaster/`) tracks **spec-derived task state**, not general issue intake; it -belongs to the spec process (see `${CLAUDE_PLUGIN_ROOT}/shared/sdd-coordination.md`). When -Taskmaster co-exists with a general tracker, keep one owner per item: work decomposed from a -spec routes its status through `.taskmaster/tasks/tasks.json`; bugs and general work intake -route through the tracker. Never mirror the same item's state in both. - -## How `harness-setup` uses this - -1. After detecting the present tracker (Step 0), look up its row above and capture the - **coordination context**: `{tracker, version, entry point, ready-work query, create - convention, status write-back, auto-invokable}`. -2. With the user, settle which phases touch the tracker (phase 0 pull/create, integrate - write-back) and whether access is auto-invokable or human-gated (Step 2). Fold the decision - into the change manifest. -3. Splice the **Tracker coordination addenda** 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 commands; do not leave it pointing at this file. -4. Record the relationship in the `CLAUDE.md` pointer's **Issue tracking** line — see - `${CLAUDE_PLUGIN_ROOT}/shared/claude-md-pointer.md`. diff --git a/agentic-harness/shared/tracker-sync-protocol.md b/agentic-harness/shared/tracker-sync-protocol.md deleted file mode 100644 index 4b36d2b..0000000 --- a/agentic-harness/shared/tracker-sync-protocol.md +++ /dev/null @@ -1,235 +0,0 @@ -# Tracker sync protocol - -When a project runs **two** trackers — a repo-native tracker the agents work (Beads, -Backlog.md, git-bug, …) and a human-oriented SaaS tracker people watch (Jira, Linear, GitHub -Issues) — the two drift apart unless something keeps them in sync. This file defines that -sync: the lanes and their boundaries, the state store, identity and idempotency, concurrency, -conflict and failure policies, and the per-SaaS map. It is an instance-level companion to -`${CLAUDE_PLUGIN_ROOT}/shared/tracker-coordination.md`, under the generic protocol in -`${CLAUDE_PLUGIN_ROOT}/shared/coordination-protocol.md`. - -`harness-setup` reads this file at **generation time** and inlines the relevant values into -the generated sync skill, agent, and sync config — the templates are in -`skills/harness-setup/references/tracker-sync-template.md`. The generated artifacts never -read this file at runtime. - -## Source of truth and the three lanes - -The repo-native tracker is the **source of truth** for every synced field; the SaaS tracker -is a projection humans watch. One direction of authority is what makes the sync tractable — -two writable masters need merge machinery (vector clocks, last-write-wins heuristics) that -silently loses someone's edit sooner or later. Three lanes, strictly bounded: - -1. **Push (continuous, one-way).** Repo-tracker changes to synced fields propagate to the - SaaS. Remote edits to title or labels are overwritten on the next push, with the - overwritten value logged in `conflicts.md` — never discarded silently. -2. **Intake (one-time import).** Issues humans create in the SaaS — within the configured - **intake filter** — are imported once into the repo-native tracker, marked - `origin: remote`, and are from then on repo-owned like any other issue. Intake is not a - second sync direction: after the import, the item follows the push and proposal rules. -3. **State proposals (the one controlled exception to source-of-truth-wins).** A remote - change to an issue's *state* — a PM closes it in Jira as won't-do, blocks it, reopens it — - is a deliberate human decision the sync must not fight. The sync (a) records it in - `.tracker-sync/proposals.md` with both states and their sources, (b) **suspends state push - for that item** until the proposal is resolved (title and label push continue), and - (c) surfaces it in the run report. Adoption into the repo tracker happens only on - user/orchestrator confirmation — at which point the proposal is marked resolved and state - push resumes. This is a proposal lane, not field-level two-way merge. - -**Full two-way merge is deliberately out** and recommended against: every field-level merge -policy either overwrites a human edit or overwrites an agent edit, and the failure is silent -by construction. If a future release revisits it, it revisits it against this protocol — the -lanes above are the supported model. - -## Synced fields and the canonical state machine - -| Field | Direction | Notes | -|---|---|---| -| title | push (remote edits overwritten + logged) | normalized for fingerprinting, below | -| description | **push-only** | excluded from the remote fingerprint entirely | -| state | push, with the proposal lane as the exception | via the canonical machine below | -| labels | push (namespaced; remote edits overwritten + logged) | sorted + case-folded for fingerprinting | -| commit / PR links | **push-only** | excluded from the remote fingerprint | -| priority, assignee | optional, **off by default** | enable explicitly at setup | - -**Not synced (non-goals):** comments, attachments, worklogs, sprints/boards/epics, custom -fields, SaaS-side automation. The sync projects work state; it does not replicate a tracker. - -**Canonical state machine:** `ready → in_progress → blocked → done → closed`. Each SaaS maps -to it through its state table (per-SaaS map, below). A remote state with **no canonical -mapping** is a no-op for that item plus a log entry — never guess a mapping at runtime. - -## The sync state store — `.tracker-sync/` - -Sync state lives at the **repo root**, not under `.claude/` — it is data, not harness -config; it is tracker-agnostic and survives a tracker migration. - -``` -.tracker-sync/ - map.jsonl # one JSON record per issue pair — the authoritative ID map (git-tracked) - cursor.json # intake watermark ONLY (git-tracked) - conflicts.md # overwritten-value log, append-only (git-tracked) - proposals.md # open + resolved state proposals (git-tracked) - reports/ # machine-local drift/run reports — GITIGNORED -``` - -Generation adds `.tracker-sync/reports/` to the project's `.gitignore`. **No secrets ever -live under `.tracker-sync/`** (see Credential posture). - -**`map.jsonl` record** — one line per pair, updated in place: - -```json -{"local_id": "bd-123", "remote_id": "PROJ-456", "remote_url": "https://…", - "origin": "local|remote", "fp_local": "…", "fp_remote": "…", - "last_synced_at": "2026-06-12T09:00:00Z", "state": "active|orphaned-remote|orphaned-local"} -``` - -- **Canonical ordering:** records sorted by `local_id`, one line per record, fixed key order - as above. This keeps git merges line-stable when two branches touch different items. -- **`cursor.json` is the intake watermark only** — the last SaaS created/updated timestamp - scanned, per remote. Push idempotency comes entirely from per-item fingerprints, so a lost - or merge-conflicted cursor degrades to a **full intake re-scan** deduped against - `map.jsonl` and the SaaS markers — an efficiency loss, never corruption. On an - unresolvable merge conflict in `cursor.json`, delete it and re-scan. -- **`conflicts.md` / `proposals.md`** are append-mostly markdown. Each proposal carries a - status line (`open` / `adopted` / `declined`) edited in place when it is resolved. - -## Identity and idempotency - -### Fingerprints - -Per side, `fp = hash(canonical tuple of the two-way-sensitive fields)`: title, canonical -state (mapped through the per-SaaS state table), sorted namespaced labels. Normalization -before hashing: trim, collapse internal whitespace, case-fold labels, and map the remote -state to canonical *before* comparing. **Push-only fields — description, commit/PR links — -are excluded from the remote fingerprint entirely**: Jira returns descriptions as ADF rather -than the markdown that was pushed, and a naive whole-issue hash would flag a spurious change -on every run. "Changed since last sync" = current fp ≠ stored fp on that side. - -### SaaS markers — the pre-create idempotency check - -Each remote issue carries a namespaced marker — a label or remote link such as `repo:bd-123` -(per-SaaS convention below) — identifying its local counterpart. Before **creating** a -remote issue, the sync queries the SaaS by marker for that `local_id`; a hit means a -previous run created it but the map commit was lost — **re-link instead of re-create**. The -map stays primary; the marker is the recovery index *and* the duplicate-creation guard. - -### Intake ordering - -Import = create the local issue → append the map record → push the marker to the remote, in -that order. A re-run skips any `remote_id` already present in `map.jsonl` regardless of -marker state, so a failed marker write cannot cause a duplicate import. Imported issues are -marked `origin: remote` in the map and get a back-reference to the remote URL in the local -issue body. - -## Concurrency policy - -Sync **write** runs execute only from the **designated sync branch** — default: the -integration branch, normally `main` — recorded in the generated sync config. Write-run -preflight requires: on the sync branch, `.tracker-sync/` clean, branch up to date with its -remote. After a run, `.tracker-sync/` changes are committed (`chore(tracker-sync): …`) and -pushed with **one rebase-retry**; if the push still fails, stop and report — never force. -Read-only runs (the scheduled drift report) have no branch requirement. - -There is no cross-machine lock. Designated-branch + clean-preflight + the marker pre-create -check together bound the race to "two simultaneous in-session write runs on the same -branch", which the preflight makes loud rather than silent. - -## Conflicts, proposals, orphans - -- **Conflict** (title / labels) = both fingerprints changed since `last_synced_at`. Policy: - **source-of-truth-wins**, with both values appended to `conflicts.md` with their sources — - never discarded. Alternatives (latest-timestamp-wins, a manual merge queue) are documented - here only and not implemented: both reintroduce the silent-loss problem the one-way - authority avoids. -- **State divergence is not a conflict** — it is a proposal (lane 3 above). Lifecycle: - `open` (state push suspended for the item) → `adopted` (the repo tracker takes the remote - state; push resumes) or `declined` (the repo state stands; the next push restores it - remotely; push resumes). -- **Orphans:** `orphaned-remote` (a human deleted or archived the SaaS issue) and - `orphaned-local` (the local issue vanished) are **terminal map states pending a user - decision**. The sync never auto-recreates in either direction — a delete is a human - decision, like a state change. - -## Failure semantics - -- A remote state with **no canonical mapping** → no-op for that item + log entry. Never - guess. -- A **failed transition** (Jira screens can require fields the sync does not carry) → - conflict-log entry + skip the item this run. No retry loop; the run report names the item - and the reason. -- **Description push** converts repo markdown into whatever the role's tool accepts (the - official MCPs accept markdown; `gh` is native markdown). Conversion fidelity is - logged-not-blocking: a degraded description never fails the item. -- **Per-item failures:** retry once, then skip and report. The cursor and fingerprints - advance only for items that completed, so re-runs are idempotent and pick up the skipped - tail. - -## Rate limits - -Per-SaaS notes are in the map below. The skill rule is uniform regardless of SaaS: cap the -items processed per run (default 50, recorded in the sync config); on a 429 or -limit-exceeded response, **stop the phase**, record the position in the run report, and let -the next run resume from the map and cursor — never busy-retry against a limiter. - -## Credential posture - -SaaS access in every generated artifact goes through the **`human-tracker` role** in the -orchestrator's `tools.md` registry — never a hard tool name. Auth lives where the tool keeps -it (an MCP OAuth session, `gh auth`, an environment variable); **nothing under -`.tracker-sync/` or the sync config ever holds a token**. Scheduled headless runs are -read+report-only by design, which makes headless auth structural rather than operational: -when even read auth is absent, the preflight degrades to "report: human-tracker role -unavailable" and exits cleanly — a visible signal in `harness-review`'s stale-reports check, -not a silent failure. - -## Per-SaaS map — Jira, Linear, GitHub Issues - -The access path for each SaaS is its row in the per-tracker coordination map in -`${CLAUDE_PLUGIN_ROOT}/shared/tracker-coordination.md`; this map adds what the *sync* -needs. Values are a curated baseline — confirm against the tracker's own docs when a call -fails, and note that label character rules differ per SaaS (Jira labels cannot contain -spaces; adjust the marker spelling to what the instance accepts). - -| | **GitHub Issues** | **Linear** | **Jira** | -|---|---|---|---| -| Access role | `human-tracker` → `gh` (authenticated) | `human-tracker` → official MCP (mcp.linear.app) | `human-tracker` → Atlassian MCP (mcp.atlassian.com) | -| Marker convention | label `repo:{local_id}` | label `repo:{local_id}` | label `repo-{local_id}` (no spaces; fall back to a remote link titled `repo:{local_id}` if labels are restricted) | -| Intake-filter shape | a label (repo identity already scopes the rest) | team and/or label | a JQL fragment — typically project + label | -| Rate-limit notes | secondary (content-creation) limits on rapid writes | complexity-based GraphQL budgets | Jira Cloud per-account API budgets | - -### State-table starters - -**GitHub Issues** — trivially two-state; the rest is carried by labels: - -| Canonical | GitHub | -|---|---| -| ready | open | -| in_progress | open + label `in-progress` | -| blocked | open + label `blocked` | -| done | closed (reason: completed) | -| closed | closed (reason: not planned) | - -**Linear** — the default workflow is near-1:1 with the canonical machine: - -| Canonical | Linear | -|---|---| -| ready | Todo | -| in_progress | In Progress | -| blocked | Todo + label `blocked` (or the team's Blocked state, if one exists) | -| done | Done | -| closed | Canceled | - -**Jira** — **elicited per project**: Jira workflows are per-instance, so a starter table -would mis-map most of them. At setup time, when the `human-tracker` role resolves, read the -project's live statuses and transitions via the Atlassian MCP and propose the -canonical→Jira mapping; otherwise interview the user. **Either way the user confirms the -table** before it is inlined into the generated sync config. A typical confirmed shape: - -| Canonical | Jira (typical — confirm per project) | -|---|---| -| ready | To Do | -| in_progress | In Progress | -| blocked | Blocked (or In Progress + flag, where no Blocked status exists) | -| done | Done | -| closed | Done with resolution Won't Do (or the project's closing status) | diff --git a/agentic-harness/skills/harness-review/SKILL.md b/agentic-harness/skills/harness-review/SKILL.md deleted file mode 100644 index 705e711..0000000 --- a/agentic-harness/skills/harness-review/SKILL.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -name: harness-review -description: "Assess an existing agentic harness — read-only. Use to review, audit, or assess a harness, to judge how well its skills and agents are actually used, to check drift between the files and the CLAUDE.md record, or to validate that skills trigger and agents wire up. It produces a prioritized review context that hands off to harness-setup, and writes nothing. To build or change a harness, use harness-setup. Not for reviewing ordinary code or a pull request (that is code review)." -model: inherit -disallowed-tools: Write, Edit, NotebookEdit ---- - -# Harness review — assess an existing harness (read-only) - -This skill diagnoses an existing agentic harness and produces a *review context*: a -prioritized account of what works well and what to improve. It is the **reader** half of the -plugin — it writes nothing. The fixes it identifies are carried out by `harness-setup`. - -The harness model it assesses against is in `${CLAUDE_PLUGIN_ROOT}/shared/harness-model.md` -(agent = who, skill = how, orchestrator = when/order). - -## This skill vs harness-setup - -`harness-review` reads and judges; `harness-setup` writes. A request to "review / assess / -audit a harness" or "how well is the harness used" is this skill. A request that creates or -changes anything is `harness-setup`. The output here is a review context that hands off to -`harness-setup` — this skill never applies a change itself. - -## The read-only contract - -Make no edits — not to `.claude/agents/`, not to `.claude/skills/`, not to `CLAUDE.md`, not -to project memory. Run nothing that mutates the project. When a fix is obvious, write it into -the review context as a recommendation for `harness-setup`; do not apply it. The value of a -reader is that its findings are trustworthy precisely because it changed nothing. - -This contract is also backed mechanically: the skill sets `disallowed-tools: Write, Edit, -NotebookEdit`, so those tools are removed from the pool while it runs. `Bash` stays available -for read-only inventory — the prose above still governs it; run nothing that mutates the project. - -## Step 1: Inventory the harness - -1. List `.claude/agents/` and `.claude/skills/`; identify the orchestrator skill. -2. For each agent, read its frontmatter and role; for each skill, read its name and - description. Note the declared execution mode. -3. Map which skills each agent uses and how the orchestrator wires them together. - -## Step 2: Read the record - -Read the harness section of `CLAUDE.md` — the goal, the entry-point directive (the hard gate -routing every prompt through the orchestrator), and the change-history table. The convention is -in `${CLAUDE_PLUGIN_ROOT}/shared/claude-md-pointer.md`. The history tells you how the harness has -evolved and where recent changes concentrated. - -## Step 3: Detect drift - -Compare three views of the harness: - -- the files in `.claude/agents/` and `.claude/skills/`, -- the orchestrator's stated composition, -- the `CLAUDE.md` pointer and change history. - -List every discrepancy: an agent or skill present in the files but absent from the record or -the orchestrator; something the record names that no longer exists; an orchestrator that -references a member it never forms. Do not reconcile drift — report it. Reconciliation is a -write, and belongs to `harness-setup`. - -**Tracker-sync drift** — when the harness includes a generated `tracker-sync` skill (a -`.tracker-sync/` store at the repo root; model in -`${CLAUDE_PLUGIN_ROOT}/shared/tracker-sync-protocol.md`), read its state read-only and judge -each signal against the sync config (the `mapping.md` under the generated skill): - -- **Cursor age vs the configured cadence** — a cursor far older than the cadence means the - sync is not running. -- **Unresolved conflict count** in `conflicts.md` — a growing log nobody reads is drift in - the projection. -- **Open-proposal backlog age** in `proposals.md` — an old `open` proposal means a human - state decision is waiting for adoption while state push stays suspended for that item. -- **Orphan counts** (`orphaned-remote` / `orphaned-local` in `map.jsonl`) — terminal states - pending a user decision that nobody has made. -- **A stale `reports/` directory** — a schedule is registered but not producing reports - (or producing only "role unavailable" reports, which points at headless auth). - -Each is a finding for `harness-setup` — including "the sync exists but shows no sign of -running at all". - -## Step 4: Assess effective usage - -Drift tells you what *exists*; usage tells you what is *used*. Judge effective usage from a -fixed, deterministic signal set — read each, infer nothing you cannot ground in one: - -- **Project auto-memory** at `~/.claude/projects//memory/` — what the project - has recorded about how work actually happens. -- **The `CLAUDE.md` pointer and change history** — whether the entry-point directive is present - and current (a soft "use the skill for X" trigger instead of the hard gate is itself a finding), - and what has been changing. -- **The `.claude/` inventory** — what the harness offers. -- **The tools registry**, if present (a `tools.md` in the orchestrator's `references/` - directory) — which roles are filled by which tools, and their alternatives. - -From these, classify each skill and agent as **used**, **unused**, **bypassed** (the work -happens but around the harness), or **drifted** (present but out of sync). When the orchestrator -itself is bypassed — work in its domain happening without it — treat the entry-point directive as -the first suspect: flag it for `harness-setup` to strengthen (hard gate in `CLAUDE.md`, plus an -entry-point description), not just the skill's keywords. Apply the same lens -to registered tools: is each one still used, and is there now a better alternative for its -role? Flag tools that look unnecessary or superseded — as findings for `harness-setup`, not -changes you make. If there is no tools registry at all, treat that as a finding too — -recommend that `harness-setup` offer tool research — since a harness with no considered -tooling is more often an oversight than a decision. The method for reading each signal and -making the call is in `references/usage-assessment.md`. This step is strictly read-only. - -## Step 5: Validate - -- **Structural.** Agents are files in the right place (including built-in types); skill - frontmatter has `name` and `description`; cross-references between agents are consistent; - no `commands/` directory was generated. -- **Triggering.** For each skill description, write should-trigger and should-NOT-trigger - queries — the should-NOT set built from near-misses, including ones that belong to a - *different* skill. Confirm the descriptions separate cleanly and don't collide. The method - is in `references/skill-testing-guide.md`. -- **Effectiveness.** Where feasible, compare the deliverable with the skill against the same - task without it, to confirm the skill adds value. Also in `references/skill-testing-guide.md`. -- **Dry-run.** Walk the orchestrator: is the phase order logical, do data-passing paths have - no dead links, does each phase's input match the previous phase's output, is each error - fallback executable? Check the declared execution mode against - `${CLAUDE_PLUGIN_ROOT}/shared/execution-modes.md` — in particular, that a team-mode - harness has the subagent fallback it needs. -- **QA agent, if present.** Check it against the QA methodology — does it compare across - boundaries rather than only confirm existence, and run incrementally rather than once at - the end? See `references/qa-agent-guide.md`. - -## Step 6: Emit the review context - -Produce a prioritized review context — the deliverable of this skill — and hand it to -`harness-setup`: - -````markdown -## Harness review: {domain} — {date} - -### Works well (keep) -- {finding} — {brief evidence} - -### To improve (act on) -| Priority | Finding | Target | Why | -|----------|---------|--------|-----| -| high | {what's wrong} | {agent / skill / orchestrator / CLAUDE.md} | {evidence and impact} | -| medium | ... | ... | ... | - -### Drift -- {discrepancy between files, orchestrator, and record} - -### Suggested next step -Hand this context to `harness-setup` to act on the "to improve" items in priority order. -```` - -Order the "to improve" items by impact, name a concrete target for each (so `harness-setup` -knows where the fix lands), and ground each in evidence from the steps above — not in -speculation. Keep "works well" honest: it tells `harness-setup` what not to touch. - -## References - -- `references/usage-assessment.md` — the deterministic signal set and how to read each to - classify a skill or agent as used, unused, bypassed, or drifted. -- `references/skill-testing-guide.md` — trigger validation (should / should-not), with-skill - vs baseline effectiveness checks, and the iterative-improvement method. -- `references/qa-agent-guide.md` — what a good QA agent does (cross-boundary comparison, - boundary-bug patterns, incremental QA), for assessing a harness that includes one. -- `${CLAUDE_PLUGIN_ROOT}/shared/harness-model.md`, - `${CLAUDE_PLUGIN_ROOT}/shared/claude-md-pointer.md`, - `${CLAUDE_PLUGIN_ROOT}/shared/execution-modes.md` — shared concepts. diff --git a/agentic-harness/skills/harness-review/references/qa-agent-guide.md b/agentic-harness/skills/harness-review/references/qa-agent-guide.md deleted file mode 100644 index 123436f..0000000 --- a/agentic-harness/skills/harness-review/references/qa-agent-guide.md +++ /dev/null @@ -1,137 +0,0 @@ -# QA agent guide - -What a good QA agent does, so you can assess one in an existing harness or specify one for -`harness-setup` to build. The method is drawn from common boundary-bug patterns — recurring -failure modes that surface where two correctly-built components meet. - -## Table of contents - -1. [The bugs QA agents miss](#1-the-bugs-qa-agents-miss) -2. [Why static checks don't catch them](#2-why-static-checks-dont-catch-them) -3. [Cross-boundary verification](#3-cross-boundary-verification) -4. [Design principles](#4-design-principles) -5. [Integration-consistency checklist](#5-integration-consistency-checklist) -6. [QA agent definition template](#6-qa-agent-definition-template) - ---- - -## 1. The bugs QA agents miss - -The most common defect is a **boundary mismatch**: two components are each correct on their -own, but the contract between them is broken at the seam. Each passes its own review; nobody -compares the two sides. Recurring forms: - -| Boundary | Mismatch | Why it's missed | -|----------|----------|-----------------| -| response → consumer type | the producer returns `{ items: [...] }`; the consumer expects a bare array | each is fine alone; no one compares the shapes | -| field name across layers | one layer uses camelCase, another snake_case for the same field | a generic cast hides it from the compiler | -| route path → link target | a page lives under one path prefix; a link points at another | file layout and link values aren't cross-checked | -| state map → update sites | the transition map allows a move the code never performs (or vice versa) | only the map's existence is confirmed, not every update site | -| endpoint → caller | an endpoint exists but nothing calls it (or a caller hits a missing one) | the endpoint list and caller list aren't mapped 1:1 | -| immediate vs async result | the immediate response lacks a field the consumer reads off it | only the type is checked, not sync vs async timing | - -## 2. Why static checks don't catch them - -- **Generic casts defeat the type checker.** A typed fetch annotated to return one shape will - compile even when the runtime value has another — the annotation is a claim, not a check. -- **A passing build is not correct behavior.** With casts, `any`, or generics in play, the - build succeeds and the code still fails at runtime. -- **Existence is not connection.** "Does the endpoint exist?" and "does its response match - what the caller expects?" are different questions; only the second catches boundary bugs. - -## 3. Cross-boundary verification - -The core technique: compare the two sides of a contract directly, never one in isolation. - -- **Response shape ↔ consumer type.** Extract the shape the producer actually returns and the - type the consumer expects, and compare — including any wrapper (does the producer return - `{ data: [...] }` while the consumer reads a bare array?), and field-name casing across - layers, and the difference between an immediate acknowledgement and the eventual result. -- **Route path ↔ link target.** Derive each page's real path from the file layout and compare - it against every link, redirect, and navigation target in the code; account for path - prefixes and dynamic segments. -- **State map ↔ update sites.** List the transitions the map allows, then find every place the - code changes state; flag transitions the code performs that the map forbids, and transitions - the map allows that the code never performs. -- **Endpoint ↔ caller.** List every endpoint and every call site and pair them; an endpoint no - one calls is either dead or a missing wire-up — decide which. - -## 4. Design principles - -- **Use the `general-purpose` type, not `Explore`.** Effective QA greps for patterns, runs - comparison scripts, and sometimes fixes — `Explore` is read-only and can't. Give the agent a - "verify → report → request fix" protocol instead of read-only tooling. -- **Prefer cross-boundary comparison over existence checks.** "Does the response shape match - the consumer's type?" beats "does the endpoint exist?"; "does every update obey the state - map?" beats "is the map defined?". -- **Read both sides at once.** To catch a seam bug, open the producer and the consumer - together — the route and its caller, the state map and the update code, the file layout and - the links. State this explicitly in the agent definition. -- **Run incrementally, not just at the end.** QA placed only after everything is built lets - early mismatches propagate and raises the cost of every fix. Verify each module's boundaries - as it lands. - -## 5. Integration-consistency checklist - -A template to fold into a QA agent for a typical web application: - -```markdown -### Integration consistency - -#### Response ↔ consumer -- [ ] Every response shape matches the consumer's expected type -- [ ] Wrapped responses ({ items: [...] }) are unwrapped on the consumer side -- [ ] camelCase/snake_case is consistent across layers -- [ ] Immediate acknowledgements and eventual results are distinguished on the consumer -- [ ] Every endpoint has a caller, and every caller hits a real endpoint - -#### Routing -- [ ] Every link / redirect / navigation target resolves to a real page path -- [ ] Path prefixes and route groups are accounted for -- [ ] Dynamic segments are filled with the right parameters - -#### State machine -- [ ] Every transition the code performs is allowed by the map (no unauthorized moves) -- [ ] Every transition the map allows is reachable in the code (no dead transitions) -- [ ] Intermediate-to-final transitions are present, not missing -- [ ] State-based branches on the consumer are actually reachable - -#### Data flow -- [ ] Field names match from storage through response to consumer type -- [ ] Optional-field null/undefined handling is consistent on both sides -``` - -## 6. QA agent definition template - -```markdown ---- -name: qa-inspector -description: "QA verification specialist. Checks spec compliance, integration consistency, and design quality across module boundaries." -model: inherit ---- - -# QA inspector - -## Core role -Verify implementation quality against the spec, and **integration consistency between -modules** — boundary mismatch is the leading cause of runtime failure. - -## Verification priority -1. Integration consistency (highest) -2. Functional spec compliance -3. Design quality -4. Code quality (dead code, naming) - -## Method: read both sides at once -| Target | Producer side | Consumer side | -|--------|---------------|---------------| -| response shape | where the response is built | where it is consumed and typed | -| routing | page path from the file layout | link / redirect / navigation target | -| state | the transition map | the state-update sites | -| data | storage field names | response field → consumer type | - -## Team communication protocol -- On a finding, send a specific fix request (location + fix) to the responsible agent. -- For a boundary issue, notify **both** sides. -- To the leader: a report separating passed / failed / unverified. -``` diff --git a/agentic-harness/skills/harness-review/references/skill-testing-guide.md b/agentic-harness/skills/harness-review/references/skill-testing-guide.md deleted file mode 100644 index 96bb6d0..0000000 --- a/agentic-harness/skills/harness-review/references/skill-testing-guide.md +++ /dev/null @@ -1,106 +0,0 @@ -# Skill testing guide - -How to test whether a harness's skills trigger correctly and add value, and how to improve -them. Supplements the validation step. - -## Table of contents - -1. [Two kinds of evaluation](#1-two-kinds-of-evaluation) -2. [Writing test prompts](#2-writing-test-prompts) -3. [With-skill vs baseline](#3-with-skill-vs-baseline) -4. [Assertion-based scoring](#4-assertion-based-scoring) -5. [Trigger validation](#5-trigger-validation) -6. [The improvement loop](#6-the-improvement-loop) - ---- - -## 1. Two kinds of evaluation - -Skill quality is judged two ways, and most skills need both: - -| Kind | How | Fits | -|------|-----|------| -| Qualitative | the user reads the deliverable | subjective quality — prose, design, judgment calls | -| Quantitative | assertion-based scoring | objectively checkable results — a file created, data extracted, code generated | - -The loop is the same either way: **write a test → run it → evaluate → improve → re-run**. - -## 2. Writing test prompts - -A test prompt should read like a real request a real user would type — specific and natural. -Abstract prompts ("process the data", "generate a chart") have little test value. - -A good prompt carries concrete detail: - -```text -In the quarterly sales sheet in my downloads folder, add a margin column from the revenue and -cost columns, then sort by margin descending. -``` - -Vary the prompts so the set covers more than the happy path: - -- Mix formal and casual phrasing. -- Mix explicit intent (states the file type) with implicit (must be inferred from context). -- Mix simple and multi-step tasks. -- Start with two or three: one core case, one edge case, optionally one composite. - -## 3. With-skill vs baseline - -To confirm a skill actually adds value, run the same prompt twice in parallel — once with the -skill, once without — and compare: - -- **With-skill:** the agent reads the skill and does the work. -- **Baseline:** the same prompt, no skill. When improving an *existing* skill, the baseline is - the previous version (keep a snapshot), not an empty run. - -Keep each run's outputs in their own directory so iterations don't overwrite each other. If -you capture timing or token counts, save them from the completion notification immediately — -that data is available only at that moment and cannot be recovered later. - -## 4. Assertion-based scoring - -When the deliverable is objectively checkable, write assertions. A good assertion can be -judged true or false, has a descriptive name, and tests the skill's core value. A bad one is -subjective ("it reads well") or passes regardless of the skill ("output exists"). - -Watch for **non-discriminating** assertions — ones that pass in both the with-skill and the -baseline run. They measure nothing about the skill; drop them or replace them with a harder -one. Where an assertion can be checked by code, script it: faster, repeatable, and reusable -across iterations. Record results with the field names `text`, `passed`, `evidence` (the same -schema the setup-side skill-writing guide defines). - -## 5. Trigger validation - -A skill's description is its only trigger. Validate it with two query sets: - -- **Should-trigger (8–10):** the same need phrased many ways — formal and casual, explicit and - implicit, including cases where this skill should win over a competing one. -- **Should-NOT-trigger (8–10):** **near-misses are the point.** A query with overlapping - keywords but where a *different* tool is the right fit tests the boundary; an obviously - unrelated query ("write a Fibonacci function") tests nothing. Build the should-NOT set from - queries that belong to adjacent skills — especially, for this plugin's own two skills, a - "review my harness" that must not fire `harness-setup` and an "extend my harness" that must - not fire `harness-review`. Include near-misses from *external* neighbours too: "recommend - Claude Code automations for this repo" (belongs to `claude-code-setup`), "write a skill or - plugin for X" (`plugin-dev` / `skill-creator`), and "review this PR / this code" (code - review) — none of these should fire either harness skill. - -Then check for collisions: confirm the should-trigger queries don't wrongly fire a *different* -existing skill. Where two descriptions overlap, sharpen the boundary wording in both. - -## 6. The improvement loop - -When a test surfaces a problem: - -1. **Generalize the fix.** Repair the principle, not the one example that failed — a narrow - patch that fits only the test case is overfitting. -2. **Cut what doesn't earn its place.** If the transcript shows the skill making the agent do - unproductive work, remove that part. -3. **Explain the why.** Even terse feedback has a reason behind it; fold the reason into the - skill so it generalizes. -4. **Bundle repetition.** If every run writes the same helper, pre-bundle it under `scripts/`. - -Re-run all cases in a fresh iteration directory, show the user the result against the previous -one, and repeat. Stop when the user is satisfied, when feedback comes back empty, or when -there is no more meaningful improvement to make. Draft, then re-read with fresh eyes — don't -expect the first pass to be the final one. diff --git a/agentic-harness/skills/harness-review/references/usage-assessment.md b/agentic-harness/skills/harness-review/references/usage-assessment.md deleted file mode 100644 index d69738f..0000000 --- a/agentic-harness/skills/harness-review/references/usage-assessment.md +++ /dev/null @@ -1,81 +0,0 @@ -# Usage assessment - -How to judge whether a harness is actually *used*, not just whether it *exists*. This reads a -fixed, deterministic signal set and classifies each skill, agent, and tool. It changes -nothing — every output is a finding for `harness-setup`, never an edit. - -## Why a fixed signal set - -Usage is inferred, not measured directly — there is no usage counter. So ground every -judgment in a concrete signal rather than a guess. Four signals, all read-only. Read each, -state what it shows, and make the call only from evidence one of them supports. When the -signals are thin, say so and lower your confidence rather than inventing certainty. - -## Signal 1: project auto-memory - -Location: `~/.claude/projects//memory/`. The `` is the project's -absolute path with the separators turned into dashes — e.g. a project at -`/Users/me/work/app` becomes a directory like `-Users-me-work-app`. Find the one whose slug -matches the project you are reviewing. - -Read `MEMORY.md` (the index) and the memory files it points to. This is where the project has -recorded how work actually happens. What to look for: - -- Does the memory mention the orchestrator skill, the agents, or the harness at all? Silence - is itself a signal — a harness the project never records using is likely unused. -- Does it describe work being done **by hand** in the harness's domain? That points to the - orchestrator being bypassed. -- Does it record friction ("the agent kept doing X")? That points to a quality or trigger - problem to flag. - -## Signal 2: the CLAUDE.md pointer and change history - -Read the harness section of `CLAUDE.md`. The pointer's entry-point directive is the hard gate -routing every prompt to the orchestrator; compare what *should* route against how the project -actually describes its work (Signal 1) — a directive softer than a hard gate, or work that -happens around it, is itself a finding. The change-history table tells you the evolution: - -- A pointer that names an orchestrator the files no longer contain → drift. -- A long history that stops abruptly → the harness may have been abandoned. -- History concentrated on one agent or skill → that area has been unstable; worth a look. - -## Signal 3: the `.claude/` inventory - -List `.claude/agents/` and `.claude/skills/`, and read the orchestrator's composition. This -is the ground truth of what the harness offers. Cross-check it against the other signals: -something in the inventory that no signal ever mentions is a candidate for "unused"; something -the memory or pointer references that is missing from the inventory is drift. - -## Signal 4: the tools registry - -If the orchestrator has a `tools.md` registry (from the tool-discovery step), read it: the -roles, the preferred tool and alternative per role, and the `Last reviewed` dates. What to -look for: - -- A registered tool no agent or skill references by role → unused. -- A `Last reviewed` date that is far in the past → due for re-evaluation. -- A role whose preferred tool the project's memory shows failing, so the alternative is what - runs in practice → flag the preferred tool as a candidate to swap. - -## Classifying from the signals - -Combine the signals and label each skill, agent, and tool: - -| Class | What the signals show | -|-------|------------------------| -| **Used** | the inventory has it, and memory or history shows it being invoked or changed | -| **Unused** | it exists in the inventory, but no other signal ever references it | -| **Bypassed** | the work in its domain happens (memory shows it), but around the harness rather than through the orchestrator | -| **Drifted** | the pointer, history, or orchestrator names it, but the files disagree (missing, moved, or out of sync) | - -A label is only as good as its evidence. For each, name the signal that supports it. "Unused -— not referenced in memory, history, or the orchestrator" is a finding; "probably unused" with -nothing behind it is not. - -## Staying read-only - -This assessment writes nothing — not the files, not `CLAUDE.md`, not memory. When the right -fix is obvious (retire an unused agent, swap a superseded tool, widen a trigger that memory -shows missing), record it as a prioritized recommendation in the review context and hand it to -`harness-setup`. The separation is the point: a reader that never writes can be trusted, and -its findings stay clean for the writer to act on. diff --git a/agentic-harness/skills/harness-setup/SKILL.md b/agentic-harness/skills/harness-setup/SKILL.md deleted file mode 100644 index 7d9144f..0000000 --- a/agentic-harness/skills/harness-setup/SKILL.md +++ /dev/null @@ -1,389 +0,0 @@ ---- -name: harness-setup -description: "Build, extend, and maintain a project's agentic harness — the agents, skills, and orchestrator under .claude/. This skill writes files. Use it to set up, scaffold, extend, rebuild, or sync a harness, to add or change an agent or skill, or to apply a review context from harness-review; on request it also discovers and registers fitting MCP/plugin tools. When a project runs both a repo-native tracker and a human tracker (Jira, Linear, GitHub Issues), it also generates the dual-tracker sync — use it for 'keep the trackers in sync', 'sync issues to Jira/Linear', or 'tracker sync setup'. For read-only assessment of an existing harness, use harness-review — this skill is the writer, that one is the reader. Not for authoring a single standalone skill or plugin (use plugin-dev or skill-creator), or one-shot automation recommendations (use claude-code-setup). Not for choosing a project's spec-driven development system or issue tracker — use spec-advisor or tracker-advisor." -model: inherit ---- - -# Harness setup — build and maintain the agent team - -This skill builds and maintains a project-local **agentic harness**: a team of agent -definitions, the skills those agents use, an orchestrator that coordinates them, and a -pointer in the project's `CLAUDE.md`. It writes files. It does not do the project's domain -work — it builds the agents and skills that do. - -Read the model first: `${CLAUDE_PLUGIN_ROOT}/shared/harness-model.md` defines the three -parts (agent = who, skill = how, orchestrator = when/order) and why they stay separate. - -## This skill vs harness-review - -`harness-setup` is the **writer** — every change to the harness goes through it. `harness-review` -is the **reader** — it assesses an existing harness and writes nothing. When a request is -"assess / review / audit / how well is it used," that is `harness-review`. When a request -creates or changes anything, it is this skill. After `harness-review` hands off a *review -context*, this skill is what acts on it. - -## Step 0: Orient before writing - -Always check the current state first, then pick the path. Do not start generating until the -plan is confirmed. - -1. **Take the user's starting context, if any.** This skill accepts an optional context at - the start — domain notes, constraints, tools already in use, or a review context from - `harness-review`. Read it and fold it into everything below. -2. Read `.claude/agents/`, `.claude/skills/`, and the harness section of `CLAUDE.md`. -3. Branch on what you find: - - **New build** — no harness, or empty agent/skill dirs → run Steps 1–7 in full. - - **Extend** — a harness exists and the request adds or changes an agent or skill → run - only the needed steps, per the extension matrix in `references/maintenance.md`. - - **Apply a review context** — `harness-review` produced a prioritized list → work it as - an interactive improvement pass (see `references/maintenance.md`). - - **Sync** — the files and the `CLAUDE.md` record disagree → reconcile and record the - correction. -4. Present the plan and confirm it before generating. Tool research and tool maintenance are - part of a good harness, so make them part of the plan you present **every run** — don't - wait to be asked: - - **Always ask whether to run tool discovery** (Step 1b), on a new build or an extension. - - **On an existing harness** (extend / apply-review-context / sync), **also ask whether to - run a tool-maintenance review** of the registered `tools.md` (see - `references/maintenance.md`). - 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. **Account for the project's process layers.** A harness is the *who/how/when* of the work; a - project may also follow *process layers* — a spec process (what to build) and an issue - tracker (what work is ready and in what state). They are complementary to the harness, so - check each advisor area — scan with - `${CLAUDE_PLUGIN_ROOT}/shared/detection-signatures.md`: - - | Process area | Advisor skill | Coordination map | - |---|---|---| - | Spec process (SDD) | `spec-advisor` | `${CLAUDE_PLUGIN_ROOT}/shared/sdd-coordination.md` | - | Issue tracking | `tracker-advisor` | `${CLAUDE_PLUGIN_ROOT}/shared/tracker-coordination.md` | - - The same gate applies to every area: - - **No system, project looks like software** → offer to run the area's advisor skill, which - advises what fits and delegates setup to the chosen system's own installer. Offering is the - default; running is gated on a yes, and nothing is installed without the advisor's own - per-system approval. If the user installs one, fold its coordination into the plan below. - **If the advisor reports an installer failure, treat the area as having no system** — record - no coordination context; the advisor leaves the retry path with the user. - - **A system is present** (detected, or just installed) → do not re-recommend and do not - install. Identify the system and version, look up its row in the area's coordination map, - and record a **coordination context** — for SDD `{system, version, owned-segment, - activation, auto-invokable, hand-back contract, write-back rule}`; for a tracker - `{tracker, version, entry point, ready-work query, create convention, status write-back, - auto-invokable}` — to carry into Step 2 and Step 5. This is the lightweight read - `harness-setup` needs to bake the coordination into the orchestrator; the advisor skills - still own recommending and installing. The protocol behind every map is - `${CLAUDE_PLUGIN_ROOT}/shared/coordination-protocol.md`. - - - **Both an agentic tracker and a human tracker present or declared** (a repo-native - tracker like Beads plus Jira, Linear, or GitHub Issues — the human-tracker usage signals - are in `${CLAUDE_PLUGIN_ROOT}/shared/detection-signatures.md`) → also offer the - **dual-tracker sync sub-step**: generate the project's `tracker-sync` skill, agent, and - sync config per `${CLAUDE_PLUGIN_ROOT}/shared/tracker-sync-protocol.md`, using - `references/tracker-sync-template.md`. Offer it **only** on this dual-tracker condition — - never when one tracker or none is present. Before generating any sync artifact, run the - **sync preflight**: validate the recorded tracker coordination context by actually calling - both entry points — the ready-work query on the agentic side, `human-tracker` role - resolution plus a cheap ping on the SaaS side. A failed validation stops the sub-step and - corrects the context first; never generate against a stale context. - - Record the answer for each area either way. A future advisor adds a row to the table; the - gate itself does not change. - -## Step 1: Analyze the domain - -1. Identify the domain and the core task types (creation, validation, editing, analysis). -2. Explore the codebase — tech stack, data models, key modules — so agents and skills fit - the project rather than a generic template. -3. Check for conflicts or overlap with any existing agents and skills from Step 0. -4. Read the user's technical level from the conversation and match your wording to it. - Explain a term like "assertion" or "schema" when the cues suggest it is unfamiliar. - -## Step 1b: Discover tools — always offered, run on acceptance - -Step 0 always offers tool research as part of the plan; run this step when the user accepts. -It can also be triggered on its own later, against an existing harness. Offering is the -default; running is gated on that yes — and adopting any individual candidate is gated on a -separate, explicit per-tool yes (Step 3). Those two gates are the safeguard: the user is -always asked, and nothing is installed behind their back. - -This skill proposes nothing of its own — the candidates come from a live search, not a -built-in catalog: - -1. Hand a **search-optimized subagent** (`general-purpose`, with web search) a tight context - — the project's domain, stack, and task types from Step 1 — and have it find candidate - MCP servers and plugins that fit. Also inspect the local and session configuration for - tools already available, so you don't propose what is already there. -2. Present each candidate with the **role** it would fill, what it does, and its trade-off. - The user **accepts or rejects each one explicitly**. Adopt only what is accepted. -3. Accepted tools become install/register rows in the Step 2b manifest; once that is - approved, register them **by role** in the tools registry under the orchestrator — a - `tools.md` file in `.claude/skills/{domain}-orchestrator/references/`. It is a lookup of - role → preferred tool → alternative (for when the preferred one is unavailable) → status. - Agents and skills reference a tool by its **role**, never by a hard tool name, so the - harness falls back to the alternative when a tool is missing. - -The subagent's context template, the acceptance flow, and the registry schema are in -`references/tool-discovery.md`. Registered tools are reviewed periodically — see -`references/maintenance.md`. - -## Step 2: Choose the execution mode and the architecture pattern - -**Execution mode.** Default to an **agent team** when two or more agents genuinely need to -exchange information mid-task; fall back to **subagents** when they do not, or when the -experimental team tools are unavailable. The team-tools caveat and the mechanical fallback -mapping are in `${CLAUDE_PLUGIN_ROOT}/shared/execution-modes.md` — read it and decide the -mode before designing the team, because the mode shapes the agent definitions and the -orchestrator. - -**Architecture pattern.** Decompose the work into areas of expertise and pick a structure. -The six patterns — Pipeline, Fan-out/Fan-in, Expert Pool, Producer-Reviewer, Supervisor, -Hierarchical Delegation — with their fit and their team-mode suitability are in -`references/agent-design-patterns.md`. Composite patterns are common; the same reference -covers them. - -**Split agents** along four axes — expertise, parallelism, context, reusability. The -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 process layers.** If Step 0 recorded a coordination context, decide *with -the user* how the orchestrator and each present system compose — they must work together without -overlap and with minimal friction, not run in parallel. - -- **Spec process (SDD).** 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). -- **Issue tracker.** Using `${CLAUDE_PLUGIN_ROOT}/shared/tracker-coordination.md`, settle: which - phases touch the tracker (phase 0 pulls ready work or creates the issue; integrate writes status - back); whether access is **auto-invokable** (CLI / configured MCP) or **human-gated** (a SaaS UI - with no configured access); and the **one-status-owner rule** when Taskmaster or an SDD task - artifact co-exists with the tracker — each item's work state has exactly one owning system. - -Fold the decisions into the Step 2b manifest so they are 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 -tool — present a single explicit **change manifest** and get the user's formal approval. This -is mandatory on every path: new build, extend, apply-review-context, sync. Nothing is written -to `.claude/` or `CLAUDE.md`, and no tool is installed or removed, until the user approves it. - -This is not the Step 0 plan confirmation. Step 0 agrees the approach before the design exists; -the manifest is the concrete, itemized list of exactly what this run will touch, produced once -the design is settled. Writes and installs change the user's repository and environment and are -awkward to undo — one explicit sign-off on the exact list is what keeps the run from making a -change the user did not expect. - -Present it as concrete items, each labelled with its action and target: - -| Action | Target | -|--------|--------| -| create / update / remove | `.claude/agents/{name}.md` (one row per agent) | -| create / update / remove | `.claude/skills/{name}/` (one row per skill) | -| create / update | `.claude/skills/{domain}-orchestrator/` | -| update | `CLAUDE.md` (harness pointer + change-history row) | -| install / uninstall | `{role} -> {tool}` (only if tool discovery or maintenance proposed it) | -| register / unregister schedule | `{venue} — {cadence} — {mode}` (one row per scheduled run; **environment-level** — approving it changes the user's machine, not just the repo) | - -List only the rows that apply. If the user amends the list — drops an agent, declines a tool, -renames a skill — revise and present it again; the approval is of the final list. Once -approved, carry out exactly what was approved in Steps 3–6 — no extra files, no extra installs. - -## Step 3: Generate the agent definitions - -Write every agent as a file under `.claude/agents/{name}.md` — including agents that use a -built-in type (`general-purpose`, `Explore`, `Plan`). Put the built-in type in the spawn -call; put the role, principles, and protocol in the file. The reason is in the harness -model: a role defined only inline is not reusable next session and carries no collaboration -contract. - -Each agent file states: core role, working principles, input/output protocol, error -handling, and collaboration. In team mode, add a **team communication protocol** section — -who it messages, who messages it, and what it claims from the shared task list. The -definition template and worked agent files are in `references/agent-design-patterns.md` and -`references/team-examples.md`. - -**Model.** Default each agent to `model: inherit` so it follows the session's model. A -harness's quality tracks its agents' reasoning, so for a role that depends on judgment rather -than throughput, pin the strongest reasoning model explicitly — by its current dated id (e.g. -`claude-opus-4-8`), not a bare `opus` alias that ages. - -**If the team includes a QA agent.** Use the `general-purpose` type (`Explore` is read-only -and cannot run validation). Make its core method *cross-boundary comparison* — read both -sides of a contract together (the producer and the consumer), not each in isolation — and -run it incrementally as each module lands, not once at the end. The full methodology, -boundary-bug patterns, and a QA agent template are in the `qa-agent-guide` reference under -the `harness-review` skill. - -## Step 4: Create the skills - -Create each skill the agents use at `.claude/skills/{name}/SKILL.md`. The authoring guide — -description writing, body principles, progressive disclosure, data-schema standards — is in -`references/skill-writing-guide.md`. The essentials: - -- **Description.** It is the only trigger mechanism. Write it to be specific about what the - skill does and when it should fire, slightly pushy to offset conservative triggering, and - worded to stay clear of skills that should *not* fire on the same request. -- **Body.** Explain the *why* rather than issuing bare "ALWAYS/NEVER" rules — an agent that - understands the reason handles edge cases correctly. Keep it lean (aim under 500 lines; - move detail to `references/`). Generalize to the principle instead of overfitting to one - example. Write imperatively. -- **Progressive disclosure.** Metadata is always in context; the body loads on trigger; - `references/` load only when needed. Split large or domain-specific detail into - `references/` so only the relevant file loads. -- **Linking.** One agent uses one or more skills; a skill may be shared across agents. The - skill holds *how*; the agent holds *who*. - -## Step 5: Build the orchestrator and register the pointer - -The orchestrator is a skill whose subject is the team: which agents take part, what each -produces, how outputs flow, and how failures are handled. Templates for team, subagent, and -hybrid modes — with data-passing, error handling, and test scenarios — are in -`references/orchestrator-template.md`. - -Build into the orchestrator: - -- **An intake-and-triage first phase**, because the orchestrator is the repo's entry point and - runs for every prompt: it triages first — a trivial or out-of-domain request is answered - directly and stops there; in-domain work then goes through the context check (initial run vs. - follow-up vs. partial re-run, branching on whether `_agents_workspace/` already exists). This - triage is what makes the `CLAUDE.md` hard gate practical — it routes every prompt without - spinning up a team for trivia. -- **An entry-point description** that opens by stating the orchestrator is the entry point for - the domain (invoke before responding to any domain request), then carries **follow-up trigger - keywords** ("re-run", "update", "modify", "supplement", "improve the previous result", and - everyday domain phrasings). The description backs the `CLAUDE.md` directive; without the - follow-up keywords the harness goes unused after its first run. -- **Data-passing** stated explicitly, matched to the mode — see - `${CLAUDE_PLUGIN_ROOT}/shared/execution-modes.md`. -- **Error handling** that does not assume success: retry once, then proceed without the - missing result and note the omission; never delete conflicting data — record it with its - source. -- **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 an SDD 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`. -- **Tracker coordination**, when Step 0 recorded a tracker coordination context: splice the - addenda from `references/orchestrator-template.md` (Tracker coordination section) into the - orchestrator's phase 0 and integrate phases, **inlining the tracker's concrete commands** (the - ready-work query, the create command, the status write-back). The model is in - `${CLAUDE_PLUGIN_ROOT}/shared/tracker-coordination.md`. -- **Tracker-sync write-through**, when the dual-tracker sync sub-step generated artifacts: - splice **Addendum T4** (Tracker coordination section of - `references/orchestrator-template.md`) immediately after T3, so the integrate phase invokes - the generated `tracker-sync` skill in `scoped` mode for the items it just wrote back. The - sync model is in `${CLAUDE_PLUGIN_ROOT}/shared/tracker-sync-protocol.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 -trigger keywords. - -**Verify generation before declaring it complete.** After writing the generated artifacts — -the orchestrator and, when the sync sub-step ran, the sync skill, agent, and sync config — -grep **every written file** for unsubstituted `{PLACEHOLDER}` tokens and for -`${CLAUDE_PLUGIN_ROOT}` references. Any hit fails the run: fix the file and re-verify before -moving to Step 6. Generated files must be self-contained — a leaked placeholder or plugin -path surfaces later inside the target project, at worst in a scheduled headless run that -fails with nobody watching. - -Then **register the pointer** in the project's `CLAUDE.md`: goal, the **entry-point directive** -(the hard gate that makes the orchestrator the single entry point — every prompt routes through -it before any response), and the change-history table — and nothing the file system already -holds. The convention and the template are in `${CLAUDE_PLUGIN_ROOT}/shared/claude-md-pointer.md`. - -## Step 6: Record the change in history - -Every write to the harness appends a row to the change-history table in `CLAUDE.md` -(`Date | Change | Target | Reason`). This is a required step, not optional — it is how -evolution stays visible and regressions stay catchable. The table format is in -`${CLAUDE_PLUGIN_ROOT}/shared/claude-md-pointer.md`. - -## Step 7: Capture feedback - -A harness is a system that keeps changing, not a one-time artifact. After a run, offer the -user the chance to feed back ("anything to improve in the result, the team, or the -workflow?"). If there is none, move on — do not force it. When there is, route it to the -right place: output quality → the relevant skill; missing role → a new agent definition; -wrong order → the orchestrator; missing trigger → a description. The routing table and the -evolution triggers (recurring feedback, repeated failures, the user bypassing the -orchestrator) are in `references/maintenance.md`. - -## Deliverable checklist - -Before calling a setup or change complete: - -- [ ] The full change manifest (agents / skills / orchestrator / pointer / tools to create / - update / remove / install / uninstall) was formally approved before any write. -- [ ] Every agent is a file under `.claude/agents/` — including built-in types. -- [ ] Skills exist under `.claude/skills/` with valid `name` + `description` frontmatter. -- [ ] One orchestrator, with data flow, error handling, and test scenarios. -- [ ] Execution mode is stated (team / subagent / hybrid; per-phase if hybrid), with the - subagent fallback covered when team mode is the default. -- [ ] Each agent's model is set deliberately (`inherit` by default; a pinned dated model id only where judgment needs it). -- [ ] No `commands/` directory was generated. -- [ ] No conflict with existing agents or skills. -- [ ] Skill and orchestrator descriptions are pushy and include follow-up keywords. -- [ ] The orchestrator description opens by asserting it is the entry point for the domain - (invoke before responding to any domain request). -- [ ] Each SKILL.md body is within ~500 lines; overflow moved to `references/`. -- [ ] The orchestrator's first phase is intake & triage: it short-circuits trivial / off-domain - requests, then runs the context check (initial / follow-up / partial) for in-domain work. -- [ ] 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/`. -- [ ] If a tracker is present: phase 0 pulls ready work or creates the issue, integrate writes - status back, each item's work state has exactly one owner, and no issue content is copied - into `_agents_workspace/`. -- [ ] Every generated artifact passed the placeholder check — no unsubstituted `{PLACEHOLDER}` - token or `${CLAUDE_PLUGIN_ROOT}` reference remains in any written file. -- [ ] If the dual-tracker sync sub-step ran: it was offered only because both an agentic and a - human tracker are present/declared; the sync preflight validated both entry points before - anything was generated; the sync config is complete (confirmed state table, intake filter, - backfill choice, designated branch, cadence, item cap); and every schedule row was - approved in the manifest as an environment-level change. -- [ ] The `CLAUDE.md` pointer is registered (goal + entry-point directive (hard gate) + change - history; plus the spec-process and issue-tracking lines when those systems are 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. -- [ ] If tool discovery ran: nothing was adopted without explicit approval, and accepted - tools are registered by role (with alternatives) in the orchestrator's `tools.md`. - -## References - -- `references/agent-design-patterns.md` — execution-mode comparison, the six architecture - patterns, agent-split criteria, the agent-definition template. -- `references/team-examples.md` — worked agent teams across generic domains, with full - sample agent files. -- `references/orchestrator-template.md` — orchestrator templates by mode, with data-passing, - error handling, and test scenarios. -- `references/skill-writing-guide.md` — skill authoring: descriptions, body style, - progressive disclosure, data-schema standards. -- `references/maintenance.md` — extending an existing harness (the extension matrix), - applying a review context, syncing drift, feedback routing, and periodic tool review. -- `references/tool-discovery.md` — the optional, on-request tool-discovery step: the - search subagent's context, the explicit-acceptance flow, and the `tools.md` registry schema. -- `references/tracker-sync-template.md` — what the dual-tracker sync sub-step generates: the - `tracker-sync` skill, agent, and sync-config templates, the elicitation guidance, and the - schedule-registration block per venue. -- `${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 or issue tracker (shared with `spec-advisor` and `tracker-advisor`); - `${CLAUDE_PLUGIN_ROOT}/shared/coordination-protocol.md` — the generic coordination protocol; - `${CLAUDE_PLUGIN_ROOT}/shared/sdd-coordination.md` and - `${CLAUDE_PLUGIN_ROOT}/shared/tracker-coordination.md` — the per-area instances with their - per-system coordination maps; - `${CLAUDE_PLUGIN_ROOT}/shared/tracker-sync-protocol.md` — the dual-tracker sync model - (lanes, state store, fingerprints, concurrency, failure rules, per-SaaS map). diff --git a/agentic-harness/skills/harness-setup/references/agent-design-patterns.md b/agentic-harness/skills/harness-setup/references/agent-design-patterns.md deleted file mode 100644 index 575e08a..0000000 --- a/agentic-harness/skills/harness-setup/references/agent-design-patterns.md +++ /dev/null @@ -1,224 +0,0 @@ -# Agent design patterns - -How to structure a team, which architecture pattern fits the work, when to split a role -into its own agent, and the shape of an agent definition file. - -## Table of contents - -1. [Execution modes, in brief](#1-execution-modes-in-brief) -2. [The six architecture patterns](#2-the-six-architecture-patterns) -3. [Composite patterns](#3-composite-patterns) -4. [Agent type selection](#4-agent-type-selection) -5. [Splitting vs merging agents](#5-splitting-vs-merging-agents) -6. [Skill vs agent](#6-skill-vs-agent) -7. [Agent definition template](#7-agent-definition-template) - ---- - -## 1. Execution modes, in brief - -Two modes, with a third that mixes them. The full decision logic, the experimental -team-tools caveat, and the team-to-subagent fallback mapping are in the shared execution-modes -doc — read that before designing the team. The short version: - -- **Agent team** — members run as peers and coordinate directly (`SendMessage`) over a - shared task list (`TaskCreate`). Use it when agents need to exchange information while they - work: sharing findings, challenging each other, reconciling conflicts. Only one team is - active per session, but a team can be disbanded between phases and a new one formed. The - team tools are experimental — always design a subagent fallback. -- **Subagent** — the orchestrator spawns each agent with the `Agent` tool; the agent returns - its result and does not talk to siblings. Use it for a single agent, or for independent - jobs where only the combined result matters. Parallelize with `run_in_background`. - -Each pattern below notes whether a team earns its cost or a subagent is the better fit. - -## 2. The six architecture patterns - -### Pipeline - -Stages run in order; each consumes the previous stage's output. - -``` -[Analyze] → [Design] → [Build] → [Verify] -``` - -Fits work with strong sequential dependency. A slow stage stalls the whole line, so make -each stage as independent as the work allows. Team mode adds little to a pure sequence — -unless a stage has parallel sub-work, in which case a team helps there. - -### Fan-out / Fan-in - -Independent work in parallel, then integration. - -``` - ┌→ [Specialist A] ─┐ -[Distribute]┼→ [Specialist B] ─┼→ [Integrate] - └→ [Specialist C] ─┘ -``` - -Fits when one input needs several independent perspectives. The integration stage governs -final quality. This is the most natural fit for a team: members surface findings to each -other and one member's discovery can redirect another's work mid-flight, which a set of -isolated subagents cannot do. Build it as a team when the tools allow. - -### Expert Pool - -Route to the one specialist the input needs. - -``` -[Router] → { Specialist A | Specialist B | Specialist C } -``` - -Fits when different input types need different handling. The router's classification is the -weak point. Subagents usually fit better — only the chosen specialist runs, so a standing -team is wasted. - -### Producer–Reviewer - -A producer and a reviewer work as a pair, looping until the deliverable passes. - -``` -[Produce] → [Review] → (issues?) → back to [Produce] -``` - -Fits when quality matters and there are objective review criteria. Cap the retry count (two -or three) to avoid an endless loop. A team lets producer and reviewer exchange feedback -directly; subagents work too when a written review hand-off is enough. - -### Supervisor - -A central agent holds the work state and hands out work as it goes. - -``` - ┌→ [Worker A] -[Supervisor] ─┼→ [Worker B] - └→ [Worker C] -``` - -Fits variable workloads where assignment is decided at runtime, not fixed up front (the -difference from fan-out). Keep delegation units large enough that the supervisor is not the -bottleneck. The team's shared task list matches this naturally: register work, let members -claim it. - -### Hierarchical Delegation - -A higher agent decomposes a problem and delegates to lower agents, recursively. - -``` -[Lead] → [Sub-lead A] → [Worker A1], [Worker A2] - → [Sub-lead B] → [Worker B1] -``` - -Fits problems that decompose cleanly into a tree. Keep it to two levels — three or more adds -latency and loses context. Teams cannot nest (a member cannot form its own team), so -implement level one as a team and level two as subagents, or flatten to a single team. - -## 3. Composite patterns - -Real harnesses usually combine patterns: - -| Composite | Shape | Example domain | -|-----------|-------|----------------| -| Fan-out + Producer–Reviewer | parallel production, then per-item review | translate several variants in parallel, each reviewed separately | -| Pipeline + Fan-out | parallelize one stage of a sequence | sequential analysis → parallel build → sequential integration test | -| Supervisor + Expert Pool | supervisor routes to the right specialist on demand | inbound triage that assigns each case to a domain specialist | - -Default composites to a team when members benefit from talking; drop to subagents only for a -stage that is genuinely isolated and one-off. - -## 4. Agent type selection - -Pass the type via the `Agent` tool's `subagent_type`. Built-in types: - -| Type | Tool access | Fits | -|------|-------------|------| -| `general-purpose` | full (incl. web, scripts) | research, validation, any work needing tools | -| `Explore` | read-only | reading and analyzing a codebase | -| `Plan` | read-only | design and planning | - -A custom type is an agent you defined under `.claude/agents/{name}.md`, invoked with -`subagent_type: "{name}"`; it has full tool access. Choose by: - -| Situation | Choice | -|-----------|--------| -| Complex role reused across sessions | custom type (a file) | -| Simple collection where a prompt suffices | `general-purpose` + a detailed prompt | -| Read-only analysis or review | `Explore` | -| Design or planning only | `Plan` | -| Work that modifies files | custom type | - -Whatever the type, write the agent as a file (see the harness model's file rule). For a QA -agent specifically, use `general-purpose` — `Explore` cannot run validation. - -## 5. Splitting vs merging agents - -Judge along four axes: - -| Axis | Split when | Merge when | -|------|------------|------------| -| Expertise | the domains differ | the domains overlap | -| Parallelism | they can run independently | they are sequentially dependent | -| Context | the context load is large | both are light and fast | -| Reusability | other teams use it too | only this team uses it | - -Prefer a few focused agents over many thin ones — coordination cost rises with team size. - -## 6. Skill vs agent - -| Aspect | Skill | Agent | -|--------|-------|-------| -| What it is | procedural knowledge + tools | an expert persona + principles | -| Lives in | `.claude/skills/` | `.claude/agents/` | -| Triggered by | matching a request | explicit invocation via the `Agent` tool | -| Size | small to large (a workflow) | small (a role) | -| Answers | *how* | *who* | - -An agent leverages a skill in one of three ways: - -| Way | How | Fits | -|-----|-----|------| -| Skill invocation | the agent prompt says to invoke `/skill-name` via the Skill tool | reusable, independently invocable skills | -| Inline | the skill content sits inside the agent definition | short (≤50 lines), exclusive to that agent | -| Reference load | the agent reads a `references/` file when needed | large, only conditionally relevant content | - -## 7. Agent definition template - -```markdown ---- -name: agent-name -description: "One or two sentences on the role. List the trigger keywords." -model: inherit ---- - -# Agent Name — one-line role - -You are an expert [role] in [domain]. - -## Core role -1. ... -2. ... - -## Working principles -- ... - -## Input / output protocol -- Input: where it reads from, and what -- Output: where it writes, and what -- Format: file format and structure - -## Team communication protocol (team mode only) -- Receives: from whom, and what -- Sends: to whom, and what -- Claims: what it takes from the shared task list - -## Error handling -- on failure: ... -- on timeout: ... - -## Collaboration -- relationships with the other agents -``` - -Default `model` to `inherit` so the agent follows the session's model. For a role whose -quality depends on judgment rather than throughput, pin the strongest reasoning model -explicitly — by its current dated id (e.g. `claude-opus-4-8`), not a bare `opus` alias that ages. diff --git a/agentic-harness/skills/harness-setup/references/maintenance.md b/agentic-harness/skills/harness-setup/references/maintenance.md deleted file mode 100644 index 1885479..0000000 --- a/agentic-harness/skills/harness-setup/references/maintenance.md +++ /dev/null @@ -1,127 +0,0 @@ -# Maintaining a harness - -A harness is a system that keeps changing, not a one-time build. This covers the four ways it -changes after the first build: extending it, applying a review context, syncing drift, and -folding in feedback. Every one of them ends by recording the change in history. - -## Table of contents - -1. [The extension matrix](#1-the-extension-matrix) -2. [Applying a review context](#2-applying-a-review-context) -3. [Syncing drift](#3-syncing-drift) -4. [Feedback routing](#4-feedback-routing) -5. [Evolution triggers](#5-evolution-triggers) -6. [The operations workflow](#6-the-operations-workflow) -7. [Periodic tool review](#7-periodic-tool-review) - ---- - -## 1. The extension matrix - -When extending an existing harness, do not re-run the full build. Run only the steps the -change needs (step numbers are from the `harness-setup` SKILL.md): - -| Change | Domain analysis (1) | Mode/pattern (2) | Agents (3) | Skills (4) | Orchestrator (5) | History (6) | -|--------|---------------------|------------------|------------|------------|------------------|-------------| -| Add an agent | reuse Step 0 | placement only | yes | only if it needs a new skill | update composition + triggers | yes | -| Add / change a skill | skip | skip | skip | yes | only if wiring changes | yes | -| Architecture change | skip | yes | only affected agents | only affected skills | yes | yes | - -When adding an agent, modify the existing orchestrator — do not spawn a second one. Reflect -the new agent in the team composition, task assignment, data flow, and trigger keywords. - -## 2. Applying a review context - -`harness-review` hands off a prioritized list: what works well (leave it), and what to -improve (act on it). Treat it as an interactive improvement pass, not a batch rewrite: - -1. Read the review context and confirm the priority order with the user. -2. Take items one at a time, highest priority first. -3. For each, identify the right target with the routing table below, make the smallest change - that addresses it, and record it in history. -4. After each change, re-check the specific concern the item raised before moving on. - -Working one item at a time keeps each change attributable and easy to roll back. - -## 3. Syncing drift - -Drift is when the files and the `CLAUDE.md` record disagree — an agent or skill exists that -the record doesn't mention, or the record names something no longer present. - -1. List `.claude/agents/` and `.claude/skills/`; compare against the orchestrator's - composition and the `CLAUDE.md` pointer. -2. For each discrepancy, decide with the user which side is correct — the files or the - record. -3. Reconcile toward the correct side, then record the correction in history. - -The files are usually the truth; the record is what falls behind. But confirm rather than -assume — a missing file can mean a deletion that was never recorded *or* an accidental loss. - -## 4. Feedback routing - -Different feedback lands in different places. Route by type: - -| Feedback | Fix where | Example | -|----------|-----------|---------| -| Output quality | the agent's skill | "the analysis is too shallow" → add depth criteria to the skill | -| Missing role | a new agent definition | "we also need a security pass" → add an agent | -| Wrong order | the orchestrator | "validation should come first" → reorder the phases | -| Team composition | orchestrator + agents | "merge these two" → combine the agents | -| Missing trigger | the skill description | "it doesn't fire when I phrase it this way" → widen the description | -| Orchestrator bypassed | the `CLAUDE.md` entry-point directive (then the description) | "I just did it by hand" → strengthen the hard gate, not only the keywords | - -The reason this table exists is the separation in the harness model: who, how, and when each -have one home, so each kind of fault has one place to fix it. - -## 5. Evolution triggers - -Propose a change not only when the user asks, but when the signals say it is due: - -- The same kind of feedback recurs two or more times. -- An agent fails the same way repeatedly. -- The user is working around the orchestrator by hand — a sign it does not fit the real task, - *or* that the `CLAUDE.md` entry-point directive is too weak to route the prompt to it. Check - the directive is a hard gate before assuming the fit is wrong; strengthen it (and the - orchestrator's entry-point description) as the first remedy. - -When you see these, raise it; don't wait to be told. - -## 6. The operations workflow - -For an audit-fix-sync request on an existing harness: - -1. **Audit.** Compare `.claude/agents/` and `.claude/skills/` against the orchestrator's - composition; produce a discrepancy list; report it to the user. (Read-only inventory and - usage assessment are `harness-review`'s job — call it for the deeper read.) -2. **Change incrementally.** Add, modify, or remove one agent or skill at a time. Sync after - each change rather than batching. Present each change in the Step 2b manifest and get - approval before writing — the pre-write approval is mandatory here too. -3. **Record history.** Append the date, change, target, and reason to the `CLAUDE.md` table. -4. **Validate.** Re-check the changed agents and skills structurally; if the change affects - triggering, re-check the descriptions; for large changes (an architecture change, or - adding/removing several agents), re-run the relevant tests. Finally, confirm the - `CLAUDE.md` record matches the actual files. - -## 7. Periodic tool review - -If the harness has a tools registry (`references/tools.md` under the orchestrator, produced -by the tool-discovery step), the tools in it are not permanent — they fall out of use, stop -being maintained, or get overtaken. So on any run against an existing harness (extend, apply -a review context, or sync), **always offer a tool-maintenance review** as part of the plan — -the same way `harness-setup` Step 0 offers tool discovery on a build. Offering is the -default; run it when the user accepts. When you do, weigh each registered tool against these -signals: - -- A registered tool is no longer being used by any agent or skill. -- A tool has stopped being maintained, or a better alternative has appeared. -- The preferred tool fails often enough that agents are running on its alternative in - practice. - -The split follows the rest of this plugin: assessing whether a tool is still earning its -place is a read activity, so it belongs to `harness-review` (it reads the registry as one of -its usage signals); swapping, adding, or retiring a tool is a write, so it comes back here — -and a retirement is an uninstall row in the Step 2b manifest, approved before it is carried -out. When you change the registry, update the affected row's `Last reviewed` date, keep every -role's alternative current, and record the change in the `CLAUDE.md` history like any other. -Because agents and skills reference tools by role, swapping the tool behind a role needs no -edits to their files. diff --git a/agentic-harness/skills/harness-setup/references/orchestrator-template.md b/agentic-harness/skills/harness-setup/references/orchestrator-template.md deleted file mode 100644 index be5f121..0000000 --- a/agentic-harness/skills/harness-setup/references/orchestrator-template.md +++ /dev/null @@ -1,407 +0,0 @@ -# Orchestrator template - -The orchestrator is the top-level skill that coordinates the whole team. It comes in three -shapes, one per execution mode. Pick the shape from the mode chosen in Step 2; for hybrid, -state the mode per phase. - -## Table of contents - -- [Orchestrator template](#orchestrator-template) - - [Table of contents](#table-of-contents) - - [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) - - [Tracker coordination](#tracker-coordination) - - [Authoring rules](#authoring-rules) - - [Follow-up keywords](#follow-up-keywords) - ---- - -## Template A — agent team (default) - -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 and/or issue tracker, also splice in the matching -> [SDD coordination](#sdd-coordination) addenda (phase 0, prepare, integrate) and/or -> [Tracker coordination](#tracker-coordination) addenda (phase 0, work, integrate), so the -> orchestrator hands work to the spec process and keeps the tracker as the work-state owner. - -````markdown ---- -name: {domain}-orchestrator -description: "Entry point for all {domain} work in this repo — invoke before responding to any {domain} request. Coordinates the {domain} agent team to produce {deliverable}. {initial keywords}. Also use for follow-ups: re-run, update, modify, supplement, improve the previous result, and everyday {domain} requests." -model: inherit ---- - -# {Domain} orchestrator - -Coordinates the {domain} agent team to produce {final deliverable}. - -## Execution mode: agent team - -## Team - -| Member | Type | Role | Skill | Output | -|--------|------|------|-------|--------| -| {member-1} | {custom or built-in} | {role} | {skill} | {file} | -| {member-2} | ... | ... | ... | ... | - -## Workflow - -### Phase 0: intake & triage (always entered first — this skill is the repo entry point) -This skill is the repo's entry point, so it runs for *every* prompt. Triage before doing anything else: -- Trivial, conversational, or clearly outside {domain} → answer it directly (or take the obviously - small correct action) and stop. Do not form a team or open `_agents_workspace/`. -- In-{domain} work → run the context check, then continue into the workflow. - -**Context check** (in-{domain} work only) — branch on whether prior work exists: -- `_agents_workspace/` absent → initial run; go to Phase 1. -- `_agents_workspace/` present + a partial-change request → partial re-run; re-invoke only - the affected member and overwrite only its output. -- `_agents_workspace/` present + new input → new run; move the old `_agents_workspace/` to - `_agents_workspace/archive/{YYYYMMDD_HHMMSS}/`, then go to Phase 1. -On a partial re-run, pass the prior output path into the member's prompt so it reads the -existing result and folds in the change. - -### Phase 1: prepare -1. Read the input and identify {what to identify}. -2. Create `_agents_workspace/` (or recreate it after archiving the old one on a new run). -3. Save the input under `_agents_workspace/00_input/`. - -### Phase 2: form the team -1. `TeamCreate(team_name, members: [...])` — each member with its name, type, model, and a - role prompt. -2. `TaskCreate(tasks: [...])` — roughly five to six tasks per member; declare dependencies - with `depends_on`. - -### Phase 3: {the main work} -Members claim tasks from the shared list and work independently. State the communication -rules: who passes what to whom via `SendMessage`; that each member saves its output to a -file and notifies the leader on completion; that a member requesting another's result asks -over `SendMessage`. The leader watches progress (it is notified when a member goes idle), -nudges or reassigns a stuck member, and checks state with `TaskGet`. - -| Member | Output path | -|--------|-------------| -| {member-1} | `_agents_workspace/{phase}_{member-1}_{artifact}.md` | - -### Phase 4: integrate -1. Wait for all tasks to complete (`TaskGet`). -2. Read each member's output. -3. Apply the integration logic; where members conflict, record both with their sources. -4. Write the final deliverable to the user's target path. - -### Phase 5: tear down -1. Ask members to stop (`SendMessage`); `TeamDelete`. -2. Keep `_agents_workspace/` (do not delete intermediate work). -3. Report a summary to the user. - -## Error handling - -| Situation | Strategy | -|-----------|----------| -| One member fails or stalls | leader checks via `SendMessage`, restarts or replaces it | -| Most members fail | tell the user, confirm whether to continue | -| Timeout | use the partial results, stop the unfinished members | -| Members disagree | record both with sources; do not delete either | -| Task state lags | leader confirms with `TaskGet`, corrects with `TaskUpdate` | - -## Test scenarios -- **Normal:** input → analysis → team of N + M tasks → self-coordinated work → integration → - teardown → the deliverable exists at its path. -- **Error:** a member stops mid-phase → leader gets the idle notice → restart attempt → - on repeated failure, reassign its task → integrate the rest → note the gap in the report. -```` - -## Template B — subagent (fallback / lightweight) - -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 and/or issue tracker, also splice in the matching -> [SDD coordination](#sdd-coordination) and/or [Tracker coordination](#tracker-coordination) addenda. - -````markdown ---- -name: {domain}-orchestrator -description: "Entry point for all {domain} work in this repo — invoke before responding to any {domain} request. Coordinates {domain} agents to produce {deliverable}. {initial keywords} + follow-up keywords." -model: inherit ---- - -## Execution mode: subagent - -## Agents - -| Agent | subagent_type | Role | Skill | Output | -|-------|---------------|------|-------|--------| -| {agent-1} | {built-in or custom} | {role} | {skill} | {file} | - -## Workflow - -### Phase 0: intake & triage (always entered first — this skill is the repo entry point) -Same as Template A: triage every prompt first — trivial / conversational / out-of-{domain} → answer -directly and stop; in-{domain} work → run the context check (branch on whether `_agents_workspace/` -exists) and continue. - -### Phase 1: prepare -Read the input; create `_agents_workspace/` (archiving any old one on a new run). - -### Phase 2: run in parallel -Invoke the agents in a single message: - -| Agent | Input | Output | model | run_in_background | -|-------|-------|--------|-------|-------------------| -| {agent-1} | {source} | `_agents_workspace/{phase}_{agent}_{artifact}.md` | {model} | true | - -### Phase 3: integrate -Collect each return value; read file outputs; apply the integration logic; write the final -deliverable. - -### Phase 4: finish -Keep `_agents_workspace/`; report a summary. - -## Error handling -- One agent fails: retry once; on a second failure, note the omission and continue. -- Most fail: tell the user and confirm. -- Timeout: use the partial results. -```` - -## Template C — hybrid - -A different mode per phase. State `**Execution mode:** {team | subagent}` at the top of each -phase. - -> If the project has an installed SDD system and/or issue tracker, the -> [SDD coordination](#sdd-coordination) and/or [Tracker coordination](#tracker-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 -description: "Entry point for all {domain} work in this repo — invoke before responding to any {domain} request. {domain} orchestrator (hybrid). {keywords} + follow-up keywords." -model: inherit ---- - -## Execution mode: hybrid - -| Phase | Mode | Why | -|-------|------|-----| -| Phase 0 (intake & triage) | — | gate every prompt; short-circuit trivial / off-domain | -| Phase 2 (parallel collection) | subagent | independent collection, no coordination needed | -| Phase 3 (consensus integration) | agent team | reconcile conflicting inputs by discussion | -| Phase 4 (independent verification) | subagent | one QA agent verifies objectively | - -### Phase 0: intake & triage (always entered first — this skill is the repo entry point) -Same as Template A: triage every prompt first — trivial / conversational / out-of-{domain} → answer -directly and stop; in-{domain} work → run the context check and continue into the phases below. - -### Phase 2: collect — **Execution mode:** subagent -Invoke N agents in parallel (`run_in_background: true`); save each to -`_agents_workspace/02_{agent}_raw.md`. - -### Phase 3: integrate — **Execution mode:** agent team -`TeamCreate` an integration team; `TaskCreate` work that reads the Phase 2 files; members -reconcile conflicts via `SendMessage`; write `_agents_workspace/03_integrated.md`; -`TeamDelete`. - -### Phase 4: verify — **Execution mode:** subagent -One QA subagent reads `_agents_workspace/03_integrated.md` and writes a verification report. -```` - -**Transition rules.** Team → subagent: `TeamDelete` before any `Agent` call. Subagent → -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 step of phase 0 (intake & triage), reached only after triage routes the -request in as in-{domain} work, 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: intake & triage → SDD: GitHub Spec Kit -... triage (trivial/off-domain → answer and stop); then the context-check 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: intake & triage → SDD: AWS Kiro -- (triage first; for in-domain work:) 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`. - -## Tracker coordination - -Use this when the project has an installed issue tracker. The model — the tracker as the -**work-state owner**, the phase-0 pull-or-create, the write-back, and the per-tracker command map — -is in `${CLAUDE_PLUGIN_ROOT}/shared/tracker-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 -tracker's coordination row: `{tracker}`, `{READY_QUERY}` (its ready-work query), `{CREATE_CMD}` -(its create command), `{STATUS_WRITEBACK}` (its close/transition convention), and auto-invokable or -human-gated access. - -Unlike an SDD system, a tracker does not own a phase — it owns the work-state **concern** that -brackets the run. Reference issues by ID; never copy issue content into `_agents_workspace/`, and -keep no parallel status file beside the tracker. - -### Addendum T1 — phase 0 (context check): pull ready work, or create the issue -Add to the context-check step of phase 0 (intake & triage), reached only after triage routes the -request in as in-{domain} work: - -``` -- Check the tracker for a matching ready item: run `{READY_QUERY}`. If one matches this request, - claim it and carry its ID through the run. -- If the work is new, create the issue first (`{CREATE_CMD}`), so {tracker} owns the work state - from the start — then proceed with its ID. -- Human-gated access (no CLI/MCP configured): emit a contextual prompt stating what to file or - look up, and **pause** until the user confirms. -``` - -### Addendum T2 — work: reference the issue, do not copy it -Add to the prepare/work phases: - -``` -- Carry the issue ID in the headers of workspace artifacts (`issue: {tracker-id}`); read the - issue in place when context is needed. -- Do not copy issue content into `_agents_workspace/`, and keep no status file of your own — - {tracker} is the single owner of work state. -``` - -### Addendum T3 — integrate / finish: write status back in {tracker}'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 back: {STATUS_WRITEBACK}, referencing the deliverable's path. Never delete issues - and never rewrite human-authored issue prose — the tracker owns intent and history, the - harness owns execution. -``` - -### Addendum T4 — integrate / finish: tracker-sync write-through (dual-tracker projects only) -Splice this **only when the project has the generated `tracker-sync` skill** — a repo-native -tracker plus a human SaaS tracker, with the sync artifacts generated per -`${CLAUDE_PLUGIN_ROOT}/shared/tracker-sync-protocol.md`. Add immediately after Addendum T3's -write-back: - -``` -- After {STATUS_WRITEBACK} completes, invoke the `tracker-sync` skill in **scoped** mode for the - item(s) touched this run, so the human tracker's projection reflects the new work state. - Scoped mode pushes only those items — it runs no intake and no reconcile. -- If the sync run fails or its preflight stops it, note that in the run summary and continue — - the deliverable does not depend on the projection, and a later `full` run catches up. -``` - -### Worked snippet — Beads (auto-invokable) -- **READY_QUERY:** `bd ready --json` · **CREATE_CMD:** `bd create "title"` · - **STATUS_WRITEBACK:** `bd update {id} --claim` on start, `bd close {id} "summary"` on completion - -``` -### Phase 0: intake & triage -... triage (trivial/off-domain → answer and stop); then the context-check branch ... -- Run `bd ready --json`; if an item matches this request, claim it (`bd update {id} --claim`) - and carry the ID. If the work is new, `bd create "title"` first. -### Phase 4: integrate -- Write the deliverable; `bd close {id} "done — see {deliverable path}"`. -``` - -### Composing with an SDD system -When both an SDD system and a tracker are present, the SDD addenda own *what to build* (spec, -plan, decomposition) and the tracker addenda own *work state* (ready, in progress, done) — splice -both, and give each item's status exactly one owner. When Taskmaster is present, spec-derived -tasks route their status through `.taskmaster/tasks/tasks.json`, general issues through the -tracker — never mirror one item's state in both (see the Taskmaster boundary in -`${CLAUDE_PLUGIN_ROOT}/shared/tracker-coordination.md`). - -## Authoring rules - -1. State the execution mode at the top. For hybrid, a per-phase mode table is required. -2. For team mode, be concrete about `TeamCreate` / `TaskCreate` / `SendMessage` usage. -3. For subagent mode, fully specify each `Agent` call (name, type, prompt, model, - `run_in_background`). -4. Use clear paths under `_agents_workspace/`; avoid ambiguous relative paths. -5. State inter-phase dependencies — which phase needs which phase's output. For hybrid, - 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 and/or issue tracker is present, splice in the matching - [SDD coordination](#sdd-coordination) / [Tracker coordination](#tracker-coordination) addenda - with the system's concrete values inlined; mark each phase as delegated or orchestrator-owned, - and give each item's work state exactly one owner. - -## Follow-up keywords - -The description opens by asserting the orchestrator is the repo's entry point for {domain} work — -that framing is what makes the skill trigger broadly rather than only on a narrow initial phrasing. -It is the description's job to back the `CLAUDE.md` entry-point directive, not just to advertise the -initial run. - -Initial-run keywords alone leave the harness unused after its first run. Put follow-up -phrasings in the description: re-run, run again, update, modify, supplement; "only the -{part} again"; "based on the previous result", "improve the result"; and everyday domain -requests (for a launch-planning harness: "launch", "promotion", and the like). diff --git a/agentic-harness/skills/harness-setup/references/skill-writing-guide.md b/agentic-harness/skills/harness-setup/references/skill-writing-guide.md deleted file mode 100644 index b968501..0000000 --- a/agentic-harness/skills/harness-setup/references/skill-writing-guide.md +++ /dev/null @@ -1,154 +0,0 @@ -# Skill writing guide - -How to write the skills a generated harness uses, so they trigger reliably and earn their -context cost. Supplements Step 4. - -## Table of contents - -- [Skill writing guide](#skill-writing-guide) - - [Table of contents](#table-of-contents) - - [1. Writing the description](#1-writing-the-description) - - [2. Body style](#2-body-style) - - [3. Output formats and examples](#3-output-formats-and-examples) - - [4. Progressive disclosure](#4-progressive-disclosure) - - [5. When to bundle a script](#5-when-to-bundle-a-script) - - [6. Data-schema standards](#6-data-schema-standards) - - [7. What to leave out](#7-what-to-leave-out) - ---- - -## 1. Writing the description - -The description is the only thing that decides whether a skill triggers. The model judges -from the name and description alone, and it tends to skip a skill for a task it thinks it can -handle bare-handed. So: - -1. Say both **what the skill does** and **the specific situations that should trigger it**. -2. Mark the boundary — name the near-miss cases where a *different* tool is the right fit, so - this skill does not fire on them. -3. Lean slightly pushy, to offset the conservative default. - -**Weak:** `"A skill that processes data"` — which data, which task? Too vague to trigger. - -**Strong:** `"All spreadsheet operations — add columns, compute formulas, format, chart, -clean data — for .xlsx / .csv / .tsv. Use whenever the user mentions a spreadsheet file, -even in passing. Not for a Word document or a PDF: use the matching skill for those."` - -The strong version enumerates concrete actions, states the trigger, and draws the boundary. - -## 2. Body style - -**Explain the why.** A rule the agent understands generalizes; a bare command does not. - -Weak: -```text -ALWAYS use a table-aware extractor. NEVER use a plain text extractor for tables. -``` -Strong: -```text -Use a table-aware extractor for tables: a plain text extractor loses the row and column -structure, while a table-aware one recognizes cell boundaries and returns structured rows. -``` - -**Generalize, don't overfit.** Fix at the level of the principle, not the one example that -failed. - -Weak: `If a column is named "Q4 Revenue", convert it to numbers.` -Strong: `If a column name implies a numeric quantity (revenue, amount, count), convert it to -a number; if conversion fails, keep the original value.` - -**Write imperatively.** A skill is an instruction sheet: "do X", not "the skill does X". - -**Spend context deliberately.** The window is shared. For each sentence ask: does the agent -already know this (cut it), would it err without it (keep it), would one example replace the -explanation (swap it)? - -## 3. Output formats and examples - -When the deliverable's shape matters, show the template: - -```text -## Report structure -# {Title} -## Summary -## Findings -## Recommendations -``` - -Keep it short — a concrete example teaches faster than a long spec. For transformations, -pair input with output: - -```text -Input: Add token-based user authentication -Output: feat(auth): add token-based authentication -``` - -## 4. Progressive disclosure - -A skill loads in three stages: metadata (always in context), the SKILL.md body (on trigger), -and `references/` files (only when read). Use the stages: - -- As the body nears ~500 lines, move detail into `references/` and leave a one-line pointer - that says when to read it. -- Give any reference over ~300 lines a table of contents at the top. -- Split domain- or framework-specific variants into separate reference files, so only the - relevant one loads: - -```text -deploy-skill/ -├── SKILL.md (workflow + which file to load) -└── references/ - ├── provider-a.md - ├── provider-b.md - └── provider-c.md -``` - -## 5. When to bundle a script - -Watch the agents' transcripts during testing. Bundle when a pattern repeats: - -| Signal | Action | -|--------|--------| -| The same helper script is written in every test run | bundle it under `scripts/` | -| The same dependency is installed every time | state the install step in the skill | -| The same multi-step approach recurs | write it up as a standard procedure in the body | -| The same workaround follows the same error every time | document the issue and its fix | -| The same document or report is read or produced | write it up and define a json data schema for input/output payload to interact with it | - -A bundled script must pass an execution test of its own. - -## 6. Data-schema standards - -When a harness tests its own generated skills, a shared schema keeps results comparable. - -Test-case metadata: -```json -{ - "eval_id": 0, - "eval_name": "descriptive-name", - "prompt": "the user's task prompt", - "assertions": ["the deliverable contains X", "a file in format Y was produced"] -} -``` - -Assertion-based grading — use the field names `text`, `passed`, `evidence` exactly: -```json -{ - "expectations": [ - { "text": "a margin column was added", "passed": true, "evidence": "column E holds margin_pct" } - ], - "summary": { "passed": 2, "failed": 1, "total": 3, "pass_rate": 0.67 } -} -``` - -Timing — capture from the completion notification immediately; it cannot be recovered later: -```json -{ "total_tokens": 84852, "duration_ms": 23332 } -``` - -## 7. What to leave out - -- Supplementary docs (README, CHANGELOG, install guides). -- Meta-notes about how the skill was built (test logs, iteration history). -- End-user manuals — a skill is an instruction sheet for an agent, not a human. -- General knowledge the model already has. diff --git a/agentic-harness/skills/harness-setup/references/team-examples.md b/agentic-harness/skills/harness-setup/references/team-examples.md deleted file mode 100644 index b524156..0000000 --- a/agentic-harness/skills/harness-setup/references/team-examples.md +++ /dev/null @@ -1,157 +0,0 @@ -# Team examples - -Worked examples across generic domains. Each shows the architecture pattern, the execution -mode, the agent composition, and the coordination shape. Adapt them — do not copy them -literally. - -## Table of contents - -- [Team examples](#team-examples) - - [Table of contents](#table-of-contents) - - [1. Multi-source research (team, fan-out/fan-in)](#1-multi-source-research-team-fan-outfan-in) - - [2. Long-form authoring (team, pipeline + fan-out)](#2-long-form-authoring-team-pipeline--fan-out) - - [A full agent file — `consistency-reviewer.md`](#a-full-agent-file--consistency-reviewermd) - - [3. Generate-and-review (subagent, producer–reviewer)](#3-generate-and-review-subagent-producerreviewer) - - [4. Code review (team, fan-out/fan-in + debate)](#4-code-review-team-fan-outfan-in--debate) - - [5. Large migration (team, supervisor)](#5-large-migration-team-supervisor) - - [What every example shares](#what-every-example-shares) - ---- - -## 1. Multi-source research (team, fan-out/fan-in) - -Several researchers cover different source types in parallel; the leader integrates. - -| Member | Type | Scope | Output | -|--------|------|-------|--------| -| primary-source-researcher | general-purpose | official / first-party sources | `research_primary.md` | -| press-researcher | general-purpose | reporting and analysis | `research_press.md` | -| community-researcher | general-purpose | forums and social discussion | `research_community.md` | -| context-researcher | general-purpose | background, comparables, prior art | `research_context.md` | -| (leader = orchestrator) | — | integrate into one report | `synthesis-report.md` | - -The researchers use the `general-purpose` built-in type but are still defined as files — -each file states the scope and the team communication protocol so the roles are reusable and -the collaboration has a contract. - -Coordination: the four work independently, but pass relevant finds to each other over -`SendMessage` (the press researcher hands an acquisition rumor to the context researcher; -the community researcher flags a press item to the press researcher). Conflicting claims are -debated directly and, in the final report, recorded side by side with their sources. This -cross-talk is why it is a team rather than four isolated subagents. - -## 2. Long-form authoring (team, pipeline + fan-out) - -A document built in stages, with parallel groundwork. - -```text -Phase 1 (team, parallel): structure-planner + source-curator + outline-builder - — keep each other consistent via SendMessage -Phase 2 (subagent): section-writer drafts from the Phase 1 outputs -Phase 3 (team, parallel): fact-checker + consistency-reviewer review the draft - — share findings via SendMessage -Phase 4 (subagent): section-writer revises to reflect the review -``` - -Phase 1 forms a team, then tears it down. Phase 2 needs no team (one writer working alone), -so it runs as a subagent reading the Phase 1 files from `_agents_workspace/`. Phase 3 forms a -new review team (only one team is active at a time, but Phase 1's was already disbanded). -Phase 4 is again a lone subagent. - -### A full agent file — `consistency-reviewer.md` - -```markdown ---- -name: consistency-reviewer -description: "Checks a long-form draft for internal consistency — terminology, claims, and cross-references that contradict each other." -model: inherit ---- - -# Consistency reviewer - -You check a draft for internal contradictions. You do not judge prose quality — that is the -writer's concern. You judge whether the document agrees with itself. - -## Core role -1. Flag terms used with two different meanings. -2. Flag claims in one section that a later section contradicts. -3. Flag cross-references that point to the wrong place or to nothing. - -## Working principles -- Report file and location for every issue, so the writer can act without searching. -- Distinguish a true contradiction from a stylistic variation; report only the former. - -## Input / output protocol -- Input: the draft at `_agents_workspace/02_section-writer_draft.md`. -- Output: `_agents_workspace/03_consistency_report.md`. -- Format: one entry per issue — location, the two conflicting statements, suggested fix. - -## Team communication protocol -- To fact-checker: SendMessage when a consistency issue depends on a factual question. -- To the leader: a report distinguishing confirmed issues from open questions. - -## Error handling -- If the draft is missing, report that and stop rather than inventing content. - -## Collaboration -- Works alongside fact-checker; the two divide internal vs external correctness. -``` - -## 3. Generate-and-review (subagent, producer–reviewer) - -Two agents — a producer and a reviewer — looping until the output passes. With only two -agents and a hand-off that matters more than conversation, subagent mode fits; cap the loop -at two or three rounds. - -| Agent | subagent_type | Role | -|-------|---------------|------| -| asset-producer | custom | generate the batch of outputs | -| asset-reviewer | custom | inspect each, mark PASS / FIX / REDO | - -The reviewer judges on objective criteria (completeness, consistency, legibility), not -taste, and writes a per-item verdict with a specific fix instruction. Items marked REDO go -back to the producer with that instruction; after the retry cap, a still-failing item is -passed with a warning. If a large fraction needs REDO, the reviewer proposes revising the -generation prompt rather than looping further. - -## 4. Code review (team, fan-out/fan-in + debate) - -Reviewers with different lenses examine the same change and talk to each other directly. - -```text -[leader] → TeamCreate(review-team) - ├── security-reviewer: vulnerabilities, input handling, authz - ├── performance-reviewer: hot paths, query patterns, allocations - └── test-reviewer: coverage and meaningful assertions - → reviewers cross-message; leader synthesizes -``` - -The value is in the cross-talk: the security reviewer flags an injectable query and asks the -performance reviewer to weigh in; the performance reviewer finds an N+1 query and asks the -test reviewer whether a test would have caught it. Reviewers reach each other without routing -through the leader, which catches cross-domain issues a set of siloed reviews would miss. - -## 5. Large migration (team, supervisor) - -A supervisor analyzes the file set and hands out batches dynamically. - -```text -[supervisor] → analyze file list → register batches as tasks - ├→ migrator-1 (claims a batch) - ├→ migrator-2 (claims a batch) - └→ migrator-3 (claims a batch) - ← on completion, claims the next; on failure, supervisor diagnoses and reassigns -``` - -Unlike fan-out, batches are not fixed in advance — workers claim the next item from the -shared task list as they free up, which keeps fast workers busy and lets the supervisor -rebalance around failures. When all batches are done, the supervisor runs the integration -test. - -## What every example shares - -- Every agent is a file under `.claude/agents/`, with the required sections and — in team - mode — a team communication protocol. -- Skills live under `.claude/skills/{name}/SKILL.md`. -- The orchestrator names the agents and the workflow and states the execution mode. See - `references/orchestrator-template.md`. diff --git a/agentic-harness/skills/harness-setup/references/tool-discovery.md b/agentic-harness/skills/harness-setup/references/tool-discovery.md deleted file mode 100644 index 8a20ee3..0000000 --- a/agentic-harness/skills/harness-setup/references/tool-discovery.md +++ /dev/null @@ -1,101 +0,0 @@ -# Tool discovery - -How the tool-discovery step works: how to brief the search subagent, how candidates are -accepted, and how accepted tools are registered so agents and skills can use them without -hard-coding a tool name. Supplements Step 1b. - -## When it runs - -Step 0 of `harness-setup` always offers tool research as part of the plan; this step runs -when the user accepts. It can also be triggered on its own ("find tools / MCPs / plugins for -this project"), and runs equally well during an initial build or standalone against an -existing harness. Offering is automatic; running is not — and no individual tool is adopted -without a separate explicit yes. This skill ships **no catalog of recommendations** — every -candidate comes from a live search and the local configuration. - -## Step 1: Brief the search subagent - -Dispatch a search-optimized subagent and give it a tight context so its search is grounded in -this project, not generic. Use the `general-purpose` type (it has web search and fetch); run -it in the background while you continue. The brief: - -```text -You are searching for external tools — MCP servers and Claude Code plugins — that would help -this project's harness. Project context: -- Domain: {from Step 1} -- Stack / languages / frameworks: {from Step 1} -- Core task types: {creation / validation / analysis / ...} -- Pain points or repeated manual work the user mentioned: {if any} - -For each candidate, return: the ROLE it fills (e.g. "knowledge base", "language server", -"issue tracker CLI"), the concrete tool, what it does, its maturity/maintenance signal, and -its main trade-off or cost. Do not rank or recommend — just surface grounded candidates with -evidence. Prefer well-maintained, widely-used tools; flag anything experimental. -``` - -The categories are illustrative, not prescriptive — a document-heavy project might benefit -from a markup-conversion MCP, a code project from a language-server tool, a project tracked -in an external issue tracker from that tracker's CLI or MCP. What actually fits is whatever the -search and the project context turn up. - -## Step 2: Check the local configuration - -Before proposing anything, inspect what is already available in the local and session -configuration — connected MCP servers, installed plugins, CLIs on the path. The point is -twofold: don't propose a tool the project already has, and surface useful tools already -present that the harness isn't using yet. Fold both into the candidate list. - -## Step 3: Get explicit acceptance - -Present the candidates to the user, each with its role, what it does, and its trade-off. The -user **accepts or rejects each one individually**. Adopt only the accepted ones. Do not -batch-accept, and do not adopt a tool on the user's behalf because it "seems useful" — an -external tool is a dependency and a trust decision, and that decision is the user's. - -For an accepted tool that needs configuration (an MCP server, a plugin), set it up only as -far as the user authorizes, and note any credentials or installation the user must complete -themselves. - -## Step 4: Register accepted tools - -Registration and any install or uninstall is a write, so it happens only after the change -manifest is approved (`harness-setup` Step 2b). For a standalone tool run, present a -tools-only manifest and get approval before writing. - -Record accepted tools **by role** in the registry under the orchestrator: -`.claude/skills/{domain}-orchestrator/references/tools.md`. One registry per harness; the -orchestrator owns it. The schema: - -```markdown -# Tools registry - -Agents and skills reference a tool by its **role**, never by a hard tool name. When the -preferred tool is unavailable, fall back to the alternative. Reviewed on the dates below. - -| Role | Preferred tool | Alternative (if unavailable) | Status | Last reviewed | -|------|----------------|------------------------------|--------|---------------| -| knowledge-base | {accepted MCP} | built-in file search | active | {YYYY-MM-DD} | -| language-server | {accepted tool} | manual code reading | active | {YYYY-MM-DD} | -| issue-tracker | {accepted CLI} | none — note the gap | active | {YYYY-MM-DD} | -``` - -Every role needs an **alternative**, even if the alternative is "none, and here is what the -agent does without it." The alternative is what keeps the harness working when a tool is -absent or unreachable — the same graceful-degradation idea the marketplace applies to its own -optional connectors. - -## Step 5: Reference tools by role - -In an agent definition or a skill, name the **role**, not the tool. For example: "retrieve -context using the `knowledge-base` tool from the orchestrator's tools registry; if it is -unavailable, use the registered alternative." This keeps the concrete tool swappable: change -the registry row and every agent and skill follows, with no edits to their files. - -## Step 6: Periodic review - -Registered tools are not permanent. A tool can fall out of use, stop being maintained, or be -overtaken by a better option. Re-evaluate the registry periodically — whether each tool is -still earning its place, and whether a better alternative now exists — and update the `Last -reviewed` date. Assessing tool usage is a read activity that belongs to `harness-review`; -acting on it (swapping or retiring a tool) is a write that comes back here. The cadence and -the triggers are in `references/maintenance.md`. diff --git a/agentic-harness/skills/harness-setup/references/tracker-sync-template.md b/agentic-harness/skills/harness-setup/references/tracker-sync-template.md deleted file mode 100644 index 6623033..0000000 --- a/agentic-harness/skills/harness-setup/references/tracker-sync-template.md +++ /dev/null @@ -1,241 +0,0 @@ -# Tracker-sync generation templates - -What `harness-setup` generates when the process-layers gate's **sync sub-step** runs: the -project's `tracker-sync` skill, its sync config, the sync agent, the orchestrator splice, -and (when accepted) the schedule registration. The model behind every value here — lanes, -state store, fingerprints, markers, concurrency, failure rules, and the per-SaaS map — is -`${CLAUDE_PLUGIN_ROOT}/shared/tracker-sync-protocol.md`; read it before generating. - -The sub-step is offered **only when both tracker kinds are present or declared**: a -repo-native (agentic) tracker *and* a human-oriented SaaS tracker (Jira, Linear, GitHub -Issues). Its preflight, the manifest rows, and the placeholder verification are defined in -the SKILL.md (Step 0.5, Step 2b, Step 5). - -## Generation rules - -1. **Inline everything.** The generated files carry concrete values — tracker commands, the - confirmed state table, the marker spelling, the intake filter. They never reference - `${CLAUDE_PLUGIN_ROOT}` paths and never read plugin files at runtime. The one runtime - lookup the generated skill makes is its **own** `references/mapping.md` (the sync - config) and the orchestrator's `tools.md` role registry. -2. **SaaS access by role.** Every generated artifact reaches the SaaS through the - `human-tracker` role in the orchestrator's `tools.md` — never a hard tool name. If that - role is not yet registered, register it in the same manifest (the per-SaaS access path - is in the protocol doc's map). -3. **Placeholder check.** After writing, run the Step 5 placeholder verification over every - generated file — any unsubstituted `{PLACEHOLDER}` or `${CLAUDE_PLUGIN_ROOT}` reference - fails the run. -4. **Gitignore.** Add `.tracker-sync/reports/` to the project's `.gitignore` (one manifest - row). - -## Eliciting the sync config - -These values are per-project and are settled **with the user** before the Step 2b manifest; -the confirmed answers are inlined into `mapping.md`: - -- **State table.** GitHub Issues and Linear start from the protocol doc's starter tables — - present and confirm. **Jira is elicited**: when the `human-tracker` role resolves, read - the project's live statuses and transitions via the Atlassian MCP and propose the - canonical→Jira mapping; when it does not, interview the user for the project's workflow. - Either way the user confirms the table before it is written. -- **Intake filter** — the SaaS-side boundary of "this repo's issues". Jira: a JQL fragment - (typically project + label); Linear: team and/or label; GitHub: a label. Unmapped issues - outside the filter are invisible to the sync; the drift report counts them so a - mis-scoped filter is noticeable. -- **First-run backfill** — what to do with pre-existing items. `push-all-open` (every open - repo issue gets a remote projection), `new-from-now` (only issues created or changed - after setup; the cursor is initialized to setup time), or `selected` (the user picks). - **Default offer: `new-from-now`** — bulk-creating dozens of SaaS issues unannounced is - noise. The choice defines cursor initialization. -- **Designated sync branch** — default: the integration branch, normally `main`. -- **Cadence** for the scheduled drift report — default **daily on workdays**, changeable at - the manifest step. -- **Per-run item cap** — default 50. -- **Optional fields** — priority and assignee sync are **off by default**; enable only on - an explicit yes. - -## Generated skill — `.claude/skills/tracker-sync/SKILL.md` - -````markdown ---- -name: tracker-sync -description: "Keep {LOCAL_TRACKER} (the source of truth) and {SAAS} in sync. Use on 'sync the trackers', 'push issues to {SAAS}', 'import {SAAS} issues', 'tracker drift report', or when the orchestrator's integrate phase invokes it for the items just completed. Three modes: scoped (only the items touched this run), full (push + intake + reconcile), report (read-only drift report, safe headless). Not for creating or working issues — that is the orchestrator's job." -model: inherit ---- - -# Tracker sync — {LOCAL_TRACKER} ⇄ {SAAS} - -{LOCAL_TRACKER} is the **source of truth** for every synced field; {SAAS} is a projection -humans watch. Remote title/label edits are overwritten on the next push and logged — never -silently. Remote *state* changes are **proposals**, never fought: log, suspend state push -for that item, surface for adoption. All configuration — field map, state table, marker, -intake filter, branch, cadence, cap — is in `references/mapping.md`; read it first. - -Sync state lives in `.tracker-sync/` at the repo root: `map.jsonl` (the ID map, canonical -order: sorted by `local_id`, fixed key order), `cursor.json` (intake watermark only), -`conflicts.md`, `proposals.md`, and gitignored `reports/`. - -## Run modes - -| Mode | Trigger | Writes | -|---|---|---| -| `scoped` | the orchestrator's integrate write-through | pushes only the item(s) touched this run | -| `full` | on-demand / catch-up ("sync the trackers") | full push + intake + reconcile | -| `report` | the scheduled headless run, or on demand | **nothing** — drift report to `.tracker-sync/reports/` | - -`scoped` skips intake and reconcile. `report` executes every phase **read-only** and is the -only mode a headless run may use — headless runs write nothing, anywhere. - -## Phases - -1. **Preflight.** Resolve the `agentic-tracker` and `human-tracker` roles via the - orchestrator's `tools.md`; verify both answer with a cheap real call ({READY_QUERY} on - the local side, a {SAAS} ping via the role on the remote side). Role unavailable → in - `report` mode, report exactly that and exit cleanly; in write modes, stop and tell the - user. Write modes additionally require: on branch `{SYNC_BRANCH}`, `.tracker-sync/` - clean, branch up to date with its remote. -2. **Load state** — `map.jsonl`, `cursor.json`, open proposals. A missing or conflicted - cursor is not an error: delete it and fall back to a full intake re-scan deduped against - the map and the markers. -3. **Push.** Diff local fingerprints (title + canonical state + sorted namespaced labels, - normalized) against the map. Before creating a remote issue, query {SAAS} by marker - (`{MARKER_CONVENTION}`) for that `local_id` — a hit means re-link, not re-create. Update - changed items; **skip the state field for any item with an open proposal**. Description - and commit/PR links are push-only and excluded from remote fingerprints. -4. **Intake.** Scan {SAAS} within the intake filter (`{INTAKE_FILTER}`) from the cursor. - For each unmapped issue: create the local issue → append the map record - (`origin: remote`) → push the marker to the remote, in that order; skip any `remote_id` - already in the map. Advance the cursor per-item. -5. **Reconcile.** Remote title/label drift → overwrite on push + append both values to - `conflicts.md` with sources. Remote **state** drift → record a proposal in - `proposals.md` (`open`), suspend state push for that item, surface it in the report. - Remote issue deleted/archived → mark the pair `orphaned-remote`; local issue vanished → - `orphaned-local`. Orphans are terminal pending a user decision — **never auto-recreate** - in either direction. -6. **Report & commit.** Report created / updated / imported / skipped / conflicts / - proposals / orphans / rate-limit position. Write modes: commit `.tracker-sync/` changes - (`chore(tracker-sync): …`) and push with one rebase-retry; if the push still fails, stop - and report — never force. Report mode: write `.tracker-sync/reports/{date}-drift.md` - only. - -## Failure rules - -- A remote state with no canonical mapping → no-op for that item + log entry. Never guess. -- A failed {SAAS} transition → conflict-log entry + skip this run; the report names the - item and reason. No retry loops. -- Degraded description conversion is logged, never blocking. -- Per-item failure: retry once, then skip and report. Fingerprints and cursor advance only - for completed items, so re-runs pick up the skipped tail. -- Rate limits: process at most {ITEM_CAP} items per run; on a 429/limit response stop the - phase, record the position in the report, and let the next run resume. Never busy-retry. -- Proposal resolution (on user/orchestrator confirmation): `adopted` → apply the remote - state to {LOCAL_TRACKER}, mark resolved, resume state push; `declined` → mark resolved, - resume state push (the next push restores the repo state remotely). -```` - -## Generated sync config — `.claude/skills/tracker-sync/references/mapping.md` - -````markdown -# Tracker-sync config — {LOCAL_TRACKER} ⇄ {SAAS} - -Confirmed with the user on {DATE}. Edit only through `harness-setup`. - -## Access - -| Side | Role (in the orchestrator's tools.md) | Entry point | -|---|---|---| -| local | `agentic-tracker` | {LOCAL_TRACKER} — ready query `{READY_QUERY}` | -| remote | `human-tracker` | {SAAS_ACCESS_PATH} | - -## Field map - -title (push; remote edits overwritten + logged) · description (push-only) · state (push via -the table below; remote changes → proposals) · namespaced labels (push) · commit/PR links -(push-only) · priority: {on|off} · assignee: {on|off} - -## State table (confirmed) - -| Canonical | {SAAS} | -|---|---| -| ready | {…} | -| in_progress | {…} | -| blocked | {…} | -| done | {…} | -| closed | {…} | - -## Sync parameters - -| Parameter | Value | -|---|---| -| Marker convention | {MARKER_CONVENTION} | -| Intake filter | {INTAKE_FILTER} | -| Backfill choice | {push-all-open | new-from-now | selected} (cursor initialized accordingly) | -| Designated sync branch | {SYNC_BRANCH} | -| Scheduled cadence | {CADENCE} (default: daily on workdays) | -| Headless posture | **report-only** — fixed; headless runs write nothing | -| Per-run item cap | {ITEM_CAP} | -```` - -## Generated agent — `.claude/agents/tracker-sync-agent.md` - -One agent: push and pull are sequential phases over shared state, so splitting buys -nothing. Spawn it with the `general-purpose` type. - -````markdown ---- -name: tracker-sync-agent -description: Executes tracker-sync runs ({LOCAL_TRACKER} ⇄ {SAAS}) — scoped, full, or read-only report mode — for the tracker-sync skill. -model: inherit ---- - -# Tracker-sync agent - -**Core role.** Execute one tracker-sync run in the requested mode, following -`.claude/skills/tracker-sync/SKILL.md` and its `references/mapping.md` exactly. - -**Working principles.** -- Runs are idempotent: fingerprints and markers decide every write; re-running is always - safe. -- Never delete on either side; orphans are marked and reported, never reconciled silently. -- Never overwrite a human state decision — state divergence becomes a proposal, and state - push stays suspended for that item while the proposal is open. -- Record every conflict with both values and their sources; discard nothing. -- Reach {SAAS} only through the `human-tracker` role in the orchestrator's `tools.md`; - reach {LOCAL_TRACKER} through the `agentic-tracker` role. No hard-coded tool names, no - credentials anywhere in the repo. -- In `report` mode, write nothing except `.tracker-sync/reports/` — including when a role - fails to resolve: that outcome *is* the report. - -**Input.** The mode (`scoped` / `full` / `report`) and, for scoped, the local issue ID(s) -touched this run. **Output.** The run report (created / updated / imported / skipped / -conflicts / proposals / orphans / rate-limit position), and in write modes the committed -`.tracker-sync/` state. - -**Error handling.** Per-item retry once, then skip and report; stop a phase on a rate -limit; stop entirely (and say why) when a write-mode preflight fails. -```` - -## Trigger wiring - -1. **Always — orchestrator write-through.** Splice **Addendum T4** from the Tracker - coordination section of `references/orchestrator-template.md` into the generated - orchestrator, immediately after Addendum T3. It invokes `tracker-sync` in `scoped` mode - for the item(s) just written back — cheap, and keeps the projection fresh on every - completed run. -2. **Offered (manifest-gated) — scheduled drift report.** A read-only `report`-mode run on - the user's machine, default daily on workdays. One manifest row per schedule - (`register schedule`), marked **environment-level** — approving it changes the user's - machine, not the repo. Registration per venue: - - **Claude Code local scheduled agent**, where the installation supports it: register a - scheduled agent that runs `/tracker-sync report` against the repo at the confirmed - cadence. - - **Crontab**, otherwise: add a line such as - `0 9 * * 1-5 cd {REPO_PATH} && claude -p "/tracker-sync report"` - (09:00 on workdays — adjust to the confirmed cadence). - - **Unregister** is the symmetric removal (delete the scheduled agent / remove the - crontab line), also a manifest row. -3. **Documented fallback — manual.** Any mode runs on demand: in-session ("sync the - trackers", "tracker drift report") or `claude -p "/tracker-sync {mode}"`. - -**Hooks are rejected** as a trigger: a sync run is agentic, multi-step, and network-bound — -not the deterministic, fast command a hook needs to be. diff --git a/agentic-harness/skills/spec-advisor/SKILL.md b/agentic-harness/skills/spec-advisor/SKILL.md deleted file mode 100644 index 3b9cb34..0000000 --- a/agentic-harness/skills/spec-advisor/SKILL.md +++ /dev/null @@ -1,139 +0,0 @@ ---- -name: spec-advisor -description: "Detect whether a software project lacks a spec-driven development system and, if so, advise which one fits (GitHub Spec Kit, OpenSpec, BMAD-METHOD, Agent OS, Taskmaster, AWS Kiro, ADR tooling) and delegate setup to that system's own installer. Use when setting up a project's spec or planning process, when asked which spec system or SDD framework a project should use, when adopting spec-driven development, or when harness-setup detects a software project with no spec system. Scans first for any existing spec or ADR registry and stays out if one is present. Does NOT author specs itself (the installed system owns that), does NOT build the .claude/ agent harness (that is harness-setup), does NOT create Claude Code components (that is plugin-dev or skill-creator), and does NOT choose an issue or bug tracker (that is tracker-advisor)." -model: inherit ---- - -# Spec advisor — choose and set up a spec-driven development system - -When a software project has no spec-driven development (SDD) system, this skill helps the user -**choose** a fitting one and **delegates setup to that system's own installer**. It never authors -specs, PRDs, or ADRs — the installed system owns its workflow. The skill advises; it writes -nothing of its own except by running the chosen system's installer, and only after explicit -approval. - -It is offline-first. Everything needed to scan, recommend, and name an install command is in the -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 - -The "no duplication" boundary is the point of this skill, so it is worth stating as hard limits. -This skill does **not**: - -| Does NOT | Use instead | -|---|---| -| Author specs, PRDs, or ADRs | the **installed system** — it owns its workflow | -| Choose or set up an issue tracker | **tracker-advisor** | -| Build the `.claude/` agent harness (agents, skills, orchestrator) | **harness-setup** | -| Assess how well a harness is used | **harness-review** | -| Create Claude Code components (skills, agents, plugins) | **plugin-dev / skill-creator** | -| Give one-shot Claude Code automation recommendations | **claude-code-setup** | -| Push a spec system when one is already present | nothing — the scan reports and stops | -| Write to `CLAUDE.md` | nothing — the chosen system's on-disk artifacts are self-evident | - -A spec system is a *project process*, not a role-tool that agents call — so it is also kept out -of the harness `tools.md` registry. If the request is to build or change the agent harness, that -is `harness-setup`; if it is to assess one, that is `harness-review`. This skill is only about -the project's spec/planning process. - -## The flow - -Run these in order. Each gate is an off-ramp: the skill is advisory, not coercive, so a "no" -anywhere ends the run cleanly. - -### Step 0 — Scope check: is this a software project? - -SDD systems are for building software. Confirm the project is software before going further — -look for a manifest or source: `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, -`pom.xml`, a `*.csproj`, `Gemfile`, and the like. If the project is not software (docs, content, -data, ops config with no codebase), explain briefly that an SDD system is not the right tool and -**stop**. Recommending one here would be pushing a process the project has no use for. - -### Step 1 — Scan first: is a spec system already present? - -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 -scan writes nothing. The disambiguation rules (the shared `requirements/design/tasks` triple -resolved by parent directory; BMAD v4 vs v6; ADR signals) are in that reference — apply them -before concluding. - -### Step 2 — Opt-in gate: offer a recommendation - -If no system is found, offer to recommend one. This is the opt-in gate: a "no" ends the run -cleanly. Offering is the default; nothing past this point happens without the user's yes. - -### Step 3 — Profile for fit - -A good recommendation depends on the project's shape, so gather a few quick signals — by asking, -or by inferring from what Step 0 already saw: - -- **Greenfield or brownfield** — a fresh repo tolerates a heavier pipeline; an existing codebase - usually wants lighter, change-scoped specs. -- **Solo or team** — team workflows benefit from approval steps and named roles; a solo dev - rarely wants the ceremony. -- **Process appetite** — anywhere from lightweight decision records (ADRs) to a full agile - pipeline with personas. -- **Agent or IDE already in use** — an IDE/AWS commitment points one way (Kiro); a Claude - Code-centric flow points another. - -### Step 4 — Recommend (offline) - -From the curated shortlist and the **selection decision tree** in `references/spec-systems.md`, -present **2–3 best-fit candidates** with rationale — not a single verdict. Before finalizing, -**offer** the opt-in discovery search (a broad "is there anything newer than the shortlist?" web -search); run it **only on an explicit yes**, and if it stalls or the environment is offline, fall -back silently to the curated data. Then the **user picks one explicitly**. Do not choose on their -behalf. - -### Step 5 — Delegate setup - -For the selected system: - -1. **Optionally fetch current setup details** from that system's **official repository** (the URL - in its profile) — install command and docs. This is the authoritative fetch (online form b), - a precise pull from the canonical source, not a broad search. Skip it offline and use the - curated install command. -2. **Present the install command and get explicit approval before executing it.** An install is - an exec-and-write — it changes the user's repo and environment — so it is gated exactly like - harness-setup's change manifest. State the command, what it will create, and where. -3. **Run or guide the system's own installer.** Then **confirm what was created and where**. -4. **Never author specs.** Once the system is installed, its own workflow takes over. The skill's - job ends at a working, confirmed install. - -**IDE special case — AWS Kiro.** Kiro is an IDE, not a repo package. A skill cannot install an -IDE into a repository, so for Kiro this is **detect-and-advise only**: explain what it is, point -the user at the official source (kiro.dev), and stop. Do not run an installer or hand-scaffold -`.kiro/`. The Kiro caveat in `references/spec-systems.md` has the detail. - -## Error handling and graceful degradation - -- **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 `${CLAUDE_PLUGIN_ROOT}/shared/detection-signatures.md`); if still ambiguous, - report exactly what was found and ask, rather than guessing the system. -- **Installer failure** — apply the failure contract: - 1. **Report plainly** — the command run, the error, and 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. - 2. **Record nothing** — a failed install leaves no coordination context; the project still - counts as having no spec system. - 3. **Leave a clean retry path** — name any artifacts the failed installer left behind so the - user can remove them and retry; do not delete them without the user's say-so. - 4. **Tell the caller** — when invoked from `harness-setup`, state the outcome explicitly: - "install failed — proceed as if no system is present," so nothing downstream assumes the - system exists. -- **User declines at any gate** — stop cleanly. The skill is advisory; an off-ramp taken is a - valid outcome, not a failure. - -## References - -- `${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 deleted file mode 100644 index 31e3995..0000000 --- a/agentic-harness/skills/spec-advisor/references/spec-systems.md +++ /dev/null @@ -1,126 +0,0 @@ -# Spec systems — curated profiles - -The recommend-and-delegate knowledge behind flow Steps 4 and 5. One profile per system in the -curated shortlist, then the selection decision tree, the Kiro/IDE caveat, and the online policy. - -These are the facts the skill reasons over offline. Treat install commands and URLs as -load-bearing: when a system is **selected** (not before), the official-repo fetch in flow Step 5 -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 -- **Official repo:** github.com/github/spec-kit -- **Install (into repo):** `uv tool install specify-cli --from git+https://github.com/github/spec-kit.git` then `specify init .` -- **On-disk artifacts:** `.specify/`, `specs//{spec,plan,tasks}.md` -- **Philosophy / stages:** specify → plan → tasks; an agent-agnostic, prompt-driven spec workflow. -- **Claude Code affinity:** high — designed to drive coding agents, Claude Code included. -- **Maturity:** the most widely adopted of the shortlist; active. -- **Best-fit:** a popular agent-agnostic standard; greenfield or feature-driven work. - -### OpenSpec -- **Official repo:** github.com/Fission-AI/OpenSpec -- **Install (into repo):** `npm i -g @fission-ai/openspec` then `openspec init` -- **On-disk artifacts:** `openspec/` with `changes/`, `specs/`, `config.yaml` -- **Philosophy / stages:** lightweight change-proposal specs — propose a change, settle it into a capability spec. -- **Claude Code affinity:** good; CLI-driven, fits an agent loop. -- **Maturity:** newer, focused; active. -- **Best-fit:** brownfield work where a full pipeline is too heavy and change-scoped specs fit better. - -### BMAD-METHOD -- **Official repo:** github.com/bmad-code-org/BMAD-METHOD -- **Install (into repo):** `npx bmad-method install` -- **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 `${CLAUDE_PLUGIN_ROOT}/shared/detection-signatures.md`). -- **Best-fit:** teams that want a full, ceremony-rich agile workflow; greenfield-leaning. - -### Agent OS -- **Official repo:** github.com/buildermethods/agent-os -- **Install (into repo):** a base install script (`base-install.sh`) followed by a per-project install. -- **On-disk artifacts:** `agent-os/` (v2) or `.agent-os/` (v1); `standards/`, `specs/` -- **Philosophy / stages:** standards governance (coding standards, best practices) plus light specs. -- **Claude Code affinity:** good; standards-as-context fits agent prompting. -- **Maturity:** active. -- **Best-fit:** an existing team that wants standards/governance with a lighter spec layer than BMAD. - -### Taskmaster -- **Official repo:** github.com/eyaltoledano/claude-task-master -- **Install (into repo):** `npx -y task-master-ai` (also available as an MCP server). -- **On-disk artifacts:** `.taskmaster/` with `docs/prd.txt`, `tasks/tasks.json` -- **Philosophy / stages:** parse a PRD into a task graph, then track and expand tasks. -- **Claude Code affinity:** high — built for agent task execution; MCP option integrates directly. -- **Maturity:** active and popular. -- **Best-fit:** task decomposition and tracking. It **pairs** with a spec system rather than replacing one — recommend it *alongside* a spec tool when the need is breaking an existing spec into trackable work. For general issue/bug intake (not spec-derived tasks), the tracker shortlist is `tracker-advisor`'s concern. - -### spec-workflow-mcp -- **Official repo:** github.com/Pimzino/spec-workflow-mcp -- **Install (into repo):** `claude mcp add-json …` (registered as an MCP server). -- **On-disk artifacts:** `.spec-workflow/` with `specs/`, `steering/` -- **Philosophy / stages:** a spec workflow surfaced through MCP, with an approval dashboard and steering documents. -- **Claude Code affinity:** high — it is an MCP server, so it plugs into Claude Code natively. -- **Maturity:** active. -- **Best-fit:** teams who want the spec workflow exposed as MCP tooling with an explicit approval step. - -### AWS Kiro — IDE, advise only -- **Official source:** kiro.dev -- **Install:** **none into the repo.** Kiro is an IDE. Do **not** attempt a repo install — see the Kiro caveat below. -- **On-disk artifacts:** `.kiro/specs//{requirements,design,tasks}.md`, `.kiro/steering/` -- **Philosophy / stages:** EARS-style requirements → design → tasks, authored inside the Kiro IDE. -- **Claude Code affinity:** orthogonal — it is a different editor/agent surface, not a Claude Code add-on. -- **Maturity:** AWS-backed. -- **Best-fit:** teams committed to an IDE/AWS workflow who want EARS requirements. Detect-and-advise only. - -### ADR tooling -- **Official repos:** github.com/thomvaill/log4brains · github.com/npryce/adr-tools -- **Install (into repo):** log4brains — `npm i -g log4brains` then `log4brains init`; adr-tools — `adr init`. -- **On-disk artifacts:** `docs/adr/`, `.adr-dir`, `.log4brains.yml` -- **Philosophy / stages:** Architecture Decision Records — short, append-only decision logs. Not a full spec process. -- **Claude Code affinity:** neutral; plain markdown an agent can read and append. -- **Maturity:** both established. -- **Best-fit:** projects that want lightweight **decision records only**, with no full spec pipeline. - -## Selection decision tree - -Walk this top-down with the profile gathered in flow Step 3; the first match that fits wins, and -present 2–3 candidates with rationale rather than a single verdict. - -1. **Committed to an IDE / AWS workflow, want EARS?** → AWS Kiro — **advise only** (see caveat). -2. **Want decision records only, no full spec process?** → an ADR registry (log4brains, or adr-tools). -3. **Want a popular, agent-agnostic standard?** → GitHub Spec Kit. -4. **Brownfield, want lightweight change-proposal specs?** → OpenSpec. -5. **Want a heavy agile pipeline with agent personas?** → BMAD-METHOD. -6. **Want standards governance with a light spec layer?** → Agent OS. -7. **Want the workflow surfaced as MCP with an approval dashboard?** → spec-workflow-mcp. -8. **Need task decomposition over an existing/already-chosen spec?** → Taskmaster, **paired** with the spec tool above (it complements, it does not replace). - -## Kiro / IDE caveat - -Kiro is an **IDE**, not a repository package. A Claude Code skill cannot install an IDE into a -repo, and pretending to would leave the project in a half-configured state. So for Kiro the skill -is **detect-and-advise only**: explain what Kiro is, point the user at the official source -(kiro.dev), and stop. Do not run an installer, do not scaffold `.kiro/` by hand. The same rule -applies to any future IDE-bound option: if setup means "install an editor," advise, do not install. - -## Online policy - -The default is **fully offline** — everything above is enough to scan, profile, recommend, and -name an install command without touching the network. Online access is never automatic and takes -exactly two narrow forms: - -- **(a) Discovery search** — a broad "is there anything new, or a newer option than the shortlist?" - web search. **Offer** it before finalizing a recommendation; run it **only on an explicit yes**. - If it stalls or the environment is offline, fall back silently to the curated data above. -- **(b) Authoritative fetch** — once the user **selects** a system, fetch its current setup details - (install command, docs) from **that system's official repository** — the URL in its profile - above — not a broad search. This is a precise fetch from the canonical source, the lean way to - confirm the command is current before you ask for approval to run it. - -Neither form runs on its own. The offline path is complete; online is opt-in and additive. diff --git a/agentic-harness/skills/tracker-advisor/SKILL.md b/agentic-harness/skills/tracker-advisor/SKILL.md deleted file mode 100644 index 5ab1895..0000000 --- a/agentic-harness/skills/tracker-advisor/SKILL.md +++ /dev/null @@ -1,152 +0,0 @@ ---- -name: tracker-advisor -description: "Detect whether a software project lacks an issue tracker suited to agentic work and, if so, advise which one fits (Beads, Backlog.md, git-bug, git-issues, Beans, or GitHub Issues, Linear, Jira via their official access paths) and delegate setup to that system's own installer. Use when choosing or setting up a project's issue, bug, or work tracker, when asked how agents should pull ready work or record work state, or when harness-setup detects a software project with no tracker. Scans first and stays out if a tracker is already present. Does NOT author, triage, or groom issues (the installed tracker owns that), does NOT choose a spec system or spec-derived task decomposition such as Taskmaster (that is spec-advisor), does NOT build the .claude/ agent harness (that is harness-setup), and does NOT sync two trackers with each other (harness-setup generates that, via its dual-tracker sync sub-step)." -model: inherit ---- - -# Tracker advisor — choose and set up an agent-suited issue tracker - -When a software project has no issue tracker that agents can work — no place to pull ready work -from or write work state back to — this skill helps the user **choose** a fitting one and -**delegates setup to that system's own installer**. It never authors, triages, or grooms issues — -the installed tracker owns its workflow. The skill advises; it writes nothing of its own except -by running the chosen system's installer, and only after explicit approval. - -It is offline-first. Everything needed to scan, recommend, and name an install command is in the -curated reference and the shared detection signatures; the network is reached only with the -user's say-so (see the online policy in `references/tracker-systems.md`). - -## What this skill is not — and which skill to use instead - -The "no duplication" boundary is the point of this skill, so it is worth stating as hard limits. -This skill does **not**: - -| Does NOT | Use instead | -|---|---| -| Author, triage, or groom issues | the **installed tracker** — it owns its workflow | -| Choose a spec system, or spec-derived task decomposition (Taskmaster) | **spec-advisor** | -| Build the `.claude/` agent harness (agents, skills, orchestrator) | **harness-setup** | -| Assess how well a harness is used | **harness-review** | -| Create Claude Code components (skills, agents, plugins) | **plugin-dev / skill-creator** | -| Keep two trackers in sync (repo-native ⇄ Jira/Linear/GitHub Issues) | **harness-setup** — its dual-tracker sync sub-step generates the project's `tracker-sync` skill | -| Push a tracker when one is already present | nothing — the scan reports and stops | -| Write to `CLAUDE.md` | nothing — the chosen system's on-disk artifacts are self-evident | - -A tracker is a *project process*, not a role-tool that agents call ad hoc — so, like a spec -system, it is kept out of the harness `tools.md` registry. If the request is to build or change -the agent harness, that is `harness-setup`; if it is to assess one, that is `harness-review`. -This skill is only about choosing and standing up the project's issue-tracking process. - -## The flow - -Run these in order. Each gate is an off-ramp: the skill is advisory, not coercive, so a "no" -anywhere ends the run cleanly. - -### Step 0 — Scope check: is this a software project? - -These trackers are built for software work. Confirm the project is software before going -further — look for a manifest or source: `package.json`, `pyproject.toml`, `go.mod`, -`Cargo.toml`, `pom.xml`, a `*.csproj`, `Gemfile`, and the like. If the project is not software -(docs, content, data, ops config with no codebase), explain briefly that an agent-oriented issue -tracker is not the right tool and **stop**. - -### Step 1 — Scan first: is a tracker already present? - -Using `${CLAUDE_PLUGIN_ROOT}/shared/detection-signatures.md` (the issue-trackers table), scan -for any existing tracker. **If one is found, report what is present and where, then stop.** Do -not push a second tracker on top of one already in use — stacking trackers splits the work -state, exactly the duplication this skill exists to avoid. This is a read-only report; the scan -writes nothing. Three signals need their rules from that reference before concluding: - -- **git-bug is not a path** — check `git for-each-ref refs/bugs` (rule: issue trackers table). -- **`.github/ISSUE_TEMPLATE/` is a weak signal** — report "GitHub Issues appears to be in use" - and **ask** whether it is the active tracker; if yes, stop (it is agent-reachable via `gh`); - if no, continue (rule 5). -- **Taskmaster is spec-derived, not a general tracker** — report that spec-derived task - tracking is covered, and continue only if the user explicitly wants a general issue tracker - alongside it (rule 6). - -### Step 2 — Opt-in gate: offer a recommendation - -If no tracker is found, offer to recommend one. This is the opt-in gate: a "no" ends the run -cleanly. Offering is the default; nothing past this point happens without the user's yes. - -### Step 3 — Profile for fit - -A good recommendation depends on how the work runs, so gather a few quick signals — by asking, -or by inferring from what Step 0 already saw: - -- **Single agent or concurrent agents** — concurrent work needs collision-safe IDs and a - ready-work queue (Beads's home ground); a single agent tolerates anything. -- **Dependency-graph need** — does work block other work in ways agents must query, or is a - flat list enough? -- **Human surface** — do humans want a kanban/board view (Backlog.md), or is the CLI enough? -- **Existing SaaS commitment** — a team already living in GitHub Issues, Linear, or Jira points - at the advise-only profiles, not a new tool. -- **Git-purist vs MCP appetite** — issues as git objects (git-bug) vs markdown files vs an MCP - surface. - -### Step 4 — Recommend (offline) - -From the curated shortlist and the **selection decision tree** in -`references/tracker-systems.md`, present **2–3 best-fit candidates** with rationale — not a -single verdict. Flag the early-stage entries (git-issues, Beans) as such. Before finalizing, -**offer** the opt-in discovery search (a broad "is there anything newer than the shortlist?" web -search); run it **only on an explicit yes**, and if it stalls or the environment is offline, -fall back silently to the curated data. Then the **user picks one explicitly**. Do not choose on -their behalf. - -### Step 5 — Delegate setup - -For the selected system: - -1. **Optionally fetch current setup details** from that system's **official repository** (the - URL in its profile) — install command and docs. This is the authoritative fetch (online form - b), a precise pull from the canonical source, not a broad search. Skip it offline and use the - curated install command. For the early-stage entries it is strongly recommended. -2. **Present the install command and get explicit approval before executing it.** An install is - an exec-and-write — it changes the user's repo and environment — so it is gated exactly like - harness-setup's change manifest. State the command, what it will create, and where. -3. **Run or guide the system's own installer.** Then **confirm what was created and where**. -4. **Never author issues.** Once the tracker is installed, its own workflow takes over. The - skill's job ends at a working, confirmed install. - -**SaaS special case — GitHub Issues, Linear, Jira.** These are services, not repo packages, so -they are **detect-and-advise only**: explain the option, name the official access path (`gh`; -the vendor MCP servers), and stop — configuring credentials is the user's call. For Linear, -Jira, and GitHub Issues, note that a repo-native tracker can be kept in sync with them: -`harness-setup` generates that (its dual-tracker sync sub-step, model in -`${CLAUDE_PLUGIN_ROOT}/shared/tracker-sync-protocol.md`) — name it and stop; this skill does -not set it up. The SaaS/MCP caveat in `references/tracker-systems.md` has the detail. - -## Error handling and graceful degradation - -- **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** — apply the disambiguation rules in - `${CLAUDE_PLUGIN_ROOT}/shared/detection-signatures.md` (bare `backlog/`, the ISSUE_TEMPLATE - weak signal, Taskmaster); if still ambiguous, report exactly what was found and ask, rather - than guessing the system. -- **Installer failure** — apply the failure contract: - 1. **Report plainly** — the command run, the error, and 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. - 2. **Record nothing** — a failed install leaves no coordination context; the project still - counts as having no tracker. - 3. **Leave a clean retry path** — name any artifacts the failed installer left behind so the - user can remove them and retry; do not delete them without the user's say-so. - 4. **Tell the caller** — when invoked from `harness-setup`, state the outcome explicitly: - "install failed — proceed as if no system is present," so nothing downstream assumes the - tracker exists. -- **User declines at any gate** — stop cleanly. The skill is advisory; an off-ramp taken is a - valid outcome, not a failure. - -## References - -- `${CLAUDE_PLUGIN_ROOT}/shared/detection-signatures.md` — the scan-first knowledge: the - issue-trackers path→system table (plus the git-bug ref check) and the disambiguation rules - (bare `backlog/`, ISSUE_TEMPLATE weak signal, Taskmaster boundary). Shared with - `spec-advisor` and `harness-setup`. -- `references/tracker-systems.md` — the per-system profiles (official repo/docs URL, install - command, philosophy, agent affinity, maturity, best-fit), the selection decision tree, the - SaaS/MCP caveat, and the online policy. diff --git a/agentic-harness/skills/tracker-advisor/references/tracker-systems.md b/agentic-harness/skills/tracker-advisor/references/tracker-systems.md deleted file mode 100644 index eb8cfc0..0000000 --- a/agentic-harness/skills/tracker-advisor/references/tracker-systems.md +++ /dev/null @@ -1,132 +0,0 @@ -# Issue trackers — curated profiles - -The recommend-and-delegate knowledge behind flow Steps 4 and 5. One profile per tracker in the -curated shortlist, then the selection decision tree, the SaaS/MCP caveat, and the online policy. - -These are the facts the skill reasons over offline. Treat install commands and URLs as -load-bearing: when a tracker is **selected** (not before), the official-repo fetch in flow Step 5 -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 trackers once it is installed -(the phase-0 ready-work pull, the status write-back, and the per-tracker command map), see -`${CLAUDE_PLUGIN_ROOT}/shared/tracker-coordination.md` — that is `harness-setup`'s concern, not -this skill's. - -## Per-system profiles - -### Beads (`bd`) -- **Official repo:** github.com/steveyegge/beads -- **Install (into repo):** `brew install beads` or `npm install -g @beads/bd`, then `bd` init in the repo. `bd setup claude` wires the Claude Code integration. -- **On-disk artifacts:** `.beads/` (embedded Dolt database plus a git-synced `issues.jsonl` export) -- **Philosophy:** a graph-based, git-backed issue database built as working memory for coding agents — dependency types (blocks, parent/child, related, discovered-from), `bd ready --json` for unblocked work, hash-based IDs that survive concurrent branches. -- **Agent affinity:** highest of the shortlist — ready-work queries, atomic claim, multi-agent-safe IDs, JSON everywhere. -- **Maturity:** v1.x, actively maintained; license GPL-3.0. -- **Best-fit:** multi-agent concurrency, dependency-heavy work, high-volume task creation. - -### Backlog.md -- **Official repo:** github.com/MrLesk/Backlog.md -- **Install (into repo):** `npm i -g backlog.md` (or `bun add -g backlog.md`, `brew install backlog-md`), then `backlog init` -- **On-disk artifacts:** `backlog/` (or `.backlog/`) containing `config.yml` and markdown task files -- **Philosophy:** markdown-native tasks in git — one diffable file per task — with a CLI (`backlog task create/edit/list`), a terminal/web kanban board, and a bundled MCP server (`backlog mcp start`). -- **Agent affinity:** high — first-class MCP support and a clean CLI; tasks stay human-readable. -- **Maturity:** actively maintained, frequent releases; license MIT. -- **Best-fit:** solo devs or small teams who want a human-browsable kanban over plain markdown, with agents working the same files. - -### git-bug -- **Official repo:** github.com/git-bug/git-bug -- **Install (into repo):** install the binary (releases or package manager); issues then live in the repo itself — no init scaffolding in the working tree. -- **On-disk artifacts:** none in the working tree — issues are **git objects** under the `refs/bugs/` namespace (detect with `git for-each-ref refs/bugs`). -- **Philosophy:** distributed, offline-first bug tracking embedded in git, with CLI/TUI/web interfaces and bridges to GitHub and GitLab. -- **Agent affinity:** medium — solid CLI (`git bug add`, `git bug ls`), but no ready-work/dependency model and the object storage is less directly inspectable than files. -- **Maturity:** long-lived project, maintained at a slower cadence; license GPL-3.0. -- **Best-fit:** pure-git purists who want issues to travel with clones and bridge to a forge. - -### git-issues — early-stage -- **Official repo:** github.com/git-issues/git-issues -- **Install (into repo):** single Go binary; issues live as YAML-frontmatter markdown in `.issues/` -- **Philosophy:** the minimal agent loop — `issues next` → `issues claim` → `issues done` — plus a TUI board for humans and a generated `.agent.md` context file. -- **Agent affinity:** high in design (the next/claim/done verbs are agent-shaped), small in surface. -- **Maturity:** **young — no formal releases yet.** Confirm current state at the official repo before recommending; present it as an early-stage option, not an established one. License LGPL-2.1. -- **Best-fit:** minimal-footprint projects that want exactly the claim/done loop and nothing else. - -### Beans — early-stage -- **Official repo:** github.com/hmans/beans -- **Install (into repo):** `brew install hmans/beans/beans` or `go install github.com/hmans/beans@latest`, then `beans init` -- **On-disk artifacts:** `.beans/` with `.beans.yml` -- **Philosophy:** flat-file markdown issues with a built-in GraphQL query engine, so agents pull exactly the fields they need; archived issues double as project memory. -- **Agent affinity:** high in design — token-efficient structured queries over plain files. -- **Maturity:** **v0.x, under heavy development — APIs may change.** Present as early-stage. License Apache-2.0. -- **Best-fit:** small projects that value token-efficient structured queries over ecosystem maturity. - -### GitHub Issues — SaaS, advise only -- **Official source:** github.com (CLI: cli.github.com) -- **Install:** **none into the repo.** If the project is hosted on GitHub, the tracker already exists; agent access is `gh issue list --json …`, `gh issue create`, `gh issue close`, `gh issue comment` (authenticated `gh`). -- **Philosophy:** the forge's native tracker — deep PR/commit context, team-visible, zero extra tooling. -- **Agent affinity:** good via `gh` JSON output; no dependency graph or ready-work model. -- **Best-fit:** GitHub-hosted teams who want one tracker humans and agents share, with no new tool. - -### Linear — SaaS via MCP, advise only -- **Official source:** linear.app (MCP server: mcp.linear.app, vendor-provided) -- **Install:** **none into the repo.** Agent access is the official MCP server: `claude mcp add --transport http linear-server https://mcp.linear.app/mcp`, then authenticate via `/mcp`. -- **Philosophy:** a modern human-oriented tracker; the MCP server exposes issue search/create/update to agents. -- **Agent affinity:** good when the MCP server is configured; cloud-dependent, not git-managed. -- **Best-fit:** teams already running on Linear. A repo-native tracker can still be added for agent-side work — keeping the two in sync is a planned future capability of this plugin, not this skill. - -### Jira — SaaS via MCP, advise only -- **Official source:** atlassian.com (MCP: the Atlassian remote MCP server at mcp.atlassian.com, vendor-provided) -- **Install:** **none into the repo.** Agent access is the official Atlassian MCP server (added via `mcp-remote` to `https://mcp.atlassian.com/v1/sse`), OAuth-scoped to the user's own permissions. -- **Philosophy:** the enterprise standard — rich custom workflows, heavyweight for small teams. -- **Agent affinity:** workable via MCP; workflows are per-project custom, so agents must read them, not assume them. -- **Best-fit:** organizations already committed to Jira. As with Linear, dual-tracker sync with a repo-native tracker is a planned future capability of this plugin. - -### Taskmaster — boundary note, not a profile -Taskmaster (`.taskmaster/`) is **spec-derived task decomposition** — it parses a PRD into a task -graph and tracks those tasks. It belongs to the spec process and sits in `spec-advisor`'s -shortlist, not this one. If the need is "break the spec into trackable work," route to -`spec-advisor`; if Taskmaster is already present, see disambiguation rule 6 in -`${CLAUDE_PLUGIN_ROOT}/shared/detection-signatures.md`. - -## Selection decision tree - -Walk this top-down with the profile gathered in flow Step 3; the first match that fits wins, and -present 2–3 candidates with rationale rather than a single verdict. - -1. **Already committed to GitHub Issues / Linear / Jira as the team's tracker?** → that SaaS - profile — **advise only** (see caveat); for Linear/Jira mention the planned dual-tracker sync - path. -2. **Multiple agents working concurrently, or dependency-graph needs?** → Beads. -3. **Want a human-browsable kanban over plain markdown files?** → Backlog.md. -4. **Want issues as pure git objects that travel with clones, with forge bridges?** → git-bug. -5. **Want the most minimal claim/done loop, comfortable with early-stage tools?** → git-issues - or Beans (flag both as early-stage). -6. **Only need spec-derived task decomposition?** → that is Taskmaster — route to - `spec-advisor`. - -## SaaS / MCP caveat - -GitHub Issues, Linear, and Jira are **services**, not repository packages. A Claude Code skill -cannot install a SaaS into a repo, and scaffolding fake local state for one would be worse than -doing nothing. So for these the skill is **detect-and-advise only**: explain the option, point at -the official access path (`gh` for GitHub; the vendor MCP servers for Linear and Jira), and stop. -Configuring an MCP server is the user's call under their own credentials — name the official -command, do not run authentication flows for them. The same rule applies to any future SaaS -option: if setup means "sign into a service," advise, do not install. - -## Online policy - -The default is **fully offline** — everything above is enough to scan, profile, recommend, and -name an install command without touching the network. Online access is never automatic and takes -exactly two narrow forms: - -- **(a) Discovery search** — a broad "is there anything new, or a newer option than the shortlist?" - web search. **Offer** it before finalizing a recommendation; run it **only on an explicit yes**. - If it stalls or the environment is offline, fall back silently to the curated data above. -- **(b) Authoritative fetch** — once the user **selects** a system, fetch its current setup details - (install command, docs) from **that system's official repository** — the URL in its profile - above — not a broad search. This is a precise fetch from the canonical source, the lean way to - confirm the command is current before you ask for approval to run it. For the early-stage - entries (git-issues, Beans) this fetch is **strongly recommended**, since young tools change - fast. - -Neither form runs on its own. The offline path is complete; online is opt-in and additive.