work-ally 0.2.0-alpha.1

package/internal/modules/runtime/supervisor.sh

@@ -0,0 +1,216 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+# shellcheck disable=SC1091
+. "$SCRIPT_DIR/../../lib/common.sh"
+work_ally_init_context
+if [ -z "${WORK_ALLY_ASSISTANT_NAME:-}" ]; then
+  WORK_ALLY_ASSISTANT_NAME=$(work_ally_resolve_assistant_name_from_args "$@" || true)
+fi
+if [ -n "${WORK_ALLY_ASSISTANT_NAME:-}" ]; then
+  work_ally_sync_workspace_root_from_assistant "$WORK_ALLY_ASSISTANT_NAME"
+  work_ally_hydrate_assistant_context "$WORK_ALLY_ASSISTANT_NAME"
+fi
+work_ally_ensure_state_dirs
+work_ally_load_env
+work_ally_load_assistant_state || true
+
+CHANNEL_IMPL="${WORK_ALLY_CHANNEL_IMPL:-feishu}"
+RUNTIME_MODE="${WORK_ALLY_RUNTIME_MODE:-codex}"
+ASSISTANT_GIT_REMOTE="${WORK_ALLY_ASSISTANT_GIT_REMOTE:-}"
+SUPERVISOR_PID_FILE=$(work_ally_pid_file supervisor)
+BRIDGE_PID_FILE=$(work_ally_pid_file bridge)
+AUTOSAVE_PID_FILE=$(work_ally_pid_file assistant-autosave)
+BRIDGE_LOG=$(work_ally_log_file_for bridge)
+AUTOSAVE_LOG=$(work_ally_log_file_for assistant-autosave)
+POLL_INTERVAL=5
+SHUTTING_DOWN=0
+BRIDGE_OUTAGE_NOTIFIED=0
+
+send_notice_if_possible() {
+  local mode="$1"
+  shift || true
+  if [ "$CHANNEL_IMPL" != "feishu" ]; then
+    return 0
+  fi
+  if [ -z "${FEISHU_APP_ID:-}" ] || [ -z "${FEISHU_APP_SECRET:-}" ]; then
+    return 0
+  fi
+  node "$WORK_ALLY_IMPLEMENTATION_DIR/bridge/src/system-notify.ts" "$mode" "$@" >/dev/null 2>&1 || true
+}
+
+write_supervisor_health() {
+  local status="${1:-running}"
+  work_ally_write_health supervisor "$status" "{\"assistant\": \"$WORK_ALLY_ASSISTANT_NAME\", \"pid\": $$, \"workspaceRoot\": \"$WORK_ALLY_WORKSPACE_ROOT\", \"runtime\": \"$RUNTIME_MODE\", \"channel\": \"$CHANNEL_IMPL\"}"
+}
+
+stop_bridge_processes_keep_locks() {
+  {
+    work_ally_read_pid "$BRIDGE_PID_FILE" || true
+    work_ally_list_bridge_pids || true
+  } | awk 'NF && !seen[$0]++ { print $0 }' | while IFS= read -r pid; do
+      [ -n "$pid" ] || continue
+      if work_ally_is_pid_alive "$pid"; then
+        work_ally_terminate_pid "$pid"
+      fi
+    done
+
+  rm -f "$BRIDGE_PID_FILE"
+  work_ally_write_health bridge stopped '{}'
+}
+
+stop_autosave_process() {
+  local pid
+  pid=$(work_ally_read_pid "$AUTOSAVE_PID_FILE" || true)
+  if [ -n "$pid" ] && work_ally_is_pid_alive "$pid"; then
+    work_ally_terminate_pid "$pid"
+  fi
+  rm -f "$AUTOSAVE_PID_FILE"
+  work_ally_write_health assistant-autosave stopped '{}'
+}
+
+cleanup() {
+  SHUTTING_DOWN=1
+  stop_autosave_process
+  stop_bridge_processes_keep_locks
+  work_ally_release_channel_lock "$$"
+  work_ally_release_assistant_lock "$WORK_ALLY_ASSISTANT_NAME" "$$"
+  rm -f "$SUPERVISOR_PID_FILE"
+  write_supervisor_health stopped
+}
+
+trap cleanup EXIT INT TERM
+
+start_autosave_background() {
+  local existing_pid autosave_pid
+
+  [ -n "${WORK_ALLY_ASSISTANT_HOME:-}" ] || return 0
+  work_ally_assistant_git_setup "$WORK_ALLY_ASSISTANT_HOME" "$ASSISTANT_GIT_REMOTE" || true
+
+  existing_pid=$(work_ally_read_pid "$AUTOSAVE_PID_FILE" || true)
+  if [ -n "$existing_pid" ] && work_ally_is_pid_alive "$existing_pid"; then
+    work_ally_write_health assistant-autosave running "{\"assistant\": \"$WORK_ALLY_ASSISTANT_NAME\", \"pid\": ${existing_pid}, \"workspaceRoot\": \"$WORK_ALLY_WORKSPACE_ROOT\"}"
+    return 0
+  fi
+
+  nohup env \
+    WORK_ALLY_ASSISTANT_MODE="assistant" \
+    WORK_ALLY_ASSISTANT_NAME="$WORK_ALLY_ASSISTANT_NAME" \
+    WORK_ALLY_ASSISTANT_HOME="$WORK_ALLY_ASSISTANT_HOME" \
+    WORK_ALLY_ASSISTANT_CODEX_HOME="$WORK_ALLY_ASSISTANT_CODEX_HOME" \
+    WORK_ALLY_ASSISTANT_GIT_REMOTE="$ASSISTANT_GIT_REMOTE" \
+    WORK_ALLY_WORKSPACE_ROOT="$WORK_ALLY_WORKSPACE_ROOT" \
+    WORK_ALLY_STATE_DIR="$WORK_ALLY_STATE_DIR" \
+    WORK_ALLY_INSTALL_ROOT="$WORK_ALLY_INSTALL_ROOT" \
+    WORK_ALLY_IMPLEMENTATION_DIR="$WORK_ALLY_IMPLEMENTATION_DIR" \
+    "$WORK_ALLY_IMPLEMENTATION_DIR/internal/modules/runtime/assistant-autosave.sh" >"$AUTOSAVE_LOG" 2>&1 &
+  echo $! > "$AUTOSAVE_PID_FILE"
+  sleep 1
+  autosave_pid=$(work_ally_read_pid "$AUTOSAVE_PID_FILE" || true)
+  if [ -n "$autosave_pid" ] && work_ally_is_pid_alive "$autosave_pid"; then
+    work_ally_write_health assistant-autosave running "{\"assistant\": \"$WORK_ALLY_ASSISTANT_NAME\", \"pid\": ${autosave_pid}, \"workspaceRoot\": \"$WORK_ALLY_WORKSPACE_ROOT\"}"
+    return 0
+  fi
+
+  rm -f "$AUTOSAVE_PID_FILE"
+  work_ally_write_health assistant-autosave stopped '{}'
+  return 1
+}
+
+start_bridge_background() {
+  local bridge_count bridge_pid
+
+  bridge_count=$(work_ally_bridge_pid_count)
+  if [ "$bridge_count" -gt 1 ]; then
+    work_ally_warn "Multiple bridge processes detected for this workspace; restarting bridge"
+    stop_bridge_processes_keep_locks
+  fi
+
+  bridge_pid=$(work_ally_primary_bridge_pid || true)
+  if [ -n "$bridge_pid" ] && work_ally_is_pid_alive "$bridge_pid"; then
+    echo "$bridge_pid" > "$BRIDGE_PID_FILE"
+    work_ally_write_health bridge running "{\"assistant\": \"$WORK_ALLY_ASSISTANT_NAME\", \"pid\": ${bridge_pid}, \"workspaceRoot\": \"$WORK_ALLY_WORKSPACE_ROOT\", \"channel\": \"$CHANNEL_IMPL\", \"runtime\": \"$RUNTIME_MODE\"}"
+    return 0
+  fi
+
+  work_ally_note "Starting work-ally bridge"
+  nohup env \
+    CODEX_HOME="$WORK_ALLY_ASSISTANT_CODEX_HOME" \
+    WORK_ALLY_ASSISTANT_MODE="assistant" \
+    WORK_ALLY_ASSISTANT_NAME="$WORK_ALLY_ASSISTANT_NAME" \
+    WORK_ALLY_ASSISTANT_HOME="$WORK_ALLY_ASSISTANT_HOME" \
+    WORK_ALLY_ASSISTANT_CODEX_HOME="$WORK_ALLY_ASSISTANT_CODEX_HOME" \
+    WORK_ALLY_WORKSPACE_ROOT="$WORK_ALLY_WORKSPACE_ROOT" \
+    WORK_ALLY_STATE_DIR="$WORK_ALLY_STATE_DIR" \
+    WORK_ALLY_INSTALL_ROOT="$WORK_ALLY_INSTALL_ROOT" \
+    WORK_ALLY_IMPLEMENTATION_DIR="$WORK_ALLY_IMPLEMENTATION_DIR" \
+    node "$WORK_ALLY_IMPLEMENTATION_DIR/bridge/src/server.ts" >"$BRIDGE_LOG" 2>&1 &
+  echo $! > "$BRIDGE_PID_FILE"
+  sleep 2
+  bridge_pid=$(work_ally_read_pid "$BRIDGE_PID_FILE" || true)
+  if [ -n "$bridge_pid" ] && work_ally_is_pid_alive "$bridge_pid"; then
+    work_ally_write_health bridge running "{\"assistant\": \"$WORK_ALLY_ASSISTANT_NAME\", \"pid\": ${bridge_pid}, \"workspaceRoot\": \"$WORK_ALLY_WORKSPACE_ROOT\", \"channel\": \"$CHANNEL_IMPL\", \"runtime\": \"$RUNTIME_MODE\"}"
+    return 0
+  fi
+
+  rm -f "$BRIDGE_PID_FILE"
+  work_ally_write_health bridge stopped '{}'
+  return 1
+}
+
+recover_bridge_if_needed() {
+  local bridge_count bridge_pid
+
+  bridge_count=$(work_ally_bridge_pid_count)
+  if [ "$bridge_count" -eq 1 ]; then
+    bridge_pid=$(work_ally_primary_bridge_pid || true)
+    if [ -n "$bridge_pid" ] && work_ally_is_pid_alive "$bridge_pid"; then
+      echo "$bridge_pid" > "$BRIDGE_PID_FILE"
+      work_ally_write_health bridge running "{\"assistant\": \"$WORK_ALLY_ASSISTANT_NAME\", \"pid\": ${bridge_pid}, \"workspaceRoot\": \"$WORK_ALLY_WORKSPACE_ROOT\", \"channel\": \"$CHANNEL_IMPL\", \"runtime\": \"$RUNTIME_MODE\"}"
+      BRIDGE_OUTAGE_NOTIFIED=0
+      return 0
+    fi
+  fi
+
+  if [ "$BRIDGE_OUTAGE_NOTIFIED" -eq 0 ]; then
+    send_notice_if_possible text "消息桥接已断开，正在恢复……"
+    BRIDGE_OUTAGE_NOTIFIED=1
+  fi
+
+  stop_bridge_processes_keep_locks
+  if start_bridge_background; then
+    send_notice_if_possible text "消息桥接已恢复。"
+    BRIDGE_OUTAGE_NOTIFIED=0
+    return 0
+  fi
+
+  work_ally_warn "Failed to recover bridge; will retry"
+  return 1
+}
+
+work_ally_assert_assistant_available "$WORK_ALLY_ASSISTANT_NAME"
+work_ally_assert_channel_available
+work_ally_claim_assistant_lock "$WORK_ALLY_ASSISTANT_NAME" "$$"
+work_ally_claim_channel_lock "$$"
+echo "$$" > "$SUPERVISOR_PID_FILE"
+write_supervisor_health running
+
+work_ally_assistant_git_setup "$WORK_ALLY_ASSISTANT_HOME" "$ASSISTANT_GIT_REMOTE" || true
+work_ally_assistant_git_checkpoint "$WORK_ALLY_ASSISTANT_HOME" "start assistant $WORK_ALLY_ASSISTANT_NAME" || true
+
+if ! start_bridge_background; then
+  write_supervisor_health failed
+  exit 1
+fi
+start_autosave_background || true
+
+while :; do
+  [ "$SHUTTING_DOWN" = "0" ] || exit 0
+  work_ally_write_assistant_lock "$WORK_ALLY_ASSISTANT_NAME" "$$"
+  work_ally_write_channel_lock "$$"
+  write_supervisor_health running
+  recover_bridge_if_needed || true
+  start_autosave_background || true
+  sleep "$POLL_INTERVAL"
+done

package/internal/modules/runtime/update.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+# shellcheck disable=SC1091
+. "$SCRIPT_DIR/../../lib/common.sh"
+work_ally_init_context
+if [ -z "${WORK_ALLY_ASSISTANT_NAME:-}" ]; then
+  WORK_ALLY_ASSISTANT_NAME=$(work_ally_resolve_assistant_name_from_args "$@" || true)
+fi
+if [ -n "${WORK_ALLY_ASSISTANT_NAME:-}" ]; then
+  work_ally_sync_workspace_root_from_assistant "$WORK_ALLY_ASSISTANT_NAME"
+  work_ally_hydrate_assistant_context "$WORK_ALLY_ASSISTANT_NAME"
+fi
+work_ally_ensure_state_dirs
+
+work_ally_note "Install-first mode: update is handled by npm."
+cat <<EOF2
+Run one of these in your normal terminal:
+  npm i -g work-ally@alpha
+  npm update -g work-ally
+Then verify with:
+  ally status --assistant <name>
+EOF2
+
+work_ally_ok "Update guidance shown"

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "work-ally",
+  "version": "0.2.0-alpha.1",
+  "private": false,
+  "type": "module",
+  "bin": {
+    "ally": "ally.sh"
+  },
+  "files": [
+    "ally.sh",
+    "bridge/",
+    "internal/",
+    "runtime/",
+    "templates/",
+    "docs/",
+    "skills/",
+    "package.json",
+    "README.md",
+    "PRODUCT.md",
+    "DASHBOARD.md",
+    "AGENTS.md"
+  ],
+  "scripts": {
+    "test": "npm run test:shell && npm run test:bridge",
+    "test:full": "npm test",
+    "test:fast": "node --test \"tests/unit/**/*.test.mjs\" \"tests/integration/**/*.test.mjs\"",
+    "test:maintainer": "bash dev/run-regression-suite.sh",
+    "test:shell": "bash tests/shell/smoke.sh && bash tests/shell/assistant.sh && bash tests/shell/assistant-remove.sh && bash tests/shell/assistant-rename.sh && bash tests/shell/assistant-lock.sh && bash tests/shell/global-entrypoint.sh && bash tests/shell/global-manage.sh && bash tests/shell/security.sh && bash tests/shell/ops.sh && bash tests/shell/lifecycle.sh && bash tests/shell/channel-lock.sh && bash tests/shell/mcp.sh && bash tests/shell/routines.sh && bash tests/shell/recovery.sh && bash tests/shell/service-mode.sh && bash tests/shell/bridge-health-fallback.sh && bash tests/shell/startup-delivery-gate.sh && bash tests/shell/status-health.sh && bash tests/shell/codex-runtime.sh && bash tests/shell/codex-handoff.sh && bash tests/shell/supervised-start-boundary.sh",
+    "test:bridge": "node --test \"tests/unit/**/*.test.mjs\" \"tests/integration/**/*.test.mjs\"",
+    "dev:debug-workspace": "bash dev/prepare-debug-workspace.sh",
+    "bridge:start": "node bridge/src/server.ts",
+    "runtime:health": "node runtime/host/healthcheck-codex-app-server.ts",
+    "runtime:probe": "node runtime/host/probe-codex-app-server.ts",
+    "release:alpha": "bash script/release-npm-alpha.sh"
+  },
+  "dependencies": {
+    "@larksuiteoapi/node-sdk": "^1.50.0",
+    "cron-parser": "^5.2.0",
+    "yaml": "^2.8.1"
+  }
+}

package/runtime/host/healthcheck-codex-app-server.ts

@@ -0,0 +1,22 @@
+import { CodexRuntimeClient } from '../../bridge/src/runtime-client.ts';
+
+async function main() {
+  const client = new CodexRuntimeClient({
+    codexHome: process.env.CODEX_HOME || null,
+  });
+
+  try {
+    const ok = await client.healthcheck();
+    console.log(JSON.stringify({ transport: 'stdio', ok }));
+    if (!ok) {
+      process.exitCode = 1;
+    }
+  } finally {
+    await client.disconnect().catch(() => undefined);
+  }
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/runtime/host/ping-pong-codex-app-server.ts

@@ -0,0 +1,66 @@
+import { CodexRuntimeClient } from '../../bridge/src/runtime-client.ts';
+
+function parseRounds(argv: string[]): number {
+  const index = argv.findIndex((arg) => arg === '--rounds');
+  if (index >= 0) {
+    const value = Number(argv[index + 1] || '');
+    if (!Number.isInteger(value) || value <= 0) {
+      throw new Error('--rounds must be a positive integer');
+    }
+    return value;
+  }
+
+  const inline = argv.find((arg) => arg.startsWith('--rounds='));
+  if (inline) {
+    const value = Number(inline.slice('--rounds='.length));
+    if (!Number.isInteger(value) || value <= 0) {
+      throw new Error('--rounds must be a positive integer');
+    }
+    return value;
+  }
+
+  return 20;
+}
+
+async function main() {
+  const rounds = parseRounds(process.argv.slice(2));
+  const client = new CodexRuntimeClient({
+    codexHome: process.env.CODEX_HOME || null,
+  });
+
+  try {
+    const ok = await client.healthcheck();
+    if (!ok) {
+      throw new Error('Codex runtime is not reachable');
+    }
+
+    const thread = await client.startThread(process.cwd());
+    const replies: string[] = [];
+    for (let index = 1; index <= rounds; index += 1) {
+      const expected = String(index);
+      const result = await client.runTurn({
+        threadId: thread.id,
+        prompt: 'Reply with exactly: ' + expected,
+        messageId: 'ping-pong-' + expected,
+        cwd: process.cwd(),
+      });
+      const actual = String(result.reply || '').trim();
+      if (result.status !== 'completed') {
+        throw new Error('ping-pong round failed at ' + expected + ': ' + result.status + ' ' + String(result.error || ''));
+      }
+      if (actual !== expected) {
+        throw new Error('ping-pong mismatch at round ' + expected + ': expected "' + expected + '", got "' + actual + '"');
+      }
+      replies.push(actual);
+    }
+
+    console.log(JSON.stringify({ transport: 'stdio', threadId: thread.id, rounds, lastReply: replies[replies.length - 1] }, null, 2));
+  } finally {
+    await client.disconnect().catch(() => undefined);
+  }
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/runtime/host/probe-codex-app-server.ts

@@ -0,0 +1,115 @@
+import { parseMcpToolApprovalRules } from '../../bridge/src/config.ts';
+import { CodexRuntimeClient } from '../../bridge/src/runtime-client.ts';
+import { maybeAutoResolveRuntimeUserInput } from '../../bridge/src/runtime-user-input.ts';
+import type { UserInputRequest } from '../../bridge/src/types.ts';
+
+interface ProbeUserInputEvent {
+  kind: UserInputRequest['kind'];
+  requestId: string | number;
+  prompt: string;
+}
+
+function sandboxPolicyFromEnv(): unknown | undefined {
+  const mode = (process.env.WORK_ALLY_CODEX_SANDBOX_MODE || '').trim();
+  if (!mode) {
+    return undefined;
+  }
+  if (mode === 'danger-full-access') {
+    return { type: 'dangerFullAccess' as const };
+  }
+  if (mode === 'read-only') {
+    return {
+      type: 'readOnly' as const,
+      networkAccess: true,
+      access: {
+        type: 'restricted' as const,
+        includePlatformDefaults: true,
+        readableRoots: [process.cwd()],
+      },
+    };
+  }
+  return {
+    type: 'workspaceWrite' as const,
+    networkAccess: true,
+    writableRoots: [process.cwd()],
+  };
+}
+
+function summarizeUserInput(request: UserInputRequest): ProbeUserInputEvent {
+  const prompt = request.elicitation?.message || request.questions?.map((question) => question.question).join(' | ') || '';
+  return {
+    kind: request.kind,
+    requestId: request.requestId,
+    prompt,
+  };
+}
+
+async function main() {
+  const prompt = process.argv.slice(2).join(' ') || 'Reply with exactly: OK';
+  const approvalPolicy = (process.env.WORK_ALLY_CODEX_APPROVAL_POLICY || '').trim() || undefined;
+  const sandboxPolicy = sandboxPolicyFromEnv();
+  const rules = parseMcpToolApprovalRules(process.env.WORK_ALLY_MCP_TOOL_APPROVAL_ALLOWLIST);
+  const client = new CodexRuntimeClient({
+    codexHome: process.env.CODEX_HOME || null,
+  });
+  const unresolvedUserInputs: ProbeUserInputEvent[] = [];
+  const autoResolvedUserInputs: Array<ProbeUserInputEvent & { matchedRule: string }> = [];
+
+  try {
+    const ok = await client.healthcheck();
+    if (!ok) {
+      throw new Error('Codex runtime is not reachable');
+    }
+
+    const thread = await client.startThread(process.cwd());
+    const result = await client.runTurn({
+      threadId: thread.id,
+      prompt,
+      messageId: 'probe-codex-runtime',
+      cwd: process.cwd(),
+      approvalPolicy,
+      sandboxPolicy,
+      onProgress: (text) => console.log('[progress]', text),
+      onApproval: (approval) => console.log('[approval]', JSON.stringify(approval)),
+      onUserInput: async (request) => {
+        const autoResolution = maybeAutoResolveRuntimeUserInput(request, rules);
+        if (autoResolution?.answers) {
+          await client.resolveUserInput(request.requestId, { answers: autoResolution.answers });
+          const event = summarizeUserInput(request);
+          autoResolvedUserInputs.push({ ...event, matchedRule: autoResolution.matchedRule });
+          console.log('[user-input:auto]', JSON.stringify({ ...event, matchedRule: autoResolution.matchedRule }));
+          return;
+        }
+        if (autoResolution?.elicitationResponse) {
+          await client.resolveElicitation(request.requestId, autoResolution.elicitationResponse);
+          const event = summarizeUserInput(request);
+          autoResolvedUserInputs.push({ ...event, matchedRule: autoResolution.matchedRule });
+          console.log('[elicitation:auto]', JSON.stringify({ ...event, matchedRule: autoResolution.matchedRule }));
+          return;
+        }
+
+        const event = summarizeUserInput(request);
+        unresolvedUserInputs.push(event);
+        console.log('[user-input:manual]', JSON.stringify(event));
+        if (request.kind === 'mcp_elicitation') {
+          await client.resolveElicitation(request.requestId, { action: 'cancel', content: null });
+        } else {
+          await client.resolveUserInput(request.requestId, { answers: {} });
+        }
+      },
+    });
+
+    if (unresolvedUserInputs.length > 0) {
+      throw new Error(`Probe encountered manual user input: ${JSON.stringify(unresolvedUserInputs)}`);
+    }
+
+    console.log(JSON.stringify({ transport: 'stdio', thread, result, autoResolvedUserInputs }, null, 2));
+  } finally {
+    await client.disconnect().catch(() => undefined);
+  }
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/skills/archive-reader/SKILL.md

@@ -0,0 +1,9 @@
+# archive-reader
+
+Use this skill when you need to inspect workspace archive files under `memory/archive/` and extract the durable facts worth keeping.
+
+## Rules
+
+- Treat archive files as raw black-box material.
+- Prefer reading the smallest useful date range first.
+- Distinguish raw events from durable conclusions.

package/skills/feishu-production-debug/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: feishu-production-debug
+description: Use this skill when a real Feishu conversation path appears broken or missing and you need to debug the production chain from event delivery to thread routing to reply delivery, without guessing or immediately blaming the bridge core.
+---
+
+# Feishu Production Debug
+
+Use this skill for real message-path incidents seen in Feishu.
+
+Do not use this skill when:
+
+- the issue is only a local formatter or unit-test failure with no live symptom
+- the task is purely product design or permission brainstorming
+- the problem is already known to be outside Feishu message delivery
+
+## Quick start
+
+1. Read `references/feishu-debug-order.md` first.
+2. Read `references/platform-permission-baseline.md` if the symptom involves missing messages, group triggers, or bot visibility.
+3. Establish the exact symptom, time window, and conversation type first: private chat, group mention, reply context, or outbound delivery.
+4. Debug in strict order from inbound receipt to outbound reply.
+
+## Output contract
+
+Always answer with:
+
+1. most likely broken stage
+2. evidence
+3. next verification step or fix direction
+
+## Working rules
+
+- First ask whether the message ever reached the bridge.
+- If there is no inbound event evidence, check Feishu platform permissions and delivery before touching bridge logic.
+- Keep private chat and group-mention paths separate; they are different triggers and different threads.
+- Treat routing and reply-delivery as different stages.
+- Prefer fact-based localization over broad guesses like “bridge probably swallowed it.”

package/skills/feishu-production-debug/references/feishu-debug-order.md

@@ -0,0 +1,49 @@
+# Feishu Debug Order
+
+## Strict debug order
+
+### 1. Confirm the symptom
+
+Capture:
+
+- exact user message or action
+- approximate time
+- private chat or group mention
+- whether the issue is missing trigger, wrong thread, or missing reply
+
+### 2. Check inbound receipt first
+
+Ask:
+
+- Did the bridge receive the event at all?
+- Is there inbound evidence in logs or ledger?
+
+If the answer is no, do not start with routing speculation.
+
+### 3. Check platform permissions and delivery
+
+Especially verify:
+
+- private chat read permission
+- group `@bot` event permission
+- whether “receive all group messages” was intentionally left disabled
+
+### 4. Check routing
+
+If inbound exists, ask:
+
+- Was the message mapped to the expected assistant?
+- Was it mapped to the expected private or group thread?
+- Was reply context or sender context resolved correctly?
+
+### 5. Check outbound reply delivery
+
+If the assistant worked but the user saw nothing, ask:
+
+- Did a reply artifact exist?
+- Did outbound delivery fail?
+- Did the bridge suppress or dedupe a stale result?
+
+## Default rule
+
+Never jump straight from “user saw no reply” to “Codex failed.”

package/skills/feishu-production-debug/references/platform-permission-baseline.md

@@ -0,0 +1,23 @@
+# Feishu Platform Permission Baseline
+
+## Minimal supported baseline
+
+For the current shipped model, the expected Feishu bot permissions are:
+
+- enable reading private messages sent to the bot
+- enable receiving group events where the bot is explicitly mentioned
+- do not enable “receive all group messages” unless you intentionally want unsupported mixed group traffic
+
+## Why this matters
+
+### Private chat
+
+If private-message read permission is missing, the bridge will never receive the user's direct message.
+
+### Group chat
+
+Current supported group model is explicit `@assistant` trigger.
+
+If the platform is not configured to deliver group `@bot` events, the bridge cannot route anything, and there is nothing local to “recover.”
+
+If “receive all group messages” is enabled, unsupported traffic may reach the bridge and create mixed-thread behavior. That outcome belongs to unsupported configuration, not the default product contract.

package/skills/issue-to-spec-triage/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: issue-to-spec-triage
+description: Use this skill when a user brings a new idea, complaint, bug report, request, or product question and you need to decide whether it is a small bugfix, a product boundary correction, a spec-worthy feature, or something that should stay in the idea pool.
+---
+
+# Issue To Spec Triage
+
+Use this skill when the immediate job is to classify an incoming issue or idea, not to directly design or implement the solution.
+
+Do not use this skill when:
+
+- the user has already explicitly asked to draft, refine, review, or score a spec
+- the task is already clearly an implementation task
+- the issue is obviously a tiny wording fix or a low-risk local bugfix with no product-semantic impact
+
+## Quick start
+
+1. Read `references/triage-rules.md` first.
+2. Load only the minimum project context you need, usually from `PRODUCT.md`, `DASHBOARD.md`, `AGENTS.md`, or the most relevant existing spec.
+3. Decide the classification before proposing a solution.
+4. If the outcome is `spec-needed`, hand off to `skills/product-spec/` rather than mixing triage and spec writing into one blurry step.
+
+## Output contract
+
+Always answer in this order:
+
+1. classification
+2. short reason
+3. next action
+
+Valid classifications:
+
+- `small-bugfix`
+- `boundary-fix`
+- `spec-needed`
+- `hold`
+
+## Working rules
+
+- Prioritize identifying the real product problem over accepting the user's first proposed solution.
+- Ask only the minimum clarifying questions needed to classify correctly.
+- If a change would alter product meaning, default behavior, user path, long-term maintenance semantics, or cross-module/system boundaries, treat it as `spec-needed`.
+- If the issue is already covered by an existing spec or shipped contract, prefer `boundary-fix` or `small-bugfix` over opening a duplicate spec.
+- If the idea is real but not yet actionable, classify it as `hold` and point to the appropriate planning surface.