Flujo de trabajo diario

Esta guía recorre una rutina diaria repetible con AWR: comprobar el estado de tu proyecto, reservar o reanudar una tarea, registrar el progreso, guardar un punto de control y hacer el traspaso para que tú — o un agente — podáis continuar exactamente donde se detuvo todo.

Antes de empezar, asegúrate de que tu proyecto está inicializado y de que conoces los conceptos básicos (elementos de trabajo, sesiones, reservas, puntos de control): consulta Inicio rápido y Conceptos. La misma rutina funciona sobre MCP; consulta MCP.

Una nota sobre versiones: algunas capacidades de abajo (la vista de acción y work edit) reflejan el árbol fuente actual y pueden no estar habilitadas en el paquete publicado. Ejecuta awr --help para ver qué soporta tu instalación.

1. Empieza tu día: encuentra la acción siguiente

Ejecuta una comprobación de estado antes de cualquier otra cosa:

awr status

awr status y la herramienta MCP awr_project_status usan por defecto la vista de acción (view="action"). Separa tu trabajo abierto en cuatro colas, con un máximo de cinco entradas por cola más los recuentos exactos de totales y omitidos:

Acota la selección con selectores repetibles: se intersecan:

awr status --work GUIDE-1 --goal GOAL-1 --milestone M1

La cola es navegación, no autorización: las reservas y las comprobaciones de finalización siguen aplicándose por sus propias acciones. awr ready mantiene su significado más estricto — elegible para una reserva nueva — y omite el trabajo en curso.

2. Reserva o reanuda la tarea

Configura una vez por shell para que cada comando esté vinculado al proyecto y formateado en JSON:

AWR_BIN=/absolute/path/to/awr
AWR_PROJECT=/absolute/path/to/initialized/project
AWR_WORK=EXAMPLE-001
AWR_AGENT=agent-primary
AWR_MODEL=your-current-model
AWR_NOTES=$(mktemp -d "${TMPDIR:-/tmp}/awr-session.XXXXXX")
awrj() { "$AWR_BIN" --project "$AWR_PROJECT" --json "$@"; }

Trabajo nuevo, reservado bajo una sesión nueva:

AWR_REV=$(awrj status | jq -er '.project_revision')
awrj session start --work "$AWR_WORK" --agent "$AWR_AGENT" \
  --provider generic --model "$AWR_MODEL" --claim --ttl-ms 3600000 \
  --expected-revision "$AWR_REV" > "$AWR_NOTES/start.json"
AWR_SESSION=$(jq -er '.session.id' "$AWR_NOTES/start.json")

La reserva es propiedad en tiempo de ejecución; no reescribe el estado del trabajo en la fuente. Si ya existe una sesión para el trabajo, inspecciónala con session show y confirma la propiedad: un agente o modelo distinto continúa a través de session resume en su propia sesión.

3. Compila tu contexto

Antes de editar, construye el paquete de contexto para la sesión:

awrj context bootstrap --session "$AWR_SESSION" --budget 1000 \
  > "$AWR_NOTES/bootstrap.json"
jq -e '.context.complete' "$AWR_NOTES/bootstrap.json"

awrj context compile --work "$AWR_WORK" --session "$AWR_SESSION" \
  --budget 5000 > "$AWR_NOTES/context.json"
jq -e '.completeness.complete and (.work_context != null)' "$AWR_NOTES/context.json"

Lee el paquete, no solo el booleano. Ante BudgetExceeded, amplía el presupuesto o acota el alcance; ante SourceStale, ejecuta primero awr source reindex.

4. Trabaja y luego guarda un punto de control

Registra lo que realmente pasó: fallos, contexto que falta y cabos abiertos:

AWR_CONTEXT_HASH=$(jq -er '.work_context.context_hash' "$AWR_NOTES/context.json")
AWR_REV=$(awrj status | jq -er '.project_revision')
awrj session checkpoint --session "$AWR_SESSION" --agent "$AWR_AGENT" \
  --context-hash "$AWR_CONTEXT_HASH" \
  --digest "Record the work actually done; do not invent a passing review." \
  --next-action "State the exact next operator or agent action." \
  --open-loop "List every unresolved loop." \
  --expected-project-revision "$AWR_REV" > "$AWR_NOTES/checkpoint.json"

Algunas cosas que hay que entender sobre los puntos de control:

• --agent es una declaración del llamador. Una que no coincide con la sesión se rechaza con orientación de reanudación; una que coincide permanece sin verificar: la CLI no puede autenticar el modelo real detrás de una etiqueta. Omitirlo registra el origen como undeclared.
• El resumen y el hash de contexto son tus afirmaciones. Usa el último hash realmente usado; un punto de control guardado no prueba contexto verificado, pruebas superadas ni trabajo completado.
• Para el guarda de revisión, usa el project_revision de nivel superior de session show, no session.revision. Ante un conflicto, inspecciona los cambios intermedios antes de reintentar.
• Un punto de control nunca reescribe la acción siguiente respaldada por la fuente. Para cambiar el contrato, edita la fuente autoritativa.

5. Corrige pequeños campos sin editar YAML a mano

Cuando el plan fuente necesita una pequeña corrección — digamos que la fuente dice «Redactar la guía» pero el siguiente paso real es «Revisar la conclusión» — previsualiza la edición:

awr --json work edit GUIDE-1 --request-key guide-next-1 --actor writer \
  --reason 'Clarify the review step' --next-action 'Review the conclusion'

La respuesta muestra la ubicación en la fuente, los valores antiguo y nuevo, y las huellas con las que aceptar. Revísalas y luego repite el comando añadiendo:

--accept --source-fingerprint SOURCE_FINGERPRINT \
--expected-preview PREVIEW_FINGERPRINT --expected-revision REVISION

Los campos soportados son --title, --summary, --priority y --next-action. Tras una respuesta incierta, comprueba host status --key guide-next-1; una edición de campo nunca cambia la propiedad, el ciclo de vida ni la verificación.

6. Termina la sesión — o haz el traspaso

Cuando pares por el día:

AWR_REV=$(awrj status | jq -er '.project_revision')
awrj session end --session "$AWR_SESSION" --outcome incomplete \
  --expected-revision "$AWR_REV"

Terminar libera la reserva; no completa el trabajo fuente. Tu punto de control del paso 4 es lo que permite que el trabajo se reanude limpiamente.

7. Retoma donde lo dejaste tú (o un agente)

Más tarde — o desde un agente distinto — reanuda desde la sesión predecesora:

AWR_PREDECESSOR=the-recorded-awr-session-id
awrj session show "$AWR_PREDECESSOR"
AWR_REV=$(awrj status | jq -er '.project_revision')
awrj session resume --from-session "$AWR_PREDECESSOR" \
  --agent "$AWR_AGENT" --provider generic --model "$AWR_MODEL" \
  --budget 5000 --expected-revision "$AWR_REV" > "$AWR_NOTES/resume.json"
jq -e '.context_ready' "$AWR_NOTES/resume.json"
AWR_SESSION=$(jq -er '.resumed.session.id' "$AWR_NOTES/resume.json")

Reanudar crea una sesión AWR nueva; no cambia el chat nativo de tu host. Luego compila el contexto de nuevo (paso 3) y continúa. Tras la compactación del host, si la misma sesión AWR sigue activa, simplemente compila de nuevo: reserva session resume para un traspaso real.

Para comparar el plan con lo último registrado, comprueba el objeto progress expuesto por status --view action y work show KEY:

• source_next_action — el texto autoritativo del plan fuente, con su localizador, revisión de fuente y frescura.
• latest_checkpoint_next_action — el punto de control más reciente para este trabajo, rama y propiedad exactos, o null si no hay ninguno.
• differs_from_source — true cuando el texto del punto de control diverge de la fuente. Una observación, no un problema: guardar el progreso nunca modifica el contrato original ni establece la finalización.

El texto de progreso tiene un tope de 240 caracteres (señalado como truncated); usa work show KEY y session show SESSION para el texto completo.

Cuando algo va mal

• Respuesta de guardado incierta → comprueba host status --key REQUEST_KEY; usa host recover solo para una operación pendiente inspeccionada.
• Conflicto de revisión → lee status para el project_revision actual y reintenta con él.
• Punto de control sospechoso → lee el registro completo con session show SESSION; un guardado interrumpido sin recibo de finalización no es un punto de control de recuperación.

Para más modos de fallo, consulta Solución de problemas. Para el vocabulario de esta rutina, consulta Conceptos.