Timmy-time-dashboard/timmy_automations/README.md

# Timmy Automations

Central home for all automated processes that keep the Timmy development loop running smoothly.

## Purpose

This directory consolidates scripts, configurations, and manifests for automations that operate on behalf of Timmy — the autonomous development agent. These automations handle everything from daily issue triage to cycle retrospectives, workspace management, and metrics collection.

**Design principle:** Automations should be discoverable, configurable, and observable. Every automation in this folder can be found by Timmy, enabled or disabled via configuration, and reports its status for dashboard integration.

---

## Directory Structure

| Directory | Purpose |
|-----------|---------|
| `daily_run/` | Scripts that run periodically (cycle retros, idle detection, daily triage) |
| `triage/` | Deep triage helpers — intelligent issue refinement and prioritization |
| `metrics/` | Dashboard and metrics integration — data collection for loop health |
| `workspace/` | Agent workspace management — isolated environments per agent |
| `config/` | Automation manifests and configuration files |

---

## Types of Automations

### 1. Daily Run Automations

These run continuously or on a schedule to keep the dev loop operational:

- **Cycle Retrospective** (`cycle_retro.py`) — Logs structured data after each development cycle
- **Loop Guard** (`loop_guard.py`) — Idle detection with exponential backoff (prevents burning cycles on empty queues)
- **Triage Scoring** (`triage_score.py`) — Mechanical issue scoring based on scope/acceptance/alignment
- **Daily Run Orchestrator** (`orchestrator.py`) — The 10-minute ritual; fetches candidate issues and produces a concise agenda plus day summary

### 2. Deep Triage Automations

Intelligent, LLM-assisted workflows that run less frequently (~every 20 cycles):

- **Deep Triage** (`deep_triage.sh` + `deep_triage_prompt.md`) — Hermes-driven issue refinement, breaking down large issues, adding acceptance criteria
- **Loop Introspection** (`loop_introspect.py`) — Self-improvement engine that analyzes retro data and produces recommendations

### 3. Workspace Automations

Environment management for multi-agent operation:

- **Agent Workspace** (`agent_workspace.sh`) — Creates isolated git clones, port ranges, and data directories per agent
- **Bootstrap** (`bootstrap.sh`) — One-time setup for new Kimi workspaces
- **Resume** (`resume.sh`) — Quick status check and resume prompt

### 4. Metrics & Integration

Data collection for dashboard visibility:

- **Backfill Retro** (`backfill_retro.py`) — Seeds retrospective data from Gitea PR history
- **Pre-commit Checks** (`pre_commit_checks.py`) — CI hygiene validation before commits

---

## How Timmy Discovers Automations

Automations are discovered via manifest files in `config/`:

```
config/
├── automations.json      # Master manifest of all automations
├── daily_run.json        # Daily run schedule configuration
└── triage_rules.yaml     # Triage scoring weights and thresholds
```

### Discovery Protocol

1. **Scan** — Timmy scans `config/automations.json` on startup
2. **Validate** — Each automation entry is validated (script exists, is executable)
3. **Enable** — Automations marked `enabled: true` are registered
4. **Schedule** — Daily runs are scheduled via the loop's internal scheduler
5. **Report** — Status is written to `.loop/automation_state.json`

### Automation Manifest Format

```json
{
  "automations": [
    {
      "id": "cycle_retro",
      "name": "Cycle Retrospective",
      "description": "Logs structured data after each dev cycle",
      "script": "daily_run/cycle_retro.py",
      "enabled": true,
      "trigger": "post_cycle",
      "config": {
        "retro_file": ".loop/retro/cycles.jsonl",
        "summary_window": 50
      }
    },
    {
      "id": "loop_guard",
      "name": "Loop Guard",
      "description": "Idle detection with exponential backoff",
      "script": "daily_run/loop_guard.py",
      "enabled": true,
      "trigger": "pre_cycle",
      "config": {
        "backoff_base": 60,
        "backoff_max": 600
      }
    }
  ]
}
```

---

## How Timmy Enables/Disables Automations

### Method 1: Edit Manifest

Modify `config/automations.json` and set `enabled: true/false`:

```bash
# Disable the loop guard
jq '.automations[] | select(.id == "loop_guard").enabled = false' \
  config/automations.json > tmp.json && mv tmp.json config/automations.json
```

### Method 2: CLI (Future)

```bash
timmy automation enable loop_guard
timmy automation disable cycle_retro
timmy automation list
```

### Method 3: Dashboard (Future)

Mission Control panel will have toggles for each automation with real-time status.

---

## How Timmy Configures Automations

Each automation reads configuration from the manifest + environment variables:

| Priority | Source | Override |
|----------|--------|----------|
| 1 | Environment variables | `TIMMY_AUTOMATION_*` prefix |
| 2 | Manifest `config` object | Per-automation settings |
| 3 | Code defaults | Fallback values |

Example environment overrides:

```bash
export TIMMY_CYCLE_RETRO_WINDOW=100  # Override summary_window
export TIMMY_LOOP_GUARD_MAX_BACKOFF=300  # Override backoff_max
```

---

## Script References

The following scripts live in their original locations but are conceptually part of Timmy Automations:

| Script | Location | Category | Purpose |
|--------|----------|----------|---------|
| `cycle_retro.py` | `../scripts/` | Daily Run | Log cycle retrospective data |
| `loop_guard.py` | `../scripts/` | Daily Run | Idle detection & backoff |
| `triage_score.py` | `../scripts/` | Daily Run | Mechanical issue scoring |
| `orchestrator.py` | `daily_run/` | Daily Run | The 10-minute ritual — agenda + review |
| `deep_triage.sh` | `../scripts/` | Triage | LLM-driven issue refinement |
| `deep_triage_prompt.md` | `../scripts/` | Triage | Prompt template for deep triage |
| `loop_introspect.py` | `../scripts/` | Triage | Self-improvement analysis |
| `agent_workspace.sh` | `../scripts/` | Workspace | Agent environment management |
| `backfill_retro.py` | `../scripts/` | Metrics | Seed retro data from history |
| `pre_commit_checks.py` | `../scripts/` | Metrics | CI hygiene validation |

### Why scripts aren't moved here (yet)

These scripts are referenced rather than moved to maintain backward compatibility with:
- Existing CI/CD pipelines
- Agent workspace setups
- Shell aliases and documentation

Future work may migrate scripts here with symlink redirects from original locations.

---

## Integration with Dashboard

Automations report status for dashboard visibility:

```
.loop/
├── automation_state.json     # Current state of all automations
├── queue.json                # Current work queue (produced by triage)
├── retro/
│   ├── cycles.jsonl         # Cycle retrospective log
│   ├── deep-triage.jsonl    # Deep triage history
│   ├── triage.jsonl         # Mechanical triage log
│   └── insights.json        # Loop introspection output
└── quarantine.json          # Quarantined issues (repeat failures)
```

The Mission Control dashboard (`/mission-control`) displays:
- Last run time for each automation
- Success/failure counts
- Queue depth and triage statistics
- Repeat failure alerts

---

## Adding New Automations

1. **Create the script** in the appropriate subdirectory
2. **Add manifest entry** to `config/automations.json`
3. **Document in this README** — add to the relevant table
4. **Add tests** in `tests/timmy_automations/`
5. **Update dashboard** if the automation produces visible output

### Automation Script Template

```python
#!/usr/bin/env python3
"""Brief description of what this automation does.

Run:  python3 timmy_automations/daily_run/my_automation.py
Env:  See config/automations.json for configuration
"""

from __future__ import annotations

import json
import sys
from pathlib import Path

# Load automation config from manifest
CONFIG_PATH = Path(__file__).parent.parent / "config" / "automations.json"

def load_config() -> dict:
    """Load configuration for this automation."""
    manifest = json.loads(CONFIG_PATH.read_text())
    for auto in manifest["automations"]:
        if auto["id"] == "my_automation_id":
            return auto.get("config", {})
    return {}

def main() -> int:
    config = load_config()
    # Your automation logic here
    return 0

if __name__ == "__main__":
    sys.exit(main())
```

---

## Token Economy Integration

Automations participate in the token economy:

| Action | Token Cost/Reward | Reason |
|--------|-------------------|--------|
| Run daily automation | 1 token | Resource usage |
| Successful cycle retro | +5 tokens | Data contribution |
| Find quarantine candidate | +10 tokens | Quality improvement |
| Deep triage refinement | +20 tokens | High-value work |
| Automation failure | -2 tokens | Penalty |

See `src/lightning/` for token economy implementation.

---

## See Also

- `CLAUDE.md` — Architecture patterns and conventions
- `AGENTS.md` — Agent roster and development standards
- `.kimi/README.md` — Kimi agent workspace guide
- `.loop/` — Runtime data directory (created on first run)

---

_Maintained by: Timmy Automations Subsystem_
_Updated: 2026-03-21_