Understanding the Difference Between Tasks, Templates, and Checklists in AIOS-Core

Tasks are executable workflows that perform actions, templates are static document blueprints for generating artifacts, and checklists are validation protocols for quality gates—each serving distinct roles in AIOS-Core's task-first architecture.

AIOS-Core, developed by SynkraAI, implements a task-first architecture that organizes automation assets into three fundamental categories. Understanding the difference between tasks, templates, and checklists in aios-core is essential for building effective agent workflows and maintaining clean separation between executable logic, document generation, and quality validation.

Core Concepts: Tasks vs. Templates vs. Checklists

Tasks: Executable Workflows

A Task is an executable workflow that describes how to perform an operation. It defines input schemas, processing steps, and output formats, serving as the primary entry point for agent commands or user interactions.

Tasks contain executable logic such as CLI commands, scripts, or LLM-driven steps. In the source tree, development tasks reside in /.aios-core/development/tasks/, while runtime tasks live in /.aios-core/tasks/.

A minimal task definition from the test fixtures demonstrates the structure:

# File: tests/unit/squad/fixtures/complete-squad/tasks/valid-task.md

---
task: Test Task
responsavel: @test-agent
responsavel_type: agent
atomic_layer: task
Entrada: |
  - input_param: string (required)
  - optional_param: boolean (default: false)
Saida: |
  - result: Object with { success, data }
Checklist:
  - [ ] Validate input parameters
  - [ ] Execute main logic
  - [ ] Return result
---

Execute a task using the CLI:

aios run-task test-task --input_param "hello"

Templates: Document Blueprints

A Template is a static, data-driven document blueprint that contains placeholders and optional LLM-driven elicitation blocks. Unlike tasks, templates do not execute code; they are rendered by the Template Engine to produce final artifacts such as PRDs, stories, or epics.

Templates reside in .aios-core/product/templates/ and define output formats, filenames with placeholder variables, and document structures.

The Story template definition illustrates this approach:

# File: .aios-core/product/templates/story-tmpl.yaml

template:
  id: story-template-v2
  name: Story Document
  version: 2.0
  output:
    format: markdown
    filename: docs/stories/{{epic_num}}.{{story_num}}.{{story_title_short}}.md

Generate a document from a template:

aios create-doc story --title "Login Flow" --epic_num 2 --story_num 3

The engine replaces placeholders like {{epic_num}} and {{story_title_short}} with provided values to produce the final markdown file.

Checklists: Validation Protocols

A Checklist is a static markdown file that encodes validation steps for specific roles such as architects, product owners, or QA engineers. Checklists define what must be verified before a story or architecture is considered complete, but they do not contain executable logic.

Checklists live in .aios-core/product/checklists/ and are read by agents that present items to users and collect evidence or notes.

The Architect checklist demonstrates the structure:

# File: .aios-core/product/checklists/architect-checklist.md

# Architect Solution Validation Checklist

- [ ] Architecture supports all functional requirements in the PRD
- [ ] Technical approaches for all epics and stories are addressed

Execute a checklist through the CLI:

aios execute-checklist architect-checklist

The agent walks through each item, optionally requesting evidence or notes for compliance tracking.

Key Distinctions in AIOS-Core Architecture

Execution vs. Static Data

The fundamental difference lies in execution capability. Tasks contain executable logic—CLI commands, scripts, or LLM-driven steps—that actively performs operations. Templates and checklists are pure data files read by the framework but never executed directly.

According to the SynkraAI/aios-core source code, this separation ensures that document generation and validation remain declarative while task execution remains imperative.

Purpose and Intent

• Tasks perform actions: "Build the documentation" or "Deploy the service"
• Templates define document structure: "A story document contains these sections with these variables"
• Checklists define quality gates: "Before marking complete, verify these criteria"

Directory Structure and Separation of Concerns

The repository enforces clean separation through directory conventions:

• Tasks: /.aios-core/development/tasks/ (development) or /.aios-core/tasks/ (runtime)
• Templates: .aios-core/product/templates/
• Checklists: .aios-core/product/checklists/

This structure mirrors the task-first philosophy: code-centric assets reside in development areas, while PM/PO assets live in the product module.

Practical Examples from the Source Code

Task Implementation

The minimal task definition in tests/unit/squad/fixtures/complete-squad/tasks/valid-task.md demonstrates the required frontmatter structure:

---
task: Test Task
responsavel: @test-agent
responsavel_type: agent
atomic_layer: task
Entrada: |
  - input_param: string (required)
  - optional_param: boolean (default: false)
Saida: |
  - result: Object with { success, data }
Checklist:
  - [ ] Validate input parameters
  - [ ] Execute main logic
  - [ ] Return result
---

Run it with:

aios run-task test-task --input_param "hello"

Template Rendering

The Story template in .aios-core/product/templates/story-tmpl.yaml shows how templates define output generation without containing executable logic:

template:
  id: story-template-v2
  name: Story Document
  version: 2.0
  output:
    format: markdown
    filename: docs/stories/{{epic_num}}.{{story_num}}.{{story_title_short}}.md

Generate the document:

aios create-doc story --title "Login Flow" --epic_num 2 --story_num 3

Checklist Execution

The Architect checklist in .aios-core/product/checklists/architect-checklist.md provides validation criteria:

# Architect Solution Validation Checklist

- [ ] Architecture supports all functional requirements in the PRD
- [ ] Technical approaches for all epics and stories are addressed

Execute it:

aios execute-checklist architect-checklist

Summary

• Tasks are executable workflows stored in /.aios-core/development/tasks/ that perform actions and serve as the primary entry points for agent commands.
• Templates are static document blueprints located in .aios-core/product/templates/ that define document structure and variables for the Template Engine to render.
• Checklists are static validation protocols in .aios-core/product/checklists/ that encode quality gates for specific roles without containing executable logic.
• The fundamental distinction lies in execution capability: tasks run code, while templates and checklists provide declarative data for generation and validation.

Frequently Asked Questions

What is the main difference between a task and a template in AIOS-Core?

A task contains executable logic that performs actions such as running CLI commands or executing scripts, while a template is a static blueprint that only defines document structure and placeholders. Tasks live in /.aios-core/development/tasks/ and are invoked with aios run-task, whereas templates reside in .aios-core/product/templates/ and are rendered using aios create-doc.

Can checklists execute code or automate validation steps?

No, checklists in AIOS-Core are static markdown files that do not contain executable logic. They encode validation criteria for specific roles such as architects or QA engineers, but the framework only reads these files to present items to users. Actual execution or evidence collection is handled by the agent or task that invokes the checklist via aios execute-checklist.

Where should I store custom tasks in the AIOS-Core repository?

Custom tasks should be stored in /.aios-core/development/tasks/ during development or /.aios-core/tasks/ for runtime assets. This location distinguishes code-centric executable assets from product management assets like templates and checklists, which live in the .aios-core/product/ directory. The separation enforces the task-first architecture by keeping executable logic distinct from declarative document definitions.

How do templates handle dynamic content generation?

Templates use placeholder variables such as {{epic_num}} or {{story_title_short}} that the Template Engine replaces with actual values provided via CLI arguments or context. For example, the story template in .aios-core/product/templates/story-tmpl.yaml defines an output filename pattern using these variables. When you run aios create-doc story --title "Login Flow" --epic_num 2, the engine renders the final markdown file with all placeholders substituted.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}