Problem
Ballast's common/tasks-todo.md and typescript/typescript-tasks-todo.md rules define tasks/TODO.md as a simple markdown checklist:
# TODO
- [ ] Add input validation to the config parser
- [x] Write tests for the new agent content path
The global AGENTS.md / EXECUTION_TEMPLATES.md framework (used across all repos) defines tasks/todo.md as a structured template with full task lifecycle metadata. These two formats are incompatible:
- Different capitalization (
TODO.md vs todo.md)
- Different structure (flat checklist vs structured sections)
- Ballast's version is described as "branch-scoped scratchpad / working memory"; the global version is a planning artifact with scope, constraints, test strategy, and rollback strategy
An agent working in a Ballast-managed repo with the global framework loaded will produce conflicting artifacts depending on which rule it reads first.
Proposed Resolution
The Ballast tasks-todo rule should align with the global EXECUTION_TEMPLATES.md standard. The file should be tasks/todo.md (lowercase) and use the structured template below, which comes from EXECUTION_TEMPLATES.md.
The lightweight "scratchpad" use case can be preserved by noting that simple tasks may omit optional sections — but the format and filename should be canonical.
EXECUTION_TEMPLATES.md Reference
The following is the authoritative tasks/todo.md template from the global execution framework:
# Task: <title>
## Context
- Owner:
- Date:
- Mode: <Autonomous|Approval-Required>
- PRD Section:
- Requirement IDs:
## Scope
- In scope:
- Out of scope:
## Acceptance Criteria
- AC1:
- AC2:
## Constraints
- Constraint 1
## Risks and Tradeoffs
- Risk:
- Tradeoff:
## Execution Checklist
- [ ] Step 1 with observable outcome
- [ ] Step 2 with observable outcome
## Test Strategy
- Unit:
- Integration:
- E2E:
- Failure-path tests:
- Requirement-to-test mapping:
## Rollback Strategy
- Trigger:
- Rollback steps:
- Validation after rollback:
## Outcome
- Result:
- Evidence links/commands:
- PRD updates:
The full EXECUTION_TEMPLATES.md also defines:
Issue output format:
### Issue #N: <Short Description>
**Severity:** <Critical|High|Medium|Low>
**User Impact:** <who is affected and how>
**Likelihood:** <High|Medium|Low>
**Time Sensitivity:** <Immediate|This sprint|Backlog>
**Problem**
Concrete explanation with file/line references and example behavior.
**Option A (Recommended)**
- Effort:
- Risk:
- Code Impact:
- Maintenance:
**Option B**
- Effort:
- Risk:
- Code Impact:
- Maintenance:
**Option C (Optional / Do Nothing)**
- Effort:
- Risk:
- Code Impact:
- Maintenance:
**Recommendation**
Explain why Option A is best based on correctness, risk, testability, and maintenance.
**Decision Request**
Proceed with: A (recommended), B, C, or alternate direction?
tasks/lessons.md template:
# Lessons
## <YYYY-MM-DD> <Short Title>
- Incident/bug:
- Root cause pattern:
- Early signal missed:
- Preventative rule:
- Validation added (test/check/alert):
- Next trigger to detect sooner:
Acceptance Criteria
Problem
Ballast's
common/tasks-todo.mdandtypescript/typescript-tasks-todo.mdrules definetasks/TODO.mdas a simple markdown checklist:The global
AGENTS.md/EXECUTION_TEMPLATES.mdframework (used across all repos) definestasks/todo.mdas a structured template with full task lifecycle metadata. These two formats are incompatible:TODO.mdvstodo.md)An agent working in a Ballast-managed repo with the global framework loaded will produce conflicting artifacts depending on which rule it reads first.
Proposed Resolution
The Ballast tasks-todo rule should align with the global
EXECUTION_TEMPLATES.mdstandard. The file should betasks/todo.md(lowercase) and use the structured template below, which comes fromEXECUTION_TEMPLATES.md.The lightweight "scratchpad" use case can be preserved by noting that simple tasks may omit optional sections — but the format and filename should be canonical.
EXECUTION_TEMPLATES.md Reference
The following is the authoritative
tasks/todo.mdtemplate from the global execution framework:The full
EXECUTION_TEMPLATES.mdalso defines:Issue output format:
tasks/lessons.mdtemplate:Acceptance Criteria
tasks/todo.mdfilename is standardised to lowercase across all Ballast rulestasks-templatesortasks-executionrule (or update to tasks-todo) ships the canonical templates fortasks/todo.md,tasks/lessons.md, and issue output format