Templates — Harness Engineering

AGENTS.md Template

El archivo de instrucciones principal. Máximo ~80 líneas. Routing layer que apunta a docs/ detallados.

# AGENTS.md — [Project Name]

[One-sentence project purpose]

## Startup Workflow
Before writing code:
1. Read this file
2. Read docs/ARCHITECTURE.md
3. Run ./init.sh
4. Read feature_list.json (current state)

## Working Rules
- One feature at a time — no scope creep
- Verification required before claiming done
- Update progress before ending session
- If unsure, check docs/ or ask

## Required Artifacts
- `feature_list.json`: Feature state tracker
- `progress.md`: Session continuity log
- `init.sh`: Standard startup and verification

## Definition of Done
A feature is done when:
- [ ] Implementation complete
- [ ] Verification passed (tests, type checks)
- [ ] Evidence recorded in feature_list.json
- [ ] Repository restartable from clean state

## End of Session
Before ending:
1. Update progress.md
2. Update feature_list.json
3. Record blockers/risks
4. Commit with descriptive message
5. Leave clean restart path

feature_list.json Template

Single source of truth para el progreso del proyecto. Cada feature con id, dependencias, estado, y evidencia.

{
  "features": [
    {
      "id": "feat-001",
      "name": "Feature Name",
      "description": "Description of the feature",
      "dependencies": [],
      "status": "todo",
      "evidence": ""
    },
    {
      "id": "feat-002",
      "name": "Another Feature",
      "description": "Description",
      "dependencies": ["feat-001"],
      "status": "in-progress",
      "evidence": ""
    }
  ]
}

/* Status lifecycle:
   todo → in-progress → review → done
   A feature is "done" only when evidence field is populated
*/

init.sh Template

Script de inicialización que se ejecuta al inicio de cada sesión. Verifica que todo esté listo para trabajar.

#!/bin/bash
set -e

echo "=== [init.sh] Starting initialization ==="
START_TS=$(date +%s)

echo "=== Installing dependencies ==="
npm install  # or: cargo build, pip install -r requirements.txt, etc.

echo "=== Running type checks ==="
npm run check  # or: cargo check, mypy, tsc --noEmit, etc.

echo "=== Running tests ==="
npm test  # or: cargo test, pytest, etc.

echo "=== Building application ==="
npm run build  # or: cargo build --release, etc.

echo "=== Checking feature list ==="
if [ -f feature_list.json ]; then
    STATUS_COUNT=$(grep -c '"status"' feature_list.json || true)
    echo "  Feature list loaded: entries found"
else
    echo "  WARNING: feature_list.json not found"
fi

DURATION=$(( $(date +%s) - START_TS ))
echo "=== [init.sh] Complete (${DURATION}s) ==="

progress.md Template

Log de progreso de sesión. Se actualiza al final de cada sesión para mantener continuidad.

# Session Progress Log

## Current State (Last Updated: YYYY-MM-DD HH:MM)

**Active Feature:** feat-001 - Feature Name
**Status:** In Progress (XX% complete)

### What's Done
- [x] Task completed this session
- [x] Another completed task

### What's In Progress
- Current task being worked on
- Decision needed: option A vs option B

### Blockers
- Blocker description (waiting on decision, external dependency, etc.)

### Next Session Should
1. First task for next session
2. Second task for next session
3. Third task for next session

Session Handoff Template

Template para transferir contexto entre sesiones del agente.

# Session Handoff

## Session ID: [date-uuid]
## Completed: YYYY-MM-DD HH:MM

## What Was Accomplished
- [Brief summary of what was done]

## Key Decisions
- Decision 1: [what was decided and why]
- Decision 2: [what was decided and why]

## Files Modified
- path/to/file.rs — [what changed]
- path/to/file2.rs — [what changed]

## Files Created
- path/to/new-file.rs — [purpose]

## Current State
- feature_list.json status: [summary]
- Branch: [branch-name]
- Uncommitted changes: [yes/no]

## Known Issues
- Issue 1: [description]
- Issue 2: [description]

## Next Steps
1. [Next action item]
2. [Next action item]

## Notes
- [Any additional context for the next session]

Harness Assessment Checklist

Evalúa tu harness actual en los 5 subsistemas. Puntúa 1-5 cada uno.

1. Instructions (Recipe Shelf)

¿Existe un AGENTS.md / CLAUDE.md?
¿Tiene progressive disclosure (corto, enlaza a docs/)?
¿Define startup workflow claro?
¿Especifica qué leer antes de codificar?
¿Las reglas son ejecutables, no abstractas?

2. State (Prep Station)

¿Existe un feature_list.json o equivalente?
¿Cada feature tiene id, dependencias, estado, y evidencia?
¿Hay session handoff template?
¿Se actualiza el progreso al final de cada sesión?

3. Verification (Quality Check)

¿init.sh corre verificación automática?
¿Hay tests que validen el trabajo del agente?
¿Hay type checks en el pipeline?
¿El agente no puede declarar "done" sin verificar?

4. Scope (Task Boundaries)

¿Hay política de una feature a la vez?
¿Están documentadas las dependencias entre features?
¿Hay Definition of Done checklist?
¿Hay next-task templates para evitar overreach?

5. Lifecycle (Session Management)

¿Existe init.sh?
¿Hay clean-state checklist?
¿Hay procedimiento de handoff documentado?
¿Los benchmarks miden mejora del harness?

Puntúa 1-5 cada subsistema. El de menor puntuación es tu bottleneck. Mejora allí primero.

△ Templates