Skip to content

Commit cee38ca

Browse files
petrsndpetrsnd
committed
More AGENTS.md trimming
1 parent 2a0047d commit cee38ca

1 file changed

Lines changed: 16 additions & 44 deletions

File tree

‎AGENTS.md‎

Lines changed: 16 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -6,42 +6,14 @@ This file is the agent orchestrator. Read it first.
66

77
## Project structure
88

9-
```
10-
SafeguardCustomPlatform/
11-
|-- AGENTS.md # This file. Routing table + workflows.
12-
|-- agent-skills-plan.md # Master plan for the agent skill system.
13-
|-- .agents/
14-
| |-- skills/ # One subdirectory per capability skill.
15-
| | |-- target-probing/SKILL.md
16-
| | |-- strategy-selection/SKILL.md
17-
| | |-- safeguard-ps-operations/SKILL.md
18-
| | |-- script-authoring/SKILL.md
19-
| | `-- task-log-analysis/SKILL.md
20-
| |-- schemas/
21-
| | `-- evidence.schema.json # Internal probing-evidence contract.
22-
| `-- prompts/ # Per-phase implementation prompts.
23-
|-- docs/
24-
| |-- agent-reference/ # Machine-first reference material.
25-
| | |-- README.md
26-
| | |-- samples-index.md # Generated by tools/Build-SamplesIndex.ps1.
27-
| | |-- strategy-decision-tree.md
28-
| | |-- failure-patterns.md # Empty until Phase 5; populated from real runs.
29-
| | `-- vendor-doc-search-recipes.md
30-
| |-- concepts/ # Human-facing — keep untouched.
31-
| |-- guides/ # "
32-
| |-- reference/ # "
33-
| |-- tutorials/ # "
34-
| `-- quick-start/ # "
35-
|-- schema/
36-
| `-- custom-platform-script.schema.json # Authoritative platform-script schema.
37-
|-- samples/ # Tested production-grade samples (ssh, http, telnet).
38-
|-- templates/ # Pattern templates and minimal starters.
39-
`-- tools/
40-
|-- TestTool.ps1 # Existing human-facing test tool.
41-
|-- Build-SamplesIndex.ps1 # Regenerates docs/agent-reference/samples-index.md.
42-
|-- Test-AgentLinks.ps1 # Link-validity check across AGENTS.md / SKILL.md / agent-reference.
43-
`-- Invoke-PlatformDevLoop.ps1 # (Phase 2) validate->import->trigger->log wrapper.
44-
```
9+
- `AGENTS.md` (this file) — orchestrator: workflows + routing table.
10+
- `agent-skills-plan.md` — master plan for the agent skill system.
11+
- `.agents/` — `skills/` (one subdirectory per capability skill, each with a `SKILL.md`), `schemas/evidence.schema.json` (probing-evidence contract), `prompts/` (per-phase implementation prompts), `CONVENTIONS.md`.
12+
- `schema/custom-platform-script.schema.json` — authoritative platform-script schema.
13+
- `samples/` — tested production-grade samples (ssh, http, telnet).
14+
- `templates/` — pattern templates and minimal starters.
15+
- `docs/agent-reference/` — machine-first reference (samples-index, strategy-decision-tree, failure-patterns, vendor-doc-search-recipes). `docs/concepts|guides|reference|tutorials|quick-start/` are human-facing — keep untouched.
16+
- `tools/` — `Invoke-PlatformDevLoop.ps1` (validate→import→trigger→log wrapper), `Build-SamplesIndex.ps1`, `Test-AgentLinks.ps1`, `TestTool.ps1` (human-facing).
4517

4618
## Custom platform mental model
4719

@@ -86,7 +58,7 @@ See [`.agents/CONVENTIONS.md`](.agents/CONVENTIONS.md). Short version: `AGENTS.m
8658
- **Connect with `-Browser` only.** All `safeguard-ps` connections in agent flows use `Connect-Safeguard -Browser` (interactive PKCE). No password-in-script recipes.
8759
- **Never operate against a production target.** The operator must affirm the target is non-production before any probe or trigger runs. The affirmation is a soft control — responsibility rests with the operator. The agent does not (and cannot) verify environment classification independently.
8860
- **Never log session tokens or secrets.** `$SafeguardSession`, target passwords, API keys, and private keys must not appear in evidence files, status messages, or operator-visible output.
89-
- **Probe-safety contract.** The `target-probing` skill enforces a strict contract: read-only by default, per-probe operator consent for destructive probes that go beyond the seed account on the target under test (key install, account create/delete, sudo-that-mutates, POST/PUT/DELETE against undocumented endpoints), a hard auth-attempt rate limit (default 3/min), pre-flight echo of the planned probe sequence, and fail-closed behavior on lockout / throttle / MFA-challenge signals. Rotating the seed account password as part of the workflow under test is announced up front but does not require per-probe consent (see *Question discipline* above). See `.agents/skills/target-probing/SKILL.md`.
61+
- **Probe-safety contract.** The `target-probing` skill enforces a strict contract (read-only by default, per-probe consent for destructive probes beyond the seed account, auth-attempt rate limit, fail-closed on lockout/throttle/MFA). See [`.agents/skills/target-probing/SKILL.md`](.agents/skills/target-probing/SKILL.md) for the full contract. Rotating the seed account password as part of the workflow under test is announced up front but does not require per-probe consent (see *Question discipline*).
9062
- **`SchemaOnly` is not a correctness signal.** Local schema validation only proves the JSON is well-formed and conformant. It does not catch undefined variables in `Do` blocks, regex that does not match in practice, or status-message ordering. Cross-reference samples for analogous patterns before treating green as ready-to-import.
9163

9264
## Sample and template index
@@ -103,22 +75,22 @@ Use this workflow when the operator's request is to build a custom platform that
10375
- **Credential intent** — self-managed (the managed account rotates its own password) vs service-account (a separate account rotates the managed one).
10476
- Any vendor documentation the operator can share (URL the agent fetches, or an excerpt pasted into the conversation — both first-class).
10577
Ask only what is missing. Do not re-ask for facts the operator already provided.
106-
2. **Search samples-index + vendor docs.** Look up a starting point in [`docs/agent-reference/samples-index.md`](docs/agent-reference/samples-index.md) by `(protocol, auth-scheme, operations)`. If vendor docs are needed, use [`docs/agent-reference/vendor-doc-search-recipes.md`](docs/agent-reference/vendor-doc-search-recipes.md). The starting sample is just that — a starting point — not a constraint.
78+
2. **Search samples-index + vendor docs.** Look up a starting point in [`docs/agent-reference/samples-index.md`](docs/agent-reference/samples-index.md) by `(protocol, auth-scheme, operations)`. If vendor docs are needed, use [`docs/agent-reference/vendor-doc-search-recipes.md`](docs/agent-reference/vendor-doc-search-recipes.md).
10779
3. **Probe the target.** Hand off to [`target-probing`](.agents/skills/target-probing/SKILL.md). The skill enforces its own probe-safety contract and produces an evidence artifact conforming to [`.agents/schemas/evidence.schema.json`](.agents/schemas/evidence.schema.json). In `author-only` mode this step is skipped and the workflow proceeds with whatever the operator can supply by hand.
10880
4. **Select a strategy.** Hand off to [`strategy-selection`](.agents/skills/strategy-selection/SKILL.md) with the probe evidence (or the operator-supplied substitute) and any vendor docs. Output: one of the four authoring patterns plus credential-intent and self-managed-vs-service-account.
109-
5. **Author the JSON.** Hand off to [`script-authoring`](.agents/skills/script-authoring/SKILL.md). The skill mandates the fast inner loop: local schema validation against [`schema/custom-platform-script.schema.json`](schema/custom-platform-script.schema.json) before any appliance round-trip. `SchemaOnly` green is necessary but not sufficient — cross-reference samples for analogous patterns before declaring ready.
110-
6. **Validate, import, and trigger.** Hand off to [`safeguard-ps-operations`](.agents/skills/safeguard-ps-operations/SKILL.md), which prefers [`tools/Invoke-PlatformDevLoop.ps1`](tools/Invoke-PlatformDevLoop.ps1) over re-implementing the loop. The asset and account do not yet exist on the appliance — create them directly without a pre-check (the lookup-first dance belongs to the enhance-platform workflow). Trigger with extended logging enabled so a structured task log is produced. Requires `full-loop` mode.
111-
7. **Analyze the task log.** Hand off to [`task-log-analysis`](.agents/skills/task-log-analysis/SKILL.md). It classifies the failure phase, extracts the actionable signal, and recommends the next iteration.
81+
5. **Author the JSON.** Hand off to [`script-authoring`](.agents/skills/script-authoring/SKILL.md). The skill mandates the fast inner loop: local schema validation against [`schema/custom-platform-script.schema.json`](schema/custom-platform-script.schema.json) before any appliance round-trip.
82+
6. **Validate, import, and trigger.** Hand off to [`safeguard-ps-operations`](.agents/skills/safeguard-ps-operations/SKILL.md), which prefers [`tools/Invoke-PlatformDevLoop.ps1`](tools/Invoke-PlatformDevLoop.ps1) over re-implementing the loop. Create the asset and account directly without a pre-check (the platform is new). Trigger with extended logging enabled. Requires `full-loop` mode.
83+
7. **Analyze the task log.** Hand off to [`task-log-analysis`](.agents/skills/task-log-analysis/SKILL.md).
11284
8. **Enter the iterative debug loop** (below) until green or the loop budget triggers escalation.
11385

11486
## Workflow: enhance platform
11587

11688
Use this workflow when the operator wants to change a platform that is already deployed on the appliance.
11789

11890
1. **Gather requirements.** What operation is changing, what new behavior is expected, what existing behavior must not regress. Ask only what is missing.
119-
2. **Source the current JSON via export.** Run `Export-SafeguardCustomPlatformScript` against the appliance (via [`safeguard-ps-operations`](.agents/skills/safeguard-ps-operations/SKILL.md)). **The deployed copy is authoritative for the diff.** On-disk samples in `samples/` are starting points that get adjusted for a specific target — drift between the deployed JSON and any on-disk sample is expected and benign. Do not treat a sample as a substitute for the export.
120-
3. **Diff-aware authoring.** Hand off to [`script-authoring`](.agents/skills/script-authoring/SKILL.md) with the exported JSON as the base. Limit the change set to what the requirement demands; do not opportunistically rewrite unrelated operations. The fast inner loop (local schema validation) still runs before any appliance round-trip.
121-
4. **Validate, import, and trigger only operations affected by the change.** A `ChangePassword` edit does not require re-testing `DiscoverAccounts`. Re-triggering everything wastes the loop budget and obscures which change caused which symptom.
91+
2. **Source the current JSON via export.** Run `Export-SafeguardCustomPlatformScript` against the appliance (via [`safeguard-ps-operations`](.agents/skills/safeguard-ps-operations/SKILL.md)). **The deployed copy is authoritative for the diff.** On-disk samples in `samples/` are starting points — drift between the deployed JSON and any sample is expected and benign.
92+
3. **Diff-aware authoring.** Hand off to [`script-authoring`](.agents/skills/script-authoring/SKILL.md) with the exported JSON as the base. Limit the change set to what the requirement demands. The fast inner loop (local schema validation) still runs before any appliance round-trip.
93+
4. **Validate, import, and trigger only operations affected by the change.** A `ChangePassword` edit does not require re-testing `DiscoverAccounts`.
12294
5. **Analyze the task log** for each affected operation via [`task-log-analysis`](.agents/skills/task-log-analysis/SKILL.md).
12395
6. **Enter the iterative debug loop** (below) until green or the loop budget triggers escalation.
12496

0 commit comments

Comments
 (0)