103 lines
3.9 KiB
Markdown
103 lines
3.9 KiB
Markdown
# 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. **DRY Prompting:** Always reference repository guidelines (`AGENTS.md`,
|
|
`tasks/GUIDELINES.md`) instead of copy-pasting operational rules into agent
|
|
prompts.
|