Introduce the entry-point skill (skills/entry.md)

Add a new skill kind, 'entry-point', and its sole instance at
skills/entry.md. When an orchestrator points an agent at BCQuality,
the agent's first call is Entry: it receives a task context and
returns a dispatch record naming the action skill(s) to invoke.
Routing logic lives in Entry, not in the orchestrator.

Entry structurally follows DO's Source -> Relevance -> Worklist ->
Action pattern but the units it selects are action skills (not
knowledge files) and its output is a dispatch record (not a
findings-report).

Contract highlights:
- Inputs semantics in DO clarified as any-of: orchestrator supplies
  whichever listed input types it has; skill must return
  'not-applicable' if the subset is insufficient. This matches
  the existing al-* canonical skills which declare
  [pr-diff, file-path] as alternatives.
- Relevance admits candidates whose inputs intersect
  inputs-available, not whose inputs are a subset.
- Dispatched inputs are the intersection, not the full
  inputs-available set, to avoid leakage between skills.
- Super-skill precedence in Worklist supersedes a sub-skill only
  when the goal is a broader match for the super than the sub.
  When the goal specifically names a concern the sub handles
  (e.g., 'performance review'), the sub wins and the super is
  dropped with reason 'narrower-sub-skill-selected'.
- Skill layer precedence is defined here as custom > community >
  microsoft, matching READ's rule for knowledge files.
- skipped[] carries 'superseded-by' for layer-precedence,
  sub-skill, and super-skill drops, for traceability.

Propagate the concept through:
- skills/README.md: distinguish the runtime entry-point skill from
  the three meta-skill contracts.
- skills/do.md: acknowledge entry-point alongside meta-skills as
  the only kinds that live outside a layer.
- README.md: rewrite the Skills and Agent bootstrapping sections
  so the bootstrap instruction is 'invoke /skills/entry.md first'.
- agent-consumption.md: update the Mermaid flow and step narrative
  to show Entry dispatch, with READ and DO read on demand.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

agent-consumption.md

@@ -9,37 +9,35 @@ For the high-level framing and repo structure, start with the [README](README.md
 - **Orchestrator** — the tool that triggers work (e.g. AL-Go on a pull request, or a VS Code extension on save). Lives *outside* BCQuality. Knows *when* to run something, not *what* to run.
 - **Agent** — an LLM-driven process spawned by the orchestrator. The agent has no built-in knowledge of BC or of BCQuality's conventions. It knows how to read instructions and call tools.
 - **BCQuality repo** — two kinds of content:
-  - **Meta-skills** in `/skills/` — the READ · DO · WRITE contracts that teach an agent how to work with the repo.
-  - **Layer content** in `/microsoft/` and `/community/` — knowledge files and action skills grouped by authority.
+  - **Global skills** in `/skills/` — the `entry.md` entry-point skill plus the READ · DO · WRITE contracts that govern the rest of the repo.
+  - **Layer content** in `/microsoft/`, `/community/`, and `/custom/` — knowledge files and action skills grouped by authority.
 
 ## The flow
 
 ```mermaid
 flowchart LR
-    O[Orchestrator<br/>AL-Go] -->|1 trigger| A[Agent]
-    A -->|2 read /skills/| M[Meta-skills<br/>READ · DO · WRITE]
-    M -->|3 pick skill| S[Action skill<br/>e.g. al-code-review]
-    S -->|4 execute| P[Source → Relevance<br/>→ Worklist → Action]
-    P -->|5 emit| R[Findings · References<br/>· Confidence]
-    R -->|6 integrate| O
+    O[Orchestrator<br/>AL-Go] -->|1 trigger + task context| A[Agent]
+    A -->|2 invoke entry.md| E[Entry<br/>routing skill]
+    E -->|3 dispatch record| A
+    A -->|4 invoke dispatched skill| S[Action skill<br/>e.g. al-code-review]
+    S -->|5 execute| P[Source → Relevance<br/>→ Worklist → Action<br/>reading READ · DO on demand]
+    P -->|6 emit| R[Findings · References<br/>· Confidence]
+    R -->|7 integrate| O
 ```
 
 ### 1. Orchestrator triggers
-The orchestrator has a URL setting that points at BCQuality (default: `github.com/microsoft/BCQuality`) and a task to perform. It hands the task to an agent and says: *your source of truth lives at that URL; start by reading `/skills/`*.
+The orchestrator has a URL setting that points at BCQuality (default: `github.com/microsoft/BCQuality`) and a task to perform. It hands the agent a **task context** — goal, inputs available (`pr-diff`, `file-path`, …), technologies, BC version, enabled layers — and says: *your source of truth lives at that URL; start by invoking `/skills/entry.md`*.
 
-### 2. Agent bootstraps on meta-skills
-The agent has no prior knowledge of BCQuality's conventions. It reads `/skills/` first:
+### 2. Agent invokes Entry
+The agent reads `/skills/entry.md` and runs it against the task context. Entry applies its Source → Relevance → Worklist → Action steps over the action skills under `*/skills/**/*.md` and returns a **dispatch record**: the set of action skills to invoke, plus a list of candidates it skipped (with reasons). Routing is a skill, not orchestrator logic.
 
-- **READ** (Schema + Use) — how to interpret a knowledge file: frontmatter fields, section semantics, layer precedence. Any skill that consumes knowledge depends on this.
-- **DO** (Action Skill) — the template every action skill follows. Defines the four-step pattern and the structured output format.
-- **WRITE** (New Knowledge) — authoring rules. Not used during consumption; used when contributors or agents scaffold new knowledge.
+### 3. Agent consumes the dispatch record
+The dispatch record names one or more action skills and the subset of inputs each should receive. If the outcome is `no-match` or `failed`, the agent returns the record to the orchestrator unchanged.
 
-After this step, the agent is fluent in BCQuality without anything hardcoded in the orchestrator.
+### 4. Agent invokes each dispatched action skill
+Action skills live inside the layers — `/microsoft/skills/`, `/community/skills/`, `/custom/skills/` — so their authority is carried by their location. For a PR review, Entry typically dispatches `microsoft/skills/al-code-review.md`. The agent reads the file and executes it.
 
-### 3. Agent selects an action skill
-Action skills live inside the layers — `/microsoft/skills/` and `/community/skills/` — so their authority is carried by their location. For a PR review, the agent finds a review-type skill (for example `microsoft/skills/al-code-review.md`) and loads it.
-
-### 4. Action skill executes the four-step pattern
+### 5. Action skill executes the four-step pattern
 
 Each action skill is a markdown file that specifies what to do at each step. The template is always the same:
 
@@ -52,7 +50,9 @@ Each action skill is a markdown file that specifies what to do at each step. The
 
 Example: a performance review skill sources from `/microsoft/knowledge/performance/` and `/community/knowledge/performance/`, filters to `bc-version: 26` and `technologies: [al]`, narrows the 25 candidate files to the 8 that apply to the 15 objects changed in the PR, and then evaluates each file against the diff.
 
-### 5. Agent emits structured output
+At this point the agent reads READ and DO on demand — it needs READ to interpret each knowledge file's frontmatter and sections, and DO to shape its output. Those contracts are fetched when first needed, not as part of bootstrap.
+
+### 6. Agent emits structured output
 The output contract is defined in the DO meta-skill so that every action skill — today's and next year's — produces the same shape:
 
 - **Outcome** — `completed`, `not-applicable`, `no-knowledge`, `partial`, or `failed`. An orchestrator can distinguish a clean run from a no-op from a failure without guessing.
@@ -63,15 +63,15 @@ The output contract is defined in the DO meta-skill so that every action skill
 
 The orchestrator parses this **without skill-specific logic**. This is the point of the contract: orchestrators and action skills evolve independently.
 
-### 6. Orchestrator integrates
+### 7. Orchestrator integrates
 The orchestrator turns findings into PR comments, build gates, or IDE diagnostics, and links the references back to the knowledge files so the PR author — human or agent — can read the guidance.
 
 ## Why this architecture
 
-- **Meta-skills are the only hardcoded thing.** Orchestrators ship with knowledge of `/skills/` and nothing else. New action skills and new knowledge files are picked up automatically.
+- **Entry is the only hardcoded thing.** Orchestrators ship with one convention — *"invoke `/skills/entry.md` first"* — and nothing else. New action skills and new knowledge files are picked up automatically because Entry discovers them at dispatch time.
 - **Layers decide authority, not code.** The agent sees `/microsoft/` and `/community/` together; if two files conflict, the precedence rule defined in READ resolves it. A partner fork can disable `/community/` — that's a config choice, not a code change.
 - **Knowledge and skills evolve independently.** A new knowledge file requires no skill changes — existing skills pick it up via frontmatter filters. A new skill requires no knowledge changes — it sources from what's already there.
 
 ## The mental model, in one sentence
 
-The orchestrator knows **when** to run; the meta-skills teach the agent **how** to behave; the action skills define **what** to do; the knowledge files are **what** the agent knows.
+The orchestrator knows **when** to run; Entry decides **which skill** to run; the action skills define **what** to do; the meta-skills teach the agent **how** to behave; the knowledge files are **what** the agent knows.