FILE: docs/MEMORIA-TECNICA.md¶
WPDoctor — Memoria Técnica v1.0¶
Repository: agent-adk-wpdoctor
ADR authority: docs/adr/ADR-0001-wpdoctor-v1.md
1. Objetivo técnico¶
Construir un runtime ADK capaz de actuar como SRE especializado sobre estates WordPress de terceros usando SSH como interfaz mínima.
Requisitos fundamentales:
provider agnostic
multi-host
multi-site
tenant isolated
memory enabled
policy constrained
auditable
rollback aware
evaluation driven
2. Conceptos del dominio¶
Tenant¶
Cliente propietario de una infraestructura administrada por WPDoctor.
Estate¶
Conjunto completo de recursos administrados para un tenant.
Host¶
Sistema operativo alcanzable por un connector.
Site¶
Instalación WordPress.
Capability¶
Capacidad verificada en un host.
Ejemplos:
Specialist¶
Agente interno experto en un dominio.
Operation¶
Workflow SRE orientado a conseguir un resultado.
Skill¶
Procedimiento o conocimiento reusable.
Tool¶
Acción técnica acotada.
Adapter¶
Implementación concreta de una capacidad para un stack.
Incident¶
Unidad de investigación y resolución.
Evidence¶
Dato observado que soporta o contradice una hipótesis.
Policy¶
Reglas independientes del LLM que determinan qué puede ejecutarse.
3. Runtime¶
flowchart TD
API[Interaction / API] --> Manager
Manager --> Specialists
Specialists --> Ops[Operations Engine]
Ops --> Inventory
Ops --> Memory
Ops --> Policy
Policy --> Tools
Tools --> Adapters
Adapters --> SSH
SSH --> Hosts[Customer Hosts]
Ops --> Audit
Ops --> IncidentStore
4. Estado canónico¶
Los agentes NO deben almacenar estado crítico exclusivamente en contexto LLM.
Estado persistente:
Tenant
Host inventory
Site inventory
Capabilities
Policies
Incidents
Audit events
Approvals
Memory references
El runtime debe poder reconstruir una sesión a partir de almacenamiento persistente.
5. Modelo de inventario¶
Ejemplo aproximado:
tenant:
id: acme
hosts:
- id: srv01
connector:
type: ssh
os:
family: debian
distribution: ubuntu
version: "24.04"
privileges:
root: false
sudo: limited
capabilities:
nginx: true
apache: false
php_fpm: true
mysql: false
mariadb: true
redis: true
wp_cli: true
sites:
- id: shop-example
domain: shop.example.com
path: /var/www/shop.example.com
wordpress_version: "..."
Every discovered fact should include internally:
6. Specialists¶
Initial internal ADK topology:
wpdoctor-manager
├── linux-specialist
├── web-specialist
├── php-specialist
├── database-specialist
├── wordpress-specialist
├── woocommerce-specialist
├── performance-specialist
├── security-specialist
├── lifecycle-specialist
├── backup-specialist
└── reviewer
Do not expose this topology as required customer interaction.
7. Operations Engine¶
Operations must be explicit objects.
Conceptual interface:
class Operation:
id: str
risk: RiskLevel
required_capabilities: list[str]
async def preflight(...)
async def investigate(...)
async def plan(...)
async def execute(...)
async def validate(...)
Implementation details may evolve, but this conceptual boundary should remain.
8. Initial operations¶
Discovery¶
Host¶
HTTP/web¶
PHP¶
Database¶
WordPress¶
wordpress_health
investigate_plugin_conflict
investigate_wp_cron
inspect_autoload
inspect_object_cache
safe_plugin_update
safe_core_update
Performance¶
9. Operation manifests¶
Operations SHOULD expose machine-readable metadata.
Example:
id: restart_php_fpm
version: 1
risk: R2
requires:
- php.fpm
- privilege.service_restart
allowed_modes:
- COPILOT
- AUTOPILOT
autopilot:
allowed: false
validation:
required: true
10. Tool design¶
Prefer narrow tools.
Good:
service_status(service)
service_restart(service)
read_log(path, lines, since)
wp_cli(site, argv)
mysql_query(connection, readonly_query)
filesystem_usage(path)
process_snapshot()
Avoid making this the default abstraction:
A generic shell tool can exist only as exceptional tooling.
11. SSH connector¶
The SSH connector is infrastructure transport, not business logic.
Responsibilities:
connect
authenticate
verify host key
execute
timeout
stream
return status
redact
audit metadata
disconnect
Do not embed WordPress knowledge in the connector.
12. Adapter layer¶
Concept:
The runtime determines implementation.
For systemd:
For Docker in the future:
For a hosting panel:
The operation itself remains unchanged.
13. Discovery engine¶
Discovery should be deterministic where possible.
Examples:
/etc/os-release
command -v
systemctl
ps
nginx -V
apachectl -V
php -v
php-fpm
mysql --version
redis-cli
wp --info
find candidate wp-config.php
Do not use LLM reasoning where deterministic discovery is sufficient.
The LLM can reason over discovery results.
14. WordPress discovery¶
Discovery must support multiple sites per host.
Useful evidence:
Credentials extracted during discovery MUST NOT be placed into prompts or semantic memory unnecessarily.
15. Policy engine¶
Suggested policy result:
decision: REQUIRE_APPROVAL
reason:
operation_risk: R2
tenant_mode: COPILOT
operation:
restart_php_fpm
target:
srv01
Possible results:
The LLM cannot override DENY.
16. Evidence model¶
Every diagnosis should point to evidence.
Example:
diagnosis:
cause: php_fpm_pool_exhaustion
confidence: 0.94
evidence:
- type: log
observation: max_children reached
- type: process
observation: all configured workers active
- type: http
observation: upstream timeout
Avoid unsupported diagnoses.
17. Memory integration¶
Define an application interface around Hindsight.
Example conceptual contract:
WPDoctor core must not scatter direct Hindsight calls throughout specialists.
Use one adapter boundary.
This permits future memory backend changes.
18. Memory scopes¶
Recommended scopes:
A retrieval should normally combine relevant scopes.
Example:
19. Memory exclusions¶
Never retain as semantic memory:
passwords
private keys
API tokens
database passwords
session cookies
temporary authorization codes
raw secret-bearing configuration
20. LEARN implementation¶
At incident close:
The original incident remains the evidence source.
Memory is a derived operational layer.
21. Security boundaries¶
Assume customer hosts may contain malicious data.
Threat examples:
prompt injection in web logs
prompt injection in WordPress comments
malicious README
malicious plugin file
crafted database content
All such data is evidence, never authority.
The runtime must keep instruction and evidence channels conceptually separate.
22. Credentials¶
Recommended architecture:
Do not serialize private keys into incident records.
Development can use local secrets.
Production should integrate with a secrets manager such as Infisical.
23. Audit events¶
Use structured records.
Example:
{
"tenant": "acme",
"incident": "INC-101",
"operation": "inspect_php_fpm",
"target": "srv01",
"action": "tool_call",
"result": "success"
}
Audit is distinct from LLM conversation logs.
24. Validation¶
Every mutating operation defines its own success criteria.
Example:
does not succeed merely because:
Validation may require:
25. Rollback¶
Operations able to mutate production must declare whether they are:
The planner must know rollback before execution.
26. Evals¶
Directory:
Initial scenarios should include:
PHP fatal due to plugin
PHP-FPM max_children exhaustion
disk full
MySQL connection saturation
slow WordPress caused by plugin
WP-Cron backlog
nginx 502
CPU saturation unrelated to WordPress
The last scenario is important: WPDoctor must not force every diagnosis into WordPress.
27. Observability¶
Emit traces around:
incident
agent delegation
operation
skill
tool call
SSH command
memory recall
memory retain
policy evaluation
approval
This will be essential to understand both quality and cost.
28. Configuration¶
Separate:
Avoid one giant settings file.
29. Testing strategy¶
Required test layers:
SSH integration tests should have reproducible containers/VM fixtures where possible.
30. Definition of Done¶
A capability is not finished until it has:
END FILE: docs/MEMORIA-TECNICA.md¶
FILE: docs/ARCHITECTURE-PACK.md¶
WPDoctor — Initial Architectural Pack v1.0¶
Repository: agent-adk-wpdoctor
This document is the initial implementation guide for the development agent.
Read first:
docs/adr/ADR-0001-wpdoctor-v1.md
docs/MEMORIA-EJECUTIVA.md
docs/MEMORIA-TECNICA.md
docs/ARCHITECTURE-PACK.md
ADR-0001 has architectural authority.
1. Repository Layout¶
Create:
agent-adk-wpdoctor/
│
├── README.md
├── AGENTS.md
├── pyproject.toml
├── .env.example
├── .gitignore
│
├── docs/
│ ├── adr/
│ │ └── ADR-0001-wpdoctor-v1.md
│ │
│ ├── MEMORIA-EJECUTIVA.md
│ ├── MEMORIA-TECNICA.md
│ └── ARCHITECTURE-PACK.md
│
├── src/
│ └── wpdoctor/
│ │
│ ├── app.py
│ ├── runtime.py
│ │
│ ├── domain/
│ │ ├── tenant.py
│ │ ├── host.py
│ │ ├── site.py
│ │ ├── capability.py
│ │ ├── incident.py
│ │ ├── evidence.py
│ │ ├── operation.py
│ │ └── policy.py
│ │
│ ├── agents/
│ │ ├── manager.py
│ │ └── specialists/
│ │ ├── linux.py
│ │ ├── web.py
│ │ ├── php.py
│ │ ├── database.py
│ │ ├── wordpress.py
│ │ ├── woocommerce.py
│ │ ├── performance.py
│ │ ├── security.py
│ │ ├── lifecycle.py
│ │ └── backup.py
│ │
│ ├── orchestration/
│ │ ├── workflow.py
│ │ ├── planner.py
│ │ ├── validator.py
│ │ └── learning.py
│ │
│ ├── inventory/
│ │ ├── repository.py
│ │ └── discovery.py
│ │
│ ├── connectors/
│ │ └── ssh/
│ │ ├── client.py
│ │ ├── models.py
│ │ └── known_hosts.py
│ │
│ ├── adapters/
│ │ ├── linux_systemd/
│ │ ├── nginx/
│ │ ├── apache/
│ │ ├── php_fpm/
│ │ ├── mysql/
│ │ ├── redis/
│ │ └── wordpress_wpcli/
│ │
│ ├── operations/
│ │ ├── discovery/
│ │ ├── linux/
│ │ ├── web/
│ │ ├── php/
│ │ ├── database/
│ │ ├── wordpress/
│ │ └── performance/
│ │
│ ├── skills/
│ │ ├── linux/
│ │ ├── web/
│ │ ├── php/
│ │ ├── database/
│ │ ├── wordpress/
│ │ └── woocommerce/
│ │
│ ├── tools/
│ │ ├── system.py
│ │ ├── services.py
│ │ ├── filesystem.py
│ │ ├── logs.py
│ │ ├── wordpress.py
│ │ └── database.py
│ │
│ ├── policy/
│ │ ├── engine.py
│ │ ├── risk.py
│ │ └── defaults.py
│ │
│ ├── memory/
│ │ ├── interface.py
│ │ ├── hindsight.py
│ │ ├── curator.py
│ │ └── models.py
│ │
│ ├── incidents/
│ │ ├── service.py
│ │ └── repository.py
│ │
│ ├── audit/
│ │ ├── events.py
│ │ └── sink.py
│ │
│ └── telemetry/
│ └── tracing.py
│
├── operations/
│ └── manifests/
│
├── evals/
│ ├── incidents/
│ ├── fixtures/
│ └── runners/
│
├── tests/
│ ├── unit/
│ ├── integration/
│ └── policy/
│
├── deploy/
│ ├── docker/
│ │ ├── Dockerfile
│ │ └── compose.yaml
│ └── kubernetes/
│
└── scripts/
├── dev/
└── bootstrap/
Do not create every empty module blindly if unnecessary, but preserve these architectural boundaries.
2. Dependency Direction¶
Mandatory dependency direction:
flowchart TD
Agents --> Orchestration
Orchestration --> Operations
Operations --> Domain
Operations --> Policy
Operations --> Tools
Tools --> Adapters
Adapters --> Connectors
Operations --> Inventory
Operations --> Memory
Operations --> Audit
Connectors -.-> External[Customer Infrastructure]
Lower layers must not import agents.
SSH must not know about ADK.
Domain must not know about Hindsight.
Policy must not depend on LLM output to enforce hard denials.
3. Runtime Topology¶
flowchart LR
Customer --> Manager
subgraph Tenant Runtime
Manager --> Specialists
Specialists --> Engine[Operations Engine]
Engine --> Inventory
Engine --> Incidents
Engine --> Memory
Engine --> Policy
Engine --> Audit
Policy --> Tools
Tools --> Adapters
Adapters --> SSH
end
SSH --> Server1
SSH --> Server2
SSH --> ServerN
4. Tenant Model¶
One runtime must support:
tenant
├── hosts
│ ├── sites
│ └── capabilities
├── policy
├── incidents
├── approvals
├── memory
└── audit
Never encode customer identity by changing agent source code.
5. ADK Design¶
ADK is the reasoning/orchestration runtime.
Business knowledge should remain outside framework-specific internals when possible.
This is intentional.
If WPDoctor needs another runtime in the future, we should be able to retain:
ADK should therefore be treated as an important but replaceable infrastructure dependency.
6. Public Agent¶
Only one primary entry point:
Example request:
Manager tasks:
resolve target
create incident
retrieve relevant memory
inspect inventory
delegate investigation
correlate evidence
diagnose
propose operation
invoke policy
execute if permitted
validate
learn
close incident
7. First Development Milestones¶
M0 — Repository and Contracts¶
Create:
Must compile and test cleanly.
No remote mutation.
M1 — SSH + Discovery¶
Implement:
SSH connector
host-key verification
credential reference model
command timeout
structured result
host discovery
capability discovery
WordPress discovery
inventory persistence
Demo target:
Expected conceptual result:
M2 — Read-Only SRE¶
Implement read-only operations:
host-health
wordpress-health
investigate-high-load
investigate-disk-pressure
investigate-502
investigate-php-fatal
investigate-fpm-saturation
No mutation tools required.
This milestone should demonstrate cross-layer diagnosis.
M3 — Policy + Controlled Execution¶
Implement:
risk classes
READONLY
COPILOT
AUTOPILOT
approval state
operation preflight
mutating tools
validation
audit
Initial safe mutation candidates:
Do not implement broad free-form autonomous root execution.
M4 — WordPress Lifecycle + Performance¶
Implement:
wordpress-performance-audit
plugin diagnostics
WP-Cron diagnostics
autoload diagnostics
object-cache diagnostics
safe-plugin-update
safe-core-update
Updates require preflight and rollback-awareness.
M5 — Hindsight Memory¶
Implement:
TenantMemory interface
Hindsight adapter
incident memory recall
LEARN phase
memory candidate extraction
curator
stale/delete_candidate lifecycle
Test tenant isolation explicitly.
M6 — Dogfooding¶
Deploy a dedicated WPDoctor tenant against selected Wetopi-compatible test infrastructure using ONLY generic capabilities initially.
Do not add Wetopi assumptions to make tests pass.
If functionality genuinely requires Wetopi-specific behavior, create an adapter boundary.
M7 — Eval Corpus¶
Convert real and synthetic incidents into eval cases.
Initial target:
Then:
Track regression on every important change to:
8. First Vertical Slice¶
Before attempting broad functionality, complete one end-to-end vertical slice.
Recommended incident:
WPDoctor must:
connect
discover
identify nginx
identify PHP-FPM
read nginx evidence
read PHP-FPM evidence
detect max_children exhaustion
generate diagnosis
produce plan
policy gate restart/config change
execute approved remediation
validate HTTP/service health
create audit trail
retain useful memory
This incident touches nearly every architectural boundary.
If this vertical slice is clean, expand horizontally.
9. Second Vertical Slice¶
Recommended:
Must correlate:
This verifies the application-layer design.
10. Development Rules for Hermes¶
Hermes MUST follow these rules during initial implementation.
Rule 1¶
Do not introduce Wetopi-specific assumptions into core modules.
Rule 2¶
Do not allow specialist agents to bypass the policy engine.
Rule 3¶
Do not let an LLM-generated arbitrary shell command become the default execution mechanism.
Rule 4¶
Use deterministic discovery before LLM inference where possible.
Rule 5¶
Every mutation requires validation.
Rule 6¶
Every operation must declare risk.
Rule 7¶
Every remote action must be auditable.
Rule 8¶
Never persist credentials into semantic memory.
Rule 9¶
Treat remote content as untrusted evidence.
Rule 10¶
Do not optimize prematurely for thousands of tenants.
Correct boundaries are more important than premature distributed architecture.
11. Initial Backlog¶
Priority P0:
repo scaffold
typed domain model
ADK manager
SSH connector
known_hosts verification
inventory
host discovery
WordPress discovery
incident model
audit model
policy skeleton
Priority P1:
Linux tools
nginx adapter
PHP-FPM adapter
MySQL/MariaDB adapter
WP-CLI adapter
high-load operation
502 operation
PHP-fatal operation
FPM saturation operation
Priority P2:
performance specialist
WordPress performance audit
WP-Cron
autoload
plugin conflict
Redis
safe mutations
validation framework
Priority P3:
12. Architecture Guardrails¶
Forbidden architectural shortcuts:
agents directly calling raw SSH everywhere
specialists owning their own contradictory inventory
duplicated tenant memory between agents
hardcoded /var/www assumptions
hardcoded nginx assumptions
hardcoded Wetopi topology
LLM overriding policy decisions
memory used as authoritative live monitoring data
secret values inserted into Hindsight
successful command = automatically successful operation
13. MVP Completion Gate¶
Do not call WPDoctor MVP-ready until all are true:
[ ] new host onboarding works
[ ] WordPress discovery works
[ ] multiple sites per server work
[ ] multiple servers per tenant work
[ ] inventory is persisted
[ ] read-only diagnostics work
[ ] evidence-backed diagnosis works
[ ] policy cannot be bypassed
[ ] approved mutation works
[ ] validation works
[ ] audit works
[ ] memory works
[ ] tenant memory isolation is tested
[ ] at least one end-to-end performance investigation works
[ ] eval regression suite exists
[ ] no Wetopi dependency exists in core
14. Future Architecture¶
Do not implement yet, but preserve compatibility with:
central SaaS control plane
runtime worker pool
ephemeral tenant runtimes
agent installed on customer host
event-driven monitoring
Prometheus integrations
Grafana integrations
Cloudflare
hosting panel adapters
Docker
Kubernetes
Plesk
cPanel
central fleet management
billing
customer portal
The initial architecture should permit these without requiring core operational knowledge to be rewritten.
15. Starting Instruction for Hermes¶
Use the following as the implementation directive:
Read
docs/adr/ADR-0001-wpdoctor-v1.md,docs/MEMORIA-EJECUTIVA.md,docs/MEMORIA-TECNICA.mdanddocs/ARCHITECTURE-PACK.md.Treat ADR-0001 as authoritative.
Start by scaffolding repository
agent-adk-wpdoctorand implementing Milestone M0 followed by M1.Do not begin broad WordPress automation yet.
The first target is a clean vertical architecture with typed domain contracts, SSH transport, deterministic discovery, inventory, incidents, audit and policy boundaries.
Do not add Wetopi-specific assumptions.
Do not introduce unrestricted autonomous shell execution as the main operation path.
Commit the architecture documents unchanged before implementation.
Record any necessary deviation from ADR-0001 as a proposed ADR rather than silently changing the architecture.
16. First Delivery Expected From Hermes¶
The first development delivery should contain:
agent-adk-wpdoctor/
├── working Python package
├── ADK manager bootstrap
├── typed domain models
├── SSH connector
├── verified known_hosts handling
├── host discovery
├── capability inventory
├── WordPress discovery
├── incident skeleton
├── audit skeleton
├── policy skeleton
├── Docker development runtime
└── tests
And demonstrate:
connect to test server
↓
discover server
↓
discover capabilities
↓
discover WordPress installations
↓
persist inventory
↓
print structured result
No production mutations are required for this first delivery.