@excitedjs/dreamux 0.9.4 → 0.9.6

package/skills/dreamux-maintenance/references/codex-turns.md

@@ -0,0 +1,50 @@
+# Codex Turns In Dreamux
+
+## What A Turn Is
+
+A turn is one model round opened by user input and kept alive until the model
+stops requesting tools. While a turn is active, additional input can be folded
+into that same turn and processed at the next model step.
+
+## Start Versus Steer
+
+- `turn/start` is aggregate behavior: it starts a fresh turn when idle and can
+  fold input into the currently active turn when busy.
+- `turn/steer` targets an active turn and should fail when no active turn
+  exists or the expected turn id does not match.
+
+Operational rule: when you need deterministic injection, identify whether a
+turn is active before choosing start or steer behavior.
+
+## Why Steering Is Not Instant
+
+Tool calls return control only at yield boundaries. If the active turn is
+waiting inside a long-running command or poll, injected input is usually not
+processed until that tool call yields and the model samples again.
+
+## Background Work Does Not Wake An Idle Model
+
+A background command completing is an event for the host, not new user input.
+If the dispatcher starts background work and ends the turn without polling,
+the model may not observe completion until another user input starts a turn.
+
+## Compaction Can Repeat Replies
+
+Long conversations can compact mid-turn. After compaction, the model may
+re-sample and repeat a prior response. Diagnose this by checking whether there
+was one inbound user message and a compaction marker between repeated assistant
+messages. Do not infer duplicate external delivery from repeated text alone.
+
+## Head-Of-Line Blocking
+
+Modern Dreamux dispatcher inbound should submit accepted messages without
+waiting for the previous turn to complete. If a later message waits behind a
+long turn, check whether the running version still uses a serial turn
+submission path or whether another gate rejected the later message.
+
+## App-Server Readiness
+
+Before business RPCs, the Codex app-server connection must complete the
+initialize handshake. A daemon that exits before binding its socket, fails the
+handshake, or cannot read workspace-local skills should be treated as a
+startup readiness failure, not as a chat delivery bug.

package/skills/team-dev-workflow/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: team-dev-workflow
+description: Coordinate multi-teammate software development workflows from a Dreamux dispatcher: adversarial MR/PR review, design negotiation, merge readiness checks, cleanup, and unblocking a teammate. Use for coordination cycles, not ordinary single-repo edits.
+---
+
+# Team Development Workflow
+
+Use this skill when the dispatcher is coordinating people or teammates around a
+software change. It is methodology layered on top of the `dispatcher` skill:
+`dispatcher` owns `tm` mechanics, while this skill owns review, design, merge,
+and unblock workflow.
+
+## Confirm Scope
+
+Use this skill when:
+
+- An MR/PR needs independent adversarial review before merge.
+- A design direction is unsettled and two independent proposals should be
+  compared.
+- A reviewed MR/PR is ready to merge and the teammate/worktree/branch need
+  cleanup.
+- A teammate is blocked by git state, missing context, wrong base, or missed
+  review comments.
+
+Do not use this skill for a normal implementation request such as "fix this
+bug" or "add this endpoint". Delegate that as one bounded repository task with
+the `dispatcher` skill.
+
+## Coordinator Posture
+
+- Verify facts from the target repo and platform before deciding.
+- Do not edit target repo code from the coordinator context. Delegate repo work
+  to a teammate in that repo.
+- Keep prompts short: intent, coordinates, hard constraints, and requested
+  artifact.
+- When the target repo is public, explicitly forbid internal domains, tokens,
+  private identifiers, and machine-local paths in commits, MR/PRs, and comments.
+- Prefer one accountable teammate per branch or review thread; reuse it for
+  follow-up rather than spawning duplicates.
+
+## Scenario Routing
+
+Read the matching reference before acting:
+
+| Intent | Reference |
+|---|---|
+| Review an MR/PR or issue proposal adversarially | `references/review-cycle.md` |
+| Compare two design directions before implementation | `references/design-negotiation.md` |
+| Merge a reviewed change and clean up state | `references/merge-and-cleanup.md` |
+| Dispatch or unblock a teammate | `references/dispatch-and-unblock.md` |
+
+## Cross-Cutting Rules
+
+- Reviewers must be independent from authors. Fresh context matters more than
+  a specific vendor or model family.
+- The author does not review or merge its own work.
+- CI and merge mode are target-repo policy. Read the repo/platform rules before
+  acting.
+- Same-account automation may be unable to submit a formal approval or change
+  request. In that case, use a top-level MR/PR comment with a clear verdict.
+- A clean review means no blocking findings on the current head, with required
+  checks green.

package/skills/team-dev-workflow/references/design-negotiation.md

@@ -0,0 +1,40 @@
+# Design Negotiation
+
+## Trigger
+
+A design or architecture direction is unsettled, expensive to reverse, and has
+more than one plausible path. This is for choosing an approach before
+implementation, not for reviewing a finished MR/PR.
+
+## Steps
+
+1. Write one neutral input brief for all participants:
+   - business need and observable facts
+   - relevant repo paths, scripts, and constraints
+   - candidate approaches as reference only, not a forced shortlist
+   - required output shape
+   - validation expectations
+2. Dispatch two independent teammates in parallel with the same input brief.
+   Ask each to write a v1 proposal to a file.
+3. Wait for both v1 files and verify they exist before continuing.
+4. Swap the v1 files. Ask each teammate to read the other proposal and write a
+   v2 that states:
+   - what it adopts
+   - what it rebuts
+   - its revised recommendation
+   - remaining ambiguity
+5. Hand both v2 proposals to the human intact. The coordinator does not
+   synthesize a third proposal or preselect a winner.
+
+## Closeout
+
+The human receives two revised, independently argued proposals. If both v2s
+converge, report the convergence as evidence; still keep both proposals
+available.
+
+## Anti-Patterns
+
+- Do not tell either teammate about the other in the v1 round.
+- Do not skip the v2 cross-read.
+- Do not add a coordinator-authored compromise.
+- Do not let a teammate spawn its own reviewers for this cycle.

package/skills/team-dev-workflow/references/dispatch-and-unblock.md

@@ -0,0 +1,39 @@
+# Dispatch And Unblock
+
+## Trigger
+
+You are assigning a teammate to a target repo, or a teammate is blocked by git
+state, wrong base, missing context, or missed platform comments.
+
+## Steps
+
+1. Verify the target repository path and intended base branch before spawning.
+2. Reuse an existing teammate when it already owns the branch or MR/PR.
+3. Ensure the teammate brief includes only:
+   - intent
+   - branch, issue, or MR/PR coordinates
+   - hard constraints
+   - requested artifact
+4. Tell the teammate to sync its working branch before editing when the task
+   will produce commits.
+5. Tell the teammate to pull all current issue or MR/PR comments before acting.
+   Repeat this on follow-up turns when comments may have changed.
+6. For public targets, include the no-internal-content constraint explicitly.
+7. Set a short queryable task subject if the teammate tooling supports it.
+
+## Unblocking
+
+If a teammate cannot write git metadata because of sandbox permissions, the
+coordinator may run the git operation from outside the sandbox: fetch, create a
+branch, commit staged teammate-authored content, push, or clean a worktree. Do
+only the git movement needed to unblock. The teammate still owns analysis and
+content changes.
+
+If a teammate started from the wrong base, stop it, remove the bad worktree,
+reset the main checkout to the intended base, and spawn again. Do not ask a
+teammate to build on a known-bad branch unless the human accepts that risk.
+
+## Closeout
+
+The teammate is on the intended base, has current platform comments, has a
+minimal brief, and is no longer blocked on git or missing context.

package/skills/team-dev-workflow/references/merge-and-cleanup.md

@@ -0,0 +1,37 @@
+# Merge And Cleanup
+
+## Trigger
+
+An MR/PR has a clean independent review on the current head and required checks
+are green.
+
+## Steps
+
+1. Re-read the current head SHA, required check status, draft state, and merge
+   state from the target platform.
+2. If the MR/PR is a draft, mark it ready before merging and confirm the head
+   SHA did not change.
+3. Scan the MR/PR title for bracketed CI-skip tokens. Remove or reword them
+   before squash merging so post-merge workflows are not skipped.
+4. Merge using the target repo's allowed mode and branch-deletion policy.
+5. Clean up the review cycle immediately:
+   - stop or close the reviewer teammate
+   - remove the review worktree
+   - delete the review branch if the cycle created one
+   - close the author teammate when its branch is no longer needed
+6. Record the final status in teammate history where the tooling supports it.
+
+## Closeout
+
+The change is on the target branch, required post-merge workflows are not
+accidentally skipped, and no temporary teammate, worktree, or review branch from
+the cycle remains active.
+
+## Exceptions
+
+| Case | Action |
+|---|---|
+| Merge state is unclear | Check required status checks specifically; optional jobs may be noisy. |
+| Same-account formal approval is missing | Use the clean review comment as the gate when platform policy allows owner/admin merge. |
+| Worktree removal refuses | Use the platform or git command intended for forced worktree cleanup; the branch already landed. |
+| Cleanup must be delayed | State what remains and when it will be removed. |

package/skills/team-dev-workflow/references/review-cycle.md

@@ -0,0 +1,46 @@
+# Review Cycle
+
+## Trigger
+
+An MR/PR or issue proposal needs adversarial review before it can merge or move
+to implementation.
+
+Skip this cycle only when the change is trivial, the human already accepted the
+risk, or an equally rigorous independent review already exists on the current
+head.
+
+## Steps
+
+1. Identify the author, branch, MR/PR or issue number, and current head SHA.
+2. Confirm the target repo and platform visibility. If public, include a
+   no-internal-content constraint in the reviewer brief.
+3. Confirm the change is ready to review: current branch pushed, required
+   checks known, and merge state readable.
+4. Reuse an existing reviewer teammate only if it already owns this exact
+   branch or review thread. Otherwise spawn one independent reviewer.
+5. Give the reviewer an adversarial brief:
+   - verify the author's claims instead of trusting them
+   - inspect the current diff against the target base
+   - run or justify focused verification
+   - report P0/P1/P2 findings with file and line references
+   - do not edit, commit, push, or merge
+6. Bucket the verdict:
+   - no P0/P1: eligible for merge once required checks are green
+   - P0/P1: send the author a fix brief quoting the findings exactly
+   - P2 only: merge with follow-up or ask for a cheap one-shot fix
+7. Recheck with the same reviewer after any force-push. Anchor the recheck on
+   the prior findings, new head SHA, and reported fixes.
+
+## Closeout
+
+The current head has an independent clean verdict, required checks are green,
+and any remaining non-blocking follow-up is explicit.
+
+## Exceptions
+
+| Case | Action |
+|---|---|
+| Base advanced | Ask the author to rebase or merge the target base, then re-run checks. |
+| Reviewer and author disagree | Escalate both positions to the human; do not silently pick a side. |
+| Formal review action is rejected | Post the same verdict as a top-level MR/PR comment. |
+| A reviewed line moved after force-push | Quote the problem statement so the reviewer can relocate it. |