npm - @mstar-harness/opencode - Versions diffs - 0.7.9 → 1.0.1 - Mend

@mstar-harness/opencode 0.7.9 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (39) hide show

package/harness-skills/mstar-sdd/references/file-handoffs.md ADDED Viewed

@@ -0,0 +1,76 @@
+# File handoffs (Morning Star SDD)
+PM and subagents move artifacts as **files**, not pasted text. Pasted content stays in PM context for every later turn.
+## Before implementer dispatch
+1. `export SDD_DIR=$(skills/mstar-sdd/scripts/sdd-workspace <plan-id>)`
+2. `skills/mstar-sdd/scripts/task-brief <plan-file> <N> "$SDD_DIR/task-N-brief.md"`
+3. Record `BASE_SHA` (`git rev-parse HEAD` before dispatch).
+4. Dispatch implementer with:
+   - One line scene-setting (where task fits)
+   - Brief path: read first — verbatim requirements
+   - Interfaces / decisions brief cannot know
+   - Report path: `$SDD_DIR/task-N-report.md`
+   - `Model tier` → host-specific model (required)
+   - **`SDD implementer session`**: `fresh` (new subagent) or `sticky` (resume — see **`sticky-implementer-session.md`**)
+## Implementer report file
+Implementer writes full report to `task-N-report.md`. Return to PM only:
+- Status: `DONE` | `DONE_WITH_CONCERNS` | `NEEDS_CONTEXT` | `BLOCKED`
+- Commits (SHAs)
+- One-line test summary
+- Concerns (if any)
+## After implementer DONE
+1. `HEAD_SHA=$(git rev-parse HEAD)`
+2. `skills/mstar-sdd/scripts/review-package "$BASE_SHA" "$HEAD_SHA" "$SDD_DIR/review-....diff"`
+3. Dispatch task reviewer with: brief path, report path, diff path, Global Constraints (verbatim from plan).
+**Never use `HEAD~1` as BASE** — multi-commit tasks truncate.
+## Fix loop
+Fix subagent appends to same `task-N-report.md` with test evidence:
+- Covering test file(s)
+- Command run
+- Output (pristine — warnings are findings)
+Re-dispatch reviewer only when all three are present.
+## Progress ledger
+On clean task review, append to `$SDD_DIR/progress.md`:
+```text
+Task N: complete (<base>..<head>, review clean)
+```
+Minor findings: append under `## Minor (for plan QC)` in same file.
+## Plan-level QC package
+After all tasks:
+```bash
+MERGE_BASE=$(git merge-base <target-branch> HEAD)
+skills/mstar-sdd/scripts/review-package "$MERGE_BASE" HEAD "$SDD_DIR/branch-review-....diff"
+```
+Pass **branch** diff path to QC dispatch — not task-level diffs.
+## PM context hygiene
+Do not paste:
+- Full plan text
+- Prior task summaries ("state after Tasks 1-3")
+- Full diff content
+Fresh subagent gets: brief + interfaces + constraints + file paths only.
+**Sticky implementer** (task 2+): resume same session; read new brief path + `progress.md` — do not re-paste prior task summaries. PM updates `implementer-session.json`.

package/harness-skills/mstar-sdd/references/implementer-continuation-prompt.md ADDED Viewed

@@ -0,0 +1,44 @@
+# Implementer continuation prompt (sticky session)
+Use when PM continues **`SDD implementer session: sticky`** for Task N>1. Host: **resume** same agent when supported (`sticky-implementer-session.md`).
+```
+Task / subagent:
+  resume: [HOST_AGENT_ID from implementer-session.json]
+  description: "SDD continue Task N: <name>"
+  model: [same tier as session start unless PM upgrades]
+  prompt: |
+    <SUBAGENT-STOP> Skip PM orchestration skills. You are a leaf implementer continuing a sticky SDD session.</SUBAGENT-STOP>
+    Continue as the same implementer on plan <plan-id>, Working branch: <branch>.
+    ## Completed (do not redo)
+    Read: [SDD_DIR]/progress.md and [SDD_DIR]/implementer-session.json
+    ## This task
+    Task N: <name>
+    Read first — your spec (verbatim): [BRIEF_FILE]
+    ## Context not in the brief
+    [Interfaces from earlier tasks only if not already in your session]
+    ## Report file
+    Write your full report to: [REPORT_FILE]
+    ## Your job
+    1. Implement exactly what this brief specifies (prior tasks are done)
+    2. Run tests; commit on Working branch
+    3. Write report file; return short summary only
+    ## When stuck
+    Report BLOCKED or NEEDS_CONTEXT — PM may reset session to fresh.
+```
+First task on a plan uses **`implementer-prompt.md`** (not this file).

package/harness-skills/mstar-sdd/references/implementer-prompt.md ADDED Viewed

@@ -0,0 +1,55 @@
+# Implementer subagent prompt template
+Use when PM dispatches an SDD implementer (`mstar-sdd`) — **first task** or **`SDD implementer session: fresh`**.
+For **sticky** continuation (task 2+), use **`implementer-continuation-prompt.md`** instead.
+```
+Task / subagent:
+  description: "SDD implement Task N: <name>"
+  model: [REQUIRED — per Model tier in Assignment and mstar-sdd SKILL]
+  prompt: |
+    <SUBAGENT-STOP> Skip PM orchestration skills. You are a leaf implementer.</SUBAGENT-STOP>
+    You are implementing Task N: <name>
+    ## Scene
+    [One line: where this task fits in the plan]
+    ## Requirements
+    Read first — this is your spec (verbatim values): [BRIEF_FILE]
+    ## Context not in the brief
+    [Interfaces from earlier tasks, PM resolutions]
+    ## Report file
+    Write your full report to: [REPORT_FILE]
+    ## Before you begin
+    Ask questions now about requirements, approach, or dependencies.
+    ## Your job
+    1. Implement exactly what the brief specifies
+    2. Run tests (TDD if brief requires)
+    3. Commit on Working branch
+    4. Self-review
+    5. Write report file; return short summary only
+    ## When stuck
+    Report BLOCKED or NEEDS_CONTEXT — never guess.
+    ## Report format (in file)
+    - Status: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
+    - Implemented / attempted
+    - Tests: command, output, red/green evidence if TDD
+    - Files changed
+    - Self-review notes
+```

package/harness-skills/mstar-sdd/references/sticky-implementer-session.md ADDED Viewed

@@ -0,0 +1,103 @@
+# Sticky implementer session (SDD token optimization)
+Reuse the **same implementer subagent** across multiple tasks in one plan when tasks are tightly coupled, same `Execute as` role, and same `Working branch`. **L2 task reviewers stay fresh per task** — do not sticky reviewers.
+SSOT for mode selection and host resume → this file. Per-task artifacts → **`file-handoffs.md`**.
+## When to use
+| `SDD implementer session` | Use |
+|---------------------------|-----|
+| **`fresh`** (default) | Independent tasks, module boundaries, different dev tracks, or first task on a plan |
+| **`sticky`** | Same `fullstack-dev` (or same role id), sequential tasks on one branch, strong file/context continuity (e.g. T3+T4 daemon stderr + DB reset) |
+**Prefer `sticky`** on iteration-drive Phase 2 when PM will dispatch many tasks to the same dev on one plan feature branch.
+## Assignment fields (implement dispatch)
+```markdown
+**Execution mode**: sdd
+**SDD implementer session**: sticky | fresh
+**SDD dir**: `{HARNESS_DIR}/sdd/<plan-id>/`
+**Model tier**: standard
+**Execute as**: fullstack-dev
+**Working branch**: <branch>
+**Covers task**: N | N–M   # single task id for this dispatch turn
+```
+- **Task 1** (or first task after `fresh` reset): `SDD implementer session: fresh` or `sticky` (starts sticky ledger).
+- **Task 2+** with sticky: `SDD implementer session: sticky` + host **resume** (Cursor) or continuation prompt (fallback).
+## Session ledger: `implementer-session.json`
+PM writes/updates at `{SDD_DIR}/implementer-session.json` when starting or continuing sticky mode:
+```json
+{
+  "plan_id": "<plan-id>",
+  "execute_as": "fullstack-dev",
+  "session_mode": "sticky",
+  "host": "cursor",
+  "host_agent_id": "<agent-id from first Task return — required for resume>",
+  "working_branch": "feature/...",
+  "started_task": 1,
+  "last_task": 1,
+  "started_at": "2026-07-07T00:00:00Z"
+}
+```
+After each completed task review, PM sets `last_task` to N. **Do not** resume if `host_agent_id` is missing — fall back to `fresh` for that task.
+## Per-task loop (sticky implementer)
+Same as default SDD for artifacts and L2 review; only implementer dispatch differs:
+1. `task-brief` → `{SDD_DIR}/task-N-brief.md`
+2. Record `BASE_SHA`
+3. **Implementer dispatch**
+   - **First task** (`fresh` or sticky start): normal Task/subagent invoke → save `host_agent_id` to ledger
+   - **Next tasks** (`sticky`): host **resume** with same `host_agent_id` + continuation prompt (`implementer-prompt.md` § Continuation)
+4. On `DONE` → `review-package` → **fresh** task reviewer (never resume reviewer)
+5. Append `progress.md`; update ledger `last_task`
+6. Next task
+**Still required per task:** commit, `task-N-report.md`, task-level diff, task reviewer, `progress.md` line.
+## When to reset to `fresh`
+Start a **new** implementer session (`session_mode: fresh` or new ledger) when any:
+- `BLOCKED` / `NEEDS_CONTEXT` not resolved in one continuation turn
+- `Execute as` role changes (`fullstack-dev` → `fullstack-dev-2`)
+- `Working branch` changes
+- Host does not support resume (OpenCode without resume → use **micro-batch** or `fresh`)
+- Context clearly degraded (implementer confuses prior tasks) — PM judgment
+- Switching from another dev track mid-plan
+Delete or archive `implementer-session.json` when resetting.
+## Micro-batch fallback (no host resume)
+When resume is unavailable, PM may dispatch **one** implementer for **2–3** tightly coupled tasks:
+- Prompt lists `task-N-brief.md` … `task-M-brief.md` and matching report paths only
+- Implementer completes tasks **in order** in one session
+- PM still runs **per-task** `review-package` + **fresh** task reviewer after each task (or after batch if PM documents per-task SHAs in Assignment)
+Max **3** tasks per micro-batch without user override. See `project-manager.md` batch sizing.
+## Host mapping
+| Host | Sticky implementer |
+|------|-------------------|
+| **Cursor** | `Task` with `resume: <host_agent_id>` — **`mstar-host/references/cursor.md`** § SDD sticky |
+| **OpenCode** | Resume only if task tool supports it; else micro-batch or `fresh` per task |
+| **Codex** | Thread resume only when callable multi-agent tool documents agent id; else micro-batch or `fresh` |
+## PM NEVER (sticky)
+- Resume task **reviewer** sessions — reviewers stay fresh per task
+- Parallel sticky implementers on the same branch
+- Resume without updating `implementer-session.json` / `progress.md`
+- Skip per-task review because implementer "remembers" prior tasks
+- Paste full plan into continuation prompt — only new brief path + report path

package/harness-skills/mstar-sdd/references/task-reviewer-prompt.md ADDED Viewed

@@ -0,0 +1,51 @@
+# Task reviewer subagent prompt template
+One reviewer per task: spec compliance + code quality (`mstar-sdd`).
+```
+Task / subagent:
+  description: "SDD review Task N (spec + quality)"
+  model: [REQUIRED — standard tier default; capable if diff is large/subtle]
+  prompt: |
+    <SUBAGENT-STOP> Skip PM orchestration. Read-only review.</SUBAGENT-STOP>
+    Review one task implementation: spec compliance first, then quality.
+    Task-scoped gate — plan-level QC comes later on the whole branch.
+    ## What was requested
+    Brief: [BRIEF_FILE]
+    Global constraints (verbatim):
+    [GLOBAL_CONSTRAINTS]
+    ## Implementer report
+    [REPORT_FILE] — treat claims as unverified until checked against diff.
+    ## Diff
+    Base: [BASE_SHA]
+    Head: [HEAD_SHA]
+    Diff file: [DIFF_FILE]
+    Read the diff file once. Do not re-run git. Do not mutate checkout.
+    Do not re-run full test suite — trust implementer evidence unless a
+    specific doubt needs one focused test.
+    ## Output
+    ### Spec Compliance
+    - ✅ Spec compliant | ❌ Issues found (file:line)
+    - ⚠️ Cannot verify from diff: [items for PM to check]
+    ### Strengths
+    ### Issues
+    #### Critical | Important | Minor
+    ### Assessment
+    **Task quality:** Approved | Needs fixes
+```
+Re-review after fixes covers both verdicts. PM resolves all ⚠️ items before marking task complete.

package/harness-skills/mstar-sdd/scripts/review-package ADDED Viewed

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# Write commit list, stat summary, and diff to a file for reviewer Read.
+# Usage: review-package BASE HEAD [OUTFILE]
+# Never use HEAD~1 as BASE for multi-commit tasks.
+set -euo pipefail
+if [ $# -lt 2 ] || [ $# -gt 3 ]; then
+  echo "usage: review-package BASE HEAD [OUTFILE]" >&2
+  exit 2
+fi
+base=$1
+head=$2
+git rev-parse --verify --quiet "$base" >/dev/null || { echo "bad BASE: $base" >&2; exit 2; }
+git rev-parse --verify --quiet "$head" >/dev/null || { echo "bad HEAD: $head" >&2; exit 2; }
+if [ $# -eq 3 ]; then
+  out=$3
+else
+  if [ -z "${SDD_DIR:-}" ]; then
+    echo "review-package: set SDD_DIR or pass OUTFILE" >&2
+    exit 2
+  fi
+  mkdir -p "$SDD_DIR"
+  out="$SDD_DIR/review-$(git rev-parse --short "$base")..$(git rev-parse --short "$head").diff"
+fi
+{
+  echo "# Review package: ${base}..${head}"
+  echo
+  echo "## Commits"
+  git log --oneline "${base}..${head}"
+  echo
+  echo "## Files changed"
+  git diff --stat "${base}..${head}"
+  echo
+  echo "## Diff"
+  git diff -U10 "${base}..${head}"
+} > "$out"
+commits=$(git rev-list --count "${base}..${head}" 2>/dev/null || echo 0)
+echo "wrote ${out}: ${commits} commit(s), $(wc -c < "$out" | tr -d ' ') bytes"

package/harness-skills/mstar-sdd/scripts/sdd-workspace ADDED Viewed

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# Resolve and ensure {SDD_DIR} for Morning Star SDD artifacts.
+# Usage: sdd-workspace PLAN_ID
+# Prints absolute path to {HARNESS_DIR}/sdd/<plan-id>/ (or legacy .agents/sdd/).
+set -euo pipefail
+if [ $# -ne 1 ]; then
+  echo "usage: sdd-workspace PLAN_ID" >&2
+  exit 2
+fi
+plan_id=$1
+root=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+if [ -d "$root/.mstar" ]; then
+  harness="$root/.mstar"
+elif [ -d "$root/.agents" ]; then
+  harness="$root/.agents"
+else
+  harness="$root/.mstar"
+fi
+dir="$harness/sdd/$plan_id"
+mkdir -p "$dir"
+printf '*\n' > "$dir/.gitignore"
+cd "$dir" && pwd

package/harness-skills/mstar-sdd/scripts/task-brief ADDED Viewed

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# Extract one task's full text from a plan into a file for the implementer.
+# Usage: task-brief PLAN_FILE TASK_NUMBER [OUTFILE]
+# Default OUTFILE: {SDD_DIR}/task-N-brief.md (SDD_DIR from env or second arg via sdd-workspace)
+set -euo pipefail
+if [ $# -lt 2 ] || [ $# -gt 3 ]; then
+  echo "usage: task-brief PLAN_FILE TASK_NUMBER [OUTFILE]" >&2
+  exit 2
+fi
+plan=$1
+n=$2
+[ -f "$plan" ] || { echo "no such plan file: $plan" >&2; exit 2; }
+if [ $# -eq 3 ]; then
+  out=$3
+else
+  if [ -z "${SDD_DIR:-}" ]; then
+    echo "task-brief: set SDD_DIR or pass OUTFILE (run sdd-workspace PLAN_ID first)" >&2
+    exit 2
+  fi
+  mkdir -p "$SDD_DIR"
+  out="$SDD_DIR/task-${n}-brief.md"
+fi
+awk -v n="$n" '
+  /^```/ { infence = !infence }
+  !infence && /^#+[ \t]+Task[ \t]+[0-9]+/ {
+    intask = ($0 ~ ("^#+[ \t]+Task[ \t]+" n "([^0-9]|$)"))
+  }
+  intask { print }
+' "$plan" > "$out"
+if [ ! -s "$out" ]; then
+  echo "task ${n} not found in ${plan} (no heading matching Task ${n})" >&2
+  exit 3
+fi
+echo "wrote ${out}: $(wc -l < "$out" | tr -d ' ') lines"

package/harness-skills/pm/SKILL.md CHANGED Viewed

@@ -1,58 +1,34 @@
 ---
 name: pm
-description: "Morning Star PM orchestration entry. On Cursor/Codex, /pm launches project-manager. On OpenCode, switch to project-manager when the active agent is not PM. The autonomous Execute flow (per-plan dispatch, iteration management, compound) lives in mstar-iteration — this skill covers PM role identity, host entry, dispatch-first rules, and host-specific concerns."
+description: "PM entry shim — force project-manager orchestration when user invokes /pm or this skill (Codex and Cursor). General per-plan PM work: this skill + project-manager.md. Formal iteration lifecycle on Cursor/OpenCode: commands (iteration-start, iteration-drive, mstar-bootstrap). Boot, routing, dispatch SSOT → mstar-roles/references/project-manager.md and topic mstar-* skills — not here."
 ---
-# PM — Morning Star orchestration entry
+# PM (entry shim)
-**PM role launcher and host adapter.** Iteration flow (start → Execute → close) → **`mstar-iteration`** (canonical SSOT). This skill handles: PM role identity per host, boot order, dispatch-first rules, Cursor Plan mode.
+**Thin launcher only.** Boot lists, iteration phases, Assignment templates, and SDD loops are **not** maintained in this file.
-## Host entry (read `mstar-host` first)
+## Host entry
-| Host | Entry | PM role |
-| --- | --- | --- |
-| **Cursor / Codex** | User invokes **`/pm`** (or explicit "run as PM") | Force **`project-manager`** for the session |
-| **OpenCode** | User may already be on a configured agent | **If active role ≠ `project-manager`**: operate **only** as PM — load `mstar-roles` → `references/project-manager.md`; do **not** stay in dev/QC/architect voice for orchestration. Host invoke: task tool **`subagent`** matching Assignment `Execute as` (see `mstar-host` → `opencode.md`); Assignment body uses **plain role ids** |
+| Host | Use |
+|------|-----|
+| **Codex** | **`/pm`** or this skill → **`project-manager`** for the session |
+| **Cursor** | **`/pm`** or this skill → general PM orchestration (single-plan, hotfix, QC waves, dispatch) **without** starting an iteration. Formal iteration → **`commands/`** below |
+| **OpenCode** | Same as Cursor when no command: **`project-manager`** via `mstar-roles` → `references/project-manager.md` |
-Detect host → Read `mstar-host` → `references/cursor.md` | `opencode.md` | `codex.md`.
+**Iteration commands** (optional; carry their own Boot): `iteration-start`, `iteration-drive`, `mstar-bootstrap` — use when running Phase 1–5 iteration lifecycle, not required for ordinary PM work.
-## Boot (order)
+Detect host → **`mstar-host`** → `references/codex.md` | `cursor.md` | `opencode.md`.
-1. `mstar-harness-core`
-2. `mstar-roles` → `references/project-manager.md`
-3. Before first **implement** dispatch: `mstar-dispatch-gates` + host reference
-4. Before **QC**: `mstar-review-qc`
-5. **Iteration flow** (start / Execute / close): **`mstar-iteration`** — canonical SSOT for per-plan dispatch loop, integration branch, compound round. Do **not** re-describe the flow in this skill.
-6. **On demand:** `mstar-phase-gates`, `mstar-plan-conventions`, `mstar-plan-artifacts`, `mstar-branch-worktree`, `mstar-skill-authoring` for skill work
-Prepare/Execute gates, routing, Assignment templates, Task Board, QC tri-review, residuals, compound → topic skills + PM references (not repeated here).
-## Dispatch-first (`implement`)
-| Do | Don't |
-| --- | --- |
-| **Loop:** `## Assignment` → invoke → Completion Report v2 → report-to-status → next batch | Parent **Write/Edit/Shell** on product code to "move faster" |
-| **1 Assignment ⇒ 1 invoke** when host supports Task/subagent (`mstar-dispatch-gates`) | Assignment markdown only, no matching invoke |
-| Put merge/branch/handoff from **this thread** into Assignment | Skip subagent because context is "already here" |
-- **NEVER** implement while staying PM — QC 3× comes later; **implement still delegates** dev roles.
-- **Delegate scope / PM whitelist:** `mstar-roles` → PM Execution Boundary.
+## Read next (in order)
-**Exceptions:** user explicitly asks PM thread to implement; hotfix per `mstar-phase-gates`.
-## Iteration
-Formal iteration（Phase 1 → Phase 2 → Phase 3）→ **`mstar-iteration`** only. Do not duplicate phase gates, branch policy, or close checklists here.
-## Cursor Plan mode
-CreatePlan / SwitchMode: Read **`mstar-host/references/cursor-plan-mode-bridge.md`**. Bootstrap todos `harness-init` → `spec-register` → `mirror-plan` before implement todos; evidence on **subagent** work.
+1. `mstar-harness-core`
+2. `mstar-roles` → **`references/project-manager.md`** — required reading list, routing, dispatch-first, iteration branch policy
+3. Topic skills **on demand** per that file and the active workflow (`mstar-dispatch-gates`, `mstar-iteration`, `mstar-sdd`, `mstar-review-qc`, …)
-## Conflict order
+## Three rules (everything else is a pointer)
-1. User explicit instructions
-2. Project `AGENTS.md` / `CLAUDE.md`
-3. `mstar-harness-core` + runtime `mstar-*`
-4. This skill
+1. **Delegate** — PM does not implement, QC, or QA in-thread (`project-manager.md` Execution Boundary; hotfix → `mstar-phase-gates`).
+2. **Dispatch** — when host has invoke/Task tools: **1 Assignment ⇒ 1 invoke** (`mstar-dispatch-gates`). Markdown alone is not dispatch.
+3. **SSOT** — iteration lifecycle → **`mstar-iteration`** (or **`commands/`** on Cursor/OpenCode); Cursor Plan mode → **`mstar-host/references/cursor-plan-mode-bridge.md`**.
-**Dispatch-first + `mstar-dispatch-gates`** win over "fast parent agent" unless user overrides.
+Conflict: user instructions → project `AGENTS.md` / `CLAUDE.md` → `mstar-harness-core` → this file.

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@mstar-harness/opencode",
-  "version": "0.7.9",
+  "version": "1.0.1",
   "description": "Morning Star harness OpenCode plugin (skills bootstrap and agent loading).",
   "license": "MIT",
   "repository": {