# Agentic Engineering Lite

## Purpose

This is a lightweight version of enterprise agentic engineering principles adapted for this personal assistant / homelab / learning workspace.

The goal is to gain the benefits of AI-assisted work without pretending a homelab needs the full overhead of a large enterprise.

## Core Principle

If the assistant can change systems, code, data, or long-term records, then the assistant is part of the system and needs engineering controls.

## Lightweight Controls

### 1. Plans over prompts

For non-trivial work, do not jump straight from request to action.

Use:
- ticket for scoped work
- spec for infrastructure/security/data-affecting work
- short plan before commands

Minimum standard:

```text
Goal:
Plan:
Risks:
Verification:
Rollback:
```

### 2. Bounded tools and scope

Before acting, identify:
- which host/repo/files are in scope
- which tools will be used
- what is explicitly out of scope
- whether approval is needed

Examples:
- okay: edit files in this repo and commit
- cautious: restart a service on Nextcloud VM
- ask first: firewall changes, destructive deletes, public exposure, credential changes

### 3. Verification before done

Every meaningful change needs evidence.

Examples:
- `git diff`
- syntax check
- unit/self-test
- service status
- log tail
- manual test result from Deeso

Record important verification in tickets, runbooks, or change logs.

### 4. State and memory governance

Persistent state should be deliberate.

Use:
- `AGENTS.md` for durable operating instructions
- `docs/` for reference/process
- `tickets/` for scoped work
- `docs/server-change-log.md` for server changes
- git commits for repo history

Avoid:
- hidden state only in chat context
- storing secrets in repo
- stale assumptions without documenting them

### 5. Autonomy levels

Use explicit autonomy levels:

- **L0 Advisory**: plan/draft only
- **L1 Assisted**: local/sandbox changes
- **L2 Controlled change**: repo changes with git workflow
- **L3 Conditional apply**: bounded server changes with verification and rollback
- **L4 Supervised autonomy**: background operation; future only

Default:
- Docs/code in repo: L1-L2
- Servers/infrastructure: cautious L3 only with approval/logging
- Security monitoring: read-only first

### 6. Observability

We need to be able to answer:

- What changed?
- Why?
- Who/what changed it?
- How was it verified?
- How can it be rolled back?

Tools:
- git history
- server change log
- runbooks
- service logs
- ticket notes

### 7. Stop and rollback

Before starting risky work, know how to stop or reverse it.

Examples:
- systemd stop command
- revoke app password
- restore config backup
- git revert
- VM snapshot restore

## Agent Certification Checklist

Before giving a role more autonomy, confirm:

- [ ] Role and owner are clear
- [ ] Scope is documented
- [ ] Allowed tools/actions are documented
- [ ] Secrets handling is safe
- [ ] Verification path exists
- [ ] Logs/audit trail exist
- [ ] Rollback/stop path exists
- [ ] Failure modes are understood

## Current Application

For the Nextcloud Talk assistant bridge:

- Role: Bishop + Ada + EDI
- Autonomy: L3 for bounded bridge operation, L2 for repo code changes
- Controls:
  - single Talk conversation
  - allowed sender list
  - pending draft approval flow
  - no shell execution from chat
  - server change log
  - systemd stop path
  - app password revocation path
  - git-tracked source code

## Blunt Rules

- If we cannot bound it, we do not trust it.
- If we cannot verify it, we do not automate it.
- If we cannot observe it, we do not operate it.
- If nobody owns it, it will become a mess.
- Autonomy is earned with evidence, not enthusiasm.