Add AGENTS.md
This commit is contained in:
parent
b4150997aa
commit
2b07888e8e
|
|
@ -0,0 +1,210 @@
|
|||
# AGENT.md — Win Diagnostics
|
||||
|
||||
## Mission
|
||||
|
||||
Win Diagnostics collects and analyses Windows diagnostic information.
|
||||
|
||||
Its pipeline is:
|
||||
|
||||
Windows system
|
||||
↓
|
||||
collect
|
||||
↓
|
||||
normalize
|
||||
↓
|
||||
analyse
|
||||
↓
|
||||
diagnostic.json
|
||||
|
||||
The structured diagnostic result is the primary output.
|
||||
|
||||
This project does NOT generate corporate reports or PDFs.
|
||||
|
||||
---
|
||||
|
||||
## Migration source
|
||||
|
||||
The existing `WinDiagnostics` repository is the primary migration source.
|
||||
|
||||
Migrate progressively rather than copying the entire repository.
|
||||
|
||||
Before migrating a component, determine whether it is:
|
||||
|
||||
- collection logic;
|
||||
- normalization logic;
|
||||
- generic diagnostic analysis;
|
||||
- historical evidence;
|
||||
- investigation-specific analysis;
|
||||
- report-generation logic.
|
||||
|
||||
Only the first three belong here.
|
||||
|
||||
Historical evidence and investigation-specific material will eventually
|
||||
move to `beffroi-reports`.
|
||||
|
||||
---
|
||||
|
||||
## Responsibilities
|
||||
|
||||
Win Diagnostics owns:
|
||||
|
||||
- Windows evidence collection;
|
||||
- event extraction;
|
||||
- normalization;
|
||||
- diagnostic rules;
|
||||
- technical analysis;
|
||||
- evidence correlation;
|
||||
- confidence/severity classification;
|
||||
- machine-readable diagnostic output.
|
||||
|
||||
---
|
||||
|
||||
## Non-goals
|
||||
|
||||
Win Diagnostics does NOT own:
|
||||
|
||||
- PDF generation;
|
||||
- Typst;
|
||||
- corporate branding;
|
||||
- report layout;
|
||||
- historical incident management;
|
||||
- executive summaries;
|
||||
- organisational recommendations.
|
||||
|
||||
Do not add dependencies on Reportist.
|
||||
|
||||
---
|
||||
|
||||
## Diagnostic format
|
||||
|
||||
Define a versioned structured diagnostic format.
|
||||
|
||||
Prefer JSON for machine-generated output.
|
||||
|
||||
Conceptually:
|
||||
|
||||
{
|
||||
"schema_version": 1,
|
||||
"metadata": {},
|
||||
"system": {},
|
||||
"collection": {},
|
||||
"observations": [],
|
||||
"findings": [],
|
||||
"warnings": []
|
||||
}
|
||||
|
||||
Findings should preferably contain:
|
||||
|
||||
id
|
||||
severity
|
||||
confidence
|
||||
title
|
||||
description
|
||||
evidence
|
||||
|
||||
Adapt this structure where existing diagnostic data requires it.
|
||||
|
||||
---
|
||||
|
||||
## Evidence
|
||||
|
||||
Preserve raw evidence wherever practical.
|
||||
|
||||
A diagnostic conclusion must be traceable back to observations.
|
||||
|
||||
Do not replace precise machine evidence with prose summaries when the
|
||||
underlying structured information can reasonably be retained.
|
||||
|
||||
---
|
||||
|
||||
## Schemas
|
||||
|
||||
Prefer:
|
||||
|
||||
schemas/diagnostic.schema.json
|
||||
|
||||
Treat the diagnostic schema as an interface consumed by other tools.
|
||||
|
||||
Changes to internal collectors should not require downstream changes when
|
||||
the schema remains compatible.
|
||||
|
||||
---
|
||||
|
||||
## Privacy
|
||||
|
||||
Example and test fixtures must be sanitized.
|
||||
|
||||
Avoid committing unnecessarily identifying:
|
||||
|
||||
- usernames;
|
||||
- hostnames;
|
||||
- serial numbers;
|
||||
- account identifiers;
|
||||
- network identifiers.
|
||||
|
||||
Real investigation evidence belongs in the appropriate private reporting
|
||||
repository rather than generic fixtures.
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
Prefer conceptual separation between:
|
||||
|
||||
collection
|
||||
normalization
|
||||
analysis
|
||||
schemas
|
||||
|
||||
Do not force directory boundaries where they make implementation worse.
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
Maintain sanitized fixtures representing known diagnostic situations.
|
||||
|
||||
Analysis should be testable against stored fixtures without requiring
|
||||
access to the original machine.
|
||||
|
||||
Regression tests are particularly valuable for diagnostic rules.
|
||||
|
||||
---
|
||||
|
||||
## Output
|
||||
|
||||
The end of a successful diagnostic run should be a documented structured
|
||||
artifact such as:
|
||||
|
||||
diagnostic.json
|
||||
|
||||
Human-readable console summaries are useful but are not the canonical
|
||||
integration interface.
|
||||
|
||||
---
|
||||
|
||||
## Development principles
|
||||
|
||||
Prefer:
|
||||
|
||||
- PowerShell for native Windows collection where appropriate;
|
||||
- structured output;
|
||||
- deterministic analysis;
|
||||
- explicit evidence references;
|
||||
- testable rules;
|
||||
- minimal dependencies.
|
||||
|
||||
Avoid:
|
||||
|
||||
- parsing presentation-oriented output when structured APIs exist;
|
||||
- report-specific prose;
|
||||
- renderer dependencies;
|
||||
- absolute machine-specific paths.
|
||||
|
||||
---
|
||||
|
||||
## Definition of success
|
||||
|
||||
A fresh clone can collect/analyse supported Windows diagnostic information
|
||||
and produce a valid structured diagnostic result without Reportist or any
|
||||
Beffroi reporting repository installed.
|
||||
Reference in New Issue