From 7212e921eeb486e7cc10f4027cabe718f49c896e Mon Sep 17 00:00:00 2001 From: Jesper Schulz-Wedde Date: Wed, 9 Sep 2026 16:51:26 +0200 Subject: [PATCH] Organize conceptual guides under docs Move architecture and standalone runner documentation out of the repository root, add a documentation index, and update all inbound links. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- README.md | 10 ++++++---- docs/README.md | 8 ++++++++ agent-consumption.md => docs/agent-consumption.md | 3 ++- standalone-runner.md => docs/standalone-runner.md | 2 +- skills/README.md | 2 +- 5 files changed, 18 insertions(+), 7 deletions(-) create mode 100644 docs/README.md rename agent-consumption.md => docs/agent-consumption.md (98%) rename standalone-runner.md => docs/standalone-runner.md (98%) diff --git a/README.md b/README.md index 07daf67..f3ea476 100644 --- a/README.md +++ b/README.md @@ -129,8 +129,9 @@ lives at `microsoft/skills/review/al-code-review.md`. Partners that want model selection, parallel leaf execution, retries, or usage telemetry can add a thin runner outside BCQuality. See -[Build a lightweight standalone review runner](standalone-runner.md) for the -integration contract and a minimal implementation checklist. +[Build a lightweight standalone review runner](docs/standalone-runner.md) for the +integration contract and a minimal implementation checklist. Architecture and +partner guides are collected in the [documentation index](docs/README.md). ## Knowledge file format @@ -177,16 +178,17 @@ Action skills follow a four-step pattern: Every action skill produces output in a common format that orchestrators can consume without skill-specific parsing. The format is JSON and includes an `outcome` (so a clean run, a not-applicable skill, and a partial failure are all distinguishable), `findings` (what the skill observed), structured `references` back to the knowledge files that informed each finding, per-finding `confidence`, and a `suppressed` list recording any knowledge files overridden by layer precedence. This contract is defined in the Action Skill meta-skill so that orchestrators and action skills remain independently evolvable. -BCQuality is an **additive** knowledge layer: it augments the agent's review judgement, it does not replace it. Super-skills (such as `al-code-review`) run a self-review pass alongside their sub-skills and surface concerns the agent identified on its own, marked with `from-sub-skill: "agent"` and an empty `references: []` so consumers can render them distinctly from knowledge-backed findings. See [agent-consumption.md](agent-consumption.md) and [`skills/do.md`](skills/do.md) for the full contract. +BCQuality is an **additive** knowledge layer: it augments the agent's review judgement, it does not replace it. Super-skills (such as `al-code-review`) run a self-review pass alongside their sub-skills and surface concerns the agent identified on its own, marked with `from-sub-skill: "agent"` and an empty `references: []` so consumers can render them distinctly from knowledge-backed findings. See [How agents consume BCQuality](docs/agent-consumption.md) and [`skills/do.md`](skills/do.md) for the full contract. The meta-skills in `/skills/` define this pattern. Every concrete action skill follows it. -For the end-to-end flow — from orchestrator trigger through to how output reaches developers — see [agent-consumption.md](agent-consumption.md). +For the end-to-end flow — from orchestrator trigger through to how output reaches developers — see [How agents consume BCQuality](docs/agent-consumption.md). ## Repository structure ``` ├── /skills/ # Global: entry-point skill + meta-skill contracts (READ, DO, WRITE) +├── /docs/ # Architecture and partner integration guides ├── /evaluation/ # Neutral good/bad review fixtures and scoring contract ├── /.github/ # Actions and workflows ├── /microsoft/ # Microsoft-endorsed layer diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..c8e8290 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,8 @@ +# Documentation + +- [How agents consume BCQuality](agent-consumption.md) explains the operational + flow from Entry dispatch through structured findings and integration. +- [Build a lightweight standalone review runner](standalone-runner.md) explains + the walk-up app-folder flow and how an external runner can add model + selection, concurrency, retries, and telemetry without moving orchestration + into BCQuality. diff --git a/agent-consumption.md b/docs/agent-consumption.md similarity index 98% rename from agent-consumption.md rename to docs/agent-consumption.md index 37a7a10..aaa6772 100644 --- a/agent-consumption.md +++ b/docs/agent-consumption.md @@ -2,7 +2,8 @@ BCQuality is content — knowledge files and skills. It is consumed by agents that live elsewhere (AL-Go, a VS Code extension, a GitHub Agent invocation, etc.). This document explains the end-to-end flow, so that skill authors, orchestrator maintainers, and contributors share one mental model. -For the high-level framing and repo structure, start with the [README](README.md). This document is the operational view. +For the high-level framing and repo structure, start with the +[README](../README.md). This document is the operational view. ## The actors diff --git a/standalone-runner.md b/docs/standalone-runner.md similarity index 98% rename from standalone-runner.md rename to docs/standalone-runner.md index 3c346b5..605ffcc 100644 --- a/standalone-runner.md +++ b/docs/standalone-runner.md @@ -1,6 +1,6 @@ # Build a lightweight standalone review runner -BCQuality contains review knowledge, routing, execution instructions, and +BCQuality provides review knowledge, routing, execution instructions, and structured output contracts. It intentionally does not choose models, schedule agents, retry failures, or collect usage telemetry. A standalone runner can add those host-specific capabilities without copying Business Central rules out of diff --git a/skills/README.md b/skills/README.md index 3d8fdfb..b8d3fd3 100644 --- a/skills/README.md +++ b/skills/README.md @@ -57,4 +57,4 @@ each review domain to run in an isolated context. These contracts are stable. Changes require a PR approved by both maintainers. -For the end-to-end flow — from orchestrator trigger through to findings integration — see [`../agent-consumption.md`](../agent-consumption.md). For the high-level project framing, see [`../README.md`](../README.md). +For the end-to-end flow — from orchestrator trigger through to findings integration — see [How agents consume BCQuality](../docs/agent-consumption.md). For the high-level project framing, see [`../README.md`](../README.md).