maxsimcli 4.14.0 → 4.15.1

package/dist/assets/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [4.15.0](https://github.com/maystudios/maxsimcli/compare/v4.14.0...v4.15.0) (2026-03-11)
+
+
+### Features
+
+* **agents:** update agent prompts for GitHub I/O, create github-artifact-protocol skill, update installer ([2eaf852](https://github.com/maystudios/maxsimcli/commit/2eaf852bd04d129a5b9b95ceb62e0b14a2aced6f))
+
+# [4.14.0](https://github.com/maystudios/maxsimcli/compare/v4.13.0...v4.14.0) (2026-03-11)
+
+
+### Features
+
+* **workflows:** rewrite execute workflows for GitHub-first plan reading, per-task board transitions, and summary posting ([9d47215](https://github.com/maystudios/maxsimcli/commit/9d472159835a65058cd5d72a7a2265e4d58394c4))
+
 # [4.13.0](https://github.com/maystudios/maxsimcli/compare/v4.12.0...v4.13.0) (2026-03-11)
 
 

package/dist/assets/templates/agents/executor.md

@@ -10,14 +10,16 @@ skills:
   - handoff-contract
   - evidence-collection
   - commit-conventions
+available_skills:
+  | github-artifact-protocol | .skills/github-artifact-protocol/SKILL.md | When reading from or writing to GitHub Issues |
 ---
 
-You are a plan executor. You implement PLAN.md files atomically -- one commit per task, deviations handled inline, every completion claim backed by tool output.
+You are a plan executor. You implement plans atomically -- one commit per task, deviations handled inline, every completion claim backed by tool output.
 
 ## Input Validation
 
 Before any work, verify required inputs exist:
-- PLAN.md file path (from orchestrator prompt) -- `test -f`
+- Plan content (provided by the orchestrator from a GitHub Issue comment, or as a PLAN.md file path)
 - STATE.md readable -- `test -f .planning/STATE.md`
 
 If missing, return immediately:
@@ -48,7 +50,11 @@ For each task in the plan:
 
 ## Requirement Evidence
 
-When creating SUMMARY.md, populate the `## Requirement Evidence` section:
+When creating the summary, populate the `## Requirement Evidence` section.
+
+The summary is posted as a GitHub comment by the orchestrator via `mcp_post_comment` with `type: 'summary'`. The orchestrator handles this after the executor returns its handoff result.
+
+Note: The orchestrator handles board transitions. After each task completes, the orchestrator moves the task sub-issue on the project board.
 
 1. Read the plan's `requirements` frontmatter field to get requirement IDs
 2. For each requirement ID, document:
@@ -82,7 +88,7 @@ When running in a worktree (orchestrator passes `<constraints>` block with workt
 
 1. **Do NOT modify** `.planning/STATE.md` or `.planning/ROADMAP.md` -- the orchestrator handles all metadata
 2. **Do NOT run** `state advance-plan`, `state update-progress`, or `roadmap update-plan-progress` -- skip these steps
-3. **Create SUMMARY.md** as normal -- the orchestrator reads it from your worktree after completion
+3. **Return summary content** in your handoff result -- the orchestrator posts it as a GitHub comment via `mcp_post_comment` with `type: 'summary'`
 4. **Commit code normally** -- commits go to the worktree branch, orchestrator merges after wave completion
 5. **Skip** the `update_current_position`, `update_session_continuity`, `update_roadmap`, and `extract_decisions_and_issues` steps -- orchestrator handles these centrally
 

package/dist/assets/templates/agents/planner.md

@@ -9,22 +9,28 @@ model: inherit
 skills:
   - handoff-contract
   - input-validation
+available_skills:
+  | github-artifact-protocol | .skills/github-artifact-protocol/SKILL.md | When reading from or writing to GitHub Issues |
 ---
 
-You are a plan creator. You produce PLAN.md files with frontmatter, task breakdown, dependency graphs, wave ordering, and must_haves verification criteria.
+You are a plan creator. You produce phase plans with frontmatter, task breakdown, dependency graphs, wave ordering, and must_haves verification criteria.
+
+The plan is posted as a GitHub Issue comment via `mcp_post_plan_comment` by the orchestrator after the planner returns its output. Task sub-issues are created via `mcp_batch_create_tasks` after the plan is posted.
+
+Context and research input is provided from GitHub Issue comments (type: `context` and type: `research`) -- the orchestrator supplies these in the spawn prompt.
 
 ## Input Validation
 
 Before any work, verify required inputs exist:
 - ROADMAP.md -- `test -f .planning/ROADMAP.md`
 - REQUIREMENTS.md -- `test -f .planning/REQUIREMENTS.md`
-- Phase directory -- `test -d .planning/phases/{phase}/`
+- Phase directory -- `test -d .planning/phases/{phase}/` (if running in local mode) or context provided in spawn prompt (if running in GitHub mode)
 
 If missing, return immediately using the input-validation error format.
 
 ## Planning Protocol
 
-1. **Load context** -- read ROADMAP.md, REQUIREMENTS.md, CONTEXT.md, RESEARCH.md for the phase
+1. **Load context** -- read ROADMAP.md, REQUIREMENTS.md, and context/research provided from GitHub Issue comments (or local CONTEXT.md, RESEARCH.md if in local mode)
 2. **Identify scope** -- extract phase goal, requirements, and user decisions from context
 3. **Break into tasks** -- each task is an atomic unit with clear action, done criteria, verify block, and file list
 4. **Build dependency graph** -- identify which tasks depend on others

package/dist/assets/templates/agents/verifier.md

@@ -11,6 +11,8 @@ skills:
   - verification-gates
   - evidence-collection
   - handoff-contract
+available_skills:
+  | github-artifact-protocol | .skills/github-artifact-protocol/SKILL.md | When reading from or writing to GitHub Issues |
 ---
 
 You are a verifier. You check work against specifications using fresh tool output as evidence. You NEVER trust prior claims -- you gather your own evidence for every criterion.
@@ -86,3 +88,5 @@ Return results using the handoff-contract format (loaded via skills). Include:
 - Overall verdict: PASS or FAIL
 - Evidence blocks for every criterion
 - Findings summary with counts (X pass, Y fail, Z warnings)
+
+Verification results are posted as a GitHub comment by the orchestrator via `mcp_post_comment` with `type: 'verification'`.

package/dist/assets/templates/skills/github-artifact-protocol/SKILL.md

@@ -0,0 +1,68 @@
+# Skill: GitHub Artifact Protocol
+
+## Trigger
+When reading from or writing to GitHub Issues for MAXSIM artifacts.
+
+## Protocol
+
+### Artifact Types and Comment Conventions
+
+All MAXSIM artifacts are stored as GitHub Issue comments with type metadata:
+
+| Artifact | Comment Type | Tool | Format |
+|----------|-------------|------|--------|
+| Context decisions | `context` | `mcp_post_comment` | `<!-- maxsim:type=context -->` header |
+| Research findings | `research` | `mcp_post_comment` | `<!-- maxsim:type=research -->` header |
+| Plan content | (plan header) | `mcp_post_plan_comment` | `<!-- maxsim:type=plan -->` header |
+| Summary | `summary` | `mcp_post_comment` | `<!-- maxsim:type=summary -->` header |
+| Verification | `verification` | `mcp_post_comment` | `<!-- maxsim:type=verification -->` header |
+| UAT | `uat` | `mcp_post_comment` | `<!-- maxsim:type=uat -->` header |
+| Completion | (structured) | `mcp_post_completion` | Commit SHA + files |
+
+### Issue Lifecycle State Machine
+
+**Phase Issues:**
+```
+To Do --> In Progress --> In Review --> Done
+(created)  (plan done)    (PR created)  (PR merged + verified)
+```
+
+**Task Sub-Issues:**
+```
+To Do --> In Progress --> Done
+(created)  (started)      (completed + review passed)
+Done --> In Progress (review failed, reopened)
+```
+
+### Write Order (WIRE-01)
+
+1. Build content in memory
+2. POST to GitHub via MCP tool
+3. If successful, operation succeeds
+4. If failed, operation aborts entirely -- no partial state
+
+### Rollback Pattern (WIRE-07)
+
+On partial failure during batch operations:
+1. Close partially-created issues with `state_reason: 'not_planned'`
+2. Post `[MAXSIM-ROLLBACK]` comment explaining why
+3. Report what succeeded and what failed
+4. Offer targeted retry
+
+### External Edit Detection (WIRE-06)
+
+- Body hash (SHA-256) stored in `github-issues.json` mapping after each write
+- On read, compare live body hash against stored hash
+- If different, warn user about external modification
+- Do not auto-incorporate -- user decides
+
+### What Stays Local
+
+- `config.json` -- project settings
+- `PROJECT.md` -- project vision
+- `REQUIREMENTS.md` -- requirements
+- `ROADMAP.md` -- phase structure
+- `STATE.md` -- decisions, blockers, metrics
+- `github-issues.json` -- mapping cache (rebuildable)
+- `codebase/` -- stack, architecture, conventions
+- `todos/` -- pending/completed todos

package/dist/assets/templates/workflows/execute-phase.md

@@ -552,6 +552,12 @@ If any plan has unresolved BLOCKED/FAIL status: list the blocking issues below.]
 [Aggregate from summary comments, or "None"]
 ```
 
+**Move phase issue to "In Review" on GitHub (WIRE-08):**
+All tasks are complete — move the phase to "In Review" before running verification:
+```
+mcp_move_issue(issue_number: phase_issue_number, status: "In Review")
+```
+
 **Phase completion gate:** If any plan has unresolved review issues (BLOCKED or FAIL in Spec Review or Code Review stages), the phase CANNOT proceed to `verify_phase_goal`. Present unresolved issues and offer:
 - "Fix review issues now" — re-run the review cycle for affected plans
 - "Override and continue" — mark as acknowledged, proceed (adds warning to VERIFICATION.md)

package/dist/assets/templates/workflows/execute.md

@@ -286,6 +286,12 @@ After all waves complete:
 Proceeding to verification...
 ```
 
+**Move phase issue to "In Review" on GitHub (WIRE-08):**
+```
+mcp_move_issue(issue_number: phase_issue_number, status: "In Review")
+```
+This signals all tasks are complete and the phase is awaiting verification. The phase moves to "Done" only after verification passes.
+
 Wait for user confirmation before proceeding to verification.
 
 ## 5. Auto-Verify
@@ -513,7 +519,8 @@ Display final results:
 - [ ] Spot-check reads summary comments and checks sub-issue closure instead of local SUMMARY.md
 - [ ] Gate confirmation shown after execution completes
 - [ ] Auto-verification spawns verifier agent that posts to GitHub
-- [ ] Phase issue moved to Done on verification pass
+- [ ] Phase issue moved to "In Review" after all tasks complete (before verification)
+- [ ] Phase issue moved to "Done" on verification pass
 - [ ] Retry loop with gap closure (max 2 retries, 3 total attempts)
 - [ ] Checkpoint-before-clear posts to GitHub issue
 - [ ] No references to old SUMMARY.md local file checks for completion detection

package/dist/assets/templates/workflows/quick.md

@@ -592,7 +592,7 @@ INIT=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs init todos)
 mkdir -p .planning/todos/pending .planning/todos/done
 ```
 
-Extract from init JSON: `todo_count`, `todos`, `pending_dir`, `date`, `timestamp`.
+Extract from init JSON: `todo_count`, `todos`, `pending_dir`, `date`, `timestamp`, `github_ready`.
 
 ---
 
@@ -669,7 +669,9 @@ files: []
 TBD
 ```
 
-5. Best-effort GitHub Issue with 'todo' label: `node ~/.claude/maxsim/bin/maxsim-tools.cjs todos add "$TITLE" "$PRIORITY" 2>/dev/null || true`
+5. Best-effort GitHub Issue creation:
+   - Always attempt: `node ~/.claude/maxsim/bin/maxsim-tools.cjs todos add "$TITLE" "$PRIORITY" 2>/dev/null || true`
+   - If `github_ready` is true in init context: also call `mcp_create_todo_issue` with title, priority, area, and description to create a tracked GitHub Issue linked to the todo file
 6. Commit: `node ~/.claude/maxsim/bin/maxsim-tools.cjs commit "docs: capture todo - ${TITLE}" --files .planning/todos/pending/${date}-${slug}.md`
 7. Confirm: "Saved: ${TITLE} (priority: ${PRIORITY})"
 

package/dist/install.cjs

@@ -7295,6 +7295,7 @@ const builtInSkills = [
 	"agent-system-map",
 	"commit-conventions",
 	"evidence-collection",
+	"github-artifact-protocol",
 	"handoff-contract",
 	"input-validation",
 	"research-methodology",