Guías prácticas de autoría y canalización

Recorridos orientados a tareas para crear artefactos de Apothem y manejar la canalización de planes. Cada guía responde a una única pregunta concreta.

Para las recetas de configuración de primera ejecución (añadir un entorno, editar el perfil, ejecutar el instalador), consulta en su lugar la sección Recetas prácticas.

Canalización de la suite de planCopy Anchor Link

¿Cómo refino contenido en bruto hasta convertirlo en una especificación?Copy Anchor Link

Invoca /plan-spec con el contenido en bruto como entrada. El rol Forge ejecuta seis fases de transformación (Descubrimiento, Consideración Meticulosa, Mapeo de Potencia, Verificación de Preservación, Aplicación de Pericia, Barrido de Resolución de Preguntas) y emite la especificación consolidada en .apothem/plans/{suite}/_spec/spec.md. Consulta src/apothem/commands/plan-spec.md para el protocolo completo.

¿Cómo genero una suite de plan a partir de una especificación?Copy Anchor Link

Invoca /plan-generate .apothem/plans/{suite}/_spec/spec.md una vez que /plan-spec haya escrito la especificación. El generador emite los archivos canónicos de infraestructura más los archivos phases/NN-kebab-topic/PHASE.md por fase. Consulta src/apothem/commands/plan-generate.md.

¿Cómo reviso un plan generado?Copy Anchor Link

Invoca /plan-review path/to/plan-suite/. El revisor aplica las nueve técnicas de planificación y emite cuadros de mando. Los cuadros de mando con fallos bloquean la ejecución en SHARED+ hasta que se resuelvan. Consulta src/apothem/commands/plan-review.md.

¿Cómo ejecuto un plan?Copy Anchor Link

Invoca /plan-execute path/to/plan-suite/ [phase-id]. Sin un phase-id, se ejecuta la siguiente fase pendiente. Con un id concreto, solo se ejecuta esa fase. Consulta src/apothem/commands/plan-execute.md.

¿Cómo compruebo el estado de un plan?Copy Anchor Link

Invoca /plan-status path/to/plan-suite/ [--verbose]. Informe de solo lectura. Consulta src/apothem/commands/plan-status.md.

Autoría de artefactosCopy Anchor Link

¿Cómo añado una nueva regla?Copy Anchor Link

1. Elige un nombre de archivo en kebab-case bajo src/apothem/rules/, por ejemplo, src/apothem/rules/my-new-rule.md.
2. Escribe el frontmatter (name, description, pathFilter, alwaysApply).
3. Escribe el cuerpo con las secciones canónicas: Purpose, Obligations, Seriousness Scaling, Anti-Patterns, Enforcement y Bindings.
4. Ejecuta python scripts/dev/validate_ecosystem.py --check frontmatter-cohort para verificar.

El cargador de reglas se basa en globs: recoge todo archivo que coincida con src/apothem/rules/*.md, así que no hace falta ninguna entrada de registro; basta con colocar el archivo con el nombre canónico en el directorio para completar el registro.

¿Cómo añado un nuevo trabajador delegado?Copy Anchor Link

Elige un nombre de archivo en kebab-case bajo el directorio que se muestra a continuación, con la forma my-worker.md:

src/apothem/agents/
src/apothem/agents/my-worker.md

Después:

1. Escribe el frontmatter, incluyendo name, version, updated, description, tools, disallowedTools, maxTurns y effort.

2. Escribe el prompt del sistema como cuerpo.

La cohorte de trabajadores delegados se carga mediante globs desde src/apothem/agents/*.md, así que el archivo con el nombre canónico se recoge en cuanto se coloca; no hay ninguna tabla de registro que editar.

¿Cómo añado un nuevo hook?Copy Anchor Link

1. Escribe un mensaje de contexto bajo src/apothem/hooks/messages/<event>-<scope>.md.
2. Conecta el hook en settings.json.
3. Actualiza la canalización de hooks.
4. Ejecuta python scripts/dev/validate_ecosystem.py.

Puertas de calidadCopy Anchor Link

¿Cómo ejecuto las puertas de calidad locales?Copy Anchor Link

python -m ruff check .
python -m ruff format --check .
python -m mypy
python -m pytest -q
python scripts/dev/validate_ecosystem.py
python scripts/dev/chaos_pass.py

La canalización de CI ejecuta el mismo conjunto en paralelo.

¿Cómo compruebo el frontmatter de una sola clase de artefacto?Copy Anchor Link

python scripts/dev/validate_ecosystem.py --check frontmatter-cohort