diff --git a/agentic-harness/.claude-plugin/plugin.json b/agentic-harness/.claude-plugin/plugin.json index eb311ed..b53e9a5 100644 --- a/agentic-harness/.claude-plugin/plugin.json +++ b/agentic-harness/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agentic-harness", - "version": "0.5.0", + "version": "0.6.0", "description": "Stand up, assess, and maintain an agentic harness in an existing repo. A meta-tool that generates project-specific agent teams and the skills they use, then assesses how effectively they are used. When a spec-driven development system is present, the generated orchestrator coordinates with it — activating the spec workflow and resuming on hand-back. Three skills: harness-setup (build, extend, maintain), harness-review (read-only assessment), and spec-advisor (advise and delegate setup of a spec-driven development system).", "author": { "name": "MrBogomips", diff --git a/agentic-harness/README.md b/agentic-harness/README.md index c76aa38..4bce3a1 100644 --- a/agentic-harness/README.md +++ b/agentic-harness/README.md @@ -6,7 +6,7 @@ This plugin does not do your domain work. It builds and maintains the agents and ## The three 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`. Also extends an existing harness, applies a review context, and records every change. +- **`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. diff --git a/agentic-harness/shared/claude-md-pointer.md b/agentic-harness/shared/claude-md-pointer.md index 6a9f75b..a5d8a96 100644 --- a/agentic-harness/shared/claude-md-pointer.md +++ b/agentic-harness/shared/claude-md-pointer.md @@ -11,13 +11,16 @@ project's `CLAUDE.md`. It carries three things — plus, when the project has an spec-driven development (SDD) system, one line recording how the orchestrator coordinates with it: 1. The harness's **goal**, in one line. -2. The **trigger rule** — which orchestrator skill to use, and for which kind of request. +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. -This is enough for a fresh session: the trigger rule routes domain requests to the -orchestrator, and the orchestrator handles the rest from the files under `.claude/`. +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 @@ -29,8 +32,11 @@ orchestrator, and the orchestrator handles the rest from the files under `.claud **Spec process:** {system} ({version}) — orchestrator activates it for {owned segment}; hand-back via {contract}. *(omit this line entirely when no SDD system is present)* -**Trigger:** For {domain} work, use the `{orchestrator-skill-name}` skill. Answer simple -questions directly. +**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 | @@ -38,10 +44,26 @@ questions directly. | {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 line records the **coordination relationship**, not the spec contents — the requirements, plan, and tasks stay in the SDD system's own files. The full coordination model is in `${CLAUDE_PLUGIN_ROOT}/shared/sdd-coordination.md`. +### When the repo has more than one harness + +Write the hard-gate sentence **once**, as a shared routing preamble above the per-domain sections — +"Before responding to any request, invoke the orchestrator whose domain matches it; if none matches, +answer directly" — and keep each `## Harness: {domain}` section to its goal, an **Orchestrator:** +`{orchestrator-skill-name}` line (so the preamble can resolve domain → orchestrator), its +spec-process line, and change history. Do not repeat "invoke *this* orchestrator before any prompt" +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`: diff --git a/agentic-harness/shared/harness-model.md b/agentic-harness/shared/harness-model.md index ab925e5..8bb8135 100644 --- a/agentic-harness/shared/harness-model.md +++ b/agentic-harness/shared/harness-model.md @@ -50,6 +50,6 @@ the harness. 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 trigger rule — see -`claude-md-pointer.md`. Nothing in the harness duplicates what the file system already +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/skills/harness-review/SKILL.md b/agentic-harness/skills/harness-review/SKILL.md index 92510ba..a2ac209 100644 --- a/agentic-harness/skills/harness-review/SKILL.md +++ b/agentic-harness/skills/harness-review/SKILL.md @@ -41,9 +41,10 @@ for read-only inventory — the prose above still governs it; run nothing that m ## Step 2: Read the record -Read the harness section of `CLAUDE.md` — the goal, the trigger rule, 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. +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 @@ -65,14 +66,18 @@ fixed, deterministic signal set — read each, infer nothing you cannot ground i - **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 trigger rule is current and - what has been changing. +- **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). Apply the same lens +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 — diff --git a/agentic-harness/skills/harness-review/references/usage-assessment.md b/agentic-harness/skills/harness-review/references/usage-assessment.md index fc3ab8e..d69738f 100644 --- a/agentic-harness/skills/harness-review/references/usage-assessment.md +++ b/agentic-harness/skills/harness-review/references/usage-assessment.md @@ -30,9 +30,10 @@ recorded how work actually happens. What to look for: ## Signal 2: the CLAUDE.md pointer and change history -Read the harness section of `CLAUDE.md`. The pointer's trigger rule tells you what *should* -route to the orchestrator; compare it against how the project actually describes its work -(Signal 1). The change-history table tells you the evolution: +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. diff --git a/agentic-harness/skills/harness-setup/SKILL.md b/agentic-harness/skills/harness-setup/SKILL.md index 7cd3dc2..594a81a 100644 --- a/agentic-harness/skills/harness-setup/SKILL.md +++ b/agentic-harness/skills/harness-setup/SKILL.md @@ -213,11 +213,17 @@ hybrid modes — with data-passing, error handling, and test scenarios — are i Build into the orchestrator: -- **A context-check first phase** so it distinguishes an initial run from a follow-up or a - partial re-run (branch on whether `_agents_workspace/` already exists). -- **Follow-up trigger keywords** in its description ("re-run", "update", "modify", - "supplement", "improve the previous result", and everyday domain phrasings). Without - these, the harness goes unused after its first run. +- **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 @@ -237,9 +243,10 @@ When extending rather than building new, modify the existing orchestrator — do second one. Reflect a new agent in the team composition, task assignment, data flow, and trigger keywords. -Then **register the pointer** in the project's `CLAUDE.md`: goal, trigger rule, 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`. +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 @@ -273,13 +280,16 @@ Before calling a setup or change complete: - [ ] 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 does a context check (initial / follow-up / partial). +- [ ] 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/`. -- [ ] The `CLAUDE.md` pointer is registered (goal + trigger + change history; plus the spec-process - line when an SDD system is present). +- [ ] The `CLAUDE.md` pointer is registered (goal + entry-point directive (hard gate) + change + history; plus the spec-process line when an SDD system is present). - [ ] The change-history table records this change. - [ ] The user was asked whether to run tool research (and, on an existing harness, tool maintenance), and the answer was recorded — whatever they chose. diff --git a/agentic-harness/skills/harness-setup/references/maintenance.md b/agentic-harness/skills/harness-setup/references/maintenance.md index a105d0d..1885479 100644 --- a/agentic-harness/skills/harness-setup/references/maintenance.md +++ b/agentic-harness/skills/harness-setup/references/maintenance.md @@ -68,6 +68,7 @@ Different feedback lands in different places. Route by type: | 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. @@ -78,7 +79,10 @@ 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. +- 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. diff --git a/agentic-harness/skills/harness-setup/references/orchestrator-template.md b/agentic-harness/skills/harness-setup/references/orchestrator-template.md index 4abbacf..ac209b5 100644 --- a/agentic-harness/skills/harness-setup/references/orchestrator-template.md +++ b/agentic-harness/skills/harness-setup/references/orchestrator-template.md @@ -29,7 +29,7 @@ The first choice when two or more agents need to talk while they work. Build the ````markdown --- name: {domain}-orchestrator -description: "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." +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 --- @@ -48,8 +48,13 @@ Coordinates the {domain} agent team to produce {final deliverable}. ## Workflow -### Phase 0: context check -Branch on whether prior work exists: +### 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. @@ -119,7 +124,7 @@ with the `Agent` tool and collect return values. ````markdown --- name: {domain}-orchestrator -description: "Coordinates {domain} agents to produce {deliverable}. {initial keywords} + follow-up keywords." +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 --- @@ -133,8 +138,10 @@ model: inherit ## Workflow -### Phase 0: context check -Same branch as Template A — on whether `_agents_workspace/` exists. +### 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). @@ -171,7 +178,7 @@ phase. ````markdown --- name: {domain}-orchestrator -description: "{domain} orchestrator (hybrid). {keywords} + follow-up keywords." +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 --- @@ -179,10 +186,15 @@ model: inherit | 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`. @@ -215,7 +227,8 @@ Mark every phase as either delegated (`→ SDD: {system}`) or orchestrator-owned twice. Reference the SDD's artifacts in place — never copy them into `_agents_workspace/`. ### Addendum 1 — phase 0 (context check): locate, then activate the spec -Add to the context-check phase, before going to prepare: +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 @@ -251,8 +264,8 @@ Add to the integrate (team) or finish (subagent) phase: task checkboxes in `tasks.md` ``` -### Phase 0: context check → SDD: GitHub Spec Kit -... existing initial/follow-up/partial branch ... +### 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 @@ -266,8 +279,8 @@ Add to the integrate (team) or finish (subagent) phase: `.kiro/specs//{requirements,design,tasks}.md` ``` -### Phase 0: context check → SDD: AWS Kiro -- If `.kiro/specs//` is absent, emit a contextual prompt (goal + constraints + the EARS +### 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. ``` @@ -295,6 +308,11 @@ system, anchor requirements to the spec and route **task status** through `.task ## 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