# 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:

```markdown
# 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):

1. **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.
2. **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).
3. **Pre-Review Summary Gate:** Require worker agents to provide a concise
   verification summary (modified files and test pass evidence) BEFORE
   requesting code review or opening the PR.
4. **DRY Prompting:** Always reference repository guidelines (`AGENTS.md`,
   `tasks/GUIDELINES.md`) instead of copy-pasting operational rules into agent
   prompts.