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.md
View File

@@ -1,121 +1,60 @@
# AGENTS.md — Old Bear Battles Operational & Architecture Guide
# Repository Guide
Welcome to **Old Bear Battles** (`OldBearBattles`). This document serves as the primary operational orientation, architectural reference, and workflow guide for all AI agents working in this repository.
This is a generic project starter, not an application scaffold. A project can
be a novel, research, an event, software, or anything else.
Read [project-config.json](./project-config.json) for the project name,
description, and any optional commands. Do not assume software, a language,
platform, framework, package manager, architecture, or deployment target.
---
## Structure
## 1. Project Overview & Core Tenets
- [README.md](./README.md): getting started and configuration instructions.
- [project-config.json](./project-config.json): project identity and commands.
- [docs/tasks.md](./docs/tasks.md): canonical task metadata and backlog.
- [scripts/](./scripts/): Python and shell task-management tools.
- [.agents/skills/](./.agents/skills/): shared setup and task workflows.
OldBearBattles is a lightweight, mobile-friendly, zero-install Virtual Tabletop (VTT) and tactical tabletop wargaming platform (`Brawl`).
## Initial Setup
### Core Design Tenets
1. **Local-First & Zero-Mandatory Auth**: All player and scene data (maps, tokens, audio, character sheets) is stored in local browser storage (`IndexedDB` / `localStorage`). Users can join a room by URL without account friction.
2. **Hybrid P2P & Relay Networking**: Fast WebRTC mesh audio and room synchronization over WebSocket signaling, with graceful server relay fallback.
3. **High-Performance 2D Canvas**: Custom 60 FPS HTML5 Canvas engine designed for seamless trackpad gestures (two-finger pan, pinch-to-zoom) and touch usability without heavy external canvas frameworks.
4. **System-Agnostic Entity Architecture**: Attacks, spells, items, and abilities share a unified `EntityAction` and `EntityStatBlock` schema, enabling flexible play across D&D 5e, Pathfinder 2e, and homebrew systems.
5. **Dual Game Modes (`VTT` & `Brawl`)**:
- `vtt`: Traditional TTRPG mode (initiative tracker, D&D/PF2e character sheets, spellbooks, fog of war).
- `brawl`: Tabletop wargaming mode (armies, units, coherency graph halos, chess clocks, round phase stepper, victory point scoreboard).
- Configured via `GAME_MODE` environment variable (`vtt`, `brawl`, or multi-mode `vtt,brawl` with in-app toggle).
Use the `initial-setup` skill when cloning this template or reconfiguring a
project. Ask the user for the project name, description, task prefix, project
categories, and how they want to verify work. Ask about commands only when
relevant; a writing project might use editorial review instead. Preserve existing work.
Keep task prefixes and project categories in task frontmatter, not duplicated
in the JSON configuration.
---
## Working and Validation
## 2. Monorepo Structure
- Verify work using the project's agreed criteria, whether editorial review,
checklists, research validation, or automated tests.
- Run commands only when configured and appropriate. Empty `commands` means
none are configured; do not invent a test, build, or development command.
- Using the bundled CLI tools requires Python 3.9+ and Bash or Zsh. Their tests
use only the Python standard library. A project using this template need
not use those tools or any programming language.
- When changing the bundled tooling, run
`python3 -m unittest discover -s scripts/tests -v`.
- Follow existing patterns and avoid unrelated changes.
- Use relative links in repository documentation.
- Never commit credentials or local environment overrides.
```
OldBearBattles/
├── packages/
│ ├── client/ # React 18 + Vite frontend
│ │ └── src/
│ │ ├── common/ # Shared canvas engine, networking, dice, status, widgets
│ │ ├── vtt/ # TTRPG VTT application (AppVtt, character sheets, tokens)
│ │ └── brawl/ # Tabletop wargaming platform (AppBrawl, armies, coherency)
│ ├── server/ # Node.js + WebSocket signaling & relay server
│ └── shared/ # Shared TypeScript schemas, protocol payloads, entity types
├── docs/ # Specifications, architecture guides, task tracking
├── scripts/ # Python CLI tools for task management (get-tasks, update-task, etc.)
└── .agents/ # Agent skills (execute-tasks, task-management)
```
## Task Workflow
---
Use the `task-management` skill for task queries and edits, and `execute-tasks`
for implementation of specified task IDs.
## 3. Mandatory Development & Testing Commands
Before committing any code or declaring a task ready for testing:
- **Run Client Tests**:
```bash
npm test -w @oldbear/client
```
- **Run Shared Tests**:
```bash
npm test -w @oldbear/shared
```
- **Start Local Dev Server**:
```bash
npm run dev
```
- **Build Production Bundle** (only when validating build cleanliness):
```bash
npm run build
```
---
## 4. Task Management & Execution Workflow
All project tasks are tracked directly in [docs/tasks.md](file:///Users/tom/Projects/OldBearBattles/docs/tasks.md). Always use the `execute-tasks` or `task-management` skills and CLI scripts.
### Task Status Lifecycles
- `triage` / `planning`: Under research or requirements definition.
- `ready`: Ready for implementation.
- `in_progress`: Actively being worked on by an agent or developer.
- `testing`: Feature implementation is complete and currently awaiting human verification.
- `done`: Human tester has verified the feature and committed the completion.
- `blocked` / `cancelled`: Paused or abandoned.
### Rules for Agent Task Execution
1. **Transition to `testing` (Not `done`)**:
When an agent finishes implementing a task and all tests pass:
```bash
./scripts/update-task <ID> --status testing --check-all
```
Do **NOT** transition tasks directly to `done`. The human user verifies the feature and commits the transition to `done`.
2. **Log Verification in [docs/task-verification.md](file:///Users/tom/Projects/OldBearBattles/docs/task-verification.md)**:
Add step-by-step instructions to `docs/task-verification.md` for testing the feature.
3. **Permanent Human Regression Tests in [docs/human-tests.md](file:///Users/tom/Projects/OldBearBattles/docs/human-tests.md)**:
When a feature is verified and moved from `testing` to `done`, its verification steps are migrated from `docs/task-verification.md` to `docs/human-tests.md` as an ongoing regression test suite.
4. **Always Stage `docs/tasks.md` and `docs/task-verification.md`**:
Before committing, always check `git status`. Ensure that any changes to `docs/tasks.md` (including user edits or pre-staged items) and `docs/task-verification.md` are included:
```bash
git add docs/tasks.md docs/task-verification.md <modified-files>
git commit -m "<type>(<project>): <summary> (<ID>)"
```
5. **The 20-Commit Project Description Rule**:
`docs/project-description.md` and `docs/project-description.json` are consumed by external repositories and catalog scanners.
- Count 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 $\ge 20$ commits have elapsed (or if major features/technologies were added), update the `- Last Verified UTC: YYYY-MM-DDTHH:MM:SSZ` timestamp in `docs/project-description.md` and `"lastVerifiedUtc"` in `docs/project-description.json`, stage them, and commit. This resets the 20-commit counter.
---
## 5. Documentation Sitemap & Index
When working in specific functional areas, refer to these authoritative domain documents:
| Topic / Domain | Authoritative Documentation |
| :--- | :--- |
| **All Implemented VTT Features** | [Features.md](file:///Users/tom/Projects/OldBearBattles/Features.md) |
| **Wargaming Platform (Brawl)** | [docs/brawl-project-plan.md](file:///Users/tom/Projects/OldBearBattles/docs/brawl-project-plan.md) |
| **System-Agnostic Entity & Imports** | [docs/system-agnostic-import.md](file:///Users/tom/Projects/OldBearBattles/docs/system-agnostic-import.md) |
| **Active Task Backlog** | [docs/tasks.md](file:///Users/tom/Projects/OldBearBattles/docs/tasks.md) |
| **Features Awaiting Verification** | [docs/task-verification.md](file:///Users/tom/Projects/OldBearBattles/docs/task-verification.md) |
| **Human Regression Testing Suites** | [docs/human-tests.md](file:///Users/tom/Projects/OldBearBattles/docs/human-tests.md) |
| **HelpTip Component & Copy Guide** | [docs/helptip-locations.md](file:///Users/tom/Projects/OldBearBattles/docs/helptip-locations.md) |
| **Codebase Refactoring Plan** | [docs/refactor-1.md](file:///Users/tom/Projects/OldBearBattles/docs/refactor-1.md) |
| **Backlog Research & Architecture** | [docs/backlog-implementation-guide.md](file:///Users/tom/Projects/OldBearBattles/docs/backlog-implementation-guide.md) |
| **Task CLI Tooling Guide** | [scripts/README.md](file:///Users/tom/Projects/OldBearBattles/scripts/README.md) |
| **Historical Vision & Kickstarter Plans** | [docs/archive/idea.md](file:///Users/tom/Projects/OldBearBattles/docs/archive/idea.md), [docs/archive/initial-project-plan.md](file:///Users/tom/Projects/OldBearBattles/docs/archive/initial-project-plan.md) |
- Use the task CLI scripts; do not manually edit generated summary/enum tables.
- Read the configured prefix and statuses from task frontmatter. Numbers alone
can be used when invoking task commands.
- Lifecycle: `planning` / `triage` / `research` -> `ready` -> `in_progress` ->
`testing` -> `done`. Here `testing` means awaiting human verification, not
necessarily software testing. Humans, not working agents, confirm `done`.
- Record human verification steps in `docs/task-verification.md` when a task
moves to `testing`; create that document when first needed.
- When human verification succeeds, migrate those steps to
`docs/human-tests.md`, creating it when needed.
- Commit only when requested. Include relevant task and verification changes,
but do not stage unrelated edits or commit another person's work blindly.
- If the project maintains project-description documents, refresh their
verification timestamps after major changes or 20 commits since their last
update. Do not assume those optional documents already exist.