Kiluth Tasks Usage

Department

Technology

Summary

How Kiluth Tasks is built and how it checks itself. Tasks are Markdown files in a Git repository, written through Claude Code and read through a web view. Each task carries its department, assignee, project and dependency chain. An automatic checker tests every change against the Task Usage Guideline and records the verdict on the task. This document is for operators and agents; the rules themselves live in the HR guideline.

Table of Contents

Purpose

Kiluth Tasks replaces the previous task tool. The change is not only where tasks are stored. The previous tool was adopted before Kiluth had written rules, so every department used it differently and the result drifted for a year.

Kiluth Tasks starts from the rules instead. The structure is defined first, the checker enforces it on every change, and there is a single way to write a task.

Prerequisites

How It Is Built

Everyone works on the main branch, pulls before starting, and resolves any conflict locally before pushing. Because one task is one file, two people working on different tasks never touch the same file.

Infrastructure details — where the site is hosted, how access control is configured — are deliberately not in this document. They live in the kiluth-infra runbooks.

The Task File

A task is a Markdown file with a header block and a body.

---
title: Break down hours per feature from the Bonsoir proposal
dept: technology
section: In Progress
assignee: poom.pengcharoen@kiluth.com
requester: phuttipan.samranruen@kiluth.com
project: PROJ-0031
priority: high
created: 2026-09-23
due:
hygiene:
---
 
Description. Context, links, definition of done.
 
## Chain
 
Blocks: [[PROJ-0031]]
Blocked by: [[2026-09-23T14-30-creative-bonsoir-uxui-hour-breakdown]]

The file name is the identifier

YYYY-MM-DDTHH-MM-<dept>-<slug>.md

There is no ID field and no counter. The creator’s clock supplies a unique name, alphabetical order matches chronological order, and two people creating tasks at the same time on different machines cannot collide. If two are created in the same minute, add seconds.

Open and done

An open task sits in tasks/open/. Finishing it moves the file to tasks/done/. There is no Completed section, because the folder already says it. Two places recording the same fact will eventually disagree.

The chain must be links in the body

The dependency chain is written under ## Chain as links, not as header fields.

This is not a style preference. The web view builds its dependency graph from links it finds in the text of a document. A chain recorded only in the header would be correct data and still be invisible on the graph, which is the main reason the graph exists.

The Project Node

Each project has a small file whose only jobs are to terminate the chain and to appear on the graph.

---
id: PROJ-0031
portal: https://portal.kiluth.com/app/project/PROJ-0031
---
 
# PROJ-0031
 
Umbrella node. Live project data is in the Kiluth Portal, not here.

It holds nothing the Portal already owns. No customer, no dates, no billing, no status. Copying those here would create a second version that drifts from the real one. Anything you need about the project is read live from the Portal.

The Checker

Every change runs a checker against the Task Usage Guideline. It applies the guideline; it does not define it. When the guideline changes, the checker follows.

The result

The checker writes hygiene: pass or hygiene: fail into the task. On a failure it appends the reason to the task under a ## Log heading, so the person fixing it can see what was wrong without hunting.

hygiene: pass means the task is written correctly. It does not mean the work is done. Completion is moving the file to tasks/done/.

Changed from the previous tool. Status used to be prefixed to the title as [✅] or [❌]. That mixed a quality verdict into the task’s name and made lists harder to read. Status markers no longer belong in titles.

What runs where

Checks 1 and 2 read only the repository, so they work offline. Check 3 needs to reach the Kiluth Portal, so a fully offline check cannot confirm the project exists.

The Web View

Tasks are readable on the web, signed in with a Kiluth account. It is built from the same repository, so it always shows what is committed.

Writing a Task Properly

When someone asks for a task to be created or assigned, writing down what was said is not enough. Establish the context first:

Ask when it cannot be determined. A task registered without its chain is exactly the failure that made the previous tool unusable, repeated one task at a time.

Related