Living Audits
Self-updating documentation that tracks project health. Updated automatically by agents, these documents reflect the current state of your codebase.
Definition
Living Audits are markdown documents in _AUDIT/ that track the current health of your project across multiple dimensions. Unlike static documentation that becomes stale, these documents are automatically updated by specialized agents during audits.
Each audit document follows a consistent format: metadata, open items, and audit history. When an issue is resolved, it's removed from open items (not marked complete). The history table preserves what was done and when.
Philosophy
Core Principle
Documentation should reflect reality, not aspirations. Living audits always show the current state - open issues only. If it's fixed, it's gone from the list. History shows what you've accomplished.
In farming, you don't keep a list of last year's weeds. You track current problems that need attention. Living audits work the same way - they're a dashboard of what needs attention now, not a growing archive of everything ever found.
Benefits of Living Documentation
- Always current - no manual sync needed
- Quick health check at any time
- Clear priority through open items count
- Historical context without clutter
- Trackable scores over time
Audit Documents
Farmwork creates eight audit documents during initialization:
| Document | Agent | Tracks |
|---|---|---|
FARMHOUSE.md |
the-farmer | Overall framework health and metrics |
GARDEN.md |
idea-gardener | Ideas before they become plans |
COMPOST.md |
idea-gardener | Rejected/expired ideas archive |
SECURITY.md |
security-auditor | OWASP vulnerabilities, auth issues |
PERFORMANCE.md |
performance-auditor | Memory leaks, slow operations |
ACCESSIBILITY.md |
accessibility-auditor | WCAG compliance issues |
CODE_QUALITY.md |
code-quality | DRY violations, complexity |
TESTS.md |
code-quality | Test coverage, missing tests |
Standard Format
All audit documents follow a consistent structure:
# Security Audit
**Last Updated:** 2024-01-15
**Score:** 8/10
**Status:** 3 open items
---
## Open Items
*Remove items when resolved - don't mark complete*
### HIGH: SQL Injection in search endpoint
**File:** src/api/search.ts:42
User input passed directly to query. Use parameterized queries.
### MEDIUM: Missing rate limiting on auth endpoints
**File:** src/api/auth.ts
Add rate limiting to prevent brute force attacks.
### LOW: Verbose error messages in production
**File:** src/middleware/error.ts
Stack traces exposed. Use generic messages in production.
---
## Audit History
| Date | Changes |
|------|---------|
| 2024-01-15 | Fixed XSS in comments, 3 items remaining |
| 2024-01-10 | Initial audit, found 4 issues |Remove, Don't Complete
When you fix an issue, delete it from Open Items entirely. Add a history entry noting what was fixed. This keeps the document focused on current problems.
Update Mechanism
Living audits are updated automatically during specific operations:
- "open the farm" — Runs all audit agents, updates all documents
- "count the herd" — Full inspection, updates quality audits
- /push — Updates relevant audits during deployment
- Direct agent invocation — Individual agent updates its document
Agents have Edit access to their respective documents and are instructed to follow the standard format. They add new issues, remove fixed ones, and update the history table.
FARMHOUSE.md
The FARMHOUSE.md is the central command center - a dashboard that aggregates metrics from all other audits:
# Farmhouse
**Last Updated:** 2024-01-15
## Health Dashboard
| System | Score | Open |
|--------|-------|------|
| Security | 8/10 | 3 |
| Performance | 9/10 | 1 |
| Accessibility | 7/10 | 5 |
| Code Quality | 8/10 | 4 |
## Component Counts
- Skills: 6
- Agents: 13
- Commands: 2
## Ideas
- Garden: 5 fresh, 2 wilting
- Plans: 1 active
## Research
- 3 documents (1 stale)Single Source of Truth
FARMHOUSE.md should be your go-to for understanding project health at a glance. If it's out of date, run "open the farm" to refresh everything.