Project Templates

Purpose

This page documents the lab's project templates. The lab has four templates:

• Next.js template — for full-stack web apps.
• CLI Python tool template — for command-line tools that the lab's agents invoke.
• Research framework template — for adding a new tool to the research framework.
• Agent skill template — for adding a new capability to the lab's agents.

Each template has a standard structure, a standard documentation requirement, and a standard workflow. A new project should pick the closest template and follow it.

Template selection

Next.js template

Location

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

Stack

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

Structure

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

The template's .agents/skills/ includes:

• nextjs-best-practices/ — the framework's Next.js best practices.
• react-patterns/ — common React patterns.
• tailwind-utility/ — Tailwind utility classes.
• zustand-state/ — Zustand state management.
• shadcn-ui/ — shadcn/ui components.

Documentation requirement

Every project created from this template must have a docs/ directory with:

• README.md — project overview.
• code-reference.md — interfaces, functions, patterns.
• architecture.md — technical architecture.

The documentation is updated with every commit that changes the architecture or the public interfaces.

Workflow

1. Copy the template to a new directory.
2. Update package.json with the project name and dependencies.
3. Update app/page.tsx with the project-specific home page.
4. Add the project-specific routes under app/.
5. Add the project-specific components under components/.
6. Add the project-specific stores under stores/.
7. Write the documentation under docs/.
8. Initialize git and commit.
9. Run npm install and npm run dev to verify.

CLI Python tool template

Location

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

A real instance is at {workspace-root}/movie-scraper-tools/tools/torrent-finder/.

Stack

• Python 3.10+
• Click (CLI)
• Pydantic (data validation)
• requests, beautifulsoup4, lxml (HTTP and parsing)
• pytest (testing)
• AutoSkills (project context for the coding sub-agent)

Structure

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

Skills

The template's .agents/skills/ includes the AutoSkills content. The package.json is a small JSON file that the coding sub-agent uses to understand the project.

Documentation requirement

Every tool must have:

• README.md — what the tool does, how to install, how to use.
• TOOL.md — the technical spec (input schema, output schema, examples, failure modes).
• SKILL.md — the activation file the Coordinator reads.
• AGENTS.md — instructions for the coding sub-agent.

The TOOL.md is the contract between the tool and the agent. It is updated when the tool's interface changes.

Workflow

1. Copy the template to a new directory under tools/.
2. Update tool_name, package.json, and pyproject.toml.
3. Implement lib.py (core logic) and main.py (CLI entry point).
4. Write tests under tests/.
5. Write README.md, TOOL.md, SKILL.md, and AGENTS.md.
6. Register the tool in the project's tools.json.
7. Run the tests with pytest.
8. Commit.

Research framework template

Location

A new tool is added to the research framework by creating a new package under {research-root}/docs/orchestrator/tools/tool-N-name/ or {research-root}/docs/domains/<domain>/tool-N-name/.

A real instance is docs/orchestrator/tools/tool-h-report-generator/.

Structure

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

The tool's skills/<skill-name>/SKILL.md describes when to use the tool and the workflow.

Documentation requirement

Every research tool must have:

• README.md — what the tool does.
• docs/README.md — deeper documentation.
• skills/<skill-name>/SKILL.md — the activation file.
• tests/ — unit tests for the tool's logic.

The tool's public API is documented in docs/README.md with input and output schemas.

Workflow

1. Create the package under docs/orchestrator/tools/tool-N-name/ (use the next available letter for the prefix).
2. Implement the tool's modules under src/.
3. Write tests under tests/.
4. Write the SKILL.md and the documentation.
5. Register the tool in the orchestrator (if needed).
6. Run the tests with pytest.
7. Verify the tool can be invoked through the orchestrator's CLI.

Agent skill template

Location

Skills are added to the agent's .agents/skills/ directory. A skill is a single SKILL.md file (and optional supporting files).

Structure

skill-name/
├── SKILL.md           ← the main file
├── README.md          ← optional
└── examples/          ← optional
    └── example-1.md

SKILL.md format

The SKILL.md has a YAML frontmatter and a markdown body:

---
name: skill-name
description: One-paragraph description of the skill.
---
 
# Skill Name
 
## When to Use This Skill
 
[Trigger phrases and conditions.]
 
## Workflow
 
1. Step 1
2. Step 2
3. ...
 
## Inputs
 
[What the skill needs.]
 
## Outputs
 
[What the skill produces.]
 
## Failure modes
 
[What can go wrong.]

Documentation requirement

Every skill must have a SKILL.md with the frontmatter (name, description) and the body (when to use, workflow, inputs, outputs, failure modes).

The skill is loaded by the Coordinator's skill loader when the trigger phrases match.

Workflow

1. Create a directory under .agents/skills/.
2. Write SKILL.md with the frontmatter and the body.
3. Add any supporting files (README, examples).
4. Verify the skill can be activated by the Coordinator.

Conventions

All templates share these conventions:

• Documentation is part of the deliverable. A project without documentation is incomplete.
• Skills are first-class. Every project has a .agents/skills/ directory with the relevant skills.
• Tests are first-class. Every project has a tests/ directory with unit tests.
• Configuration is explicit. Configuration is in files, not in code.
• Sanitization is required. No real usernames, no real agent names, no real absolute paths in the documentation. Use placeholders.

See also

• Tooling Layer
• Tool Structure
• Tool Spec
• Tool Registry
• Documentation Rule