abelworkflow 0.6.2 → 0.6.4

package/.gitignore

@@ -13,3 +13,4 @@ skills/dev-browser/tmp/
 .codex/
 *pycache*/
 .codex
+openspec/

package/README.md

@@ -142,18 +142,36 @@ git -C "$HOME\.agents" pull
 
 #### 2. 执行本地初始化
 
+**Linux/macOS（bash/zsh）**
+
 ```bash
 cd ~/.agents
 node bin/abelworkflow.mjs
 ```
 
+**Windows（PowerShell）**
+
+```powershell
+Set-Location "$HOME\.agents"
+node .\bin\abelworkflow.mjs
+```
+
 如果只想重建链接，不进入菜单：
 
+**Linux/macOS（bash/zsh）**
+
 ```bash
 cd ~/.agents
 node bin/abelworkflow.mjs install
 ```
 
+**Windows（PowerShell）**
+
+```powershell
+Set-Location "$HOME\.agents"
+node .\bin\abelworkflow.mjs install
+```
+
 ### 映射关系（本仓库 → 配置目录）
 
 | 本仓库 | Claude Code | Codex | 说明 |
@@ -164,9 +182,21 @@ node bin/abelworkflow.mjs install
 
 ### 验证（可选）
 
+**Linux/macOS（bash/zsh）**
+
 ```bash
 ls -la "$HOME/.claude/CLAUDE.md" "$HOME/.claude/commands/oc"
 ls -la "$HOME/.codex/AGENTS.md" "$HOME/.codex/prompts/"{init,research,plan,implementation,diagnose}.md
 cat "$HOME/.claude/settings.json" | head
 cat "$HOME/.codex/config.toml" | head
 ```
+
+**Windows（PowerShell）**
+
+```powershell
+Get-Item "$HOME\.claude\CLAUDE.md", "$HOME\.claude\commands\oc"
+Get-Item "$HOME\.codex\AGENTS.md"
+Get-ChildItem "$HOME\.codex\prompts" | Where-Object { $_.Name -in @("init.md", "research.md", "plan.md", "implementation.md", "diagnose.md") }
+Get-Content "$HOME\.claude\settings.json" -TotalCount 10
+Get-Content "$HOME\.codex\config.toml" -TotalCount 10
+```

package/commands/oc/plan.md

@@ -77,7 +77,7 @@ argument-hint: [change_name]
 - Use `openspec list --specs` to check for conflicts with existing specifications.
 - Search existing patterns with `rg -n "INVARIANT:|PROPERTY:|Constraint:" openspec/` before defining new ones.
 - For complex proposals, consider running steps 2-4 iteratively on sub-components.
-- Use `AskUserQuestions` for ANY ambiguity—do not assume or guess.
+- Ask the user directly for ANY ambiguity—do not assume or guess.
 
 **Exit Criteria**
 A proposal is ready to exit the Plan phase only when:

package/commands/oc/research.md

@@ -26,7 +26,7 @@ Produce constraint sets that narrow the solution space, plus measurable success
 
 ## Phase 0 — Requirement Intake Gate (MANDATORY)
 - **MUST** confirm the user’s requirement exists and is clear **before** any research/action.
-- If missing/unclear, **MUST** use `AskUserQuestions` to collect: goal, in-scope area, top scenarios, non-goals, known constraints, success signals.
+- If missing/unclear, **MUST** ask the user directly in a concise grouped message to collect: goal, in-scope area, top scenarios, non-goals, known constraints, success signals.
 - **MUST NOT** run `/opsx:new`, any codebase retrieval, spawn subagents, or generate artifacts until the user confirms a brief requirement summary.
 
 ---
@@ -97,7 +97,7 @@ All explore subagents MUST return valid JSON using this schema:
 
 ## Phase 7 — User Interaction for Ambiguity Resolution
 - Compile prioritized list of open questions from aggregated reports.
-- Use `AskUserQuestions` tool to present questions systematically:
+- Present questions directly to the user in a concise grouped message:
   * Group related questions together.
   * Provide context for each question.
   * Suggest default answers when applicable.
@@ -122,5 +122,5 @@ All explore subagents MUST return valid JSON using this schema:
   - `openspec status --change <name>` - Check artifact completion status
   - `openspec instructions proposal --change <name>` - Get proposal instructions
 - Validate subagent outputs conform to template before aggregation.
-- Use `AskUserQuestions` for ANY ambiguity—do not assume or guess.
-<!-- OC:RESEARCH:END -->
+- Ask the user directly for ANY ambiguity—do not assume or guess.
+<!-- OC:RESEARCH:END -->

package/lib/cli.mjs

@@ -1871,8 +1871,8 @@ function buildCodexConfigContent(currentContent, {
     content = mergeCodexTemplateDefaults(content, effectiveTemplateContent);
   }
   const lineEnding = detectLineEnding(content);
-  if (includeSubagentDefaults && readTopLevelTomlString(content, "approvals_reviewer") === "guardian_subagent") {
-    content = updateTopLevelTomlField(content, "approvals_reviewer", "reviewer");
+  if (includeSubagentDefaults && readTopLevelTomlString(content, "approvals_reviewer") === "reviewer") {
+    content = updateTopLevelTomlField(content, "approvals_reviewer", "guardian_subagent");
   }
   content = updateTopLevelTomlField(content, "model_provider", providerId);
   content = updateTopLevelTomlField(content, "preferred_auth_method", "apikey");

package/lib/templates/codex/config-base.toml

@@ -2,7 +2,7 @@ personality = "pragmatic"
 model_provider = "abelworkflow"
 disable_response_storage = true
 preferred_auth_method = "apikey"
-approvals_reviewer = "reviewer"
+approvals_reviewer = "guardian_subagent"
 approval_policy = "on-request"
 sandbox_mode = "workspace-write"
 service_tier = "fast"

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "abelworkflow",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Install AbelWorkflow into ~/.agents and create Claude/Codex symlinks.",
   "type": "module",
+  "scripts": {
+    "test:contracts": "node --test test/runtime-doc-contracts.test.mjs"
+  },
   "bin": {
     "abelworkflow": "bin/abelworkflow.mjs"
   },

package/skills/dev-browser/scripts/start.ts

@@ -43,6 +43,7 @@ async function main() {
       ensurePlaywrightChromium({
         isInstalled: () =>
           isPlaywrightChromiumInstalled({
+            skillDir: runtimePaths.skillDir,
             platform: process.platform,
             env: process.env,
             exists: existsSync,

package/skills/dev-browser/src/runtime.test.ts

@@ -0,0 +1,60 @@
+import { join } from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+import { getPlaywrightBrowserRoots, isPlaywrightChromiumInstalled } from "./runtime.js";
+
+describe("getPlaywrightBrowserRoots", () => {
+  const skillDir = "/tmp/dev-browser";
+
+  it("uses the hermetic local browser directory when PLAYWRIGHT_BROWSERS_PATH is 0", () => {
+    expect(
+      getPlaywrightBrowserRoots({
+        skillDir,
+        platform: "win32",
+        env: { PLAYWRIGHT_BROWSERS_PATH: "0" },
+      })
+    ).toEqual([join(skillDir, "node_modules", "playwright-core", ".local-browsers")]);
+  });
+
+  it("prefers LOCALAPPDATA on Windows before USERPROFILE fallback", () => {
+    expect(
+      getPlaywrightBrowserRoots({
+        skillDir,
+        platform: "win32",
+        env: {
+          LOCALAPPDATA: "C:\\Users\\Alice\\AppData\\Local",
+          USERPROFILE: "C:\\Users\\Alice",
+        },
+      })
+    ).toEqual([join("C:\\Users\\Alice\\AppData\\Local", "ms-playwright")]);
+  });
+
+  it("falls back to USERPROFILE when LOCALAPPDATA is unavailable", () => {
+    expect(
+      getPlaywrightBrowserRoots({
+        skillDir,
+        platform: "win32",
+        env: { USERPROFILE: "C:\\Users\\Alice" },
+      })
+    ).toEqual([join("C:\\Users\\Alice", "AppData", "Local", "ms-playwright")]);
+  });
+});
+
+describe("isPlaywrightChromiumInstalled", () => {
+  const skillDir = "/tmp/dev-browser";
+
+  it("detects chromium in the hermetic local browser directory", () => {
+    const hermeticRoot = join(skillDir, "node_modules", "playwright-core", ".local-browsers");
+
+    expect(
+      isPlaywrightChromiumInstalled({
+        skillDir,
+        platform: "win32",
+        env: { PLAYWRIGHT_BROWSERS_PATH: "0" },
+        exists: (path) => path === hermeticRoot,
+        readDir: () => ["chromium-1162"],
+      })
+    ).toBe(true);
+  });
+});

package/skills/dev-browser/src/runtime.ts

@@ -12,6 +12,7 @@ export interface PackageManager {
 }
 
 export interface ChromiumInstallCheckOptions {
+  skillDir: string;
   platform: NodeJS.Platform;
   env: NodeJS.ProcessEnv;
   exists: (path: string) => boolean;
@@ -66,21 +67,43 @@ export function getPlaywrightInstallCommand(manager: PackageManager): string {
   return [manager.command, ...manager.args].join(" ");
 }
 
+function normalizePathForComparison(path: string): string {
+  return path.replaceAll("\\", "/").replace(/\/+/g, "/").toLowerCase();
+}
+
 export function getPlaywrightBrowserRoots({
+  skillDir,
   platform,
   env,
 }: {
+  skillDir: string;
   platform: NodeJS.Platform;
   env: NodeJS.ProcessEnv;
 }): string[] {
   const explicitPath = env.PLAYWRIGHT_BROWSERS_PATH?.trim();
   if (explicitPath) {
+    if (explicitPath === "0") {
+      return [join(skillDir, "node_modules", "playwright-core", ".local-browsers")];
+    }
     return [explicitPath];
   }
 
   if (platform === "win32") {
-    const userProfile = env.USERPROFILE ?? env.HOME;
-    return userProfile ? [join(userProfile, "AppData", "Local", "ms-playwright")] : [];
+    const roots: string[] = [];
+    const localAppData = env.LOCALAPPDATA?.trim();
+    if (localAppData) {
+      roots.push(join(localAppData, "ms-playwright"));
+    }
+
+    const userProfile = env.USERPROFILE?.trim() ?? env.HOME?.trim();
+    if (userProfile) {
+      const fallbackRoot = join(userProfile, "AppData", "Local", "ms-playwright");
+      if (!roots.some((root) => normalizePathForComparison(root) === normalizePathForComparison(fallbackRoot))) {
+        roots.push(fallbackRoot);
+      }
+    }
+
+    return roots;
   }
 
   const home = env.HOME ?? env.USERPROFILE;
@@ -88,12 +111,13 @@ export function getPlaywrightBrowserRoots({
 }
 
 export function isPlaywrightChromiumInstalled({
+  skillDir,
   platform,
   env,
   exists,
   readDir,
 }: ChromiumInstallCheckOptions): boolean {
-  for (const root of getPlaywrightBrowserRoots({ platform, env })) {
+  for (const root of getPlaywrightBrowserRoots({ skillDir, platform, env })) {
     if (!exists(root)) {
       continue;
     }

package/skills/grok-search/SKILL.md

@@ -35,9 +35,55 @@ python "<SKILL_DIR>/scripts/groksearch_entry.py" get_config_info [--no-test]
 python "<SKILL_DIR>/scripts/groksearch_entry.py" toggle_builtin_tools --action on|off|status [--root /path/to/project]
 ```
 
-## Failure Recovery
+## Tool Routing Policy
+### Forced Replacement Rules
 
-- Connection or auth failure: run `get_config_info` and verify `GROK_API_URL` and `GROK_API_KEY`.
-- `web_search` needs broader coverage: add `--extra-sources N`; if Tavily is unavailable, keep Grok results and note the warning.
-- `web_fetch` fails on Tavily extract: retry with `--fallback-grok`.
-- Hash-route/docsify pages may require the materialized markdown URL hinted by the CLI error.
+| Scenario | Disabled | Use Instead |
+|----------|----------|-------------|
+| Web Search | `WebSearch` | CLI `web_search` via `groksearch_entry.py` |
+| Web Fetch | `WebFetch` | CLI `web_fetch` via `groksearch_entry.py` |
+
+### Tool Capability Matrix
+
+| Tool | Parameters | Output |
+|------|------------|--------|
+| `web_search` | `query`(required), `platform`/`min_results`/`max_results`/`model`/`extra_sources`(optional) | `[{title,url,description}]` |
+| `web_fetch` | `url`(required), `out`/`fallback_grok`(optional) | Structured Markdown |
+| `web_map` | `url`(required), `instructions`/`max_depth`/`max_breadth`/`limit`/`timeout`(optional) | JSON string |
+| `get_config_info` | `no_test`(optional) | `{api_url,status,connection_test}` |
+| `toggle_builtin_tools` | `action`(on/off/status), `root`(optional) | `{blocked,deny_list}` |
+
+## Search Workflow
+
+### Phase 1: Query Construction
+- **Intent Recognition**: Broad search → `web_search` | Deep retrieval → `web_fetch`
+- **Parameter Optimization**: Set `platform` for specific sources, adjust result counts; if you need broader source coverage, consider adding `--extra-sources 3`
+
+### Phase 2: Search Execution
+1. Start with `web_search` for structured summaries
+2. Use `web_fetch` on key URLs if summaries insufficient
+3. Retry with adjusted query if first round unsatisfactory
+
+### Phase 3: Result Synthesis
+1. Cross-reference multiple sources
+2. **Must annotate source and date** for time-sensitive info
+3. **Must include source URLs**: `Title [1](URL)`
+
+## Error Handling
+
+| Error | Recovery |
+|-------|----------|
+| Connection Failure | Run `get_config_info`, verify API URL/Key |
+| No Results | Broaden search terms |
+| Fetch Timeout | Try alternative sources |
+| Tavily unavailable while using `--extra-sources` | Command keeps Grok results and prints a Tavily warning to stderr |
+| Tavily extract failure | Use `--fallback-grok`, or inspect the Tavily warning/error message |
+
+## Anti-Patterns
+
+| Prohibited | Correct |
+|------------|---------|
+| No source citation | Include `Source [1](URL)` |
+| Assume current repo has `skills/grok-search` | Check global skill directories under `$HOME` first, then project-level `.claude/.codex/.agents`, then call `<SKILL_DIR>/scripts/groksearch_entry.py` |
+| Call `scripts/groksearch_cli.py` directly | Call `python scripts/groksearch_entry.py ...` |
+| Use built-in WebSearch/WebFetch | Use GrokSearch CLI |

package/skills/dev-browser/resolve-skill-dir.sh

@@ -1,35 +0,0 @@
-#!/usr/bin/env bash
-# Resolve the installed skill directory for dev-browser.
-# Outputs the resolved path to stdout. Exits 1 if not found.
-SKILL_NAME="dev-browser"
-SKILL_DIR=""
-CANDIDATE_SUFFIXES=".agents/skills .claude/skills .codex/skills .config/agents/skills"
-for base in \
-  "${CODEX_HOME:-$HOME/.codex}/skills" \
-  "$HOME/.agents/skills" \
-  "$HOME/.claude/skills" \
-  "$HOME/.config/agents/skills"
-do
-  if [ -d "$base/$SKILL_NAME" ]; then
-    SKILL_DIR="$base/$SKILL_NAME"
-    break
-  fi
-done
-
-if [ -z "$SKILL_DIR" ]; then
-  SEARCH_DIR=$(pwd -P)
-  while :; do
-    for suffix in $CANDIDATE_SUFFIXES; do
-      if [ -d "$SEARCH_DIR/$suffix/$SKILL_NAME" ]; then
-        SKILL_DIR="$SEARCH_DIR/$suffix/$SKILL_NAME"
-        break 2
-      fi
-    done
-    [ "$SEARCH_DIR" = "/" ] && break
-    SEARCH_DIR=$(dirname "$SEARCH_DIR")
-  done
-fi
-
-[ -n "$SKILL_DIR" ] || { echo "Skill not found: $SKILL_NAME" >&2; exit 1; }
-
-echo "$SKILL_DIR"