diff --git a/.changeset/common-schools-cry.md b/.changeset/common-schools-cry.md new file mode 100644 index 0000000..4f4a9d8 --- /dev/null +++ b/.changeset/common-schools-cry.md @@ -0,0 +1,5 @@ +--- +"@cephalization/math": patch +--- + +documentation diff --git a/.math/todo/LEARNINGS.md b/.math/todo/LEARNINGS.md new file mode 100644 index 0000000..18b96c8 --- /dev/null +++ b/.math/todo/LEARNINGS.md @@ -0,0 +1,63 @@ +# Project Learnings Log + +This file is appended by each agent after completing a task. +Key insights, gotchas, and patterns discovered during implementation. + +Use this knowledge to avoid repeating mistakes and build on what works. + +--- + + + + +## update-readme-paths + +- README.md had exactly 2 locations with `todo/` references that needed updating: the `math init` section (line 73) and the `math iterate` section (line 133) +- The old date-based format `todo-{M}-{D}-{Y}/` has been replaced with AI-generated summary names in `.math/backups//` +- Added a brief explanation of what `` means (AI-generated short description) with examples like `add-user-auth`, `fix-api-bugs` +- Use `grep` to verify all path references are updated after making changes + +## add-directory-structure-table + +- Placed the directory structure table under Core Concept section as a "### Directory Structure" subsection since that's where document organization is already discussed +- Kept to exactly 2 rows as specified: `.math/todo/` and `.math/backups//` +- Mentioned AI-generated descriptions in the backups row to connect with the earlier `math iterate` explanation +- No tests needed for documentation-only changes, but ran `bun test` anyway to ensure nothing was accidentally broken + +## update-loop-diagram + +- The ASCII loop diagram (lines 166-178 in README.md) does NOT reference any file paths, only file names like `TASKS.md` and `PROMPT.md` +- The diagram accurately reflects the current flow: check tasks → exit if complete → invoke agent → agent works → loop back +- No changes were needed - the diagram was already correct +- Verification-only tasks are valid - not all tasks require code changes + +## verify-cli-help + +- All help text in index.ts already uses the correct `.math/todo/` and `.math/backups/` paths +- Found 3 `todo/` references at lines 34, 38, and 58 - all correctly prefixed with `.math/` +- No standalone `todo/` references exist that need updating +- The help output correctly describes: `init` creates `.math/todo/`, `iterate` backs up to `.math/backups/`, and `prune` deletes from `.math/backups/` +- Verification-only tasks with no required changes are valid - document findings even when everything is already correct + +## verify-subcommand-help + +- Reviewed all 6 subcommand files in `src/commands/`: init.ts, run.ts, status.ts, iterate.ts, plan.ts, prune.ts +- Used `grep "todo/"` to find 30 matches across all .ts files - all are correctly using `.math/todo/` or are intentionally referencing legacy `todo/` in migration code +- Legacy `todo/` references in src/migration.ts and src/migration.test.ts are intentional - they handle migrating from old paths +- No changes needed - all subcommand help text and descriptions already use correct `.math/` paths +- Pattern: when verifying path references, grep for the short form (`todo/`) rather than full form (`.math/todo/`) to catch any missed updates + +## final-documentation-review + +- All `todo/` references in README.md (3 matches) and index.ts (3 matches) are correctly prefixed with `.math/` +- Verified no bare `todo/` references exist that should have `.math/` prefix +- "Todo" references in product name "Multi-Agent Todo Harness" and "TODO list" descriptions are correct usage (referring to concept, not directory) +- Checked for old `todo-{date}` pattern - none found, confirming full migration to `.math/backups//` format +- Phase 3 final review confirmed all previous tasks were completed correctly - documentation is now fully consistent diff --git a/.math/todo/PROMPT.md b/.math/todo/PROMPT.md new file mode 100644 index 0000000..6e6abe6 --- /dev/null +++ b/.math/todo/PROMPT.md @@ -0,0 +1,113 @@ +# Agent Task Prompt + +You are a coding agent implementing tasks one at a time. + +## Your Mission + +Implement ONE task from TASKS.md, test it, commit it, log your learnings, then EXIT. + +## The Loop + +1. **Read TASKS.md** - Find the first task with `status: pending` where ALL dependencies have `status: complete` +2. **Mark in_progress** - Update the task's status to `in_progress` in TASKS.md +3. **Implement** - Write the code following the project's patterns. Use prior learnings to your advantage. +4. **Write tests** - For behavioral code changes, create unit tests in the appropriate directory. Skip for documentation-only tasks. +5. **Run tests** - Execute tests from the package directory (ensures existing tests still pass) +6. **Fix failures** - If tests fail, debug and fix. DO NOT PROCEED WITH FAILING TESTS. +7. **Mark complete** - Update the task's status to `complete` in TASKS.md +8. **Log learnings** - Append insights to LEARNINGS.md +9. **Commit** - Stage and commit: `git add -A && git commit -m "feat: - "` +10. **EXIT** - Stop. The loop will reinvoke you for the next task. + +--- + +## Signs + +READ THESE CAREFULLY. They are guardrails that prevent common mistakes. + +--- + +### SIGN: One Task Only + +- You implement **EXACTLY ONE** task per invocation +- After your commit, you **STOP** +- Do NOT continue to the next task +- Do NOT "while you're here" other improvements +- The loop will reinvoke you for the next task + +--- + +### SIGN: Dependencies Matter + +Before starting a task, verify ALL its dependencies have `status: complete`. + +``` +❌ WRONG: Start task with pending dependencies +✅ RIGHT: Check deps, proceed only if all complete +✅ RIGHT: If deps not complete, EXIT with clear error message +``` + +Do NOT skip ahead. Do NOT work on tasks out of order. + +--- + +### SIGN: Learnings are Required + +Before exiting, append to `LEARNINGS.md`: + +```markdown +## + +- Key insight or decision made +- Gotcha or pitfall discovered +- Pattern that worked well +- Anything the next agent should know +``` + +Be specific. Be helpful. Future agents will thank you. + +--- + +### SIGN: Commit Format + +One commit per task. Format: + +``` +feat: - +``` + +Only commit AFTER tests pass. + +--- + +### SIGN: Don't Over-Engineer + +- Implement what the task specifies, nothing more +- Don't add features "while you're here" +- Don't refactor unrelated code +- Don't add abstractions for "future flexibility" +- Don't make perfect mocks in tests - use simple stubs instead +- Don't use complex test setups - keep tests simple and focused +- YAGNI: You Ain't Gonna Need It + +--- + +## Quick Reference + +| Action | Command | +|--------|---------| +| Run tests | `bun test` | +| Typecheck | `bun run typecheck` | +| Run CLI | `bun ./index.ts ` | +| Stage all | `git add -A` | +| Commit | `git commit -m "feat: ..."` | + +**Directory Structure:** +- `.math/todo/` - Active sprint files (PROMPT.md, TASKS.md, LEARNINGS.md) +- `.math/backups//` - Archived sprints from `math iterate` + +--- + +## Remember + +You do one thing. You do it well. You learn. You exit. diff --git a/.math/todo/TASKS.md b/.math/todo/TASKS.md new file mode 100644 index 0000000..ea1fe42 --- /dev/null +++ b/.math/todo/TASKS.md @@ -0,0 +1,65 @@ +# Project Tasks + +Task tracker for multi-agent development. +Each agent picks the next pending task, implements it, and marks it complete. + +## How to Use + +1. Find the first task with `status: pending` where ALL dependencies have `status: complete` +2. Change that task's status to `in_progress` +3. Implement the task +4. Write and run tests +5. Change the task's status to `complete` +6. Append learnings to LEARNINGS.md +7. Commit with message: `feat: - ` +8. EXIT + +## Task Statuses + +- `pending` - Not started +- `in_progress` - Currently being worked on +- `complete` - Done and committed + +--- + +## Phase 1: README Updates + +### update-readme-paths + +- content: Update all `todo/` path references in README.md to `.math/todo/`. Update `math init` description to say it creates `.math/todo/` directory. Update the `math iterate` section to mention `.math/backups//` instead of `todo-{M}-{D}-{Y}/`. Add brief explanation that summaries are AI-generated short descriptions of the sprint. +- status: complete +- dependencies: none + +### add-directory-structure-table + +- content: Add a brief table to README.md documenting the `.math/` directory structure. Include `.math/todo/` (active sprint files) and `.math/backups/` (archived sprints). Keep it to 2-3 rows with one-sentence descriptions each. +- status: complete +- dependencies: update-readme-paths + +### update-loop-diagram + +- content: Update the ASCII loop diagram in README.md if it references any old paths. Verify the diagram accurately reflects the current flow. +- status: complete +- dependencies: update-readme-paths + +## Phase 2: Help Output Verification + +### verify-cli-help + +- content: Run `bun ./index.ts --help` and verify all command descriptions reference `.math/` paths correctly. The help output should already be updated based on recent commits, but verify and fix any remaining `todo/` references in help strings in index.ts. +- status: complete +- dependencies: none + +### verify-subcommand-help + +- content: Check each subcommand for help text or descriptions that may reference old paths. Review index.ts for any command descriptions that need updating. +- status: complete +- dependencies: verify-cli-help + +## Phase 3: Final Review + +### final-documentation-review + +- content: Do a final grep for any remaining `todo/` references in README.md and index.ts that should be `.math/todo/`. Ensure consistency across all documentation. Skip code files - only documentation and help text. +- status: complete +- dependencies: add-directory-structure-table, update-loop-diagram, verify-subcommand-help diff --git a/README.md b/README.md index 816cd97..6e30ad5 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,13 @@ The primary responsibility of this harness is to **reduce context bloat** by dig The harness consists of a simple for-loop, executing a new coding agent with a mandate from `PROMPT.md` to complete a *single* task from `TASKS.md`, while reading and recording any insight gained during the work into `LEARNINGS.md`. +### Directory Structure + +| Path | Description | +| ---- | ----------- | +| `.math/todo/` | Active sprint files (PROMPT.md, TASKS.md, LEARNINGS.md) | +| `.math/backups//` | Archived sprints from `math iterate`, named with AI-generated descriptions | + ## Requirements **[Bun](https://bun.sh) is required** to run this tool. Node.js is not supported. @@ -70,7 +77,7 @@ bun link math init ``` -Creates a `todo/` directory with template files and offers to run **planning mode** to help you break down your goal into tasks. +Creates a `.math/todo/` directory with template files and offers to run **planning mode** to help you break down your goal into tasks. Options: @@ -130,12 +137,14 @@ Shows task progress with a visual progress bar and next task info. math iterate ``` -Backs up `todo/` to `todo-{M}-{D}-{Y}/` and resets for a new goal: +Backs up `.math/todo/` to `.math/backups//` and resets for a new goal: - TASKS.md and LEARNINGS.md are reset to templates - PROMPT.md is preserved (keeping your accumulated "signs") - Offers to run planning mode for your new goal +The `` is a short description of the completed sprint (e.g., `add-user-auth`, `fix-api-bugs`). + Options: - `--no-plan` - Skip the planning prompt