Project Templates

Propósito

Esta página documenta los templates de proyecto del lab. El lab tiene cuatro templates:

• Next.js template — para aplicaciones web full-stack.
• CLI Python tool template — para herramientas de línea de comandos que invocan los agentes del lab.
• Research framework template — para añadir una herramienta nueva al research framework.
• Agent skill template — para añadir una capacidad nueva a los agentes del lab.

Cada template tiene una estructura estándar, un requisito de documentación estándar y un workflow estándar. Un proyecto nuevo debería escoger el template más cercano y seguirlo.

Selección de template

Next.js template

Ubicación

{workspace-root}/stack_inicial_proyectos/front-end/nextjs/

Stack

• Next.js 15
• React 19
• Tailwind CSS v4
• Zustand (state)
• shadcn/ui (components)
• TypeScript

Estructura

nextjs/
├── app/                ← Next.js app router
│   ├── layout.tsx
│   ├── page.tsx
│   ├── globals.css
│   └── ...
├── components/         ← React components
│   ├── ui/             ← shadcn/ui components
│   └── ...
├── lib/                ← utilities
├── hooks/              ← custom hooks
├── stores/             ← Zustand stores
├── public/             ← static assets
├── docs/               ← project documentation
│   ├── README.md
│   ├── code-reference.md
│   └── architecture.md
├── AGENTS.md           ← agent instructions
├── package.json
├── next.config.js
├── tailwind.config.js
├── tsconfig.json
└── .env.example

Skills

El .agents/skills/ del template incluye:

• nextjs-best-practices/ — las best practices de Next.js del framework.
• react-patterns/ — patrones comunes de React.
• tailwind-utility/ — clases utility de Tailwind.
• zustand-state/ — gestión de estado con Zustand.
• shadcn-ui/ — componentes de shadcn/ui.

Requisito de documentación

Cada proyecto creado desde este template debe tener un directorio docs/ con:

• README.md — project overview.
• code-reference.md — interfaces, funciones, patrones.
• architecture.md — arquitectura técnica.

La documentación se actualiza con cada commit que cambie la arquitectura o las interfaces públicas.

Workflow

1. Copia el template a un directorio nuevo.
2. Actualiza package.json con el nombre del proyecto y las dependencias.
3. Actualiza app/page.tsx con la home page específica del proyecto.
4. Añade las rutas específicas del proyecto bajo app/.
5. Añade los componentes específicos bajo components/.
6. Añade los stores específicos bajo stores/.
7. Escribe la documentación bajo docs/.
8. Inicializa git y haz commit.
9. Corre npm install y npm run dev para verificar.

CLI Python tool template

Ubicación

{workspace-root}/devclaw-tools/stack-template/tool_name/ (estructura general)

Una instancia real está en {workspace-root}/movie-scraper-tools/tools/torrent-finder/.

Stack

• Python 3.10+
• Click (CLI)
• Pydantic (data validation)
• requests, beautifulsoup4, lxml (HTTP y parsing)
• pytest (testing)
• AutoSkills (contexto del proyecto para el coding sub-agent)

Estructura

tool_name/
├── __init__.py
├── main.py            ← CLI entry point
├── lib.py             ← core logic
├── requirements.txt
├── package.json       ← AutoSkills
├── pyproject.toml
├── README.md
├── SKILL.md           ← activación por el Coordinator
├── TOOL.md            ← technical spec
├── AGENTS.md          ← agent instructions
└── tests/
    ├── __init__.py
    └── test_main.py

Skills

El .agents/skills/ del template incluye el contenido AutoSkills. El package.json es un pequeño fichero JSON que el coding sub-agent usa para entender el proyecto.

Requisito de documentación

Cada herramienta debe tener:

• README.md — qué hace la herramienta, cómo instalarla, cómo usarla.
• TOOL.md — la spec técnica (input schema, output schema, ejemplos, failure modes).
• SKILL.md — el fichero de activación que lee el Coordinator.
• AGENTS.md — instrucciones para el coding sub-agent.

El TOOL.md es el contrato entre la herramienta y el agente. Se actualiza cuando cambia la interfaz de la herramienta.

Workflow

1. Copia el template a un directorio nuevo bajo tools/.
2. Actualiza tool_name, package.json y pyproject.toml.
3. Implementa lib.py (core logic) y main.py (CLI entry point).
4. Escribe tests bajo tests/.
5. Escribe README.md, TOOL.md, SKILL.md y AGENTS.md.
6. Registra la herramienta en el tools.json del proyecto.
7. Corre los tests con pytest.
8. Commit.

Research framework template

Ubicación

Una herramienta nueva se añade al research framework creando un nuevo paquete bajo {research-root}/docs/orchestrator/tools/tool-N-name/ o {research-root}/docs/domains/<domain>/tool-N-name/.

Una instancia real es docs/orchestrator/tools/tool-h-report-generator/.

Estructura

tool-N-name/
├── requirements.txt
├── pyproject.toml
├── README.md
├── src/
│   ├── __init__.py
│   ├── <module>.py
│   ├── <other_module>.py
│   └── ...
├── tests/
│   ├── __init__.py
│   └── test_<module>.py
├── docs/
│   └── README.md
└── skills/
    └── <skill-name>/
        └── SKILL.md

Skills

El skills/<skill-name>/SKILL.md de la herramienta describe cuándo usarla y el workflow.

Requisito de documentación

Cada herramienta de research debe tener:

• README.md — qué hace la herramienta.
• docs/README.md — documentación más profunda.
• skills/<skill-name>/SKILL.md — el fichero de activación.
• tests/ — tests unitarios para la lógica de la herramienta.

La API pública de la herramienta está documentada en docs/README.md con los esquemas de input y output.

Workflow

1. Crea el paquete bajo docs/orchestrator/tools/tool-N-name/ (usa la siguiente letra disponible para el prefijo).
2. Implementa los módulos de la herramienta bajo src/.
3. Escribe tests bajo tests/.
4. Escribe el SKILL.md y la documentación.
5. Registra la herramienta en el orquestador (si es necesario).
6. Corre los tests con pytest.
7. Verifica que la herramienta se puede invocar a través del CLI del orquestador.

Agent skill template

Ubicación

Los skills se añaden al directorio .agents/skills/ del agente. Un skill es un único fichero SKILL.md (y ficheros de soporte opcionales).

Estructura

skill-name/
├── SKILL.md           ← el fichero principal
├── README.md          ← opcional
└── examples/          ← opcional
    └── example-1.md

Formato de SKILL.md

El SKILL.md tiene un YAML frontmatter y un body markdown:

---
name: skill-name
description: Descripción de un párrafo del skill.
---
 
# Skill Name
 
## When to Use This Skill
 
[Frases disparadoras y condiciones.]
 
## Workflow
 
1. Paso 1
2. Paso 2
3. ...
 
## Inputs
 
[Lo que el skill necesita.]
 
## Outputs
 
[Lo que el skill produce.]
 
## Failure modes
 
[Lo que puede fallar.]

Requisito de documentación

Cada skill debe tener un SKILL.md con el frontmatter (name, description) y el body (when to use, workflow, inputs, outputs, failure modes).

El skill lo carga el skill loader del Coordinator cuando las frases disparadoras matchean.

Workflow

1. Crea un directorio bajo .agents/skills/.
2. Escribe SKILL.md con el frontmatter y el body.
3. Añade los ficheros de soporte (README, examples).
4. Verifica que el Coordinator puede activar el skill.

Convenciones

Todos los templates comparten estas convenciones:

• La documentación es parte del deliverable. Un proyecto sin documentación está incompleto.
• Los skills son first-class. Cada proyecto tiene un directorio .agents/skills/ con los skills relevantes.
• Los tests son first-class. Cada proyecto tiene un directorio tests/ con tests unitarios.
• La configuración es explícita. La configuración está en ficheros, no en código.
• La sanitización es obligatoria. Sin usernames reales, sin nombres de agentes reales, sin rutas absolutas reales en la documentación. Usa placeholders.

Ver también

• Tooling Layer
• Tool Structure
• Tool Spec
• Tool Registry
• Regla de documentación