Task Management Guidelines

This document outlines the standard operating procedure for the repository-based Kanban workflow using Markdown files to safely manage and track technical stories, architectural planning, and audits. All agents and developers must adhere to these guidelines.

A. The Filename Convention

All task files MUST be Markdown (.md). The naming schema is strict and must follow this exact format:

YYYY-MMDD.[sequence].[agent].[type].[scope].[short-description]-[HHMM].md

YYYY-MMDD: The 4-digit year, a single hyphen, and the 4-digit month/day (e.g., 2026-0820).
[sequence]: A 2-digit zero-padded number for the session's file order (e.g., 01, 02).
[agent]: The 3-letter author abbreviation (e.g., jul, gem, tyl).
[type]: The work category, matching conventional commits (e.g., story, audit, fix, feat, sec).
[scope]: The specific architectural boundary or target component (e.g., setup-ts, auth-api).
[short-description]-[HHMM]: A kebab-case title followed by a single hyphen and a 4-digit timestamp (hour and minute, e.g., 1702) to guarantee no filename collisions during simultaneous sessions.

Example: 2026-0820.01.jul.feat.auth-api.add-rate-limiting-1702.md

B. The Task Lifecycle (Kanban)

Task status is determined strictly by the file's directory location, NOT its name.

Files must never be renamed once created to preserve links and history.
Files should only be moved at the absolute end of a work session.

The directories and their purposes are:

tasks/new/: Where new tasks are generated. Work begins while the file remains in this folder.
tasks/wip/: This is strictly a parking lot. A file is only moved here at the end of a session if the task could not be completed.
tasks/complete/: Where the file is moved at the end of a session once the work is successfully finished or the PR is merged.

C. The Required Metadata Header

Every task markdown file must begin with this exact header structure:

# TASK METADATA

- **Target Files:** [List of files involved]
- **Core Objective:** [1-sentence goal]
- **Dependencies:** [List any prerequisites or blockers]
- **Additional Important Notes:** [Any specific constraints, warnings, or
  context]

---

D. Mandatory Task File Structure

Every technical story or feature task file MUST include the following sections in this exact order:

1. TASK METADATA

The YAML/header block containing Target Files, Core Objective, Dependencies, and Additional Notes.

2. Architectural Considerations & Risks

Before detailing any implementation steps, the authoring agent MUST analyze the objective against the existing codebase and document:

Risks: Identify any potential regressions, security vulnerabilities, or architectural anti-patterns this task might introduce.
Alternatives: Explicitly state if a cleaner, more native, or highly modular approach exists compared to the initial request.

3. Proposed Implementation

The structured phases, code extraction points, or execution steps required to complete the task safely.

E. Multi-Agent Orchestration & Dispatching Standards

When dispatching tasks to autonomous external agents (e.g. Jules, CI workers, subagents):

Black-Box Delegation: Treat the worker agent's execution loop as a black box. Specify architectural invariants and domain rules clearly, but never dictate or forbid specific internal tooling, helper scripts, or workflow mechanics.
Positive Final-State Delivery: Never use negative constraints to govern tool use. Instead, formulate unambiguous terminal Acceptance Criteria (clean git tree, passing test suites, formatted code).
DRY Prompting: Always reference repository guidelines (AGENTS.md, tasks/GUIDELINES.md) instead of copy-pasting operational rules into agent prompts.

3.9 KiB Raw Permalink Blame History