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 CLI instalada permite seleccionar otro proyecto con --proyecto; en esta guía trabajamos dentro del checkout descargado.

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 cada herramienta en su propio entorno.

uv python install 3.13
uv tool install --python 3.13 oracle-metalenguaje==0.38.1
uv tool install --python 3.13 trackertast==0.1.0
uv tool update-shell

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

oracle --version
tasks --version

Los nombres del paquete y del comando pueden ser distintos: oracle-metalenguaje instala oracle; trackertast instala tasks. Consultá las versiones en PyPI: Oracle y PyPI: Trackertast.

PASO 02

Descargá la POC de Factory.

Elegí una carpeta de trabajo, abrí la terminal allí y descargá el proyecto. Git crea una carpeta nueva llamada oracle-factory; el segundo comando entra en ella.

git clone https://github.com/Segtem/oracle-factory.git
cd oracle-factory
git switch -c demo/notas

La rama demo/notas es tu espacio para esta prueba. Todos los comandos siguientes se ejecutan dentro de oracle-factory.

uv run --no-project --python 3.13 python fabrica.py --help

Deberías ver los comandos nuevo, aprobar-spec, importar, revision, juzgar y cerrar. No hace falta activar un entorno ni instalar Python por separado: uv lo selecciona para cada ejecución.

PASO 03

Abrí tu primer cambio.

uv run --no-project --python 3.13 python fabrica.py 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 incluidos en el repositorio.

# 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á:

uv run --no-project --python 3.13 python fabrica.py 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:

uv run --no-project --python 3.13 python fabrica.py 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:

uv run --no-project --python 3.13 python fabrica.py 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.

uv run --no-project --python 3.13 python fabrica.py juzgar ID_DEL_CAMBIO --con .factory-demo/hechos.json

uv run --no-project --python 3.13 python fabrica.py 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.

uv run --no-project --python 3.13 python fabrica.py 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.