# Understanding the Difference Between Tasks, Templates, and Checklists in AIOS-Core > Discover the AIOS-Core difference between tasks executable workflows templates static blueprints and checklists validation protocols Understand their distinct roles in this task-first architecture - Repository: [SynkraAI/aios-core](https://github.com/synkraai/aios-core) - Tags: deep-dive - Published: 2026-02-16 --- **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: ```yaml # 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: ```bash 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: ```yaml # 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: ```bash 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: ```markdown # 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: ```bash 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`](https://github.com/SynkraAI/aios-core/blob/main/tests/unit/squad/fixtures/complete-squad/tasks/valid-task.md) demonstrates the required frontmatter structure: ```yaml --- 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: ```bash aios run-task test-task --input_param "hello" ``` ### Template Rendering The Story template in [`.aios-core/product/templates/story-tmpl.yaml`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/product/templates/story-tmpl.yaml) shows how templates define output generation without containing executable logic: ```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 the document: ```bash 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`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/product/checklists/architect-checklist.md) provides validation criteria: ```markdown # Architect Solution Validation Checklist - [ ] Architecture supports all functional requirements in the PRD - [ ] Technical approaches for all epics and stories are addressed ``` Execute it: ```bash 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`](https://github.com/SynkraAI/aios-core/blob/main/.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.