Trying to be more lean in AGENTS.md

Author: petrsnd

.agents/CONVENTIONS.md

@@ -0,0 +1,12 @@
+# Notation conventions
+
+Agent-facing material in this repo distinguishes three shapes so an agent never has to guess whether a token is a cmdlet parameter, an API field, or a transport-agnostic idea.
+
+- **PowerShell** — backtick the literal as it appears in `Get-Help <Cmdlet> -Full`. Switches stand alone; valued parameters use a space before the value.
+  - `` `-ExtendedLogging` `` (switch), `` `-TaskId <GUID>` `` (valued), `` `Connect-Safeguard -Browser` `` (cmdlet + switch).
+- **API / JSON** — backtick a PascalCase field as `Field: value`, mirroring the transfer-object shape SPP emits and accepts.
+  - `` `ExtendedLogs: true` ``, `` `OperationType: CheckPassword` ``.
+- **Concept (transport-agnostic)** — plain English, no backticks. Use this in orchestration prose where the agent should not yet be biased toward PS or API.
+  - "with extended logging enabled", "trigger the affected operation".
+
+Rule of thumb: `AGENTS.md` speaks **concept**. The skills speak **PowerShell** (e.g., `safeguard-ps-operations`) or **API** with backticks. When a skill bridges them, it shows both forms side by side.

AGENTS.md

@@ -79,16 +79,7 @@ If the agent finds itself drafting a third clarifying question before any tool h
 
 ## Notation: PowerShell vs API vs concept
 
-Agent-facing material in this repo distinguishes three shapes so an agent never has to guess whether a token is a cmdlet parameter, an API field, or a transport-agnostic idea.
-
-- **PowerShell** — backtick the literal as it appears in `Get-Help <Cmdlet> -Full`. Switches stand alone; valued parameters use a space before the value.
-  - `` `-ExtendedLogging` `` (switch), `` `-TaskId <GUID>` `` (valued), `` `Connect-Safeguard -Browser` `` (cmdlet + switch).
-- **API / JSON** — backtick a PascalCase field as `Field: value`, mirroring the transfer-object shape SPP emits and accepts.
-  - `` `ExtendedLogs: true` ``, `` `OperationType: CheckPassword` ``.
-- **Concept (transport-agnostic)** — plain English, no backticks. Use this in orchestration prose where the agent should not yet be biased toward PS or API.
-  - "with extended logging enabled", "trigger the affected operation".
-
-Rule of thumb: this `AGENTS.md` speaks **concept**. The skills speak **PowerShell** (e.g., `safeguard-ps-operations`) or **API** with backticks. When a skill bridges them, it shows both forms side by side.
+See [`.agents/CONVENTIONS.md`](.agents/CONVENTIONS.md). Short version: `AGENTS.md` speaks concept (plain English); skills speak PowerShell (backticked cmdlets/switches) or API (backticked PascalCase fields).
 
 ## Authentication and safety
 
@@ -100,15 +91,7 @@ Rule of thumb: this `AGENTS.md` speaks **concept**. The skills speak **PowerShel
 
 ## Sample and template index
 
-The agent-facing index of every sample and template lives at [`docs/agent-reference/samples-index.md`](docs/agent-reference/samples-index.md). It is generated by `tools/Build-SamplesIndex.ps1` and CI fails the build if the committed copy is stale.
-
-Use the index to find a starting point by `(protocol, auth-scheme, operations)`. Telnet samples are excluded — telnet is out of scope for the agent skill system (see `agent-skills-plan.md` §2). The repo retains the telnet samples for human reference.
-
-Other agent-reference material:
-
-- [`docs/agent-reference/strategy-decision-tree.md`](docs/agent-reference/strategy-decision-tree.md) — backs the `strategy-selection` skill.
-- [`docs/agent-reference/failure-patterns.md`](docs/agent-reference/failure-patterns.md) — empty until Phase 5; grown from real extended task logs.
-- [`docs/agent-reference/vendor-doc-search-recipes.md`](docs/agent-reference/vendor-doc-search-recipes.md) — query templates and a paste-normalization recipe.
+The agent-facing index of every sample and template lives at [`docs/agent-reference/samples-index.md`](docs/agent-reference/samples-index.md) (generated by `tools/Build-SamplesIndex.ps1`; CI fails if stale). Use it to find a starting point by `(protocol, auth-scheme, operations)`. Telnet samples are excluded — telnet is out of scope for the agent skill system. Other agent-reference material lives alongside it in [`docs/agent-reference/`](docs/agent-reference/) (decision tree, failure-pattern catalog, vendor-doc search recipes).
 
 ## Workflow: new platform
 
@@ -175,22 +158,6 @@ The five capability skills. Each `SKILL.md` opens with a pre-flight pointer back
 | `safeguard-ps-operations` | Driving a live SPP appliance through `safeguard-ps`: `Connect-Safeguard -Browser`, `Test-` / `Import-` / `Export-SafeguardCustomPlatformScript`, asset/account create-or-update, triggering operations with extended logging, fetching task-log JSON. Wraps [`tools/Invoke-PlatformDevLoop.ps1`](tools/Invoke-PlatformDevLoop.ps1). All cmdlet syntax must come from `Get-Help <Cmdlet> -Full`. | `full-loop` (most operations); `author-only` for `Test-` and `Export-` against a local file | [`.agents/skills/safeguard-ps-operations/SKILL.md`](.agents/skills/safeguard-ps-operations/SKILL.md) |
 | `task-log-analysis` | An operation has run and produced an extended task log that must be classified (`connect` / `auth` / `parse` / `operation` / `unknown`) and turned into a next step. Backed by [`docs/agent-reference/failure-patterns.md`](docs/agent-reference/failure-patterns.md), which ships empty and grows only from real runs. | `full-loop` (live log); `author-only` (saved JSON file) | [`.agents/skills/task-log-analysis/SKILL.md`](.agents/skills/task-log-analysis/SKILL.md) |
 
-### Family-consistency note
-
-The structure here matches the safeguard-ps `AGENTS.md` precedent (overview → project structure → conventions → on-demand skills routing table → "Keeping this file current"). Two intentional deviations:
-
-- **Workflows live in this file** rather than as separate skills. They are orchestration, which is what `AGENTS.md` is for; promoting them to skills would create load-order ambiguity with the routing table. (See `agent-skills-plan.md` §4–§5.)
-- **The routing table includes a `Modes` column.** This repo has explicit `author-only` / `probe-only` / `full-loop` modes; safeguard-ps does not. Surfacing modes in the table prevents an agent from loading a skill in a mode where it fails closed.
-
 ## Keeping this file current
 
-Update this file when any of the following change:
-
-- A skill is added, renamed, retired, or its supported modes change → update the routing table and any workflow step that references it.
-- A workflow step is added, removed, or reordered → update both `Workflow: new platform` and `Workflow: enhance platform` so they stay aligned.
-- The iterative debug-loop budget changes → update both the loop section and any skill that restates the budget in its pre-flight (currently `task-log-analysis`).
-- Files in `docs/agent-reference/` are added or moved → update the pointers in `Sample and template index` and the routing table.
-- The safeguard-ps `AGENTS.md` precedent diverges from this file in a way we want to track → update the family-consistency note above with the reason.
-- A new section is added that describes cmdlet parameters, API fields, or transport-agnostic concepts → follow the conventions in **Notation: PowerShell vs API vs concept**. Skills authored or revised after this file changes should adopt the same convention so PS / API / concept stay visually distinct across the corpus.
-
-Propose updates as part of the same change that introduces the underlying drift; do not let routing entries and skill files drift out of sync.
+When skills, workflows, modes, the loop budget, or `docs/agent-reference/` paths change, update this file in the same change. Do not let the routing table drift from the skills it points at.