# Tu primera tarea (/docs/empezar/primera-tarea)

Vas a conectar tu máquina como runtime, crear un agente y asignarle un issue. El agente trabajará en una rama
propia y, cuando termine, revisarás su diff y lo integrarás. Necesitas un servidor en marcha
([Instalación local](/docs/empezar/instalacion-local)) y un workspace.

Lleva unos diez minutos, y la mayor parte es esperar al agente.

## Antes de empezar [#antes-de-empezar]

- Un CLI de agentes instalado en la máquina, con su sesión iniciada. Esta guía usa Claude Code. Si no tienes ninguno,
  `hqf harness install claude-code` lo instala sin sudo.
- git 2.45.1 o más nuevo.

## Pasos [#pasos]

<Steps>
<Step>
### Compila el CLI [#compila-el-cli]

```bash
make cli
```

Deja el binario en `bin/hqf`. Ponlo en tu `PATH` o llámalo con su ruta.
</Step>

<Step>
### Conecta tu máquina [#conecta-tu-máquina]

```bash
./bin/hqf setup --server http://127.0.0.1:8080 --app http://127.0.0.1:3000
```

Te pide el correo y el código, como la web. Después elige tu workspace, detecta tus CLIs de agentes y arranca el
daemon en segundo plano:

```text
→ Servidor: http://127.0.0.1:8080
Correo: ℹ El servidor no tiene correo configurado: el código aparece en los logs del backend.
Código: ✔ Sesión iniciada como ana (ana@hqfabric.example)
  ✔ Acme
  CLIs de agentes detectados:
    ✔ Claude Code          2.1.0      /usr/local/bin/claude
✔ Daemon iniciado (pid 6088). Logs: /Users/ana/.hqfabric/daemon.log

✔ Listo. Abre http://127.0.0.1:3000, crea un agente y asígnale un issue.
```

En la web, **Runtimes** muestra tu máquina **En línea**, con sus **CLIs detectados**.
</Step>

<Step>
### Crea un proyecto [#crea-un-proyecto]

En **Ajustes → Proyectos**, pulsa **Nuevo proyecto**. Ponle un **Nombre** y la **Rama base**, por ejemplo `main`, y
pulsa **Crear proyecto**. La **URL del repositorio** es opcional.
</Step>

<Step>
### Vincula el repo de tu máquina [#vincula-el-repo-de-tu-máquina]

Para que el agente trabaje sobre tu código, vincula la carpeta del repo al proyecto. En **Runtimes**, pulsa
**Configurar** en tu máquina y, en **Repos de los proyectos**, **Vincular**. El daemon recibe el cambio en el acto.

Desde la terminal, el mismo vínculo es:

```bash
./bin/hqf repo link api ~/src/api
./bin/hqf daemon stop
./bin/hqf daemon start
```

El daemon lee su configuración al arrancar: si lo vinculas con `hqf repo link`, reinícialo.

Si no vinculas nada, el proyecto no se queda sin trabajar. El runtime clona la URL del repositorio, si la pusiste, o
crea un repo de prueba vacío en `~/.hqfabric/repos/<workspace>/_scratch-<proyecto>`. Para una primera prueba, ese
repo de prueba basta.
</Step>

<Step>
### Crea un agente [#crea-un-agente]

En **Agentes**, pulsa **Nuevo agente**. Ponle un **Nombre**, elige **Claude Code** en **Proveedor** y tu máquina en
**Runtime**, y pulsa **Crear agente**.

El agente nace con la autonomía segura: con Claude Code, edita archivos y pide permiso para ejecutar comandos.
Corre en modo autónomo, sin terminal interactiva, y se activa cuando se le asigna un issue o lo mencionan con `@`.
</Step>

<Step>
### Asígnale un issue [#asígnale-un-issue]

En el **Tablero**, pulsa **Nuevo issue** (o la tecla `C`). Escribe el **Título** y la **Descripción** de lo que
quieres, elige el **Proyecto** y, en **Asignado a**, tu agente.

Al asignarlo, HQ Fabric encola una tarea. El daemon la reclama en unos segundos, crea un worktree con una rama nueva,
como `hqf/hqf-1-claude-0f498f`, y lanza el agente ahí.
</Step>

<Step>
### Mira cómo trabaja [#mira-cómo-trabaja]

Abre la tarea desde el issue. **Terminal** muestra la salida del agente en vivo, **Pasos** sus herramientas y
**Contexto** el lienzo que recibió: el presupuesto de tokens, cuántos usó y qué entró por cada ranura.

Si el agente necesita algo de ti, pregunta o se bloquea, y lo verás en el issue y en **Necesita de ti**. Cuando
termina, la tarea queda completada y el issue pasa a revisión.
</Step>

<Step>
### Revisa el diff y apruébalo [#revisa-el-diff-y-apruébalo]

En **Diff** ves lo que cambió, archivo por archivo. Si algo debe cambiar, pulsa **Comentar esta línea**; al enviar
los comentarios, el agente los recibe en una ejecución nueva sobre la misma rama.

Si está bien, pulsa **Aprobar e integrar**. Sin GitHub, la rama se fusiona en la rama base de tu repo y el issue pasa a
hecho. Con un proyecto de GitHub, la rama se sube y se abre el PR. **Aprobar sin integrar** aprueba y deja la rama
como está.
</Step>
</Steps>

## Comprueba que funciona [#comprueba-que-funciona]

En tu repo, la rama base tiene el commit del agente y el de la fusión:

```bash
git -C ~/src/api log --oneline -3
```

```text
9100caf Merge hqf/hqf-2-claude-763b06 (HQF-2: Documentar el límite de peticiones)
5f8a53d HQF-2: Documentar el límite de peticiones
f8d27da primer commit
```

## Probar sin gastar tokens [#probar-sin-gastar-tokens]

El repo trae `scripts/fake-claude.sh`, un Claude Code falso para pruebas. Ponlo en tu `PATH` como `claude` antes de
arrancar el daemon: escribe un archivo de ejemplo, comenta en el issue y deja una lección, sin llamar a ningún modelo.

```bash
mkdir -p ~/bin-falso
cp scripts/fake-claude.sh ~/bin-falso/claude
chmod +x ~/bin-falso/claude
PATH="$HOME/bin-falso:$PATH" ./bin/hqf daemon start
```

## Si algo falla [#si-algo-falla]

- **El daemon dice que arrancó, pero la máquina sale desconectada.** `hqf daemon start` lo dice aunque el proceso
  muera enseguida. Mira `./bin/hqf daemon logs`.
- **El agente trabajó en otro repo.** Vinculaste la carpeta con `hqf repo link` con el daemon en marcha. Reinícialo, o
  vincúlala desde **Runtimes → Configurar**.
- **La tarea falla porque falta el CLI.** El runtime no encontró el binario del proveedor. Comprueba
  `./bin/hqf agents` en esa máquina.