Skip to content

feat: v0.1 scaffold with task engine and agent loop#1

Open
mcj-coder wants to merge 44 commits into
mainfrom
feat/v0.1-scaffold
Open

feat: v0.1 scaffold with task engine and agent loop#1
mcj-coder wants to merge 44 commits into
mainfrom
feat/v0.1-scaffold

Conversation

@mcj-coder
Copy link
Copy Markdown
Contributor

@mcj-coder mcj-coder commented Feb 9, 2026

Summary

  • Scaffold project with dev tooling (husky, lint-staged, prettier, shellcheck, shfmt, markdownlint)
  • Task engine (lib/tasks.js): list, filter by capabilities/deps/priority, claim, update status
  • Prompt builder (lib/prompt-builder.js): assemble agent prompts from task JSON + CLAUDE.md
  • Minimal TOML parser (lib/toml.js): parse config files without external deps
  • CLI entrypoint (bin/coordinator.sh): init, start, stop, status subcommands
  • Agent loop (bin/agent-loop.sh): per-agent competing consumer loop
  • Template files for .coordination/ scaffolding (config.toml, claude-md/*.md)

Architecture

  • Bash core + Node.js for task logic — zero production dependencies
  • Git worktrees for agent isolation (one per agent)
  • Coordination branch holds task JSON — never merged to main
  • Competing consumer via git push conflict (first push wins)
  • Dynamic role assignment — agents claim by capability + priority
  • Fresh context per task — one-shot claude -p invocations

Test plan

  • 21 tests passing (node --test) — tasks, prompt-builder, TOML parser
  • shellcheck clean on all bash scripts
  • Pre-commit hooks (lint-staged auto-fix) working
  • Pre-push hooks (full test suite + shellcheck) working
  • Manual test: coordinator init in a test project
  • Manual test: coordinator start with agents.toml configured
  • Manual test: coordinator stop --clean

🤖 Generated with Claude Code

mcj-coder and others added 30 commits February 9, 2026 12:17
@mcj-coder @claude
feat: add listTasks — read task JSON files from directory
6c5b9f9 
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@mcj-coder @claude
feat: add minimal TOML parser for config files
7462c2c 
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@mcj-coder @claude
feat: add prompt-builder — assembles agent prompts from task + CLAUDE.md
c559d7f 
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@mcj-coder @claude
feat: add findClaimable — filter tasks by capabilities, deps, priority
2628153 
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@mcj-coder @claude
feat: add coordinator.sh CLI entrypoint with subcommand dispatch
ef48749 
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@mcj-coder @claude
feat: add claimTask and updateTask — task state mutations
38c15f0 
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@mcj-coder @claude
feat: implement coordinator init — scaffold .coordination/ and orphan…
7e71273 
… branch

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@mcj-coder @claude
feat: add CLI interface to tasks.js for agent-loop.sh
a37454e 
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@mcj-coder @claude
feat: wire TOML config parsing into tasks.js CLI
3f0b52d 
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@mcj-coder @claude
feat: add agent-loop.sh — per-agent competing consumer loop
153c873 
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@mcj-coder @claude
feat: implement coordinator start and stop — worktrees, WT tabs, cleanup
0e9e2d1 
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@mcj-coder @claude
fix: three bugs found during manual testing
12d7346 
- Add .gitkeep to tasks/ on coordination branch (git doesn't track empty dirs)
- Check for TTY before prompting for Spec-Kit install (non-interactive fix)
- Handle missing coordination worktree in status command gracefully

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@mcj-coder @claude
fix: add markdownlint-cli2 config to ignore node_modules
76e8a12 
markdownlint-cli2 uses .markdownlint-cli2.jsonc (not .markdownlintignore)
for file exclusions. Also fixes prettier trailing comma in .markdownlint.jsonc.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@mcj-coder @claude
feat: add npm run check for full repo validation
9c9ba89 
Runs unit tests, shellcheck, prettier, and markdownlint in one command.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@mcj-coder @claude
feat: add E2E and smoke test scripts
c378fa0 
- tests/e2e.sh: 36 automated tests covering init, start, status, stop
  with mocked wt.exe for CI-safe execution
- tests/smoke.sh: interactive test that opens real WT tabs for manual
  verification of agent launch and lifecycle
- npm run test:e2e / test:smoke / check

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@mcj-coder @claude
feat: comprehensive E2E smoke test with mock agents
725fbba 
Replaces basic lifecycle smoke test with full journey demo:
- Sets up bare repo as origin, clone as project
- Initializes coordinator, creates 4 tasks (test → implement → review → fix)
- Starts agents with mock AI script that produces real files
- Polls task progress with live status display
- Verifies hello.js and hello.test.js artifacts
- Demonstrates capability-based + priority-based task claiming
- Clean shutdown with verification

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@mcj-coder @claude
fix: two bugs preventing agents from claiming tasks
342b596 
1. wt.exe launches non-interactive bash — .bashrc not sourced, nvm/node
   unavailable. Fixed by using `bash --login` for agent tabs.
   Added node availability check in agent-loop.sh with clear error.

2. DONE_STATUSES missing 'complete' — agent-loop.sh sets tasks to
   'complete' but isBlocked() only recognized 'done'/'approved',
   so blocked tasks could never unblock. Added 'complete' to the set.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@mcj-coder @claude
fix: source nvm directly in agent-loop.sh for WT tabs
f4b02bf 
bash --login doesn't help because .bashrc exits early for
non-interactive shells. Instead, agent-loop.sh now sources
~/.nvm/nvm.sh directly when node isn't in PATH.

Reverts the --login flag (ineffective) and replaces with
targeted nvm sourcing with clear error if node still missing.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@mcj-coder @claude
feat: add Spec-Kit tasks.md parser
4c62dce 
Implements parseTasksMarkdown() to convert Spec-Kit markdown format
to JSON task objects. Extracts task IDs, parallel markers [P], user
story labels [US#], and file paths from task descriptions.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@mcj-coder @claude
fix: improve file path extraction and add edge case tests
a99fa45 
- Update file path regex to match both nested paths (src/file.py)
  and root-level files (README.md, package.json)
- Add comprehensive JSDoc with detailed type definitions and examples
- Add edge case tests: root-level files, undefined input, duplicate IDs
- Document that duplicate ID validation is caller's responsibility

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@mcj-coder
feat: add task converter from Spec-Kit to coordinator format
1948dac
@mcj-coder
fix: add acceptanceCriteria field for schema consistency
30cc82e
@mcj-coder @claude
feat: add dependency graph builder for task ordering
8c5b0e0 
Implements buildDependencyGraph() to automatically set blockedBy based
on file ownership. Tasks that touch files owned/touched by earlier
tasks are blocked until those earlier tasks complete.

Key features:
- Builds file ownership map from owns/touches arrays
- Only blocks on earlier tasks (lower task IDs)
- Handles multiple dependencies and complex chains
- Returns sorted blockedBy arrays for deterministic output

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@mcj-coder @claude
fix: add input validation for missing owns/touches fields
bfb19c2 
Prevents TypeError crashes when tasks have missing owns or touches
fields by using defensive || [] checks when spreading arrays.

Added test case to verify graceful handling of:
- Missing touches field
- Missing owns field
- Missing both fields

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@mcj-coder @claude
feat: add plan CLI for converting tasks.md to JSON
45513ff 
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@mcj-coder @claude
feat: implement coordinator plan command
c8f569b 
Add cmd_plan function to coordinator.sh that:
- Checks for .coordination/ directory
- Accepts optional tasks.md path argument
- Auto-discovers specs/*/tasks.md if no arg given
- Switches to coordination branch
- Runs node lib/plan.js to convert tasks.md to JSON
- Commits generated task files
- Returns to original branch

Add E2E test for plan command that verifies:
- tasks.md is converted to JSON files
- Files are committed to coordination branch
- Task JSON has correct status field

Also fix specify init hanging in tests by adding --force flag.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@mcj-coder @claude
docs: add coordinator plan usage documentation
84bbb80 
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@mcj-coder
fix: handle unbound variable in cmd_plan when no args passed
be234e5
@mcj-coder
fix: run conversion before switching to coordination branch
9e601d7
@mcj-coder @claude
chore: add implementation plan and final cleanup
831a308 
- Add comprehensive implementation plan document
- Fix Spec-Kit init error handling (graceful failure)
- Improve shellcheck compliance (direct exit code checks)
- Update markdownlint ignores for generated/plan directories

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
mcj-coder and others added 14 commits February 9, 2026 16:24
@mcj-coder @claude
fix: read claude-md files from main repo, not agent worktree
3d15b47 
Agent worktrees are on agent/* branches and don't have .coordination/
directory. The .coordination/claude-md/ files exist in the main repo
after 'coordinator init', so read from there instead.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@mcj-coder @claude
fix: agent worktrees should track feature branch, not main
dfb009b 
When coordinator is run from a feature branch, agents should base
their work on that branch, not main. Detect the current branch from
the main repo and use it as the base for agent worktrees.

Changes:
- Detect BASE_BRANCH from main repo on startup
- Use BASE_BRANCH instead of hardcoded 'main' in agent sync
- Pull from origin/$BASE_BRANCH instead of origin/main

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@mcj-coder @claude
fix: find main repo from within worktree, not parent dir
8f24b96 
The coordination worktree's parent directory is not a git repo.
Git worktrees have a .git file that points back to the main repo,
so run git rev-parse from within the worktree itself.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@mcj-coder @claude
fix: reclaim orphaned tasks on agent startup
4537ad1 
When agents crash or are stopped mid-task, tasks remain in "claimed"
status and are never picked up again. This adds a reclaim mechanism
that runs on agent startup:

1. Finds all tasks with status="claimed" and claimedBy=this-agent
2. Resets them to status="pending" and claimedBy=null
3. Records the reclaim in task history
4. Cleans the agent worktree (git reset --hard + git clean -fd)

This ensures agents always start with a clean slate and no orphaned
tasks are left behind.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@mcj-coder @claude
fix: correctly find main repo from worktree
2431d76 
Previously used git rev-parse --show-toplevel which returns the
worktree directory itself, not the main repository. This caused
ENOENT errors when trying to read .coordination/claude-md files.

Now uses git rev-parse --git-common-dir to get the main repo's
.git directory, then navigates up one level to get the main repo path.

Tested: git rev-parse --git-common-dir returns main repo's .git even
from within a worktree, allowing us to reliably find the main repo.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@mcj-coder @claude
fix: source user profile to enable aliases in agent loops
0603755 
Agent command aliases (like claude-zai) defined in user profile are
not available in WT tabs since they don't source .bashrc/.bash_profile.

This fix:
- Enables alias expansion with 'shopt -s expand_aliases'
- Sources .bash_profile, .bashrc, and .profile if they exist
- Makes user-defined aliases available to agent command execution

Without this, agents fail with "command not found" when using aliases.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@mcj-coder @claude
fix: also source zsh profile files for aliases
3813504 
User's shell profile may be in .zshrc/.zprofile instead of bash files.
Now sources both bash and zsh profile files to support both shells.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@mcj-coder @claude
fix: handle shell-incompatible profile files gracefully
3b56513 
When sourcing .zshrc in bash, oh-my-zsh references ZSH_VERSION
which causes "unbound variable" errors with set -u.

Solution:
- Temporarily disable unbound variable check (set +u)
- Suppress errors with 2>/dev/null and || true
- Re-enable check after sourcing (set -u)

This allows sourcing zsh configs in bash without breaking the script.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@mcj-coder @claude
feat: auto-retry failed tasks with configurable limit
875708a 
Failed tasks are now automatically retried up to MAX_RETRIES (default 3).
When a task fails, it increments the retry counter and resets to "pending"
if retries < MAX_RETRIES. Once the limit is reached, the task stays "failed".

Also adds reset-failed command to manually reset all failed tasks to pending
and clear their retry counters.

Configuration:
- Set max-retries in .coordination/config.toml [settings] section
- Defaults to 3 if not specified

CLI commands:
- node lib/tasks.js update <file> failed <agent> <maxRetries>
- node lib/tasks.js reset-failed <tasksDir>

This prevents tasks from being permanently stuck in failed state due to
transient errors like network issues or command not found errors.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@mcj-coder
docs: document auto-retry and reset-failed command
624128f
@mcj-coder @claude
feat: add coordinator reset-failed command
8b0b608 
Adds reset-failed as a first-class coordinator command:
- coordinator reset-failed
- Documented in help output
- Automatically handles coordination branch operations
- Much simpler than the manual node script approach

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@mcj-coder @claude
fix: prevent reset-failed when agents are running
6ca1a84 
Adds safety check to coordinator reset-failed:
- Counts tasks with status='claimed' (agents running)
- Exits with error if any claimed tasks exist
- Instructs user to run 'coordinator stop' first
- Prevents task confusion when resetting while agents run

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@mcj-coder @claude
fix: reset-failed works without coordination worktree
72c858c 
Previously required 'coordinator start' to have been run (confusing).
Now works like 'coordinator plan' - temporarily checks out coordination
branch, resets tasks, and returns to original branch.

Can be run before or after 'coordinator start'.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@mcj-coder @claude
fix: prevent git lock conflicts and handle missing worktrees
8a6199b 
Two critical fixes for agent startup races:

1. Git index.lock conflicts when multiple agents start simultaneously
   - Add random 0-3 second delay before reclaim
   - Retry push with exponential backoff (3 attempts)
   - Pull between retries to resolve conflicts

2. Agent worktree disappearing mid-execution
   - Check worktree exists before cd
   - Exit with clear error message
   - Happens when 'coordinator stop' runs during agent work

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@mcj-coder