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

161
.agents/skills/execute-tasks/SKILL.md
View File

@@ -1,130 +1,55 @@
---
name: execute-tasks
description: >-
Execute and complete a specific list of tasks one by one. Use this skill
whenever the user asks to work on, implement, execute, or do a specific set
or batch of task IDs (e.g. "Do tasks OT-001, OT-002", "Work on these tasks
one at a time"). Validates task statuses, executes implementation
sequentially, updates documentation, transitions tasks to testing, records
follow-up tasks, includes tasks.md changes in git commits, logs verification
instructions in docs/task-verification.md, and checks project-description timestamps.
description: "Execute and complete a specified list of project tasks sequentially. Use when asked to work on, implement, execute, or do a set of task IDs. Supports writing, research, planning, software, and other projects; verifies results, records human review steps, and transitions completed work to testing."
---
# Execute Tasks Workflow Skill
# Execute Tasks
This skill defines the standardized procedure for executing a specific set of tasks sequentially with strict status validation, documentation updates, follow-up tracking, inclusion of `tasks.md` changes, per-task commits, and comprehensive verification instructions.
## Orient
---
1. Read [AGENTS.md](../../../AGENTS.md),
[project-config.json](../../../project-config.json), and
[the task tracker](../../../docs/tasks.md).
2. Load the `task-management` skill and query each requested task with
`./scripts/get-task <ID>`. Do not assume a prefix or software project.
3. Confirm tasks are ready for work. If not, explain the status and ask for
direction; do not silently bypass blocked or unscoped work.
4. Inspect existing materials and changes. Preserve unrelated work.
## 1. Task Status Validation & Confirmation
## Execute Sequentially
Before starting execution on any given task ID, inspect its status using `./scripts/get-task <ID>`:
For each task:
- **Valid Statuses to Work On**:
- `ready` / `pending` (Ready for implementation)
- `in_progress` (Work currently active)
1. Transition it to `in_progress` using `update-task`.
2. Resolve material ambiguities with the user and agree on acceptance criteria.
3. Complete the requested deliverable using the project's established methods.
For a novel this may be manuscript edits; for research it may be source
analysis; for software it may be code. Do not invent a language or platform.
4. Update directly related documentation and verify acceptance criteria.
Use configured commands only when applicable. For non-command workflows,
review deliverables and report what still needs human judgment.
5. When editing the bundled task tooling, run
`python3 -m unittest discover -s scripts/tests -v`.
6. Record step-by-step human verification in `docs/task-verification.md`,
creating it if needed. Include expected results and limitations.
7. Transition successful work to `testing` with `--check-all`, then query
the task again to verify the transition. Never mark your own work `done`.
8. Record newly discovered work with `add-task`; do not expand scope silently.
- **Invalid / Ambiguous Statuses**:
- `planning`: Scoping incomplete; requirements still unknown.
- `triage`: Requirements known, but prioritization or technical approach unconfirmed.
- `research`: Technical investigation required before planning.
- `testing`: Feature is already implemented and currently awaiting human verification.
- `done` / `fixed`: Task is already completed and verified.
- `cancelled`: Task was discarded or rejected.
- `blocked`: Task is waiting on external dependencies or decisions.
Stop and explain blockers when an acceptance criterion cannot be met. Do not
present unverified work as complete.
> [!WARNING]
> **Status Check Rule**: If any requested task is in an invalid status (such as `planning`, `triage`, `research`, `testing`, `done`, `cancelled`, or `blocked`), you **must stop, report the task ID and its current status to the user, explain why it is not ready for implementation, and ask for explicit confirmation** before proceeding with that task.
## Persistence
---
## 2. Step-by-Step Task Execution Loop
Process each validated task **strictly one at a time** in the requested order:
```mermaid
graph TD
A[Inspect & Validate Task Status] --> B[Mark Task In Progress]
B --> C[Implement Code & Fixes]
C --> D[Run Build & Verification Tests]
D --> E[Update Relevant Documentation]
E --> F[Check Off Requirements & Transition to Testing]
F --> G[Add Verification Steps to docs/task-verification.md]
G --> H[Check 20-Commit Rule on docs/project-description.md]
H --> I[Stage tasks.md & Create Git Commit per Task]
I --> J{More Tasks in Batch?}
J -- Yes --> A
J -- No --> K[Output Verification Summary to User]
```
### Step A: Mark In Progress
Transition the task to active work:
```bash
./scripts/update-task <ID> --status in_progress
```
### Step B: Implement Requirements
1. Read the task requirements using `./scripts/get-task <ID>`.
2. Inspect the relevant source files and implement the requested changes adhering to project architecture and best practices.
3. If partial implementation is required or edge cases emerge, record notes directly in the task description.
### Step C: Verify & Test
Run build verification and automated tests to ensure no regressions:
```bash
npm test -w @oldbear/client
npm test -w @oldbear/shared
```
### Step D: Update Documentation
Check if the changes affect:
- [README.md](file:///Users/tom/Projects/OldBearBattles/README.md)
- `docs/` specifications or architecture guides
Update the corresponding documentation files accordingly.
### Step E: Transition Task to Testing (Not Done)
Check off completed checklist items and transition status to `testing`:
```bash
./scripts/update-task <ID> --status testing --check-all
```
If specific items need implementation notes:
```bash
./scripts/update-task <ID> --status testing --append-description "### Implementation Notes:\n- Completed core logic."
```
> [!IMPORTANT]
> **Testing vs Done**: The agent sets the status to `testing`. The user will manually test the feature and create their own commit transitioning the status to `done` once verified.
### Step F: Record Newly Discovered Tasks
If during the work any new bugs, edge cases, refactor opportunities, or follow-ups are discovered, log them immediately in `planning` status:
```bash
./scripts/add-task "Follow-up: <Descriptive Title>" --project=<proj> --type=<type> --status=planning -d "Discovered during work on <ID>:\n- [ ] Detail"
```
### Step G: Update `docs/task-verification.md`
Add clear, step-by-step verification instructions for the completed task into [docs/task-verification.md](file:///Users/tom/Projects/OldBearBattles/docs/task-verification.md) under the appropriate section:
- Include task ID, title, where to find it in the UI, exact steps to execute, and pass/fail criteria.
- *(Note: Once a human tester verifies a feature and marks it `done`, the verification steps are migrated from `docs/task-verification.md` into `docs/human-tests.md` as permanent regression tests).*
### Step H: Check 20-Commit Rule on Project Description
Check the number of commits since `docs/project-description.md` was last modified:
```bash
LAST_COMMIT=$(git log -n 1 --pretty=format:"%H" -- docs/project-description.md)
git rev-list --count ${LAST_COMMIT}..HEAD
```
If the count is $\ge 20$ (or if major features/technologies were added):
1. Update `docs/project-description.md` with current UTC timestamp (`- Last Verified UTC: YYYY-MM-DDTHH:MM:SSZ`) and any major feature changes.
2. Update `docs/project-description.json` with `"lastVerifiedUtc": "YYYY-MM-DDTHH:MM:SSZ"`.
3. Include these files in the commit (resetting the 20-commit counter).
### Step I: Include tasks.md & Create Git Commit
When creating the commit for the task:
1. **Always include `docs/tasks.md` and `docs/task-verification.md`**: Check `git status`. Ensure all changes to `docs/tasks.md` (including user edits or pre-staged edits) and `docs/task-verification.md` are staged:
```bash
git add docs/tasks.md docs/task-verification.md <other-modified-files>
git commit -m "<type>(<project>): <concise summary of task ID>"
```
*(At least one commit must be made per completed task before moving to the next task).*
### Step J: Verification Instructions in Response
Always provide clear verification instructions so the user can easily test the work:
1. **Single Task / Small Batch**: Include clear, actionable step-by-step verification instructions directly in your response to the user.
2. **Batch / Many Tasks**: If executing a batch of multiple tasks, create a dedicated verification report in `docs/` (e.g. `docs/verification-report.md`) detailing the changes, commits, and verification steps for each task, and link to it in your final response.
- Do not commit unless asked. If asked, inspect `git status` and include the
task/verification changes relevant to the deliverable. Do not stage unrelated
edits blindly.
- Use descriptive commit messages including task IDs and the required
co-author trailer where applicable.
- If project-description documents exist, check their last update and refresh
verification timestamps after major changes or 20 commits. Do not require
nonexistent project-specific documents.
- Human reviewers move `testing` to `done` and migrate verification steps to
`docs/human-tests.md`, creating it when first needed.
- If CLI tools cannot run, disclose that and agree on a manual workflow with
the user rather than reporting fabricated checks.

93
.agents/skills/initial-setup/SKILL.md Normal file
View File

@@ -0,0 +1,93 @@
---
name: initial-setup
description: "Set up or customize a freshly cloned generic project template. Use when asked for initial setup, getting started, onboarding, creating project configuration, or replacing sample project values. Interview the user and configure task tracking for any project, including novels, research, events, and software, without assuming a language or platform."
---
# Initial Project Setup
Configure this clone for its actual project, not for the project that originally
supplied the template. This workflow is equally valid for a novel, research,
an event, or software.
## Inspect First
Read [the README](../../../README.md),
[project-config.json](../../../project-config.json),
[AGENTS.md](../../../AGENTS.md), and
[task frontmatter and details](../../../docs/tasks.md). Check Git status.
Preserve existing materials and uncommitted changes.
## Interview
Use the available user-question tool, one question at a time. Reuse answers
already given; do not ask again unnecessarily. Collect:
1. Project name.
2. A short description of its purpose, audience, and intended outcome.
3. Task ID prefix (recommend `EX` for an example; otherwise let the user choose).
Validate `[A-Za-z][A-Za-z0-9_-]*`; display IDs will be uppercase.
4. Whether there is one project category or several. Collect each label,
unique stable key, and repository-relative path (`.` for a single project).
5. How completed work should be verified. Ask about named commands only if
relevant. Do not assume tests, builds, a development server, a programming
language, or a target platform. Editorial review is a valid answer.
6. Whether to keep and adapt the sample task. Preserve real tasks unless the
user explicitly approves replacing them. Collect any desired task-type
changes; generic `task` and `chore` are sufficient for many projects.
Present a concise configuration summary and obtain confirmation before
replacing existing configuration or task content.
## Write the Configuration
Update `project-config.json` as valid JSON:
```json
{
"name": "Example Project",
"description": "Describe the project's purpose and intended outcome.",
"commands": {}
}
```
`name` and `description` must be non-empty strings. `commands` maps arbitrary
non-empty names to non-empty command strings. Leave it empty when no commands
are applicable. Record non-command acceptance/review criteria in AGENTS.md or
the task descriptions. Never store secrets or machine-specific absolute paths.
Commands are prompt guidance, not automatically run by the task-agent helpers.
Update task frontmatter with the agreed prefix and project categories.
Keep YAML in the flat format understood by the task parser: unindented scalar
fields, two-space list items, and four-space item fields. Do not introduce YAML
anchors, nested mappings, or multiline scalar values. Keep the existing
status lifecycle unless the user explicitly requests changes.
If renaming a project key, migrate matching task anchor `data-project`
attributes. Preserve task numbers, descriptions, checklists, epic/subproject
assignments, and existing internal links. Do not duplicate task configuration
in JSON. Update the README's project description and examples to match, keeping
Getting Started at the top. Update AGENTS.md only with confirmed project facts
and verification criteria; never invent an application architecture.
## Synchronize and Verify
If the optional CLI runtime is available:
1. Check whether `TASK_ID_PREFIX` or `TASKS_FILE` overrides the intended
configuration; explain conflicts rather than silently changing the result.
2. Run `./scripts/update-tasks -f docs/tasks.md`. This migrates IDs/internal
links and regenerates tables. Do not manually edit generated tables.
3. Run `./scripts/get-tasks --all -f docs/tasks.md` and query a task by number.
4. Run `python3 -m json.tool project-config.json` and
`python3 -m unittest discover -s scripts/tests -v`.
5. Verify the configured name, description, commands, project labels, and task
prefix persisted. Check for stale template identities and broken links.
6. Summarize changed files, verification results, and any remaining human review.
The tracker synchronizer currently requires at least one detailed task. Do
not remove the last task and claim synchronization succeeded; keep/adapt it or
ask how to handle an explicitly requested empty tracker.
If the runtime is unavailable, disclose that and offer either tool installation
or a manual Markdown workflow. Do not run application commands merely because
setup recorded them. Do not commit unless the user asks.

174
.agents/skills/task-management/SKILL.md
View File

@@ -1,155 +1,67 @@
---
name: task-management
description: >-
Manage, query, create, triage, research, and update project tasks using the
repository's task CLI scripts in scripts/ (get-tasks, get-task, add-task,
update-task, update-tasks, triage, research) and docs/tasks.md. Activate this
skill whenever reading, creating, editing, prioritizing, or updating tasks,
checklists, or project progress.
description: "Manage, query, create, triage, research, and update project tasks using scripts/ and docs/tasks.md. Use when reading, creating, editing, prioritizing, or updating tasks, checklists, or project progress for any kind of project."
---
# Task Management Skill
# Task Management
This skill provides operational guidelines and procedures for managing project tasks using the automation scripts in `scripts/` and the Single Source of Truth (SSOT) document `docs/tasks.md`.
Read [the script guide](../../../scripts/README.md) and
[the tracker](../../../docs/tasks.md). Use its configured prefix, project keys,
statuses, and types, not an assumed project or software stack.
Examples below use task numbers so they work with any prefix.
---
## Environment
## Quick Reference & Environment Setup
To make scripts available on your `PATH` and load shell aliases:
The optional CLI tools require Python 3.9+ and Bash or Zsh:
```bash
source ./scripts/env.sh
```
> **Note**: For local configurations that should not be committed (such as custom environment variables, agent endpoints, or tokens), create a `scripts/env.local.sh` or `.env.local` file. It will be automatically sourced by `env.sh` and is ignored by Git.
Keep local overrides in ignored `scripts/env.sh.local` or `.env`. These are
trusted shell scripts. `TASKS_FILE` chooses the tracker; `TASK_ID_PREFIX`
overrides its prefix. All task commands accept `-f /path/to/tasks.md`.
---
## Core Procedures
### 1. Querying and Inspecting Tasks
- **List active pending tasks**:
```bash
./scripts/get-tasks
```
- **List tasks in Planning and Triage**:
```bash
./scripts/get-tasks --planning
# or alias: get-planning-tasks
```
- **List all tasks**:
```bash
./scripts/get-tasks --all
```
- **Filter tasks**:
```bash
./scripts/get-tasks --accept "Status:In Progress"
./scripts/get-tasks --reject "Project:Android"
./scripts/get-tasks --sort asc
```
- **Inspect a specific task**:
```bash
./scripts/get-task OT-001
# Output as JSON:
./scripts/get-task OT-001 --json
# View description and checklist only:
./scripts/get-task OT-001 --description-only
```
---
### 2. Creating New Tasks
Use `add-task` to add a new entry to `docs/tasks.md`. The script automatically assigns the next monotonic ID and re-synchronizes the summary table:
## Querying
```bash
./scripts/add-task "Task Title" --project=<project-key> --type=<type> --status=<status> -d "Description text"
./scripts/get-tasks
./scripts/get-tasks --all
./scripts/get-tasks --planning
./scripts/get-tasks --accept "Status:Ready"
./scripts/get-task 1
./scripts/get-task 1 --json
./scripts/get-task 1 --description-only
```
**Common Flags**:
- `-p`, `--project`: Project value from frontmatter (e.g., `example-project`, `android`, `ios`, `shared`).
- `-t`, `--type`: Task type (`feature`, `bug`, `chore`, `lint`). Default: `feature`.
- `-s`, `--status`: Initial status (`planning`, `triage`, `pending`, `in_progress`, `done`, `blocked`, `cancelled`, `research`). Default: `triage`.
- `-d`, `--description`: Initial description and markdown checklist items.
- `--subproject`: Subproject name if applicable.
## Creating and Updating
---
### 3. Updating Tasks
Modify task attributes, title, status, and checklist items using `update-task`:
- **Change status**:
```bash
./scripts/update-task OT-001 --status in_progress
./scripts/update-task OT-001 --status done
```
- **Update title or description**:
```bash
./scripts/update-task OT-001 --title "Updated Descriptive Title"
./scripts/update-task OT-001 --description "New full description text"
```
- **Append checklist items or notes**:
```bash
./scripts/update-task OT-001 --append-description "- [ ] New requirement step"
```
- **Check/uncheck checklist items**:
```bash
# Check all items:
./scripts/update-task OT-001 --check-all
# Check specific item by keyword:
./scripts/update-task OT-001 --check-items "Define initial requirements"
# Uncheck all items:
./scripts/update-task OT-001 --uncheck-all
```
---
### 4. Synchronizing the Document
If tasks are modified or if table alignment needs re-calculation, run `update-tasks`:
Read valid project/type/status values from frontmatter before invoking:
```bash
./scripts/update-tasks
./scripts/add-task "Task Title" --project example-project --type task --status triage -d "Description and review criteria"
./scripts/update-task 1 --status in_progress
./scripts/update-task 1 --title "Updated Title"
./scripts/update-task 1 --append-description "- [ ] Additional criterion"
./scripts/update-task 1 --check-all
./scripts/update-task 1 --status testing
```
This script:
1. Re-indexes and sorts all detailed task chunks strictly by numeric ID.
2. Re-renders the **Overall Progress Table** (`#tasks-list`).
3. Re-renders the metadata enum tables (**Projects**, **Task Statuses**, **Task Types**) based on frontmatter.
Use `--epic` or `--subproject` only with values defined in frontmatter.
Numbers and configured prefixed IDs are accepted.
---
## Synchronization and Review
### 5. Running Triage & Research Workflows
- **Triage a task**:
```bash
./scripts/triage OT-001
./scripts/triage OT-001 --agy
```
- **Research a task**:
```bash
./scripts/research OT-001
./scripts/research OT-001 --agy
```
---
## Operational Rules & Best Practices
1. **Single Source of Truth (SSOT)**:
- The `<a id="ot-XXX" class="task" data-project="..." data-status="..." data-task-type="..."></a>` anchor tag in `## Detailed Tasks` is the canonical record.
- **Never manually edit the summary table** in `docs/tasks.md`. Always modify task entries using `update-task` or run `update-tasks` after editing details.
2. **Lifecycle Discipline**:
- `planning`: Scoping and defining requirements.
- `triage`: Prioritizing and deciding architecture.
- `pending`: Clear scope, ready for execution.
- `in_progress`: Work actively being executed.
- `done`: All requirements verified and complete.
- `blocked`: Waiting on an unresolved external dependency.
- `cancelled`: No longer applicable.
- `research`: Technical investigation needed before planning.
3. **Verification**:
- Always run `./scripts/get-tasks` or `./scripts/get-task <ID>` after updating to verify that status transitions and checklist updates have persisted accurately.
- Anchor attributes in Detailed Tasks are the canonical task metadata.
- Do not manually edit generated summary/enum tables. Run
`./scripts/update-tasks` to regenerate them.
- Run `./scripts/get-task <number>` after edits to verify persisted values.
- `planning` / `triage` / `research` scope work; `ready` permits execution;
`in_progress` tracks active work; `testing` awaits human verification.
- `testing` applies to any project, including writing and research. It need
not involve automated tests. Humans confirm `done`.
- Optional `triage` / `research` helpers require a supported external agent CLI;
normal task management does not.
- If the CLI runtime is unavailable, explain that limitation. With user
agreement, maintain canonical task details in Markdown and ensure tables
remain consistent; do not silently claim script verification succeeded.