maj/base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Adds basic task management tools.

Browse Source
This commit is contained in:
Tom Hicks
2026-10-08 19:15:08 -07:00
parent 5725de2dac
commit 0c7c20b6e6
34 changed files with 676 additions and 868 deletions
Download Patch File Download Diff File Expand all files Collapse all files

224
docs/tasks.md
View File

@@ -1,120 +1,101 @@
---
# Most projects only have one or two projects. label is used in prose and value is used as an index. Setup those task-id-prefix and projects values.
task-id-prefix: 'OB'
task-id-prefix: 'EX'
projects:
- label: 'Old Bear VTT'
- label: 'Example Project'
path: '.'
prefix: 'OBV'
value: 'old-bear-vtt'
- label: 'Old Bear Brawl'
path: '.'
prefix: 'OBB'
value: 'old-bear-brawl'
- label: 'Common'
path: '.'
prefix: 'CMN'
value: 'cmn'
value: 'example-project'
task-statuses:
- label: 'Planning'
value: 'planning'
description: 'We do not yet know what it should do.'
description: 'Define the goals and scope.'
- label: 'Triage'
value: 'triage'
description: 'We do not yet know how to do it.'
description: 'Decide how to approach the work.'
- label: 'Research'
value: 'research'
description: 'Investigate before planning or execution.'
- label: 'Ready'
value: 'ready'
description: 'Task is ready to be worked on.'
description: 'Ready to be worked on.'
- label: 'In Progress'
value: 'in-progress'
description: 'Task is currently being worked on.'
value: 'in_progress'
description: 'Work is underway.'
- label: 'Testing'
value: 'testing'
description: 'Task is currently being tested.'
description: 'Awaiting human review or verification.'
- label: 'Blocked'
value: 'blocked'
description: 'Task is waiting on external dependencies.'
description: 'Waiting on a dependency or decision.'
- label: 'Done'
value: 'done'
description: 'Task is completed and verified.'
description: 'Completed and verified by a human.'
- label: 'Cancelled'
value: 'cancelled'
description: 'No longer applicable.'
task-types:
- value: 'bug'
prefix: 'BUG'
label: 'Bug'
description: 'The task is a bug to fix.'
- value: 'feature'
prefix: 'ENH'
label: 'Feature'
description: 'The task is a new feature to implement.'
- value: 'task'
label: 'Task'
description: 'A project deliverable or activity.'
- value: 'chore'
prefix: 'CHR'
label: 'Chore'
description: 'The task is a routine maintenance or administrative task.'
description: 'Routine maintenance or administrative work.'
- value: 'feature'
label: 'Feature'
description: 'A new capability, when relevant to the project.'
- value: 'bug'
label: 'Bug'
description: 'A defect to fix, when relevant to the project.'
---
# Project Task Tracker
## Instructions for Working with Tasks
## Working with Tasks
### Quick Start (Environment Setup)
This tracker works for any project, including writing, research, and software.
`testing` means awaiting review or verification; it does not require automated
tests. This is a sample backlog. Customize the sample task for your project.
Before running task commands, source the helper environment script in your shell to load convenient aliases and paths:
### Configuration
- `task-id-prefix` controls display IDs and anchors. This example uses `EX`.
- `TASK_ID_PREFIX` overrides frontmatter; the script default is `EX`.
- Prefixes start with a letter and contain letters, digits, underscores, or
hyphens. Display IDs are uppercase; anchors are lowercase.
- Numbers are globally monotonic with at least three digits. Use a number alone
with task commands to avoid dependence on the configured prefix.
- After changing the prefix, run `./scripts/update-tasks` to migrate IDs and
internal links without changing task numbers.
- `projects` defines labels, keys, and repository-relative paths. If renaming
a project key, update corresponding task anchor `data-project` attributes.
- All task commands accept `-f /path/to/tasks.md`; exported `TASKS_FILE` sets
the default tracker.
- Optional `epics` and `subprojects` can group work. Define their values and
labels in frontmatter before assigning them.
### Commands
The CLI tools require Python 3.9+ and Bash or Zsh. They are optional; you can
also maintain this Markdown tracker with your assistant.
```bash
source ./scripts/env.sh
./scripts/get-tasks --all
./scripts/get-tasks --accept "Status:Ready"
./scripts/get-task 1 --json
./scripts/add-task "Outline the next deliverable" --project example-project --type task --status triage
./scripts/update-task 1 --status in_progress
./scripts/update-task 1 --append-description "- [ ] Additional review criterion"
./scripts/update-task 1 --status testing --check-all
./scripts/update-tasks
```
### Task ID Configuration
Task anchor attributes in **Detailed Tasks** are the canonical metadata.
Do not manually edit generated summary or enum tables; regenerate them with
`update-tasks`. Working agents transition completed work to `testing`, not
`done`. A human confirms completion.
- Set the document-wide `task-id-prefix` in YAML frontmatter (this tracker uses `OB`).
- Optionally export `TASK_ID_PREFIX` in your shell or in the local settings sourced by `scripts/env.sh` (`scripts/env.sh.local` or `.env`). It overrides frontmatter; when neither is set, the default is `OT`.
- Prefixes must start with a letter and contain only letters, digits, underscores, or hyphens. Display IDs are uppercase and anchors are lowercase.
- Numbers remain globally monotonic across the document, with at least three digits. Project and task-type `prefix` fields do not control these IDs.
- After changing the prefix, run `update-tasks` to normalize existing IDs and internal anchor links. Numeric IDs can still be used with task commands.
- All task commands accept `-f /path/to/tasks.md`; `TASKS_FILE` supplies the default path when exported.
### Command Reference
You can manage tasks using the provided automation scripts in `./scripts/` (or via their aliases):
- **List tasks**:
- `get-tasks` (or `./scripts/get-tasks`): Show active pending tasks.
- `get-planning-tasks` (or `get-tasks --planning`): Show tasks in _Planning_ or _Triage_ status.
- `get-tasks --all`: List all tasks regardless of status.
- `get-tasks --accept "Status:In Progress"` / `get-tasks --reject "Project:Example"`: Filter tasks.
- `get-tasks --all --accept "Epic:poc" --select "ID,Title,Epic"`: Filter or select the Epic column. Epic filters accept frontmatter values (`poc`) or labels (`Proof of Concept`), case-insensitively.
- `get-tasks --all --reject "Epic:poc"`: Exclude an Epic by value or label; comma-separated lists such as `Epic:poc,bootstrap` also work.
- **View a specific task**:
- `get-task OT-001` (or `./scripts/get-task 1`): Inspect task details, requirements, and metadata.
- `get-task OT-001 --json`: Output task data in JSON format, including `epic` (value) and `epic_label`.
- `get-task OT-001 --epic`: Output only the canonical Epic value.
- **Add a new task**:
- `add-task "Task Title" --project=example-project --type=feature --status=triage`
- (Optionally supply `-d "Description and checklist"`)
- Add `--epic=poc` (or `--epic="Proof of Concept"`) to assign an Epic defined in frontmatter.
- **Update an existing task**:
- `update-task OT-001 --status in_progress`
- `update-task OT-001 --title "New Title"`
- `update-task OT-001 --status done --check-all`
- `update-task OT-001 --append-description "- [ ] Additional subtask"`
- `update-task OT-001 --epic=poc` / `update-task OT-001 --clear-epic`: Assign or remove an Epic.
- **Synchronize document**:
- `update-tasks` (or `./scripts/update-tasks`): Re-indexes task IDs, re-renders the summary progress table, and regenerates metadata enum tables.
### Workflow Guidelines
1. **Do Not Edit the Summary Table Manually**: The summary table below is automatically regenerated from the detailed task entries. Use `./scripts/add-task` and `./scripts/update-task`, or edit the detailed task blocks directly and run `./scripts/update-tasks`.
2. **Anchor Tags as SSOT**: Each task in `## Detailed Tasks` is defined by an anchor tag:
`<a id="ot-XXX" class="task" data-project="PROJECT" data-epic="EPIC" data-status="STATUS" data-task-type="TYPE"></a>`
The attributes on this anchor tag are the canonical source of truth for the task's state.
`data-epic` is optional; its value comes from frontmatter `epics`. Summary and detail views display the corresponding label.
3. **Task Lifecycle**:
- **Triage**: Conceptualization and scoping phase.
- **Ready**: Ready to be picked up for implementation.
- **In Progress**: Actively being worked on.
- **Testing**: Code complete and ready for verification.
- **Done**: Completed and verified.
- **Blocked**: Waiting on external dependencies.
See the [script guide](../scripts/README.md) and
[getting started guide](../README.md) for details.
<a id="tasks-summary"></a>
@@ -122,53 +103,26 @@ You can manage tasks using the provided automation scripts in `./scripts/` (or v
<a id="tasks-list"></a>
| ID | Title | Project | Status | Type |
|:-----|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------|:-------|:-----------------|
| OB-001 | In voice and audio settings the 4th button for streaming is mostly off screen | Old Bear VTT | Done | [Feature](#ob-001) |
| OB-002 | When adding a new token to the board try to not put it on top of an existing one | Old Bear VTT | Done | [Feature](#ob-002) |
| OB-003 | When uploading files allow selecting multiple files at once | Old Bear VTT | Done | [Feature](#ob-003) | | Common | Ready | [Feature](#ob-211) |
| ID | Title | Project | Status | Type |
|:-----|:-------------------------|:--------------|:-----|:--------------|
| EX-001 | Define the project's goals | Example Project | Ready | [Task](#ex-001) |
---
<a id="task-details"></a>
## Detailed Tasks
<a id="ob-001" class="task" data-project="old-bear-vtt" data-status="done" data-task-type="feature"></a>
### In voice and audio settings the 4th button for streaming is mostly off screen
**ID:** OB-001
**Project:** Old Bear VTT
**Status:** Done
**Type:** Feature
<a id="ex-001" class="task" data-project="example-project" data-status="ready" data-task-type="task"></a>
### Define the project's goals
**ID:** EX-001
**Project:** Example Project
**Status:** Ready
**Type:** Task
**Description:**
In voice and audio settings the 4th button for streaming is mostly off screen
<a id="ob-002" class="task" data-project="old-bear-vtt" data-status="done" data-task-type="feature"></a>
### When adding a new token to the board try to not put it on top of an existing one
**ID:** OB-002
**Project:** Old Bear VTT
**Status:** Done
**Type:** Feature
**Description:**
When adding a new token to the board try to not put it on top of an existing one
<a id="ob-003" class="task" data-project="old-bear-vtt" data-status="done" data-task-type="feature"></a>
### When uploading files allow selecting multiple files at once
**ID:** OB-003
**Project:** Old Bear VTT
**Status:** Done
**Type:** Feature
**Description:**
When uploading files allow selecting multiple files at once
Replace this sample with the first meaningful activity for your project.
- [ ] Describe the intended outcome and audience.
- [ ] Identify the first deliverable.
- [ ] Agree on how the deliverable will be reviewed or verified.
---
@@ -176,26 +130,6 @@ When uploading files allow selecting multiple files at once
#### Projects (Rendered from frontmatter projects)
| Value | Label | Prefix | Path |
| :------------- | :------------- | :----- | :--- |
| old-bear-vtt | Old Bear VTT | OBV | . |
| old-bear-brawl | Old Bear Brawl | OBB | . |
#### Task Statuses (Rendered from frontmatter task-statuses)
| Value | Label | Description |
| :---------- | :---------- | :---------------------------------------- |
| triage | Triage | Task is still being defined. |
| ready | Ready | Task is ready to be worked on. |
| in-progress | In Progress | Task is currently being worked on. |
| testing | Testing | Task is currently being tested. |
| blocked | Blocked | Task is waiting on external dependencies. |
| done | Done | Task is completed and verified. |
#### Task Types (Rendered from frontmatter task-types)
| Value | Label | Prefix | Description |
| :------ | :------ | :----- | :-------------------------------------------------------- |
| bug | Bug | BUG | The task is a bug to fix. |
| feature | Feature | ENH | The task is a new feature to implement. |
| chore | Chore | CHR | The task is a routine maintenance or administrative task. |