maxsimcli 5.0.6 → 5.1.0

package/dist/assets/templates/skills/commit-conventions/SKILL.md

@@ -1,75 +1,109 @@
 ---
 name: commit-conventions
 description: >-
-  Commit message format using conventional commits with scope. Defines atomic
-  commit rules, breaking change markers, and co-author attribution for
-  AI-assisted work. Use when creating git commits, reviewing commit messages,
-  or establishing commit conventions for a project.
-user-invocable: false
+  Enforces conventional commit format with atomic changes and co-author
+  attribution. Use when committing code changes to maintain consistent git
+  history.
 ---
 
 # Commit Conventions
 
-Consistent commit messages that enable automated versioning, changelogs, and clear project history.
+Consistent commit messages enable automated versioning, changelogs, and clear project history. Every commit follows this format.
 
-## Conventional Commit Format
+## Format
 
 ```
-{type}({scope}): {description}
+type(scope): description
 
-- {key change 1}
-- {key change 2}
+- key change 1
+- key change 2
+
+Co-Authored-By: Claude <noreply@anthropic.com>
 ```
 
-### Types
+Subject line under 72 characters. Body bullet points are optional for trivial commits. Co-author line always present for AI-assisted work.
+
+## Types
 
-| Type | When | Triggers |
-|------|------|---------|
-| `feat` | New feature or capability | Minor version bump |
-| `fix` | Bug fix | Patch version bump |
-| `chore` | Build, deps, config, maintenance | No version bump |
-| `docs` | Documentation only | No version bump |
-| `test` | Adding or fixing tests | No version bump |
-| `refactor` | Code change that's neither fix nor feature | No version bump |
+| Type | When to Use | Version Impact |
+|------|-------------|---------------|
+| `feat` | New feature or capability | Minor bump |
+| `fix` | Bug fix | Patch bump |
+| `refactor` | Code restructure with no behavior change | No bump |
+| `test` | Adding or correcting tests | No bump |
+| `docs` | Documentation only | No bump |
+| `chore` | Build, deps, config, tooling, maintenance | No bump |
+| `style` | Formatting, whitespace, no logic change | No bump |
+| `perf` | Performance improvement | No bump |
+| `ci` | CI/CD pipeline changes | No bump |
 
-### Breaking Changes
+## Breaking Changes
 
 Append `!` after the type for breaking changes:
 
 ```
-feat!(install): require Node 20 minimum
+feat!(api): require authentication on all endpoints
 fix!(config): rename model_profile to profile
 ```
 
-Breaking changes trigger a major version bump.
+Breaking changes trigger a major version bump. Always explain what breaks and the migration path in the commit body.
 
-### Scope
+## Scope
 
-Scope identifies the area of change:
+Scope identifies the affected area:
 
-- Phase work: `feat(04-01):`, `fix(phase-04):`
-- Module: `fix(install):`, `refactor(core):`
+- Module or package: `fix(install):`, `refactor(core):`
 - Component: `feat(dashboard):`, `test(cli):`
+- Phase work: `feat(04-01):`, `fix(phase-04):`
+
+Scope is required when the change is not project-wide.
 
 ## Atomic Commits
 
-One logical change per commit:
+One logical change per commit. The diff and message should describe a single coherent unit of work.
+
+Do:
+- Separate feature implementation from test additions
+- Commit each task in a plan individually
+- Commit a refactor separately from a bug fix found during refactor
 
-- **DO:** Separate feature implementation from test additions
-- **DO:** Commit each task in a plan individually
-- **DO NOT:** Bundle unrelated changes in one commit
-- **DO NOT:** Include "fix typo" changes in feature commits
+Do not:
+- Bundle unrelated changes in one commit
+- Mix "fix typo" with feature work
+- Commit "work in progress" or partial implementations
 
 ## Co-Author Attribution
 
-When work is AI-assisted, include the co-author line:
+All AI-assisted commits include the co-author line:
 
 ```
 Co-Authored-By: Claude <noreply@anthropic.com>
 ```
 
-## Commit Message Guidelines
+## Common Mistakes
+
+| Mistake | Correct Approach |
+|---------|-----------------|
+| `fix: fixed stuff` | `fix(auth): handle expired token on refresh` |
+| `update things` | Missing type prefix entirely -- add `chore:` or appropriate type |
+| `feat: add feature and also fix bug` | Two commits: one `feat`, one `fix` |
+| `WIP` | Never commit WIP to main; finish the unit of work |
+| Past tense: "added validation" | Imperative mood: "add validation" |
 
-- **Subject line:** Under 72 characters, imperative mood ("add" not "added")
-- **Body:** Bullet points for key changes (optional for small commits)
-- **Why over what:** The diff shows what changed; the message explains why
+## Examples
+
+```
+feat(api): add rate limiting to public endpoints
+
+- Default: 100 requests per minute per IP
+- Configurable via RATE_LIMIT_RPM env var
+- Returns 429 with Retry-After header
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+```
+fix(install): resolve path resolution failure on Windows
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+```

package/dist/assets/templates/skills/github-operations/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: github-operations
+description: Unified GitHub interaction covering artifact types, comment conventions, CLI commands, and issue lifecycle. Use when reading from or writing to GitHub Issues, managing the project board, or posting structured comments.
+user-invocable: false
+---
+
+## GitHub as Source of Truth
+
+All project state lives on GitHub. No local `.planning/` files. The canonical record for every phase, task, decision, and progress update is an Issue or Issue comment on the configured repository.
+
+## Issue Structure
+
+- Phase issues: `[Phase N] Description` — labeled `type:phase`, added to board
+- Task sub-issues: `[Task N.M] Description` — labeled `type:task`, parented to phase issue
+- Issue bodies contain HTML comment markers for machine-readable metadata
+
+## Comment Types
+
+Every artifact posted to GitHub must include a type marker as the first line of the comment body.
+
+| Type | Marker | Purpose |
+|------|--------|---------|
+| plan | `<!-- maxsim:type=plan -->` | Task breakdown posted after planning |
+| research | `<!-- maxsim:type=research -->` | Investigation findings |
+| context | `<!-- maxsim:type=context -->` | Phase context and decisions |
+| progress | `<!-- maxsim:type=progress -->` | Status update during execution |
+| verification | `<!-- maxsim:type=verification -->` | Verification results |
+| summary | `<!-- maxsim:type=summary -->` | Phase or task completion summary |
+| error | `<!-- maxsim:type=error -->` | Error report |
+| escalation | `<!-- maxsim:type=escalation -->` | Escalation to user requiring input |
+| handoff | `<!-- maxsim:type=handoff -->` | Agent handoff with state transfer |
+
+## CLI Commands Reference
+
+All commands use the MAXSIM tools router:
+
+```bash
+node ~/.claude/maxsim/bin/maxsim-tools.cjs github <command> [--flag value]
+```
+
+Add `--raw` to any command for machine-readable JSON output: `{"ok": true, "result": "...", "rawValue": {...}}`.
+
+### Core Commands
+
+| Command | Purpose |
+|---------|---------|
+| `status` | Combined progress + interrupted phases + board overview |
+| `get-issue --issue-number N` | Get issue details |
+| `get-issue --issue-number N --include-comments` | Get issue with all comments |
+| `post-comment --issue-number N --body "..."` | Post comment (include type marker in body) |
+| `post-comment --issue-number N --body-file F` | Post comment from file (preferred for long content) |
+| `move-issue --issue-number N --status "In Progress"` | Move issue to board column |
+| `close-issue --issue-number N --state-reason completed` | Close issue as completed |
+| `close-issue --issue-number N --state-reason not_planned` | Close issue as cancelled |
+| `reopen-issue --issue-number N` | Reopen a closed issue |
+
+### Phase and Task Lifecycle
+
+| Command | Purpose |
+|---------|---------|
+| `create-phase --phase-number "01" --phase-name "Name" --goal "Goal"` | Create phase issue, add to board, set To Do |
+| `create-task --phase-number "01" --task-id "T1" --title "T" --body "B" --parent-issue-number N` | Create task sub-issue |
+| `batch-create-tasks --phase-issue N --tasks-json "[{...}]"` | Batch create tasks with rollback on failure |
+| `post-plan-comment --phase-issue-number N --plan-content "..."` | Post plan comment on phase issue |
+| `list-sub-issues --phase-issue-number N` | List all sub-issues under a phase |
+| `bounce-issue --issue-number N --reason "feedback"` | Move back to In Progress with feedback comment |
+
+### Board and Search
+
+| Command | Purpose |
+|---------|---------|
+| `query-board --project-number N` | Query all board items |
+| `query-board --project-number N --status "In Progress"` | Filter board by column |
+| `search-issues --labels "type:phase" --state open` | Search issues by label or state |
+| `phase-progress --phase-issue-number N` | Phase completion from sub-issue states |
+| `all-progress` | All phases progress overview |
+| `ensure-labels` | Create any missing standard labels |
+| `sync-check` | Verify local mapping matches GitHub state |
+
+### Large Text Arguments
+
+For multi-line content, write to a temp file and use `--body-file`:
+
+```bash
+TMPFILE=$(mktemp)
+cat > "$TMPFILE" << 'EOF'
+<!-- maxsim:type=summary -->
+## Summary
+Content here...
+EOF
+node ~/.claude/maxsim/bin/maxsim-tools.cjs github post-comment --issue-number 42 --body-file "$TMPFILE"
+rm "$TMPFILE"
+```
+
+## Board Columns
+
+Valid values for `--status`:
+
+```
+To Do  →  In Progress  →  In Review  →  Done
+```
+
+- Phase issues move through all four columns
+- Task sub-issues move: To Do → In Progress → Done (skip In Review unless a PR is involved)
+- On review failure: Done → In Progress via `bounce-issue`
+
+## Labels
+
+| Label | Applied To |
+|-------|-----------|
+| `type:phase` | Phase issues |
+| `type:task` | Task sub-issues |
+| `type:bug` | Bug reports |
+| `type:quick` | Quick tasks |
+| `priority:p0` through `priority:p3` | All issues (p0 = critical) |
+| `status:blocked` | Blocked issues |
+| `status:needs-review` | Awaiting review |
+| `maxsim:managed` | All issues created by MAXSIM |
+
+## Write Order
+
+1. Build full comment content in memory before any write
+2. POST to GitHub via CLI command
+3. If successful, operation complete
+4. If failed, abort entirely — no partial state
+
+## Rollback on Batch Failure
+
+When `batch-create-tasks` partially fails:
+
+1. Close partially-created issues with `--state-reason not_planned`
+2. Post an `error` comment on the phase issue explaining the failure
+3. Report what succeeded and what failed
+4. Offer targeted retry for the failed subset
+
+## External Edit Detection
+
+If a body hash mismatch is detected (issue edited outside MAXSIM):
+
+- Warn about the external modification
+- Do not auto-incorporate changes
+- Await explicit user instruction before proceeding

package/dist/assets/templates/skills/handoff-contract/SKILL.md

@@ -1,70 +1,104 @@
 ---
 name: handoff-contract
 description: >-
-  Structured return format for agent handoffs. Defines Key Decisions, Artifacts,
-  Status, and Deferred Items sections that every agent must include when returning
-  results. Use when completing any agent task, returning results to orchestrator,
-  or transitioning between workflow stages.
-user-invocable: false
+  Standardizes agent output format with key decisions, artifacts, status, and
+  deferred items. Use when any agent completes a task and needs to report
+  results to the orchestrator.
 ---
 
 # Handoff Contract
 
-Every agent returns results using this structured format. The orchestrator depends on these sections for state tracking, artifact management, and pipeline decisions.
+Every agent output includes exactly four sections. The orchestrator reads these sections for state tracking, artifact management, and pipeline decisions. Missing sections break the pipeline.
 
-## Required Return Sections
+## Required Sections
 
 ### Key Decisions
 
-Document decisions made during execution that affect downstream work:
+What was decided during execution and why. Downstream agents depend on this context.
 
 ```markdown
 ### Key Decisions
-- Chose X over Y because [reason]
-- Deferred Z to [phase/plan] because [reason]
+- Chose X over Y because [reason with evidence]
+- Deferred Z to [phase/plan] because [scope constraint]
+- Interpreted ambiguous requirement as [interpretation] because [reasoning]
 ```
 
-Include: technology choices, scope adjustments, interpretation of ambiguous requirements. Omit: routine implementation details.
+Include: technology choices, scope adjustments, interpretations of ambiguous requirements, tradeoffs made.
+
+Omit: routine implementation steps, decisions with no downstream impact.
 
 ### Artifacts
 
-List all files created or modified, grouped by action:
+All files created or modified, grouped by action.
 
 ```markdown
 ### Artifacts
-- Created: path/to/new-file.ts
-- Created: path/to/another-file.md
-- Modified: path/to/existing-file.ts
+- Created: /absolute/path/to/new-file.ts
+- Created: /absolute/path/to/another-file.md
+- Modified: /absolute/path/to/existing-file.ts
+- Deleted: /absolute/path/to/removed-file.ts
 ```
 
-Use absolute paths from project root. Include every file touched, not just the primary deliverables.
+Use absolute paths. Include every file touched — not just primary deliverables. Config changes, test files, and generated files all count.
 
 ### Status
 
-One of three values:
+One of three values with supporting evidence:
 
-| Status | Meaning | Orchestrator Action |
-|--------|---------|-------------------|
-| `complete` | All tasks done, verification passed | Advance to next plan or stage |
-| `blocked` | Cannot proceed without external input | Present blocker to user, await resolution |
-| `partial` | Some tasks done, stopped at checkpoint | Resume from checkpoint with user input |
+| Status | Meaning | Required Evidence | Orchestrator Action |
+|--------|---------|-------------------|-------------------|
+| `PASS` | All tasks done, verification passed | Test output, build output, or explicit verification | Advance to next stage |
+| `FAIL` | Could not complete; stopped | What failed, what was attempted | Escalate to user |
+| `PARTIAL` | Some tasks done; stopped at checkpoint | Which tasks passed, which remain | Resume from checkpoint |
 
 ```markdown
 ### Status
-complete
+PASS
+
+Evidence:
+- Tests: 47 passed, 0 failed (npm test output)
+- Build: exit code 0
+- All 4 plan tasks completed
 ```
 
+Evidence is not optional. A status claim without evidence is treated as FAIL.
+
 ### Deferred Items
 
-Work discovered but not implemented (outside current scope):
+Work discovered but not implemented. Captures scope that would otherwise be lost.
 
 ```markdown
 ### Deferred Items
 - [feature] Add caching layer -- not in current plan scope
-- [bug] Race condition in parallel writes -- needs investigation
-- [refactor] Extract shared validation logic -- deferred to Phase 5
+- [bug] Race condition in parallel writes -- needs investigation in Phase 5
+- [refactor] Extract shared validation logic -- deferred to cleanup phase
+- [investigation] Memory growth after 100+ concurrent connections -- repro needed
 ```
 
-If none: `### Deferred Items\nNone`
-
 Categories: `feature`, `bug`, `refactor`, `investigation`
+
+If none: write `### Deferred Items\nNone`
+
+## Complete Output Template
+
+```markdown
+### Key Decisions
+- [decision]: [reason]
+
+### Artifacts
+- Created: /path/to/file
+- Modified: /path/to/file
+
+### Status
+PASS | FAIL | PARTIAL
+
+Evidence:
+- [verification output or description]
+
+### Deferred Items
+- [category] [description] -- [reason deferred]
+```
+
+## Enforcement
+
+An orchestrator receiving output without all four sections treats the result as PARTIAL and requests re-submission. Agents cannot mark a task complete without producing a conforming handoff.

package/dist/assets/templates/skills/maxsim-batch/SKILL.md

@@ -1,86 +1,112 @@
 ---
 name: maxsim-batch
 description: >-
-  Parallel worktree execution for independent work units. Isolates agents in
-  separate git worktrees for conflict-free parallel implementation. Use when
-  executing multiple independent plans, batch processing, or parallelizable
-  tasks.
+  Orchestrates parallel agent execution using worktree isolation following
+  Anthropic's batch pattern. Use when multiple independent tasks can be
+  executed simultaneously.
 ---
 
-# Batch Worktree Execution
+# Batch Parallel Execution
 
-Decompose large tasks into independent units and execute each in an isolated git worktree.
+Decompose large tasks into independent units, spawn all agents in a single message block, track progress, collect results.
 
 ## When to Use
 
-- 3 or more independent work units with no shared file modifications
-- Tasks that can be verified independently (each unit's tests pass without the others)
-- Parallelizable implementation where speed matters
+Use batch execution when:
+- 3 or more tasks with no shared file modifications
+- Each task can be verified independently
+- Speed matters and the overhead of coordination is worth it
 
-**Do not use for:** Fewer than 3 units (overhead not worth it), sequential dependencies, tasks that modify the same files.
+Do not use for fewer than 3 tasks (overhead exceeds benefit), sequential dependencies, or tasks that modify the same files.
 
 ## Process
 
-### 1. DECOMPOSE -- Analyze Independence
+### 1. DECOMPOSE -- Verify Independence
 
-List all units with a one-line description each. For each unit, list the files it will create or modify. Verify:
+List all units. For each unit, list the files it will create or modify. Check:
 
 - No file appears in more than one unit
-- No runtime dependency (unit A output is not unit B input)
+- No unit's output is another unit's input
 - Each unit's tests pass without the other units' changes
 
-If overlap exists, merge overlapping units or extract shared code into a prerequisite unit that runs first.
+If overlap exists: merge overlapping units, or extract shared code into a prerequisite unit that runs first (serially) before the parallel batch begins.
 
-### 2. PLAN -- Define Unit Specifications
+### 2. SPAWN -- All Agents in One Message Block
 
-For each unit, prepare:
+Spawn all agents in a single message. Each agent call must be self-contained -- the prompt includes all context the agent needs without relying on shared state or prior conversation.
 
-- Unit description and acceptance criteria
-- The list of files it owns (and only those files)
-- The base branch to branch from
-- Instructions: implement, test, commit, push, create PR
+Agent configuration:
+- `isolation: "worktree"` -- each agent works in an isolated git worktree
+- `run_in_background: true` -- agents run in parallel
 
-### 3. SPAWN -- Create Worktree Per Unit
+Each agent prompt must include:
+1. The specific task and acceptance criteria
+2. The exact files it owns (and only those files)
+3. The base branch to branch from
+4. Instructions: implement, run tests, commit, push, create PR
+5. Output contract (see below)
 
-For each unit, create an isolated worktree and spawn an agent. Each agent works independently: read source, implement changes, run tests, commit, push, create PR.
+### 3. OUTPUT CONTRACT
 
-### 4. TRACK -- Monitor Progress
+Every agent returns a terminal line that the orchestrator reads:
 
-Maintain a status table:
+```
+RESULT: PASS — [brief summary]
+RESULT: FAIL — [reason for failure]
+```
 
-| # | Unit | Status | PR |
-|---|------|--------|----|
-| 1 | description | done | #123 |
-| 2 | description | in-progress | -- |
+The line must be the last non-whitespace line of agent output. This is what the orchestrator uses to update the status table -- do not use other formats.
 
-Statuses: `pending`, `in-progress`, `done`, `failed`
+Full handoff output follows the `handoff-contract` skill format.
 
-### 5. MERGE -- Collect Results
+### 4. TRACK -- Status Table
 
-When all units complete, list all created PRs. Handle failures:
+Maintain a status table and re-render it after each agent completion:
 
-- Unit fails tests: spawn a fix agent in the same worktree
-- Merge conflict: decomposition was wrong -- fix overlap and re-run unit
-- 3+ failures on same unit: stop and escalate
+| # | Unit | Branch | Status | PR |
+|---|------|--------|--------|----|
+| 1 | description | feat/unit-1 | done | #123 |
+| 2 | description | feat/unit-2 | in-progress | -- |
+| 3 | description | feat/unit-3 | pending | -- |
+
+Statuses: `pending` → `in-progress` → `done` | `failed`
+
+Update the table in place -- replace the previous table, do not append a new one each time.
+
+### 5. COLLECT -- Handle Results
+
+When all agents complete:
+1. List all PRs created
+2. Verify each PR is independently mergeable (no dependency on another PR)
+3. Handle failures:
+   - Unit fails tests: spawn a fix agent in the same worktree (up to 2 retries)
+   - Merge conflict found: decomposition was wrong -- fix overlap and re-run the conflicting units
+   - 3+ failures on one unit: stop and escalate to user with full failure context
 
 ## Limits
 
-- Up to 30 parallel agents, but typically 3-10 for manageable coordination
-- Fast-forward merge preferred, rebase if needed
-- Each unit must be independently mergeable
+- Up to 30 parallel agents; typically 3-10 for manageable coordination
+- Each unit must be independently mergeable -- prefer fast-forward, rebase if needed
+- Context budget: each agent consumes its own context window; keep prompts focused
 
 ## Common Pitfalls
 
-- "The overlap is minor" -- Minor overlap causes merge conflicts. Split shared code into a prerequisite unit.
-- "We'll merge in the right order" -- Order-dependent merges are not independent. Serialize those units.
-- "Only 2 units, let's still use worktrees" -- Worktree overhead is not worth it for fewer than 3 units.
+| Pitfall | Reality |
+|---------|---------|
+| "The overlap is minor" | Minor overlap causes merge conflicts. Extract shared code first. |
+| "We'll merge in dependency order" | Order-dependent merges are not independent. Serialize those units. |
+| "Only 2 units, let's use batch anyway" | Overhead is not worth it. Run sequentially. |
+| "Agents can ask each other for context" | Agents are isolated. All context goes in the spawn prompt. |
+| "I'll fix the prompt after spawning" | Re-spawning restarts work. Write complete prompts before spawning. |
 
-## Verification
+## Verification Before Completion
 
-Before reporting completion:
+Before reporting batch complete:
 
 - [ ] All units touch non-overlapping files
+- [ ] All agents returned `RESULT: PASS`
 - [ ] Each unit was implemented in an isolated worktree
 - [ ] Each unit's tests pass independently
 - [ ] Each unit has its own PR
 - [ ] No PR depends on another PR being merged first
+- [ ] Status table shows `done` for all units