feat(agentic-harness): make generated orchestrator the hard-gate entry point (v0.6.0)

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",

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.
 

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,19 +32,38 @@ 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 |
 |------|--------|--------|--------|
 | {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`:

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`.

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/<project-hash>/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 —

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.

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.

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.