From 9df845f872cae3866cb52094ff8b5c4dca2480bc Mon Sep 17 00:00:00 2001 From: Tony Powell Date: Fri, 16 Jan 2026 10:58:06 -0500 Subject: [PATCH 1/8] feat: update-readme-paths - Update path references to .math/todo/ and .math/backups// --- .math/todo/LEARNINGS.md | 25 +++++++++ .math/todo/PROMPT.md | 113 ++++++++++++++++++++++++++++++++++++++++ .math/todo/TASKS.md | 65 +++++++++++++++++++++++ README.md | 6 ++- 4 files changed, 207 insertions(+), 2 deletions(-) create mode 100644 .math/todo/LEARNINGS.md create mode 100644 .math/todo/PROMPT.md create mode 100644 .math/todo/TASKS.md diff --git a/.math/todo/LEARNINGS.md b/.math/todo/LEARNINGS.md new file mode 100644 index 0000000..4665c5e --- /dev/null +++ b/.math/todo/LEARNINGS.md @@ -0,0 +1,25 @@ +# 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 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..3449c69 --- /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: pending +- 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: pending +- 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: pending +- 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: pending +- 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: pending +- dependencies: add-directory-structure-table, update-loop-diagram, verify-subcommand-help diff --git a/README.md b/README.md index 816cd97..0111c09 100644 --- a/README.md +++ b/README.md @@ -70,7 +70,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 +130,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 an AI-generated short description of the completed sprint (e.g., `add-user-auth`, `fix-api-bugs`). + Options: - `--no-plan` - Skip the planning prompt From 6c5505c9f5f1f9cfa96827793880c01bb313e74d Mon Sep 17 00:00:00 2001 From: Tony Powell Date: Fri, 16 Jan 2026 10:59:18 -0500 Subject: [PATCH 2/8] feat: add-directory-structure-table - Add .math/ directory structure table to README --- .math/todo/LEARNINGS.md | 7 +++++++ .math/todo/TASKS.md | 2 +- README.md | 7 +++++++ 3 files changed, 15 insertions(+), 1 deletion(-) diff --git a/.math/todo/LEARNINGS.md b/.math/todo/LEARNINGS.md index 4665c5e..fe2104e 100644 --- a/.math/todo/LEARNINGS.md +++ b/.math/todo/LEARNINGS.md @@ -23,3 +23,10 @@ Use this knowledge to avoid repeating mistakes and build on what works. - 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 diff --git a/.math/todo/TASKS.md b/.math/todo/TASKS.md index 3449c69..1019131 100644 --- a/.math/todo/TASKS.md +++ b/.math/todo/TASKS.md @@ -33,7 +33,7 @@ Each agent picks the next pending task, implements it, and marks it complete. ### 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: pending +- status: complete - dependencies: update-readme-paths ### update-loop-diagram diff --git a/README.md b/README.md index 0111c09..1891fe6 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. From 24f8055383a68c6f905a9bd799888c3fdc4b7214 Mon Sep 17 00:00:00 2001 From: Tony Powell Date: Fri, 16 Jan 2026 11:00:36 -0500 Subject: [PATCH 3/8] feat: update-loop-diagram - verify ASCII diagram is correct --- .math/todo/LEARNINGS.md | 7 +++++++ .math/todo/TASKS.md | 2 +- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/.math/todo/LEARNINGS.md b/.math/todo/LEARNINGS.md index fe2104e..e81113b 100644 --- a/.math/todo/LEARNINGS.md +++ b/.math/todo/LEARNINGS.md @@ -30,3 +30,10 @@ Use this knowledge to avoid repeating mistakes and build on what works. - 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 diff --git a/.math/todo/TASKS.md b/.math/todo/TASKS.md index 1019131..ba4afee 100644 --- a/.math/todo/TASKS.md +++ b/.math/todo/TASKS.md @@ -39,7 +39,7 @@ Each agent picks the next pending task, implements it, and marks it complete. ### 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: pending +- status: complete - dependencies: update-readme-paths ## Phase 2: Help Output Verification From 16d3dbf85873e4bb48026ecf436b1c8bbc1f7f11 Mon Sep 17 00:00:00 2001 From: Tony Powell Date: Fri, 16 Jan 2026 11:02:12 -0500 Subject: [PATCH 4/8] feat: verify-cli-help - verify all CLI help text uses .math/ paths --- .math/todo/LEARNINGS.md | 8 ++++++++ .math/todo/TASKS.md | 2 +- 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/.math/todo/LEARNINGS.md b/.math/todo/LEARNINGS.md index e81113b..175d5de 100644 --- a/.math/todo/LEARNINGS.md +++ b/.math/todo/LEARNINGS.md @@ -37,3 +37,11 @@ Use this knowledge to avoid repeating mistakes and build on what works. - 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 diff --git a/.math/todo/TASKS.md b/.math/todo/TASKS.md index ba4afee..0ff92a5 100644 --- a/.math/todo/TASKS.md +++ b/.math/todo/TASKS.md @@ -47,7 +47,7 @@ Each agent picks the next pending task, implements it, and marks it complete. ### 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: pending +- status: complete - dependencies: none ### verify-subcommand-help From 0906e8dd759f356d84d3ba56cfe752173ffc4012 Mon Sep 17 00:00:00 2001 From: Tony Powell Date: Fri, 16 Jan 2026 11:03:31 -0500 Subject: [PATCH 5/8] feat: verify-subcommand-help - Verify all subcommand help text uses .math/ paths --- .math/todo/LEARNINGS.md | 8 ++++++++ .math/todo/TASKS.md | 2 +- 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/.math/todo/LEARNINGS.md b/.math/todo/LEARNINGS.md index 175d5de..074fb4a 100644 --- a/.math/todo/LEARNINGS.md +++ b/.math/todo/LEARNINGS.md @@ -45,3 +45,11 @@ Use this knowledge to avoid repeating mistakes and build on what works. - 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 diff --git a/.math/todo/TASKS.md b/.math/todo/TASKS.md index 0ff92a5..837dd13 100644 --- a/.math/todo/TASKS.md +++ b/.math/todo/TASKS.md @@ -53,7 +53,7 @@ Each agent picks the next pending task, implements it, and marks it complete. ### 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: pending +- status: complete - dependencies: verify-cli-help ## Phase 3: Final Review From 9d10eb5b7bd93253dcc04226cce08d3eb18ccffb Mon Sep 17 00:00:00 2001 From: Tony Powell Date: Fri, 16 Jan 2026 11:04:48 -0500 Subject: [PATCH 6/8] feat: final-documentation-review - Verify all todo/ references use .math/ prefix --- .math/todo/LEARNINGS.md | 8 ++++++++ .math/todo/TASKS.md | 2 +- 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/.math/todo/LEARNINGS.md b/.math/todo/LEARNINGS.md index 074fb4a..18b96c8 100644 --- a/.math/todo/LEARNINGS.md +++ b/.math/todo/LEARNINGS.md @@ -53,3 +53,11 @@ Use this knowledge to avoid repeating mistakes and build on what works. - 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/TASKS.md b/.math/todo/TASKS.md index 837dd13..ea1fe42 100644 --- a/.math/todo/TASKS.md +++ b/.math/todo/TASKS.md @@ -61,5 +61,5 @@ Each agent picks the next pending task, implements it, and marks it complete. ### 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: pending +- status: complete - dependencies: add-directory-structure-table, update-loop-diagram, verify-subcommand-help From 1e786732bdc5de7fbf0420c3137e2eb16ee727d7 Mon Sep 17 00:00:00 2001 From: Tony Powell Date: Fri, 16 Jan 2026 11:09:59 -0500 Subject: [PATCH 7/8] changeset --- .changeset/common-schools-cry.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/common-schools-cry.md 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 From 018474182addf56102d16492ff265b29c8ba91c8 Mon Sep 17 00:00:00 2001 From: Tony Powell Date: Fri, 16 Jan 2026 11:11:35 -0500 Subject: [PATCH 8/8] chore: Tweak readme --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 1891fe6..6e30ad5 100644 --- a/README.md +++ b/README.md @@ -143,7 +143,7 @@ Backs up `.math/todo/` to `.math/backups//` and resets for a new goal: - PROMPT.md is preserved (keeping your accumulated "signs") - Offers to run planning mode for your new goal -The `` is an AI-generated short description of the completed sprint (e.g., `add-user-auth`, `fix-api-bugs`). +The `` is a short description of the completed sprint (e.g., `add-user-auth`, `fix-api-bugs`). Options: