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

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

Automation Manifest Format

{
  "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:

# 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)

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:

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

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

Automation Script Template

#!/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.

README.md

Timmy Automations

Purpose