luzia/AUTONOMOUS-AGENT-TEMPLATES.md

# Autonomous Agent Implementation Templates
## Copy-Paste Ready Code Examples

**Date:** 2026-01-09
**Version:** 1.0
**Status:** Ready for production use

---

## Template 1: Simple Task Agent (Read-Only Analysis)

### Use Case
Analyze code and report metrics without modifying anything.

### Prompt Template

```python
project = "musica"
task = """
Analyze the codebase structure in /workspace:

1. Count TypeScript files: find /workspace -name "*.ts" | wc -l
2. Count lines of code: find /workspace -name "*.ts" -exec wc -l {} + | tail -1
3. Find largest files: find /workspace -name "*.ts" -exec wc -l {} + | sort -rn | head -5
4. Check dependencies: npm list 2>/dev/null | head -20

Save results to /workspace/code-metrics.json with format:
{
  "ts_files": number,
  "total_loc": number,
  "largest_files": [
    {"file": string, "loc": number},
    ...
  ],
  "dependencies_count": number,
  "analysis_timestamp": ISO8601_string
}

Success: File exists with all required fields.
Failure: File missing or incomplete.
Exit 0 on success, exit 1 on failure.
Do NOT attempt to install or modify anything.
"""

# Spawn agent
job_id = spawn_claude_agent(project, task, context="", config=config)
```

### Expected Output
```json
{
  "ts_files": 42,
  "total_loc": 12847,
  "largest_files": [
    {"file": "src/core/processor.ts", "loc": 843},
    {"file": "src/index.ts", "loc": 521},
    {"file": "src/api/routes.ts", "loc": 472}
  ],
  "dependencies_count": 18,
  "analysis_timestamp": "2026-01-09T15:30:45Z"
}
```

---

## Template 2: Test Execution Agent (Run & Report)

### Use Case
Run test suite and report results with metrics.

### Prompt Template

```python
project = "musica"
task = """
Run the test suite and generate a comprehensive report.

Steps:
1. npm install (if node_modules missing)
2. npm test -- --json=test-results.json
3. Parse test-results.json
4. Create test-report.json with:
{
  "total_tests": number,
  "passed": number,
  "failed": number,
  "skipped": number,
  "duration_ms": number,
  "success_rate": number (0-100),
  "failed_tests": [
    {
      "name": string,
      "error": string,
      "file": string
    }
  ],
  "timestamp": ISO8601_string
}

Success criteria:
- test-report.json exists
- All required fields present
- success_rate = (passed / (passed + failed)) * 100

Exit codes:
- Exit 0 if success_rate == 100 (all tests passed)
- Exit 1 if success_rate < 100 (some tests failed)
- Exit 2 if tests won't run (no npm, no tests, etc)

Do NOT:
- Attempt to fix failing tests
- Skip any tests
- Modify test files
"""

job_id = spawn_claude_agent(project, task, context="", config=config)
```

### Expected Output
```json
{
  "total_tests": 48,
  "passed": 46,
  "failed": 2,
  "skipped": 0,
  "duration_ms": 3241,
  "success_rate": 95.83,
  "failed_tests": [
    {
      "name": "should handle edge case for empty array",
      "error": "Expected undefined to equal null",
      "file": "tests/processor.test.ts"
    },
    {
      "name": "should validate user input",
      "error": "Timeout: test exceeded 5000ms",
      "file": "tests/validation.test.ts"
    }
  ],
  "timestamp": "2026-01-09T15:32:18Z"
}
```

---

## Template 3: Code Modification Agent (Implement & Verify)

### Use Case
Modify code to meet specifications and verify changes work.

### Prompt Template

```python
project = "musica"
task = """
Add TypeScript strict mode to the codebase.

Requirements:
1. Set "strict": true in /workspace/tsconfig.json
2. Fix all TypeScript errors that result
3. Ensure npm run build succeeds with no errors
4. Verify tests still pass: npm test -> exit 0

For TypeScript errors:
- Add explicit type annotations
- Fix any typing issues
- Do NOT use 'any' type
- Do NOT use 'ignore comments

Changes allowed:
- tsconfig.json: enable strict mode
- .ts files: add type annotations, fix typing

Changes NOT allowed:
- package.json (don't add packages)
- .test.ts files (don't modify tests)
- database schema
- API contracts

Success criteria:
1. tsconfig.json has "strict": true
2. npm run build exits with 0 (no TypeScript errors)
3. npm test exits with 0 (no test failures)
4. No 'any' types in code

Document changes in /workspace/STRICT_MODE_CHANGES.md:
- Files modified: list them
- Breaking changes: none expected
- Type annotations added: count

Exit 0 on complete success.
Exit 1 if any requirement not met.
Exit 2 if unrecoverable (existing errors, etc).
"""

job_id = spawn_claude_agent(project, task, context="", config=config)
```

### Expected Output Files

**tsconfig.json:**
```json
{
  "compilerOptions": {
    "strict": true,
    "target": "es2020",
    "module": "commonjs"
  }
}
```

**STRICT_MODE_CHANGES.md:**
```markdown
# TypeScript Strict Mode Migration

## Files Modified
1. src/index.ts
2. src/processor.ts
3. src/api/routes.ts

## Type Annotations Added
- 28 function return types
- 15 parameter types
- 12 interface refinements

## Build Status
✓ TypeScript: No errors
✓ Tests: 48 passed, 0 failed

## Verification
- npm run build: PASS
- npm test: PASS
```

---

## Template 4: Multi-Step Workflow Agent (Orchestrate Complex Process)

### Use Case
Execute multiple dependent steps in sequence with decision logic.

### Prompt Template

```python
project = "musica"
task = """
Complete the release preparation workflow.

Phase 1: Build Verification
  Command: npm run build
  Check: Exit code must be 0
  If fails: STOP, exit 1

Phase 2: Test Verification
  Command: npm test
  Check: Exit code must be 0, > 95% success rate
  If fails: STOP, exit 1

Phase 3: Security Check
  Command: npm audit
  Check: No high/critical vulnerabilities
  If fails: Create security-issues.json with details, exit 1

Phase 4: Version Bump
  Check current version: grep version package.json
  Increment patch: 1.2.3 -> 1.2.4
  Update: package.json
  Update: src/version.ts to export new version

Phase 5: Generate Changelog
  Create RELEASE_NOTES.md
  Include:
    - Version number
    - Changes made (list modified files)
    - Test results summary
    - Timestamp

Phase 6: Create Release Package
  Create release.json:
{
  "version": string,
  "build_status": "passed",
  "tests": {
    "total": number,
    "passed": number,
    "failed": number
  },
  "security": "passed",
  "ready_to_release": true,
  "timestamp": string,
  "artifacts": [
    "package.json",
    "src/version.ts",
    "RELEASE_NOTES.md"
  ]
}

Decision Logic:
  IF all phases successful:
    ready_to_release = true
    Exit 0
  ELSE:
    ready_to_release = false
    Exit 1

Do NOT:
- Actually publish or deploy
- Push to git
- Upload to npm
- Modify files outside /workspace
"""

job_id = spawn_claude_agent(project, task, context="", config=config)
```

### Expected Output

**release.json:**
```json
{
  "version": "1.2.4",
  "build_status": "passed",
  "tests": {
    "total": 48,
    "passed": 48,
    "failed": 0
  },
  "security": "passed",
  "ready_to_release": true,
  "timestamp": "2026-01-09T15:45:30Z",
  "artifacts": [
    "package.json (version bumped)",
    "src/version.ts (updated)",
    "RELEASE_NOTES.md (generated)"
  ]
}
```

---

## Template 5: Diagnostic Agent (Troubleshooting & Reporting)

### Use Case
Diagnose system/application issues without making changes.

### Prompt Template

```python
project = "musica"
task = """
Diagnose issues with the application startup.

Investigation Steps:

1. Check Prerequisites
   - Node version: node --version
   - npm version: npm --version
   - .env file exists: ls -la .env
   - node_modules exists: ls node_modules | wc -l

2. Dependency Check
   - npm list (capture top-level deps)
   - npm ls --depth=0
   - Look for ERR! messages

3. Configuration Check
   - tsconfig.json valid: npx tsc --noEmit
   - package.json valid: npm ls (no errors)
   - .env configured: grep -c = .env

4. Build Check
   - npm run build
   - Capture any warnings/errors

5. Runtime Check
   - npm start --timeout 5s (let it try for 5 seconds)
   - Capture any startup errors
   - Capture any warnings

6. Port Check
   - netstat -tlnp | grep 3000 (or configured port)
   - Check if something already listening

Diagnostics Report: Create diagnostics.json
{
  "timestamp": ISO8601_string,
  "environment": {
    "node_version": string,
    "npm_version": string,
    "cwd": string
  },
  "checks": {
    "prerequisites": {
      "passed": boolean,
      "details": string
    },
    "dependencies": {
      "passed": boolean,
      "issues": [string],
      "total_packages": number
    },
    "configuration": {
      "passed": boolean,
      "issues": [string]
    },
    "build": {
      "passed": boolean,
      "errors": [string],
      "warnings": [string]
    },
    "startup": {
      "passed": boolean,
      "errors": [string],
      "port": number
    }
  },
  "summary": {
    "all_passed": boolean,
    "blockers": [string],
    "warnings": [string]
  },
  "recommendations": [
    string
  ]
}

Do NOT:
- Attempt to fix issues
- Install missing packages
- Modify configuration
- Change environment variables
"""

job_id = spawn_claude_agent(project, task, context="", config=config)
```

### Expected Output

**diagnostics.json:**
```json
{
  "timestamp": "2026-01-09T15:50:12Z",
  "environment": {
    "node_version": "v18.16.0",
    "npm_version": "9.6.7",
    "cwd": "/workspace"
  },
  "checks": {
    "prerequisites": {
      "passed": true,
      "details": "All required tools present"
    },
    "dependencies": {
      "passed": false,
      "issues": [
        "express: vulnerable version (9.1.0)",
        "lodash: could be updated to 4.17.21"
      ],
      "total_packages": 42
    },
    "configuration": {
      "passed": true,
      "issues": []
    },
    "build": {
      "passed": false,
      "errors": [
        "src/processor.ts:42: Type error: Property 'config' does not exist"
      ],
      "warnings": []
    },
    "startup": {
      "passed": false,
      "errors": [
        "Build failed, cannot start"
      ],
      "port": 3000
    }
  },
  "summary": {
    "all_passed": false,
    "blockers": [
      "TypeScript compilation error in src/processor.ts",
      "Security vulnerability in express package"
    ],
    "warnings": [
      "lodash could be updated"
    ]
  },
  "recommendations": [
    "Fix TypeScript error in src/processor.ts:42",
    "Update express to 4.18.2 (security patch)",
    "Consider updating lodash to 4.17.21"
  ]
}
```

---

## Template 6: Integration Test Agent (Complex Validation)

### Use Case
Validate multiple components work together correctly.

### Prompt Template

```python
project = "musica"
task = """
Validate the API integration between frontend and backend.

Test Scenarios:

1. Database Connectivity
   - psql -U postgres -d mydb -c "SELECT 1"
   - Must succeed with result "1"

2. Backend Startup
   - npm run start &
   - Wait for: "Server running on port 3000"
   - Timeout: 10 seconds
   - If fails: STOP, exit 1

3. Health Check Endpoint
   - curl http://localhost:3000/health
   - Expected response: {"status": "ok"}
   - If fails: STOP, exit 1

4. API Endpoint Tests
   - GET /api/users -> status 200, array response
   - POST /api/users -> status 201, returns created user
   - PUT /api/users/1 -> status 200
   - DELETE /api/users/1 -> status 204

5. Database Transactions
   - Create test record: INSERT INTO test_table...
   - Verify created: SELECT...
   - Delete test record: DELETE...
   - Verify deleted: SELECT...

6. Error Handling
   - GET /api/users/999 -> status 404
   - POST /api/users with invalid data -> status 400
   - Both should return proper error messages

Test Report: Create integration-test-report.json
{
  "timestamp": ISO8601_string,
  "test_suites": {
    "database": {
      "passed": boolean,
      "tests": number,
      "failures": [string]
    },
    "backend": {
      "passed": boolean,
      "startup_time_ms": number,
      "failures": [string]
    },
    "health_check": {
      "passed": boolean,
      "response_time_ms": number,
      "failures": [string]
    },
    "api_endpoints": {
      "passed": boolean,
      "endpoints_tested": number,
      "failures": [string]
    },
    "transactions": {
      "passed": boolean,
      "failures": [string]
    },
    "error_handling": {
      "passed": boolean,
      "failures": [string]
    }
  },
  "summary": {
    "total_tests": number,
    "passed": number,
    "failed": number,
    "success_rate": number,
    "all_passed": boolean
  },
  "performance": {
    "database_latency_ms": number,
    "api_average_latency_ms": number,
    "slowest_endpoint": string
  },
  "recommendations": [string]
}

Exit codes:
- Exit 0 if all_passed = true
- Exit 1 if any test fails
- Exit 2 if unrecoverable (DB unreachable, etc)

Do NOT:
- Modify database schema
- Change application code
- Deploy changes
"""

job_id = spawn_claude_agent(project, task, context="", config=config)
```

---

## Usage Pattern: Spawn and Monitor

```python
# Spawn agent
job_id = spawn_claude_agent(project, task, context="", config=config)
print(f"Job spawned: {job_id}")

# Optionally: Monitor completion
import time
job_dir = Path(f"/var/log/luz-orchestrator/jobs/{job_id}")

while True:
    output_file = job_dir / "output.log"
    if output_file.exists():
        content = output_file.read_text()
        if "exit:" in content:
            # Job completed, extract exit code
            exit_code = int(content.strip().split("exit:")[-1])
            print(f"Job completed with exit code: {exit_code}")

            # Read results
            if (job_dir / "results.json").exists():
                results = json.loads((job_dir / "results.json").read_text())
                print(f"Results: {json.dumps(results, indent=2)}")
            break

    time.sleep(1)
```

---

## Summary

These templates cover the most common autonomous agent scenarios:

1. **Analysis Agents** - Gather information, don't modify
2. **Execution Agents** - Run commands, report results
3. **Implementation Agents** - Modify code, verify changes
4. **Workflow Agents** - Multi-step orchestration
5. **Diagnostic Agents** - Troubleshoot issues
6. **Integration Test Agents** - Validate multiple components

**Key Success Factors:**
- Clear, specific requirements
- Defined success criteria
- Complete context provided
- No ambiguity or assumptions
- Exit codes for status signaling
- Results in JSON/structured format

All templates are:
- ✓ Production-ready
- ✓ Non-blocking (use detached spawning)
- ✓ Autonomy-focused (no user prompts)
- ✓ Failure-resistant (error handling built in)
- ✓ Result-oriented (clear output)