@rubytech/create-maxy-code 0.1.196 → 0.1.198

package/payload/platform/plugins/admin/skills/superpowers-sprint/SKILL.md

@@ -0,0 +1,361 @@
+---
+name: superpowers-sprint
+description: Structured sprint workflow built only on officially-distributed Claude Code skills (superpowers, code-review, plainly). Drives an eight-phase chain — worktree → brainstorm → plan → implement → verify → code review → land → final status — with every phase resolved to a skill that ships in `~/.claude/skills/` or the official plugin marketplaces. Use on installs that do not carry the `gstack` plugin. Triggers include "superpowers sprint", "sprint without gstack", or invoking against a `.tasks/NNN-*.md` file on a maxy-code install.
+---
+
+# Superpowers Sprint
+
+A structured workflow for executing development work — features, bug fixes, refactors, any scoped unit of work — using only skills that ship with the official Claude Code distribution. No `gstack`, no custom plugin required.
+
+This skill is the maxy-code counterpart to `sprint`. The phase chain is identical in spirit; the difference is the skill at each phase. If both `gstack` and superpowers are installed and the project is set up for it, prefer `sprint` — its plan reviews are richer. Use this skill when `gstack` is not available.
+
+## Output discipline (applies to every emission in this skill)
+
+Every message the sprint writes — plan summaries, change logs, status tables, the final summary — is written `/plainly`. That means:
+
+- Plain English, spoken register, short sentences. Read it aloud; if it doesn't parse in conversation, rewrite it.
+- Only pertinent information. The operator needs to know: the outcome was achieved, how it was achieved, where the agent deviated, and what they must do to verify. Anything that does not serve one of those four is cut.
+- No filler, no inflation vocabulary, no em-dashes, no AI tells (see the `plainly` skill catalogue). No re-stating the brief back to the user.
+- Tables and checklists stay only when they carry information the operator will act on. A table with one row of "✅" everywhere is replaced by one sentence.
+
+Bloat in any phase's output is a defect, not a style choice.
+
+## Phase markers
+
+Every phase emits exactly one marker line to stdout when it begins, in the form:
+
+```
+[sprint] phase <N> — <name> — invoking <skill>
+```
+
+If a phase invokes no skill (internal-only steps like Plan Conformity or Debrief), the marker names the internal step instead: `[sprint] phase <N> — <name> — internal`. Markers exist so the operator and any transcript reader can confirm which phases ran and in what order. A missing marker is a phase that did not run.
+
+## Workflow
+
+### Phase 0: Worktree Isolation — `superpowers:using-git-worktrees`
+
+Invoke `superpowers:using-git-worktrees`. The skill creates an isolated git worktree on a fresh branch named for the task (e.g. `task-537-superpowers-sprint`). Without isolation, parallel sessions share one HEAD and one working directory — a branch switch in one session silently disrupts every other active session.
+
+After entering the worktree, install dependencies before building. Worktrees only contain tracked files, so `node_modules`, build artifacts, and untracked configuration are absent. Run `npm install` in every directory you plan to build from.
+
+`getmaxy` is one repo with two parallel installer trees living as plain directories — `packages/create-maxy/` ships `@rubytech/create-maxy`, and `maxy-code/packages/create-maxy-code/` ships `@rubytech/create-maxy-code`. Neither is a submodule, subtree, or sibling repo. Build only the tree the sprint touches; if a build needs `platform/` deps, install in the matching tree (`platform/` at the root for legacy work, `maxy-code/platform/` for Maxy Code work). If the sprint depends on recent main-branch work, merge main into the worktree branch at the start.
+
+If already in a worktree (resuming a sprint), skip — but verify `node_modules` is present.
+
+If the only repo-side artifact of the sprint is the task-file archive plus the LANES.md sync (the deliverable lives outside the repo entirely — e.g. an operator-side `~/.claude/skills/...` file), the worktree is still required: the archive commit must land on a feature branch and merge to main like any other change.
+
+### Phase 1: Brainstorm — `superpowers:brainstorming`
+
+Invoke `superpowers:brainstorming`. The skill explores user intent, requirements, and design before any code is written. It is the forcing function that prevents starting implementation against an unclear brief.
+
+Read the task file or operator brief first, then enter brainstorming with what you understood. The skill's questions surface implicit assumptions, unstated constraints, and scope ambiguity. The output of this phase is a shared understanding of *what* is being built and *why*, not yet *how*.
+
+If the operator hands over a fully-formed plan that is already broken into specific files and behaviours, brainstorming can be a fast confirmation rather than an open exploration — but it still runs, because skipping it is the failure mode the phase exists to prevent.
+
+### Phase 2: Plan — `superpowers:writing-plans`
+
+Invoke `superpowers:writing-plans` against the brainstorm output. The skill produces a single written plan: the files to touch, the behaviours to add or change, the edge cases, the test coverage, the deployment story. This is the artefact Phase 6 (Plan Conformity) checks the implementation against.
+
+This is a deliberate downgrade from `sprint`'s separate CEO and Eng reviews — multi-approach architecture review is out of scope for the superpowers chain. One reviewed plan is the baseline.
+
+Present the final plan to the operator and get explicit confirmation before writing any production code.
+
+### Phase 3: Implement — `superpowers:executing-plans` + `superpowers:test-driven-development`
+
+Invoke `superpowers:executing-plans` to drive execution against the Phase 2 plan. Within each step, follow `superpowers:test-driven-development` — RED-GREEN-REFACTOR for every behaviour change.
+
+Tests are ephemeral: design and run them to prove the implementation works during the sprint, then discard them. They are not committed to the repository unless the project's own test suite already lives in the tree and the new behaviour belongs in it. Their purpose is to enforce thinking through behaviour before writing production code, not to build a permanent regression suite.
+
+- **Test first.** Write a failing test for each behaviour before implementing it. Watch it fail. Write minimal code to pass. Refactor.
+- **Track progress.** Use TaskCreate/TaskUpdate for multi-step work. Mark tasks in_progress before starting, completed when done.
+- **Build incrementally.** Make changes file by file. Verify as you go with build scripts to catch errors early, not at the end.
+- **Follow project conventions.** Read CLAUDE.md rules.
+- **Multi-surface sync.** On a maxy-code sprint, when adding or removing MCP tools, all registration surfaces must be updated in the same commit: tool server `index.ts`, `PLUGIN.md` declarations, `ADMIN_CORE_TOOLS`, and specialist agent templates under `platform/templates/specialists/agents/`. Grep for a sibling tool name to find affected files.
+- **Don't over-engineer.** Only make changes that are directly needed. No speculative abstractions, no cleanup of surrounding code, no extra error handling for impossible scenarios.
+- **Debug with discipline.** When something breaks and the cause isn't immediately obvious, invoke `superpowers:systematic-debugging`. It enforces root-cause-first: hypothesis → evidence → fix. No fixes without root cause. This replaces the instinct to chain speculative fixes.
+
+### Phase 4: Verify — `superpowers:verification-before-completion`
+
+Invoke `superpowers:verification-before-completion`. The skill blocks any "it works" claim until an explicit verification command has been run and its output observed. Evidence before assertions, always.
+
+Minimum verification surface:
+
+1. Build — no TypeScript errors. Build success does not imply boot success. When the change touches dependencies, the build pipeline, or plugin entry points, also run the bundle command for the matching tree and confirm no runtime errors in the assembled payload.
+2. Lint — no new lint errors in changed files.
+3. Tests — the ephemeral tests from Phase 3 pass, plus any pre-existing test surface that covers the changed code.
+4. **UI sprints.** Drive the change in a real browser via the `chrome-devtools-mcp:chrome-devtools` MCP, or the `playwright` MCP if that is what the project is set up for. Walk the user-visible flow that the sprint changed and confirm the expected state. Console messages and network requests are part of the verification surface, not optional polish.
+5. **Pi signal verification (for sprints touching hooks or MCP tool input handling).** Local tests validate hook logic but cannot verify that test inputs match what production actually sends. After deploying to the Pi, trigger the relevant flow via admin chat. SSH in and read the diagnostic log (`/tmp/maxy-gate.log` for gate hooks, or the relevant log for other hooks). Compare the actual `tool_input` field names and structure against what the local tests pipe as JSON. If they diverge, the tests are wrong — fix them before proceeding. The Pi is the only environment where the real Claude Code hook protocol runs.
+
+If verification fails, return to Phase 3.
+
+### Phase 5: Code Review — `superpowers:requesting-code-review` → `code-review:code-review` → `superpowers:receiving-code-review`
+
+Invoke `superpowers:requesting-code-review` to frame the review request. Then run `code-review:code-review` against the sprint's diff. Process the response through `superpowers:receiving-code-review`, which gates whether each finding is accepted, contested, or filed as follow-up.
+
+Findings that are accepted and trivial are fixed before proceeding. Findings that are accepted but out-of-scope for this sprint become new `.tasks/NNN-*.md` files (the same deferral rule as Phase 6 — prose deferrals are banned). Findings that are contested get a one-line rebuttal in the debrief.
+
+### Phase 6: Land
+
+Land has four internal steps in fixed order: Plan Conformity, Debrief, Task Archive + LANES sync, then worktree teardown via `superpowers:finishing-a-development-branch`.
+
+**Gating model — fixed, not per-sprint.** The boundary between automatic and command-gated steps is the same on every sprint, so the user never has to remember which kind of sprint this was:
+
+| Step | When |
+|------|------|
+| Commit, archive task file, merge to local `main`, worktree + branch cleanup | **Automatic** once the user confirms the task is done in this phase |
+| `git push`, `npm publish` | **Always await explicit command** — never auto-run, never offer as a menu |
+
+No "Want me to push, or hold?" phrasings. The rule above is the answer; restating it as a question is a menu-phrasing violation. If the user wants to push, they say so; otherwise the final-status block makes the pending state visible.
+
+#### 6a. Plan Conformity
+
+Compare the implementation against the approved Phase 2 plan. Every plan item must appear in exactly one section of the conformity report:
+
+```
+## Plan Conformity
+
+### Implemented as planned
+- [item] — matches plan: [brief evidence]
+
+### Deviations
+- [item] — DEVIATED: [what the plan said] → [what was actually built] — Reason: [why]
+  → Follow-up: [.tasks/NNN-*.md path] — REQUIRED if the deviation drops any plan commitment
+
+### Omissions
+- [item] — NOT IMPLEMENTED — Follow-up: [.tasks/NNN-*.md path] — REQUIRED, no exceptions
+
+### Additions
+- [item] — NOT IN PLAN: [what was added and why it was necessary]
+```
+
+**100% coverage required.** Silent omissions — items that were in the plan but neither implemented nor flagged — are the failure mode this step exists to prevent.
+
+**Deferrals require task files, never prose.** Any plan item moved out of this sprint must point to a concrete `.tasks/NNN-*.md` file created here, before the debrief. "Deferred because X" without a task file becomes a silent regression. Binary rule: either pull the item back into scope and finish it, or file a task.
+
+If deviations or omissions are found, present them to the operator for acknowledgement before the debrief.
+
+#### 6b. Debrief
+
+**Change log.** For every file modified:
+
+```
+### `path/to/file.ts`
+**What changed:** [concise description of the change]
+**Why:** [the reason this change was needed]
+**Implication:** [what this change means for the system — behavior change, new capability, dependency, etc.]
+```
+
+Group related changes logically.
+
+**Commit table.** Run `git log --oneline <base-branch>..HEAD` and present it as a table of hash, message, files. Nothing uncommitted at debrief time without an explanation.
+
+**Testing instructions.** Specific UI steps the operator runs to exercise the feature, what to look for, what should NOT happen. "Test it" is not an instruction. "Open `/setup`, click the iMessage refresh button, verify the status shows Connected" is.
+
+**Known limitations.** Every intentionally-deferred or out-of-scope item links to a `.tasks/NNN-*.md` file. No prose-only deferrals.
+
+#### 6c. Task Archive and LANES Sync
+
+Close the loop against the original task file. For every requirement in the task:
+
+- **Complete** — implemented and verified during this sprint.
+- **Deferred** — deliberately excluded; a new `.tasks/NNN-*.md` captures what remains and why.
+- **Missing** — should have been done but wasn't. Fix it now before archiving.
+
+Present the assessment and wait for operator confirmation. Do not archive until every requirement is accounted for.
+
+Once confirmed, archive the task file. The recipe branches on whether the source is tracked, because `git mv` errors with `fatal: not under version control` on an untracked source:
+
+```bash
+if git ls-files --error-unmatch .tasks/<task-file>.md >/dev/null 2>&1; then
+  git mv .tasks/<task-file>.md .tasks/archive/
+else
+  mv .tasks/<task-file>.md .tasks/archive/<task-file>.md
+  git add .tasks/archive/<task-file>.md
+fi
+```
+
+Two post-conditions hold for both branches; a third holds only for tracked sources:
+
+```bash
+# 1. No file remains at the live path.
+[ ! -e .tasks/<task-file>.md ] || { echo "ERROR: live source still on disk"; exit 1; }
+
+# 2. The archive add is staged.
+git diff --cached --name-only | grep -qx ".tasks/archive/<task-file>.md" \
+  || { echo "ERROR: archive add not staged"; exit 1; }
+
+# 3. (Tracked branch only) Confirm the rename was atomic.
+if git ls-files --error-unmatch .tasks/<task-file>.md >/dev/null 2>&1; then
+  git diff --cached --name-status | grep -E "^R[0-9]+\s+\.tasks/<task-file>\.md\s+\.tasks/archive/<task-file>\.md$" \
+    || { echo "ERROR: tracked source not renamed atomically — re-run with git mv"; exit 1; }
+fi
+```
+
+Pre-archive safety net: if `.tasks/archive/<task-file>.md` already exists on disk, stop. A duplicate basename in archive is never a silent overwrite — investigate the prior archive cycle first.
+
+**Update `.tasks/LANES.md` in the same commit as the archive move.** Three invariants hold after the LANES edit:
+
+1. **No Ready row references the archived task.** Verify: `grep -F "<task-file>.md" .tasks/LANES.md` returns zero hits inside the Ready section.
+2. **The archive sentence names the archived task number.** Verify: the regex `\b<NNN>\b` matches at least once inside the archive sentence.
+3. **Any new task file created for deferred work gets a Ready row in the same edit.** Otherwise the next sprint inherits an open file with no tracker entry.
+
+Commit the archive move, the LANES update, and any new task files for deferred work as a single commit:
+
+```
+chore: archive <task-name>
+```
+
+#### 6d. Worktree Teardown — `superpowers:finishing-a-development-branch`
+
+Invoke `superpowers:finishing-a-development-branch` to present the integration options (merge, PR, cleanup). On this sprint chain the default action is merge-to-local-main, because the gating model says push and publish await explicit operator command — the skill should be driven toward that outcome, not toward a PR.
+
+The cleanup sequence after the operator confirms is order-sensitive:
+
+1. Return to the main working directory (the superpowers skill drives this via its worktree teardown action).
+2. Merge the feature branch into `main`: `git merge <branch-name>`.
+3. **Sweep post-merge debris in `.tasks/`.** When the worktree archived a task file that was never tracked on `main` (created in a prior session at the open path but never committed), the merge brings in the archive add but cannot delete the untracked open-path copy on main. Walk every `chore: archive` commit in the merged range and remove untracked open-path twins:
+
+   ```bash
+   MERGED_RANGE="$(git merge-base HEAD~ HEAD)..HEAD"
+   git log --format=%H --grep='^chore: archive' "$MERGED_RANGE" | while read -r sha; do
+     git show --name-only --format= "$sha" | grep -E '\.tasks/archive/.+\.md$' | while read -r archived; do
+       bn="$(basename "$archived")"
+       open="${archived%/archive/$bn}/$bn"
+       if [ -e "$open" ] && ! git ls-files --error-unmatch "$open" >/dev/null 2>&1; then
+         rm -f "$open"
+         echo "[sprint] post-merge debris removed: $open"
+       fi
+     done
+   done
+   ```
+
+4. Remove the worktree: `git worktree remove .claude/worktrees/<name>`.
+5. Force-delete the branch: `git branch -D <branch-name>` (capital `-D`; lowercase `-d` fails when `refs/remotes/origin/main` is behind local `main`).
+
+If not in a worktree, merge and force-delete the branch directly, still running the debris sweep between them.
+
+### Phase 7: Final Status — `plainly`
+
+The sprint's last emission has two parts in fixed order: (1) the live status table, computed from the working tree right now; (2) a three-sentence plain-English summary, written under the `plainly` skill rules.
+
+Every sprint ends with this block as its final output, regardless of how it went.
+
+#### 7a. Status table
+
+Compute each row from a deterministic check, then render:
+
+```
+## Sprint Status
+
+| Artifact | State | Detail |
+|----------|-------|--------|
+| Committed | ✅ / ❌ | `git status --porcelain` empty? |
+| Merged to local main | ✅ / ❌ | `git branch --contains <sha> \| grep -q '^[* ] main$'` |
+| Pushed to origin/main | ⏳ awaiting command / ✅ / N/A | `git rev-list main..origin/main --count` is 0 and HEAD == origin/main |
+| Published (every brand) | ⏳ awaiting command / ✅ / N/A — no shipped files changed | one row per brand directory under `$BRANDS_DIR`; ✅ only when `npm view <pkg> version` returns the bumped version for ALL of them |
+| Task archived | ✅ / ❌ | task file lives under `.tasks/archive/` |
+| LANES synced | ✅ / ❌ | `.tasks/LANES.md` has no Ready row for the archived task, and the archive sentence names `<NNN>` |
+```
+
+Rules:
+
+- **Always emitted**, even if every row is ✅. Skipping it is the failure mode this phase prevents.
+- **No menu phrasings.** Never end with "Want me to push, or hold?" or any variant.
+- **States are computed, not narrated.** Don't write "I think it's pushed"; run the check and render ✅ or ⏳.
+- **N/A is required when applicable.** A skill-only sprint (deliverable outside the published packages) shows publish rows as `N/A — no shipped files changed`, not ⏳.
+- **The pending-commands block (below) is omitted entirely** if no row is ⏳.
+
+#### 7b. Pending commands
+
+If any row is ⏳, render the commands the operator runs when ready. Publish-tree detection picks the installer tree from the sprint's diff against the merge base — never from `basename` of the working directory; both trees live in the one `getmaxy` repo:
+
+| Installer tree | Installer directory | Brands directory | Default brand | Default package |
+|---|---|---|---|---|
+| Repo root (legacy Maxy) | `packages/create-maxy/` | `brands/` | `maxy` | `@rubytech/create-maxy` |
+| `maxy-code/` (Maxy Code) | `maxy-code/packages/create-maxy-code/` | `maxy-code/brands/` | `maxy-code` | `@rubytech/create-maxy-code` |
+
+```bash
+git push
+# (publish block — only if any Published row is ⏳; iterates every brand directory)
+REPO_ROOT=$(git rev-parse --show-toplevel)
+CHANGED=$(git diff --name-only "$(git merge-base HEAD main)" HEAD)
+if echo "$CHANGED" | grep -q '^maxy-code/'; then
+  INSTALLER_DIR=maxy-code/packages/create-maxy-code
+  BRANDS_DIR=maxy-code/brands
+  DEFAULT_BRAND=maxy-code
+else
+  INSTALLER_DIR=packages/create-maxy
+  BRANDS_DIR=brands
+  DEFAULT_BRAND=maxy
+fi
+cd "$REPO_ROOT/$INSTALLER_DIR" && npm run bundle && npm publish
+cd "$REPO_ROOT/$INSTALLER_DIR" && for b in $(ls "$REPO_ROOT/$BRANDS_DIR" | grep -v "^${DEFAULT_BRAND}$"); do
+  npm run bundle -- --brand="$b" && npm publish --ignore-scripts
+done
+cd "$REPO_ROOT/$INSTALLER_DIR" && npm run bundle
+```
+
+A diff that touches both trees is two sprints, not one — split it before publishing. A diff that touches neither tree is a docs/tooling sprint and publishes nothing; mark every Published row N/A. Every brand under `$BRANDS_DIR` ships a separate npm package and all of them must publish in lockstep at the same version — every new deployment of any brand pulls its own `@rubytech/create-<brand>` from npm, so a brand left behind silently regresses on the next install. `--ignore-scripts` on every non-default brand prevents `prepublishOnly` from re-bundling as the default brand and republishing under the wrong name. The final `npm run bundle` restores `package.json` to the default brand.
+
+After publishing, verify every brand landed at the new version on npm:
+
+```bash
+for pkg in $(for b in $(ls "$BRANDS_DIR"); do
+  python3 -c "import json; print(json.load(open('$BRANDS_DIR/'+'$b'+'/brand.json'))['npm']['packageName'])"
+done); do
+  echo "$pkg: $(npm view "$pkg" version)"
+done
+```
+
+Every line must show the version just bumped — a lagging entry means the publish loop missed that brand and a manual `cd "$REPO_ROOT/$INSTALLER_DIR" && npm run bundle -- --brand=<that-brand> && npm publish --ignore-scripts` is required.
+
+A version bump applies once to the default installer package and propagates to every brand at bundle time — there is no per-brand version. Bump once, publish all brands at that version, every time.
+
+#### 7c. Plain summary (the literal last words of the sprint)
+
+After the status block, write exactly three short sentences, under the `plainly` skill rules. Nothing follows them. The three sentences cover, in order:
+
+1. **Outcome** — what was achieved, in the operator's words. One sentence.
+2. **How / deviation** — the single most important thing the operator needs to know about how it was done, or where the work deviated from the brief. If there was no meaningful deviation, use this sentence for the one mechanism that matters. One sentence.
+3. **Verify** — the one concrete thing the operator does to confirm the outcome landed. One sentence, imperative.
+
+Hard rules:
+
+- Three sentences total. Not four. Not "three sentences plus a bullet list".
+- No jargon, no acronyms, no file paths, no commit hashes, no em-dashes.
+- No restating what the table already said.
+- No follow-up offer, no "let me know if…", no `/schedule` tail.
+
+If the sprint deferred work to a task file, the deviation sentence names that fact in plain English (e.g. "the retry cap is filed as a follow-up task"). The task number lives in the table or the conformity report, not in this summary.
+
+---
+
+## Commits
+
+Every commit made during a sprint must include a `Session:` trailer linking it to the Claude Code session that produced it.
+
+Derive the session ID from the most recently modified JSONL in the project's session directory:
+
+```bash
+ls -t ~/.claude/projects/$(pwd | tr '/' '-')/*.jsonl | head -1 | xargs basename | sed 's/.jsonl//'
+```
+
+Include it as a trailer:
+
+```
+feat: implement feature X
+
+Co-Authored-By: Claude <model> <noreply@anthropic.com>
+Session: <session-id>
+```
+
+---
+
+## Principles
+
+- **Ship complete.** A sprint is not done until the debrief and the final-status block are delivered. Code without documentation is unfinished work.
+- **Explain the why.** Every change has a reason. "Refactored for clarity" is not a reason. "Extracted to avoid duplicate route derivation across WhatsApp and iMessage" is.
+- **Operator perspective.** Testing instructions are written for the person running the product. If the operator is non-technical, instructions are UI-based.
+- **No surprises.** If a change has side effects, non-obvious implications, or touches shared infrastructure, call it out explicitly.
+- **Iterative by default.** Scope to what's achievable, and defer the rest by filing a `.tasks/NNN-*.md` for each unfinished piece before the sprint ends. Prose-only deferrals are banned.
+- **Always close with status.** Every sprint, without exception, ends on the Phase 7 Final Status block. Same gating rule on every sprint (commit/merge automatic, push/publish await command), same final emission shape, no menu-phrasing tail.

package/payload/platform/plugins/admin/skills/task/SKILL.md

@@ -0,0 +1,283 @@
+---
+name: task
+description: |
+  Generate a task entry that fully defines a unit of work — motivation,
+  boundaries, verification, and observability — so any session can
+  implement it without further conversation. Use when asked to "task it",
+  "create a task", "write a task file", or when the user describes work
+  that should be captured before a sprint.
+allowed-tools:
+  - Read
+  - Write
+  - Glob
+  - Grep
+  - Bash
+  - AskUserQuestion
+---
+
+# Task Generation
+
+## What this skill produces
+
+A single task entry that fully defines a unit of work — its motivation,
+boundaries, verification strategy, and deployment observability — so that
+any session can implement it without further conversation.
+
+The entry is written through the **task surface of the environment this
+install exposes**. The surface resolution below decides where; the
+structure, principles, and precision pass below are identical regardless
+of surface.
+
+---
+
+## Task surface (where tasks live in this environment)
+
+Before searching prior work or writing the deliverable, resolve where
+tasks live in the current install. Check in this order; use the first
+one that exists:
+
+1. **Graph tasks (deployed maxy).** If the `work-*` MCP tools are
+   available — `work-list` and `work-get` for prior-work search,
+   `work-create` to write the deliverable (it persists `:Task` nodes in
+   Neo4j and **owns the identifier — no number scan**) — tasks live in
+   the graph. Use those tools. The plugin is `work`, not `tasks` —
+   renamed to avoid colliding with Claude Code's built-in `Task*` family.
+2. **Local `.tasks/` directory.** If the repo has a `.tasks/` directory
+   (optionally with `archive/`, `in-progress/`, `parked/`, `backlog/`
+   subdirs and a `LANES.md`), tasks live on disk as
+   `.tasks/<N>-<slug>.md`.
+3. **Neither.** State this explicitly: "No task surface detected — this
+   install has no `work-*` graph tools and no `.tasks/` directory. The
+   deliverable will be a written report only."
+
+Throughout this skill, "search prior tasks" and "write the task" mean:
+use the resolved surface. Operate inside whatever tree/surface the
+install exposes; never hard-code paths.
+
+## Before generating
+
+1. **Determine the next identifier.**
+   - **Graph surface:** `work-create` assigns the identifier on write —
+     no number scan, no manual numbering. For prior-work search use
+     `work-list` / `work-get`.
+   - **Local `.tasks/` surface:** scan `.tasks/`, `.tasks/in-progress/`,
+     `.tasks/archive/`, and `.tasks/parked/` for the highest existing
+     `<N>-<slug>.md` and increment by one. Never invent a numbering
+     convention not already in use in this tree.
+   - **No surface:** skip — the deliverable is a report.
+
+2. **Read the task tracker, if one exists.**
+   - **Local `.tasks/` surface:** read `.tasks/LANES.md` (if present) to
+     understand active lanes and file contention; the new task's lane
+     assignment and touches must be checked against in-progress work.
+   - **Graph surface:** skip — there is no `LANES.md` on a graph surface.
+
+3. **Gather context from the user.** If the user's description is
+   ambiguous or missing critical information (what's broken, what success
+   looks like, what's excluded), ask via AskUserQuestion — one focused
+   question at a time.
+
+## Task structure
+
+Every task contains these sections. Each section has a purpose — if the
+purpose can't be fulfilled, the section should say why (e.g., "No
+existing logs cover this path — observability must be added as part of
+the implementation").
+
+### Title and metadata
+
+```markdown
+# Task <N> — <Descriptive title>
+
+**Lane:** <lane from the tracker, or proposed new lane>
+**Status:** Open
+**Touches:** <precise file paths or graph node types this task will modify>
+```
+
+Optional metadata when relevant: `**Depends on:**`, `**Blocks:**`,
+`**Sequencing:**`, `**Priority:**`
+
+### Problem
+
+What is wrong, missing, or suboptimal — grounded in evidence. Include log
+extracts, reproduction steps, or code references when available. The
+problem section answers "why does this task exist?" not "what will we
+build?"
+
+### What success looks like
+
+Observable outcomes that define completion. Each criterion is
+verifiable — someone reading this section can confirm whether the task is
+done without knowing the implementation details.
+
+### Scope boundaries
+
+Two subsections, always paired:
+
+- **In scope** — the specific changes, files, and behaviours this task
+  covers. Precise file paths and line ranges when known. **100% coverage
+  rule:** if the task delivers a capability that should apply uniformly
+  across a known set of surfaces (every brand JSON, every plugin
+  manifest, every specialist template, every IDENTITY.md, every CRM
+  connector, etc.), the in-scope list must enumerate **every member of
+  that set** — not a representative subset. A task that ships the
+  capability to 1-of-N surfaces and defers the rest is incomplete by
+  construction; the deferred N-1 surfaces become silent regressions
+  because the capability is "shipped" in the changelog while most users
+  never see it. If the set is genuinely large enough that staged rollout
+  is required, the task is split into N sibling tasks, each covering
+  one surface end-to-end — never one task covering one surface with the
+  others listed as "out of scope" or "future work".
+- **Out of scope** — adjacent work that is explicitly excluded. This
+  prevents scope creep and makes the boundary between this task and
+  future tasks unambiguous. **Out of scope cannot be used to defer
+  members of a coverage set** (see 100% coverage rule above) — only
+  genuinely adjacent work (different capability, different layer,
+  different concern).
+
+### Verification
+
+How the implementation will be proven correct. This section is mandatory
+— a task without a verification strategy is incomplete.
+
+The verification section addresses:
+
+- **What is tested** — which behaviours, edge cases, and failure modes
+  have automated or manual verification. Not "write tests" but
+  specifically what the tests prove.
+- **How to reproduce** — for bug fixes, the exact reproduction steps
+  that should fail before the fix and pass after. For features, the
+  user-visible scenario that demonstrates the new capability.
+- **Regression boundary** — what existing behaviour must remain
+  unchanged and how that's confirmed (e.g., "existing tests pass",
+  "manual smoke test of X").
+
+If the project has no test infrastructure for the affected area, the
+verification section must acknowledge this and define what manual
+verification is required.
+
+### Observability
+
+How the change will be monitored once deployed. This section is
+mandatory — code that cannot be observed in production is incomplete
+code.
+
+The observability section addresses:
+
+- **What to log** — the specific events, state transitions, or error
+  conditions that must produce log output. Each log point should carry
+  enough structured context to diagnose failures without reproducing
+  them locally.
+- **What signals confirm correct behaviour** — the log patterns,
+  metrics, or observable states that indicate the feature is working
+  as intended in deployment. An operator reading the logs should be
+  able to answer "is this working?" without reading the source code.
+- **What signals indicate failure** — the absence patterns, error
+  signatures, or anomalous states that indicate something is wrong.
+  The absence of an expected log entry is as important a signal as the
+  presence of an error.
+- **Diagnostic path** — given a failure signal, what targeted grep or
+  log query surfaces the cause. On a deployed install, this means
+  log-accessible forensics with specific tag/field patterns to search
+  for.
+
+If existing observability already covers the change adequately, the
+section should state what to look for in existing logs rather than
+adding new instrumentation.
+
+### Touches
+
+Precise file paths (local-`.tasks/` surface) or graph node/edge types
+(graph surface) the task will modify. Used for lane contention checks
+on the local-`.tasks/` surface.
+
+**Documentation triple-target (local-`.tasks/` surface with a
+`task-commit-gate` only).** When the task modifies source files under
+`platform/` and the repo enforces a `task-commit-gate` hook that
+mechanically requires all three documentation targets to be updated
+before any commit is allowed, include the applicable targets in the
+Touches list so the author scopes documentation work upfront:
+
+- `.docs/` — developer and architecture reference
+- `platform/plugins/docs/references/` — user guide shipped to device,
+  loaded by admin agent
+- `.tasks/LANES.md` — task tracker reflecting what changed
+
+A graph task surface has no `LANES.md`, and the commit-gate hook
+governs only on-disk `platform/` commits — on a graph-only install
+this paragraph does not apply.
+
+### Dependencies (when relevant)
+
+What must exist or be true before this task can start. If nothing, omit
+the section entirely rather than writing "None."
+
+## Principles
+
+- **Evidence before prescription.** The problem section contains
+  observed facts. The success criteria describe verifiable outcomes.
+  Neither section prescribes implementation steps.
+
+- **Scope is defined by exclusion.** What's out of scope is as important
+  as what's in scope. Adjacent improvements, refactors, and "while
+  we're here" changes are explicitly out of scope unless the user says
+  otherwise.
+
+- **Coverage is defined by enumeration.** When a task delivers a
+  capability to a known set of surfaces, the in-scope list enumerates
+  every member of that set. Shipping to 1-of-N and deferring the rest
+  is incomplete by construction — the deferred members become silent
+  regressions. See § Scope boundaries / 100% coverage rule.
+
+- **Testing is not optional.** Every task defines how its implementation
+  will be verified. "It works when I try it" is not verification —
+  it's anecdote.
+
+- **Observability is not optional.** Every task defines how its
+  implementation will be monitored in deployment. If you can't tell
+  whether it's working from the logs, the task isn't done. If current
+  observability is insufficient to monitor the change, adding
+  observability is in-scope for the task.
+
+- **Precision over brevity.** File paths are exact. Line ranges are
+  included when known. Error messages are quoted, not paraphrased.
+  Vague tasks produce vague implementations.
+
+## Precision pass (mandatory final step before commit)
+
+After drafting the task and before staging it, compress it to ~25% of
+its initial length (75% reduction) without losing informative value.
+This step is non-optional — tasks are read by every sprint, indexed by
+every learning extraction, and paid for in every context window that
+loads them. Bloat compounds.
+
+- **Strip:** planning narrative, restated repository context already in
+  linked docs, ceremonial framing, prose that paraphrases section
+  headings, redundant motivation, and verbose phrasing. Replace
+  multi-sentence explanations with single declarative lines.
+- **Preserve:** every file path, line range, log extract quotation,
+  scope boundary item (in and out), verification criterion,
+  observability hook, error signature, dependency, and link. Precision
+  data is incompressible.
+- **Verify:** re-read the compressed task once. Every detail an
+  implementer would need to execute the task without further
+  conversation must still be present. If a fact was lost, restore it;
+  if it wasn't needed, the original was bloated.
+
+The same "additions require deletions" doctrine that governs
+`CLAUDE.md` applies here.
+
+## After generating
+
+1. Confirm the task was written through the resolved surface and that
+   the precision pass has been applied.
+2. **Local `.tasks/` surface only:** stage and commit the task file with
+   message `task: add Task <N> — <title>` and the co-author trailer. If
+   `LANES.md` was updated (new lane or touches entry), include it in
+   the same commit. Report any lane contention found in `LANES.md`
+   (files touched by both this task and an in-progress task).
+3. **Graph surface:** the `work-create` write is the commit-equivalent;
+   no git step. If a project surface is implied by the work, set it on
+   the node at write time.
+4. Do not implement. The task entry is the deliverable. Implementation
+   is a separate step that goes through the sprint workflow.

package/payload/platform/plugins/docs/references/admin-ui.md

@@ -43,7 +43,8 @@ either is a regression.
 | Mount | Purpose | Key methods |
 |---|---|---|
 | `/session` | Admin cookie session: PIN-gated mint, validate, rotate. | `GET /`, `POST /` |
-| `/sessions` | Legacy conversation list and lifecycle (kept for the ConversationsModal styling class and the post-action reconcile). | `GET /`, `POST /new`, `POST /switch`, `DELETE /:id`, `POST /:id/resume` |
+| `/sessions` | Legacy admin-server conversation routes. No UI consumer remains after the ConversationsModal was retired; the surviving handlers are deletion candidates and not described here. | (legacy, no live caller) |
+| `/sidebar-sessions` | Sole data path for the sidebar Sessions list (Task 538). One JSONL on disk equals one row; deleting the JSONL is the only way a row disappears. Each row carries `sessionId`, `title` (first user turn, falling back to a short UUID prefix), `startedAt` (file mtime ISO string), `live: boolean` (PID-file cross-reference), `isSubagent: boolean` (path matches `*/subagents/*`), and an optional `rcUrl` extracted from the JSONL body when a `claude.ai/code/session_<slug>` banner is present. The five-rule contract — JSONL on disk equals a row, subagents tagged and hidden by default, PID match paints the dot, in-body RC URL paints the external-link icon, anything else dead — lives in [`.tasks/archive/538-sessions-list-equals-jsonl-on-disk.md`](../../../.tasks/archive/538-sessions-list-equals-jsonl-on-disk.md). | `GET /` |
 | `/claude-sessions` | **Spawn surface only** (Task 500). The single `POST /` is shared by three callers: the public/visitor bridge, `linkedin-ingest`, and the turn-completed-graph-write Stop-hook recorder. The former UI-facing handlers (SSE row feed, list, resume, stop, rename, archive, delete, `/:id/meta`, `/:id/input`, `/:id/log`) were removed — the maxy dashboard no longer manages or displays sessions. | `POST /` |
 
 Task 500 — **admin session management moved entirely to claude's own interfaces** (claude.ai/code, claude desktop). A manager-owned per-account `claude rc --spawn same-dir` daemon registers the device as a Remote Control target there; the composer creates / resumes / stops / renames / archives / deletes sessions, with model + permission-mode applied at inception. The model lever is `account.json.adminModel` → `CLAUDE_CONFIG_DIR/settings.json "model"`, written by the daemon supervisor at boot. The maxy admin UI keeps a single "New session" link (`https://claude.ai/code`, opens in a new tab) and no session list, viewer, controls, or model/mode picker. The daemon supervisor lives at [`platform/services/claude-session-manager/src/rc-daemon.ts`](../../../services/claude-session-manager/src/rc-daemon.ts). The `/session-defaults` route and `SpawnPreference` node were deleted with the picker. `/new-session-failure`, `/new-session-submit`, and `/claude-capabilities` are now orphaned (consumed only by the deleted NewSessionModal) — see [`.tasks/501`](../../../.tasks/) for their removal.