@colin4k1024/tsp 2.5.0 → 2.5.2

package/README.md

@@ -15,6 +15,7 @@
 node scripts/build-platform-artifacts.js
 node scripts/install-apply.js --profile team --target claude
 node scripts/install-apply.js --profile full --target codex
+node scripts/install-apply.js --profile full --target opencode
 ```
 
 ## Who It's For / 适合谁
@@ -58,6 +59,72 @@ TSP 采用 **角色 + 技能 + Agent + 规则 + Hooks + Workflow 引擎** 六层
 
 安装工具链公开主线支持 **3 个 code agent**：Claude Code、Codex、OpenCode。其他历史 target 保留为隐藏兼容路径，不再作为公开 onboarding 主线。
 
+### OpenCode 集成
+
+TSP 为 OpenCode 提供了完整的适配支持，包括：
+
+- **AGENTS.md 自动生成**：包含完整的规则索引、角色索引、命令索引和技能索引
+- **Agent 系统适配**：所有角色和 specialist agents 都添加了 YAML front matter 配置
+- **Hooks 系统适配**：将 TSP hooks 转换为 OpenCode 插件格式
+- **配置文件生成**：自动生成 `opencode.json` 配置文件
+- **Skills 系统兼容**：所有 SKILL.md 文件都兼容 OpenCode 的 skill 工具
+
+#### OpenCode 安装
+
+```bash
+# 安装完整 OpenCode 配置
+node scripts/install-apply.js --profile full --target opencode
+
+# 或使用 npm 脚本
+npm run install:opencode
+```
+
+#### OpenCode 配置
+
+安装完成后，OpenCode 配置文件位于 `~/.config/opencode/opencode.json`，包含：
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "instructions": ["./AGENTS.md"],
+  "plugin": ["team-skills-platform"],
+  "permission": {
+    "edit": "allow",
+    "bash": "allow"
+  }
+}
+```
+
+#### OpenCode 使用
+
+1. **启动 OpenCode**：在项目目录运行 `opencode`
+2. **查看可用角色**：AGENTS.md 中包含所有角色的索引
+3. **切换角色**：使用 `@tech-lead`、`@frontend-engineer` 等方式切换角色
+4. **执行命令**：使用 `/team-intake`、`/team-plan` 等团队命令
+5. **加载技能**：使用 `skill` 工具加载 SKILL.md 文件
+
+#### OpenCode 目录结构
+
+```
+~/.config/opencode/
+├── AGENTS.md                    # 主配置文件（自动生成）
+├── opencode.json                # OpenCode 配置文件
+├── agents/                      # Agent 定义文件
+│   ├── tech-lead.md
+│   ├── product-manager.md
+│   └── ...
+├── command/                     # 命令文件
+│   ├── team-intake.md
+│   ├── team-plan.md
+│   └── ...
+└── plugins/                     # 插件目录
+    ├── team-skills-platform/    # TSP 插件
+    │   ├── skills/              # 技能文件
+    │   ├── rules/               # 规则文件
+    │   └── ...
+    └── tsp-hooks.js             # Hooks 插件
+```
+
 发布为 npm 包 `@colin4k1024/tsp`，内置 Rust bridge 预构建二进制，安装零依赖。
 
 ### 集成的开源框架与方法论

package/commands/dashboard.md

@@ -0,0 +1,105 @@
+# Dashboard Command
+
+Real-time progress visibility for goals, waves, and triage. Shows what the loop
+is doing, how much budget remains, and what needs human attention.
+
+## Usage
+
+`/dashboard`
+
+## Output
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  LOOP ENGINEERING DASHBOARD                                  ║
+╠══════════════════════════════════════════════════════════════╣
+║                                                              ║
+║  ACTIVE GOALS                                                ║
+║  ─────────────                                               ║
+║  ▶ [goal-a1b2c3d4] "Fix all failing tests"                  ║
+║    Iteration: 3/15 | Budget: $1.20/$10 | Time: 25m/2h       ║
+║    Last oracle: FAIL — 2 tests still failing in auth module  ║
+║    Next hint: Focus on token refresh mock                    ║
+║                                                              ║
+║  ⏸ [goal-e5f6g7h8] "Achieve 80% coverage"                   ║
+║    Iteration: 7/15 | Budget: $3.50/$10 | Paused             ║
+║                                                              ║
+║  HEARTBEAT                                                   ║
+║  ─────────────                                               ║
+║  Status: Running (interval: 30m)                             ║
+║  Last run: 12m ago — 2/3 passed, 1 goal created             ║
+║  Next run: 18m                                               ║
+║  Budget: $0.80/$2.00 per hour                                ║
+║                                                              ║
+║  TRIAGE INBOX                                                ║
+║  ─────────────                                               ║
+║  [3 pending] [1 high] [2 medium]                             ║
+║  • HIGH: sentry — 5 unresolved errors (2h ago)               ║
+║  • MED:  lint — 4 new lint errors (30m ago)                  ║
+║  • MED:  deps — 2 moderate vulnerabilities (1d ago)          ║
+║                                                              ║
+║  WAVE EXECUTION                                              ║
+║  ─────────────                                               ║
+║  (No active waves)                                           ║
+║                                                              ║
+║  REWORK TRACKING                                             ║
+║  ─────────────                                               ║
+║  Persistent trouble spots: 1                                 ║
+║  • src/auth/refresh.ts — 3 attempts, last: fail             ║
+║                                                              ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+## Data Sources
+
+The dashboard aggregates from:
+
+| Source | Location |
+|--------|----------|
+| Active goals | `~/.claude/goals/*.json` |
+| Heartbeat state | `~/.claude/heartbeat-last-run.json` |
+| Triage inbox | `~/.claude/triage/inbox.jsonl` |
+| Wave progress | Worker `status.md` files in coordination dirs |
+| Rework tracking | `~/.claude/rework-tracking.json` |
+| Cost tracking | Goal history `costDollars` fields |
+
+## Sections
+
+### Active Goals
+- State icon: ▶ (active), ⏸ (paused), ✓ (converged), ⚠ (escalated)
+- Progress: iteration/max, cost/budget, time/duration
+- Last oracle verdict and hint
+
+### Heartbeat
+- Running/stopped status
+- Last run results (passed/failed count)
+- Time to next run
+- Hourly budget usage
+
+### Triage Inbox
+- Pending count by severity
+- Top 3 most recent items with source and age
+- Action hint: "Use /triage to act on items"
+
+### Wave Execution
+- Active wave index / total waves
+- Per-worker status and progress estimate
+- Critical path and ETA (when workers report progress)
+
+### Rework Tracking
+- Persistent trouble spots (files with 3+ rework attempts)
+- Escalation recommendations
+
+## Integration
+
+- **`/goal status`**: Dashboard includes goal details
+- **`/heartbeat status`**: Dashboard includes heartbeat state
+- **`/triage stats`**: Dashboard includes inbox summary
+- **Wave execution**: Dashboard tracks parallel worker progress
+
+## Arguments
+
+$ARGUMENTS:
+- (none) — Show full dashboard
+- `--compact` — One-line summary per section
+- `--json` — Machine-readable output

package/commands/goal.md

@@ -0,0 +1,142 @@
+# Goal Command
+
+Define and run a goal-oriented autonomous loop with an external completion oracle.
+
+The goal primitive keeps iterating until verifiable stopping conditions are met,
+checked by a SEPARATE model (the oracle) to eliminate author-bias.
+
+## Usage
+
+`/goal <subcommand> [args]`
+
+## Subcommands
+
+### Create & Start
+
+```
+/goal "make all tests pass"
+/goal "achieve 80% coverage" --budget-iterations 10 --budget-dollars 5
+/goal "fix lint errors in src/" --checker sonnet
+```
+
+Creates a new goal, infers stopping conditions from the objective, and starts
+the maker-oracle loop immediately.
+
+**Auto-inferred stopping conditions:**
+- "tests pass" → `npm test` exit code 0
+- "coverage N%" → coverage report >= N
+- "lint clean" → `npm run lint` exit code 0
+- "build passes" → `npm run build` exit code 0
+- Custom: specify with `--condition "command"`
+
+### Status
+
+```
+/goal status
+/goal status <goalId>
+```
+
+Show active goals with current iteration, oracle verdict history, budget usage,
+and estimated remaining iterations.
+
+### Resume
+
+```
+/goal resume
+/goal resume <goalId>
+```
+
+Resume an active goal from a previous session. Reads state from
+`~/.claude/goals/{goalId}.json` and re-enters the maker loop with the oracle's
+last `nextHint` as guidance.
+
+### Pause
+
+```
+/goal pause
+/goal pause <goalId>
+```
+
+Pause without abandoning. State is persisted for later `/goal resume`.
+
+### List
+
+```
+/goal list
+```
+
+Show all goals (active, paused, converged, escalated) with summary stats.
+
+## The Maker-Oracle Loop
+
+```
+┌─────────────────────────────────────────────────────┐
+│  /goal "fix all tests"                              │
+│                                                     │
+│  ┌─────────┐    ┌─────────┐    ┌──────────┐       │
+│  │  MAKER  │───▶│ ORACLE  │───▶│ CONVERGE │       │
+│  │(primary)│    │(checker)│    │  or LOOP │       │
+│  └─────────┘    └─────────┘    └──────────┘       │
+│       ▲              │                   │          │
+│       │         verdict: fail            │          │
+│       │         + nextHint               │          │
+│       └──────────────┘                   │          │
+│                                          │          │
+│  Budget exhausted? ──▶ ESCALATE to triage│          │
+└─────────────────────────────────────────────────────┘
+```
+
+1. **Maker** (your primary model) executes one iteration toward the objective
+2. **Oracle** (different model, read-only) evaluates ALL stopping conditions
+3. If all pass → goal state becomes `converged`
+4. If any fail → oracle provides `nextHint` → maker iterates again
+5. If budget exhausted → goal becomes `escalated` → lands in triage inbox
+
+## Oracle Behavior
+
+The oracle:
+- Uses a DIFFERENT model than the maker (default: haiku for speed/cost)
+- Has READ-ONLY tool access (Read, Bash without writes)
+- Cannot modify code — only evaluate conditions
+- Returns structured verdict: `{converged, reasons[], nextHint}`
+- Is the reason you can walk away from a running loop
+
+## Budget Controls
+
+| Control | Default | Flag |
+|---------|---------|------|
+| Max iterations | 15 | `--budget-iterations N` |
+| Max duration | 2h | `--budget-duration Nh` |
+| Max cost | $10 | `--budget-dollars N` |
+| Checker model | haiku | `--checker model` |
+
+When ANY budget limit is hit, the goal escalates rather than continuing blindly.
+
+## State Persistence
+
+Goals persist to `~/.claude/goals/{goalId}.json` (follows goal.schema.json).
+
+- Active goals survive session restarts
+- SessionStart hook displays active goal reminder
+- Full iteration history is preserved for debugging
+
+## Integration
+
+- **Triage inbox:** Escalated goals create triage items (`/triage`)
+- **Heartbeat:** Heartbeat scans can auto-create goals (`/heartbeat`)
+- **Checkpoint:** Each iteration creates an implicit checkpoint
+- **Verification loop:** Oracle uses verification-loop patterns internally
+
+## Arguments
+
+$ARGUMENTS:
+- `<objective>` — Natural language goal description (quoted string)
+- `--budget-iterations N` — Max iterations (default 15)
+- `--budget-duration Nm|Nh` — Max wall time (default 2h)
+- `--budget-dollars N` — Max cost USD (default 10)
+- `--checker model` — Oracle model (default haiku)
+- `--condition "command"` — Additional stopping condition command
+- `status [goalId]` — Show goal status
+- `resume [goalId]` — Resume paused/interrupted goal
+- `pause [goalId]` — Pause active goal
+- `list` — List all goals

package/commands/heartbeat.md

@@ -0,0 +1,129 @@
+# Heartbeat Command
+
+Run discovery scans on a schedule to find issues, auto-create goals, or surface
+findings to the triage inbox. The heartbeat is what makes a loop an actual loop —
+not a one-shot run.
+
+## Usage
+
+`/heartbeat <subcommand> [args]`
+
+## Subcommands
+
+### Start
+
+```
+/heartbeat start
+/heartbeat start --interval 30m
+/heartbeat start --scan test-health,lint-drift
+```
+
+Registers a recurring CronCreate job that runs configured scans. Empty runs
+(all scans pass) archive themselves silently.
+
+### Stop
+
+```
+/heartbeat stop
+```
+
+Cancels the recurring heartbeat job via CronDelete.
+
+### Status
+
+```
+/heartbeat status
+```
+
+Shows:
+- Last scan time and results
+- Next scheduled run
+- Budget usage (cost per hour)
+- Active scan configurations
+
+### Run Once
+
+```
+/heartbeat run
+```
+
+Execute all configured scans immediately (one-shot, no scheduling).
+
+## Configuration
+
+Heartbeat reads from `.claude/heartbeat.yaml` in the project root:
+
+```yaml
+heartbeat:
+  interval: "30m"       # How often to tick (default: 30m)
+  scans:
+    - name: "test-health"
+      command: "npm test 2>&1 | tail -10"
+      onFailure: "auto-goal"    # auto-create a goal to fix it
+      description: "Run test suite"
+    - name: "lint-drift"
+      command: "npm run lint -- --quiet 2>&1 | wc -l"
+      threshold: 0               # numeric threshold: pass if output <= threshold
+      onFailure: "triage"        # surface to triage inbox for human
+      description: "Check lint errors"
+    - name: "dependency-audit"
+      command: "npm audit --production 2>&1 | grep -c 'vulnerabilities'"
+      threshold: 0
+      onFailure: "triage"
+      description: "Audit dependencies"
+    - name: "type-check"
+      command: "npx tsc --noEmit 2>&1; echo EXIT:$?"
+      onFailure: "auto-goal"
+      description: "TypeScript type checking"
+  budget:
+    maxDollarsPerHour: 2.0      # Pause heartbeat if cost exceeds this
+    pauseOnExhaust: true         # Pause vs stop on budget exhaust
+```
+
+## Scan Classification
+
+Each scan result is classified into an action:
+
+| Action | Behavior |
+|--------|----------|
+| `auto-goal` | Create a goal automatically from the failure (e.g., "fix 3 failing tests") |
+| `triage` | Append to triage inbox for human review |
+| `notify` | Desktop notification only (informational) |
+| `ignore` | Log silently, take no action |
+
+## Flow
+
+```
+┌────────────────────────────────────────────┐
+│  /heartbeat start                          │
+│                                            │
+│  CronCreate (every 30m)                    │
+│       │                                    │
+│       ▼                                    │
+│  Run all scans                             │
+│       │                                    │
+│  ┌────┼────────┬──────────┐               │
+│  ▼    ▼        ▼          ▼               │
+│ PASS  FAIL     FAIL       FAIL            │
+│  │    (goal)   (triage)   (notify)        │
+│  │      │        │          │             │
+│  ▼      ▼        ▼          ▼             │
+│ Skip  /goal    /triage    Desktop         │
+│       create   inbox      notification    │
+└────────────────────────────────────────────┘
+```
+
+## Integration
+
+- **`/goal`**: Heartbeat auto-creates goals from `auto-goal` scan failures
+- **`/triage`**: Heartbeat populates triage inbox from `triage` scan failures
+- **Budget**: Integrates with cost tracking; pauses if hourly budget exceeded
+- **Hooks**: Uses CronCreate/CronDelete for scheduling (7-day auto-expiry applies)
+
+## Arguments
+
+$ARGUMENTS:
+- `start [--interval Nm|Nh] [--scan name1,name2]` — Start recurring heartbeat
+- `stop` — Cancel heartbeat
+- `status` — Show heartbeat state
+- `run` — Execute scans once (no scheduling)

package/commands/triage.md

@@ -0,0 +1,108 @@
+# Triage Command
+
+View and act on findings that the loop could not auto-resolve. The triage inbox
+is where issues land when they need human judgment.
+
+## Usage
+
+`/triage [subcommand] [args]`
+
+## Subcommands
+
+### List (default)
+
+```
+/triage
+/triage list
+/triage list --source heartbeat
+/triage list --severity high
+```
+
+Show pending triage items with source, severity, and suggested actions.
+
+### Act
+
+```
+/triage act <id> goal      # Promote to a goal (auto-fix)
+/triage act <id> dismiss   # Dismiss (not actionable)
+/triage act <id> defer     # Defer to next session
+```
+
+Take action on a triage item. `goal` creates a goal from the finding.
+
+### Stats
+
+```
+/triage stats
+```
+
+Show inbox health metrics: pending count, sources breakdown, age distribution.
+
+### Clear
+
+```
+/triage clear --resolved
+/triage clear --older-than 7d
+```
+
+Remove resolved or stale items.
+
+## Triage Item Structure
+
+Each item in the inbox has:
+
+| Field | Description |
+|-------|-------------|
+| `id` | Unique identifier (e.g., `triage-lq4x8`) |
+| `source` | Where it came from (e.g., `heartbeat:lint-drift`, `goal:escalated`) |
+| `severity` | `high`, `medium`, `low` |
+| `summary` | One-line description |
+| `detail` | Full scan output or error context |
+| `suggestedActions` | What the system recommends |
+| `createdAt` | When the item was created |
+| `status` | `pending`, `acted`, `dismissed`, `deferred` |
+
+## Sources
+
+Items enter triage from:
+
+1. **Heartbeat scans** with `onFailure: "triage"` classification
+2. **Escalated goals** that exhausted their budget without converging
+3. **Manual** items added by the user
+4. **Connectors** (MCP) that discover issues from external tools
+
+## Flow
+
+```
+┌──────────────┐     ┌─────────┐     ┌──────────────┐
+│  Heartbeat   │────▶│ TRIAGE  │────▶│  /triage act │
+│  Goal escape │     │  INBOX  │     │  goal/dismiss│
+│  Connectors  │     │ (.jsonl)│     │  /defer      │
+└──────────────┘     └─────────┘     └──────────────┘
+                          │
+                          ▼
+                    Statusline: [Triage: N]
+```
+
+## Storage
+
+Inbox is stored as newline-delimited JSON at `~/.claude/triage/inbox.jsonl`.
+This format is:
+- Append-only (safe for concurrent writes)
+- Human-readable (one JSON object per line)
+- Easy to grep and filter
+
+## Integration
+
+- **`/heartbeat`**: Primary source of triage items
+- **`/goal`**: Escalated goals create triage items; triage items can become goals
+- **Statusline**: Hook shows `[Triage: N]` count when items are pending
+- **Session start**: Active triage items mentioned in session context
+
+## Arguments
+
+$ARGUMENTS:
+- `list [--source name] [--severity level]` — List pending items (default)
+- `act <id> goal|dismiss|defer` — Take action on an item
+- `stats` — Show inbox metrics
+- `clear --resolved|--older-than Nd` — Clean up resolved/stale items

package/hooks/README.md

@@ -26,7 +26,7 @@ User request → Claude picks a tool → PreToolUse hook runs → Tool executes
 | **Git push reminder** | `Bash` | Reminds to review changes before `git push` | 0 (warns) |
 | **Pre-commit quality check** | `Bash` | Runs quality checks before `git commit`: lints staged files, validates commit message format when provided via `-m/--message`, detects console.log/debugger/secrets | 2 (blocks critical) / 0 (warns) |
 | **Doc file warning** | `Write` | Warns about non-standard `.md`/`.txt` files (allows README, CLAUDE, CONTRIBUTING, CHANGELOG, LICENSE, SKILL, docs/, skills/); cross-platform path handling | 0 (warns) |
-| **Strategic compact** | `Edit\|Write` | Suggests manual `/compact` at logical intervals (every ~50 tool calls) | 0 (warns) |
+| **Strategic compact** | `*` | Suggests `/compact` when context usage crosses 70/85/95% thresholds, using Claude context-window metrics when available | 0 (warns) |
 | **InsAIts security monitor (opt-in)** | `Bash\|Write\|Edit\|MultiEdit` | Optional security scan for high-signal tool inputs. Disabled unless `ECC_ENABLE_INSAITS=1`. Blocks on critical findings, warns on non-critical, and writes audit log to `.insaits_audit_session.jsonl`. JS wrapper is the canonical hook entry; the Python monitor is an explicit third-party SDK exception. Requires `pip install insa-its`. [Details](../scripts/hooks/insaits-security-monitor.py) | 2 (blocks critical) / 0 (warns) |
 
 ### PostToolUse Hooks

package/hooks/harness-context-monitor.js

@@ -1,4 +1,8 @@
 #!/usr/bin/env node
+// DEPRECATED: This hook's functionality has been merged into suggest-compact.js.
+// The strategic-compact hook now covers all thresholds (65/70/85/95%).
+// This file is retained for backward compatibility but is no longer registered in hooks.json.
+//
 // harness-context-monitor.js — PostToolUse hook (all tools)
 // Reads context metrics from the bridge file written by harness-statusline.js
 // and injects advisory warnings into agent context when usage is high.

package/hooks/hooks.json

@@ -69,15 +69,27 @@
         "id": "pre:write:doc-file-warning"
       },
       {
-        "matcher": "Edit|Write",
+        "matcher": "*",
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/run-with-flags.js\" \"pre:edit-write:suggest-compact\" \"scripts/hooks/suggest-compact.js\" \"standard,strict\""
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/harness-statusline.js\""
           }
         ],
-        "description": "Suggest manual compaction at logical intervals",
-        "id": "pre:edit-write:suggest-compact"
+        "description": "Display current role and context usage statusline (must run before strategic-compact to write bridge file)",
+        "id": "pre:all:harness-statusline"
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/run-with-flags.js\" \"pre:all:strategic-compact\" \"scripts/hooks/suggest-compact.js\" \"standard,strict\"",
+            "timeout": 10
+          }
+        ],
+        "description": "Suggest strategic context compaction when context usage crosses 65/70/85/95% thresholds",
+        "id": "pre:all:strategic-compact"
       },
       {
         "matcher": "*",
@@ -151,28 +163,6 @@
         "description": "Check MCP server health before MCP tool execution and block unhealthy MCP calls",
         "id": "pre:mcp-health-check"
       },
-      {
-        "matcher": "*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/harness-statusline.js\""
-          }
-        ],
-        "description": "Display current role and context usage statusline",
-        "id": "pre:all:harness-statusline"
-      },
-      {
-        "matcher": "*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/harness-context-monitor.js\""
-          }
-        ],
-        "description": "Monitor context budget, warn at 35%/25% thresholds",
-        "id": "pre:all:harness-context-monitor"
-      },
       {
         "matcher": "Bash",
         "hooks": [
@@ -233,6 +223,17 @@
         "description": "Load previous context and detect package manager on new session",
         "id": "session:start"
       },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/session-start-goal-resume.js\""
+          }
+        ],
+        "description": "Check for active goals from previous sessions and inject resume reminder",
+        "id": "session:goal-resume"
+      },
       {
         "matcher": "*",
         "hooks": [