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

temp

Browse Source
This commit is contained in:
Tom Hicks
2026-10-08 18:29:45 -07:00
parent 8eedf03486
commit 5725de2dac
35 changed files with 3360 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

130
.agents/skills/execute-tasks/SKILL.md Normal file
View File

@@ -0,0 +1,130 @@
---
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.
---
# Execute Tasks Workflow Skill
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.
---
## 1. Task Status Validation & Confirmation
Before starting execution on any given task ID, inspect its status using `./scripts/get-task <ID>`:
- **Valid Statuses to Work On**:
- `ready` / `pending` (Ready for implementation)
- `in_progress` (Work currently active)
- **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.
> [!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.
---
## 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.

155
.agents/skills/task-management/SKILL.md Normal file
View File

@@ -0,0 +1,155 @@
---
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.
---
# Task Management Skill
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`.
---
## Quick Reference & Environment Setup
To make scripts available on your `PATH` and load shell aliases:
```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.
---
## 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:
```bash
./scripts/add-task "Task Title" --project=<project-key> --type=<type> --status=<status> -d "Description text"
```
**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.
---
### 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`:
```bash
./scripts/update-tasks
```
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.
---
### 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.