Factory,
desde cero.

ANTES DE EMPEZAR

Qué vamos a usar.

Una terminal es una ventana para escribir comandos. En Windows abrí PowerShell desde Inicio; en macOS buscá Terminal; en Linux buscá Terminal en tus aplicaciones. Pegá una línea, presioná Enter y esperá a que termine antes de seguir.

uv instala las herramientas y administra Python, el lenguaje en que están hechas. PyPI es el catálogo desde el que se descargan esos paquetes. Git conserva versiones de los archivos. También necesitás un editor de texto plano; no uses un procesador de textos como Word.

El ejemplo trae un programa mínimo ya escrito; Factory aún no genera esa implementación automáticamente. No construye aquí una app completa: sirve para aprender el flujo sobre una regla pequeña. La herramienta se instala una vez. En esta guía creamos una carpeta vacía para tu proyecto y copiamos el ejemplo incluido en el paquete; no hace falta clonar Factory.

En Windows, activá “Extensiones de nombre de archivo” en el Explorador. Así podés evitar guardar un archivo como spec.md.txt cuando debe llamarse spec.md.

PASO 01

Instalá las herramientas.

Primero instalá Git para tu sistema. Luego instalá uv con el comando que corresponda. Estos comandos provienen de la guía oficial de uv.

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

curl -LsSf https://astral.sh/uv/install.sh | sh

Cerrá y volvé a abrir la terminal. Comprobá que ambos comandos estén disponibles:

uv --version
git --version

Instalá Python y las versiones del kit con las que se verificó esta guía. uv tool install guarda Factory y sus dependencias en un entorno separado de tu proyecto. La opción --with-executables-from permite usar también los comandos oracle y tasks de ese entorno.

uv python install 3.13
uv tool install --python 3.13 --with-executables-from oracle-metalenguaje,oracle-task oracle-factory==0.1.0a2
uv tool update-shell

Volvé a abrir la terminal y verificá las herramientas:

oracle-factory --version
oracle --version
tasks --version

Si tenías Trackertast instalado con uv, ejecutá uv tool uninstall trackertast y luego uv tool install oracle-task==0.2.0: tus carpetas de tareas se conservan. Si Oracle o Oracle Task ya están instalados y uv informa que sus comandos existen, instalá Factory sin --with-executables-from y conservá esas herramientas. Los nombres del paquete y del comando pueden ser distintos: oracle-metalenguaje instala oracle; oracle-task instala oracle-task y su alias tasks. Consultá Factory en PyPI y las versiones de sus dependencias: PyPI: Oracle y PyPI: Oracle Task.

PASO 02

Prepará un proyecto nuevo.

Desde la terminal, creá una carpeta y entrá en ella. Git empieza a conservar el historial de este proyecto; Factory prepara las carpetas de trabajo y copia el ejemplo incluido en su paquete.

mkdir mi-primer-proyecto
cd mi-primer-proyecto
git init
oracle-factory init
oracle-factory ejemplo notas

Si Git avisa que eligió un nombre para la rama inicial, podés continuar. Los comandos siguientes se ejecutan dentro de mi-primer-proyecto. Ahí encontrarás oracle.json, las carpetas tareas/, openspec/changes/, catalogos/ y el ejemplo en examples/notas/.

oracle-factory --help

Deberías ver init, ejemplo, nuevo, aprobar-spec, importar, revision, juzgar y cerrar. Factory trabaja en la carpeta actual; también podés elegir otra con oracle-factory --proyecto ruta-al-proyecto antes del subcomando.

PASO 03

Abrí tu primer cambio.

oracle-factory nuevo --capacidad notas "Comprobar el título de una nota"

Factory imprime el id del cambio y las carpetas creadas. El id identifica esa tarea: copialo completo, sin inventarlo ni abreviarlo para esta CLI.

Tu tarea vive en tareas/ID_DEL_CAMBIO/TAREA.md. El acuerdo vive en openspec/changes/ID_DEL_CAMBIO/.

PASO 04

Leé, acordá y elegí las medidas.

Abrí la carpeta del proyecto con tu editor. Copiá el contenido de examples/notas/proposal.md sobre el archivo proposal.md del cambio. Copiá examples/notas/spec.md sobre specs/notas/spec.md de ese mismo cambio. Son documentos completos que el comando ejemplo notas copió desde el paquete instalado.

# Capability: notas

## ADDED Requirements

### Requirement: titulo valido
The system SHALL reject empty or whitespace-only titles and accept titles containing text.

#### Scenario: título vacío
- WHEN el título es una cadena vacía
- THEN no se puede guardar la nota

#### Scenario: título con espacios
- WHEN el título contiene solo espacios
- THEN no se puede guardar la nota

#### Scenario: título con texto
- WHEN el título es Mi nota
- THEN se puede guardar la nota

Revisá los tres casos: título vacío, solo espacios y texto válido. Si ese comportamiento representa lo que querés, ejecutá:

oracle-factory aprobar-spec ID_DEL_CAMBIO

El comando muestra la propuesta y el acuerdo. La terminal te pide escribir una frase de confirmación. Hacelo solo después de leerlos. Ahora importá sus requisitos:

oracle-factory importar ID_DEL_CAMBIO

Oracle crea un archivo .requisito dentro de requisitos/. Su id completo aparece en la salida. Al principio queda SIN MEDIR: todavía no elegiste cómo comprobarlo.

Creá la carpeta catalogos si no existe. Copiá allí los dos archivos .oracle de examples/notas/catalogos/. Uno comprueba los resultados y otro que se hayan observado tres casos. Leé su contenido; las reglas declaran sus límites.

Abrí el archivo .requisito que acaba de generarse. Conservá su id, texto y fuente. Sustituí únicamente la línea que empieza con sin_medir por esta línea, con cuatro espacios al comienzo:

    medido_por notas.casos_ejecutados, notas.resultados

oracle cobertura --proyecto .

Tu requisito debe aparecer con ✓. Otros requisitos de la POC pueden seguir sin medir. Este enlace declara que las medidas representan los tres casos de tu acuerdo; no afirma que prueben cualquier comportamiento posible.

PASO 05

Probá el programa y registrá lo que pasó.

La implementación del ejemplo está en examples/notas/notas.py. Leela con el editor. Las pruebas comprueban los tres casos; el sensor ejecuta el programa y guarda sus resultados como datos para Oracle.

uv run --no-project --python 3.13 python -m unittest discover -s examples/notas -p "test_*.py" -v

uv run --no-project --python 3.13 python examples/notas/sensor.py --salida .factory-demo/hechos.json

Esperamos tres pruebas aprobadas y un archivo .factory-demo/hechos.json con tres observaciones. Esa carpeta de salida está excluida de Git; Oracle verificará los hechos por su propia huella.

Antes de revisar, guardá la versión de trabajo. Un commit es una fotografía de los archivos elegidos. Si Git todavía no conoce tu identidad, configurala solo para esta carpeta, reemplazando los datos:

git config user.name "Tu nombre"
git config user.email "tu-correo@example.com"

git add .
git commit -m "ID_DEL_CAMBIO: ejemplo de notas"

Terminá los cambios al código, documentos y medidas antes de la revisión. Si modificás el producto o creás otro commit después, las comprobaciones anteriores quedan desactualizadas.

PASO 06

Revisá el cambio y dejá un informe.

Revisá el programa y las pruebas, o pedí una revisión asistida. Guardá el informe real en .factory-demo/review.md con lo que se comprobó, los hallazgos y cómo se resolvieron. Clue aún no ejecuta esta revisión automáticamente.

Si quedan problemas, corregilos, repetí las pruebas y el comando del sensor del paso 5 para renovar los hechos; después creá el commit corregido. Cuando una persona decida aprobar la revisión y no queden hallazgos abiertos, registrala:

oracle-factory revision ID_DEL_CAMBIO --informe .factory-demo/review.md --revisor "Tu nombre" --decision aprobar --hallazgos-abiertos 0

Reemplazá “Tu nombre” por el de quien revisó. La terminal solicita una confirmación. El informe se conserva ligado a la versión del producto revisada.

PASO 07

Evaluá la evidencia y decidí el cierre.

oracle-factory juzgar ID_DEL_CAMBIO --con .factory-demo/hechos.json

oracle-factory estado ID_DEL_CAMBIO

Si las reglas se cumplen, el estado deja el cambio listo para la decisión final. Si falta evidencia, hay un resultado rojo o cambió la versión revisada, Factory explica qué hay que renovar. Un “verde” se refiere a estas medidas y estos hechos.

oracle-factory cerrar ID_DEL_CAMBIO

Revisá los informes antes de confirmar. El cierre deja la tarea marcada como cerrada. La guía termina con un cambio local trazable; no publica una app ni envía tus cambios a GitHub.

SI ALGO NO FUNCIONA

Volvé al punto que necesita atención.