abelworkflow 0.6.5 → 0.8.0

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "abelworkflow",
-  "version": "0.6.5",
+  "version": "0.8.0",
   "description": "Install AbelWorkflow into ~/.agents and create Claude/Codex symlinks.",
   "type": "module",
   "scripts": {
+    "test": "node --test test/runtime-doc-contracts.test.mjs test/cli-contracts.test.mjs test/codex-config.test.mjs",
     "test:contracts": "node --test test/runtime-doc-contracts.test.mjs test/cli-contracts.test.mjs"
   },
   "bin": {
@@ -22,5 +23,9 @@
   "engines": {
     "node": ">=18"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "dependencies": {
+    "@clack/prompts": "^1.2.0",
+    "picocolors": "^1.1.1"
+  }
 }

package/skills/confidence-check/SKILL.md

@@ -1,124 +1,34 @@
 ---
-name: Confidence Check
+name: confidence-check
 description: Pre-implementation confidence assessment (≥90% required). Use before starting any implementation to verify readiness with duplicate check, architecture compliance, official docs verification, OSS references, and root cause identification.
 ---
 
-# Confidence Check Skill
+# Confidence Check
 
-## Purpose
-
-Prevents wrong-direction execution by assessing confidence **BEFORE** starting implementation.
-
-**Requirement**: ≥90% confidence to proceed with implementation.
-
-**Test Results** (2025-10-21):
-- Precision: 1.000 (no false positives)
-- Recall: 1.000 (no false negatives)
-- 8/8 test cases passed
+Run this BEFORE implementing to prevent wrong-direction work. Requires ≥90% confidence to proceed.
 
 ## When to Use
 
-Use this skill BEFORE implementing any task to ensure:
-- No duplicate implementations exist
-- Architecture compliance verified
-- Official documentation reviewed
-- Working OSS implementations found
-- Root cause properly identified
-
-## Confidence Assessment Criteria
-
-Calculate confidence score (0.0 - 1.0) based on 5 checks:
-
-### 1. No Duplicate Implementations? (25%)
-
-**Check**: Search codebase for existing functionality
-
-```bash
-# Use Grep to search for similar functions
-# Use Glob to find related modules
-```
-
-✅ Pass if no duplicates found
-❌ Fail if similar implementation exists
-
-### 2. Architecture Compliance? (25%)
-
-**Check**: Verify tech stack alignment
-
-- Read `CLAUDE.md`, `AGENTS.md`, `PLANNING.md`
-- Confirm existing patterns used
-- Avoid reinventing existing solutions
-
-✅ Pass if uses existing tech stack (e.g., Supabase, UV, pytest)
-❌ Fail if introduces new dependencies unnecessarily
-
-### 3. Official Documentation Verified? (20%)
-
-**Check**: Review official docs before implementation
-
-- Use Context7 MCP for official docs
-- Use WebFetch for documentation URLs
-- Verify API compatibility
-
-✅ Pass if official docs reviewed
-❌ Fail if relying on assumptions
-
-### 4. Working OSS Implementations Referenced? (15%)
-
-**Check**: Find proven implementations
-
-- Use Tavily MCP or WebSearch
-- Search GitHub for examples
-- Verify working code samples
-
-✅ Pass if OSS reference found
-❌ Fail if no working examples
-
-### 5. Root Cause Identified? (15%)
-
-**Check**: Understand the actual problem
-
-- Analyze error messages
-- Check logs and stack traces
-- Identify underlying issue
-
-✅ Pass if root cause clear
-❌ Fail if symptoms unclear
-
-## Confidence Score Calculation
-
-```
-Total = Check1 (25%) + Check2 (25%) + Check3 (20%) + Check4 (15%) + Check5 (15%)
-
-If Total >= 0.90:  ✅ Proceed with implementation
-If Total >= 0.70:  ⚠️  Present alternatives, ask questions
-If Total < 0.70:   ❌ STOP - Request more context
-```
-
-## Output Format
-
-```
-📋 Confidence Checks:
-   ✅ No duplicate implementations found
-   ✅ Uses existing tech stack
-   ✅ Official documentation verified
-   ✅ Working OSS implementation found
-   ✅ Root cause identified
-
-📊 Confidence: 1.00 (100%)
-✅ High confidence - Proceeding to implementation
-```
+- Before writing or modifying any implementation code
+- Before applying a fix to verify root cause
+- When user asks to "check confidence" or "assess readiness"
 
-## Implementation Details
+## Assessment (5 checks)
 
-The TypeScript implementation is available in `confidence.ts` for reference, containing:
+| Check | Weight | How |
+|---|---|---|
+| No duplicate implementations | 25% | Grep/Glob for similar code |
+| Architecture compliance | 25% | Read CLAUDE.md / AGENTS.md |
+| Official docs verified | 20% | Context7 or WebFetch |
+| OSS reference found | 15% | WebSearch / GitHub |
+| Root cause identified | 15% | Analyze errors and logs |
 
-- `confidenceCheck(context)` - Main assessment function
-- Detailed check implementations
-- Context interface definitions
+## Thresholds
 
-## ROI
+- **≥90%**: Proceed with implementation
+- **70–89%**: Continue investigation, do not implement yet
+- **<70%**: Stop and request more context
 
-**Token Savings**: Spend 100-200 tokens on confidence check to save 5,000-50,000 tokens on wrong-direction work.
+## Output
 
-**Success Rate**: 100% precision and recall in production testing.
+Print the checklist with pass/fail markers, the total score, and the recommended action.

package/skills/confidence-check/confidence.ts

@@ -18,7 +18,7 @@
  *    - Low (<70%): Investigation incomplete, unclear root cause, missing official docs
  */
 
-import { existsSync, readdirSync } from 'fs';
+import { existsSync } from 'fs';
 import { join, dirname } from 'path';
 
 export interface Context {
@@ -238,65 +238,6 @@ export class ConfidenceChecker {
     return context.root_cause_identified ?? false;
   }
 
-  /**
-   * Check if existing patterns can be followed
-   *
-   * Looks for:
-   * - Similar test files
-   * - Common naming conventions
-   * - Established directory structure
-   */
-  private hasExistingPatterns(context: Context): boolean {
-    const testFile = context.test_file;
-    if (!testFile) {
-      return false;
-    }
-
-    const testDir = dirname(testFile);
-
-    // Check for other test files in same directory
-    if (existsSync(testDir)) {
-      try {
-        const files = readdirSync(testDir);
-        const testFiles = files.filter(f =>
-          f.startsWith('test_') && f.endsWith('.py')
-        );
-        return testFiles.length > 1;
-      } catch {
-        return false;
-      }
-    }
-
-    return false;
-  }
-
-  /**
-   * Check if implementation path is clear
-   *
-   * Considers:
-   * - Test name suggests clear purpose
-   * - Markers indicate test type
-   * - Context has sufficient information
-   */
-  private hasClearPath(context: Context): boolean {
-    // Check test name clarity
-    const testName = context.test_name ?? '';
-    if (!testName || testName === 'test_example') {
-      return false;
-    }
-
-    // Check for markers indicating test type
-    const markers = context.markers ?? [];
-    const knownMarkers = new Set([
-      'unit', 'integration', 'hallucination',
-      'performance', 'confidence_check', 'self_check'
-    ]);
-
-    const hasMarkers = markers.some(m => knownMarkers.has(m));
-
-    return hasMarkers || testName.length > 10;
-  }
-
   /**
    * Get recommended action based on confidence level
    *

package/skills/grok-search/.env.example

@@ -6,9 +6,9 @@ GROK_API_URL=
 # 必填项：你的 API 密钥
 GROK_API_KEY=
 
-# 可选项：使用的 Grok 模型（默认：grok-4-fast）
-# 常用选项：grok-4-fast
-GROK_MODEL=
+# 可选项：使用的 Grok 模型（默认：grok-4.20-auto）
+# 常用选项：grok-4.20-auto, grok-4-fast
+GROK_MODEL=grok-4.20-auto
 
 # 可选项：启用调试模式（true/false）
 GROK_DEBUG=false

package/skills/grok-search/SKILL.md

@@ -24,7 +24,7 @@ Use this skill for web search, webpage retrieval, and current-information lookup
 ```bash
 cp "<SKILL_DIR>/.env.example" "<SKILL_DIR>/.env"
 
-python "<SKILL_DIR>/scripts/groksearch_entry.py" web_search --query "search terms" [--platform "GitHub"] [--min-results 3] [--max-results 10] [--model "grok-4-fast"] [--extra-sources 3]
+python "<SKILL_DIR>/scripts/groksearch_entry.py" web_search --query "search terms" [--platform "GitHub"] [--min-results 3] [--max-results 10] [--model "grok-4.20-auto"] [--extra-sources 3]
 
 python "<SKILL_DIR>/scripts/groksearch_entry.py" web_fetch --url "https://..." [--out file.md] [--fallback-grok]
 

package/skills/grok-search/scripts/groksearch_cli.py

@@ -65,7 +65,7 @@ load_dotenv()
 
 class Config:
     _instance = None
-    _DEFAULT_MODEL = "grok-4-fast"
+    _DEFAULT_MODEL = "grok-4.20-auto"
 
     def __new__(cls):
         if cls._instance is None:

package/skills/prompt-enhancer/.env.example

@@ -1,14 +1,12 @@
 # Prompt Enhancer CLI configuration
 # Copy this file to .env and fill in the values you want to use.
 
-# Optional: Anthropic API key (preferred when set)
-ANTHROPIC_API_KEY=
+# Optional: third-party OpenAI-compatible base URL
+PE_API_URL=
 
-# Optional: OpenAI API key (fallback when Anthropic key is absent)
-OPENAI_API_KEY=
+# Optional: third-party OpenAI-compatible API key
+PE_API_KEY=
 
-# Optional: model override
-# Examples:
-#   claude-sonnet-4-20250514
-#   gpt-4o
+# Optional: model name for the third-party endpoint
+# Leave all three fields blank to use the current agent directly.
 PE_MODEL=

package/skills/prompt-enhancer/ADVANCED.md

@@ -5,22 +5,20 @@
 Use the bootstrap entrypoint from the installed skill directory:
 
 ```bash
-# Basic usage
+# Assuming third-party config is already set in <SKILL_DIR>/.env or the environment
 python "<SKILL_DIR>/scripts/prompt_enhancer_entry.py" "your prompt here"
-
-# With custom model
-PE_MODEL=claude-sonnet-4-20250514 python "<SKILL_DIR>/scripts/prompt_enhancer_entry.py" "your prompt"
 ```
 
 `prompt_enhancer_entry.py` is the canonical entrypoint. It creates or reuses a skill-local virtual environment and then runs `scripts/enhance.py`.
+If `PE_API_URL`, `PE_API_KEY`, and `PE_MODEL` are not all present, do not call the script; rewrite the prompt directly with the current agent instead.
 
 ## Environment Variables
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `ANTHROPIC_API_KEY` | Anthropic API key for Claude | - |
-| `OPENAI_API_KEY` | OpenAI API key (fallback) | - |
-| `PE_MODEL` | Model to use | `claude-sonnet-4-20250514` |
+| `PE_API_URL` | Third-party OpenAI-compatible base URL | - |
+| `PE_API_KEY` | Third-party OpenAI-compatible API key | - |
+| `PE_MODEL` | Model to use on the third-party endpoint | - |
 | `PE_DEBUG` | Print bootstrap and fallback diagnostics to `stderr` | `0` |
 | `PROMPT_ENHANCER_VENV_DIR` | Override the skill-local venv path | `skills/prompt-enhancer/.venv` |
 | `PROMPT_ENHANCER_PYTHON` | Python version/spec for `uv venv --python` | - |
@@ -41,6 +39,8 @@ The enhanced prompt is written to `stdout`. Usage or debug diagnostics stay on `
 
 ### Piping Output
 
+Assuming `PE_API_URL`, `PE_API_KEY`, and `PE_MODEL` are already configured:
+
 ```bash
 # Pipe to clipboard (macOS)
 python "<SKILL_DIR>/scripts/prompt_enhancer_entry.py" "my prompt" | pbcopy
@@ -54,15 +54,17 @@ python "<SKILL_DIR>/scripts/prompt_enhancer_entry.py" "my prompt" | claude -p
 
 ### In Shell Scripts
 
+Assuming the environment is already configured:
+
 ```bash
 #!/bin/bash
 ENHANCED=$(python "$HOME/.agents/skills/prompt-enhancer/scripts/prompt_enhancer_entry.py" "$1")
 echo "$ENHANCED"
 ```
 
-## Manual Enhancement (No API)
+## Manual Enhancement (Current Agent)
 
-If no API key is available, you can manually apply the enhancement principles:
+If the user does not provide `url`, `apiKey`, and `model`, use the current agent directly and apply the enhancement principles:
 
 1. Read the user's prompt
 2. Apply the template from [TEMPLATE.md](TEMPLATE.md)
@@ -94,8 +96,8 @@ Run the entrypoint without a prompt to print usage information:
 python "$HOME/.agents/skills/prompt-enhancer/scripts/prompt_enhancer_entry.py"
 ```
 
-### No API Key
-The script will fall back to a local template-based enhancement if no API key is found.
+### Missing Third-Party Config
+The script requires `PE_API_URL`, `PE_API_KEY`, and `PE_MODEL`. If any field is missing, skip the script and use the current agent directly.
 
 ### Debug Fallbacks
-Set `PE_DEBUG=1` to show dependency-install, provider, or fallback diagnostics on `stderr`.
+Set `PE_DEBUG=1` to show dependency-install or configuration diagnostics on `stderr`.

package/skills/prompt-enhancer/SKILL.md

@@ -19,12 +19,16 @@ Do not use this for general writing edits like email, docs, or PR copy.
 
 ## Do
 
+- Default path: rewrite the prompt directly with the current agent using the structure from [TEMPLATE.md](TEMPLATE.md).
+- Third-party path: use the Python entrypoint only when the user explicitly provides `url`, `apiKey`, and `model`, or when all three are already configured in `<SKILL_DIR>/.env`.
+
 ```bash
 python "<SKILL_DIR>/scripts/prompt_enhancer_entry.py" "user's raw prompt here"
 ```
 
 - Do not call `scripts/enhance.py` directly.
 - Use the installed skill directory for `<SKILL_DIR>`.
+- If any of `url`, `apiKey`, or `model` is missing, do not invoke the script. Use the current agent directly instead.
 - Optional setup: `cp "<SKILL_DIR>/.env.example" "<SKILL_DIR>/.env"`
 
 ## Output
@@ -33,7 +37,7 @@ python "<SKILL_DIR>/scripts/prompt_enhancer_entry.py" "user's raw prompt here"
 - Keep `stderr` for usage or optional debug output only.
 - Preserve the user's intent and explicit constraints.
 - Add structure and missing execution context only when it helps the agent act.
-- When falling back to the local template, use placeholders for unknown context instead of inventing new requirements.
+- When running directly in the current agent, use placeholders for unknown context instead of inventing new requirements.
 
 ## Notes
 

package/skills/prompt-enhancer/scripts/enhance.py

@@ -1,8 +1,10 @@
 #!/usr/bin/env python3
-"""Prompt Enhancer CLI."""
+"""Prompt Enhancer CLI for OpenAI-compatible endpoints."""
 
+import argparse
 import os
 import sys
+from typing import Tuple
 
 from _dotenv import load_dotenv
 
@@ -42,110 +44,147 @@ Output Template:
 """
 
 
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="prompt_enhancer_entry.py",
+        description="Enhance a prompt through a third-party OpenAI-compatible API.",
+    )
+    parser.add_argument("--url", dest="api_url", help="Third-party OpenAI-compatible base URL.")
+    parser.add_argument("--api-key", dest="api_key", help="Third-party OpenAI-compatible API key.")
+    parser.add_argument("--model", help="Model name on the third-party endpoint.")
+    parser.add_argument("--prompt", help="Prompt text to enhance.")
+    parser.add_argument("prompt_parts", nargs="*", help=argparse.SUPPRESS)
+    return parser.parse_args()
+
+
 def debug_enabled() -> bool:
-    """Return True when debug logging is explicitly enabled."""
     value = os.environ.get("PE_DEBUG", "")
     return value.strip().lower() in {"1", "true", "yes", "on"}
 
 
-def get_env_or_default(name: str, default: str) -> str:
-    """Return default when an env var is missing or blank."""
-    value = os.environ.get(name)
-    if value is None:
-        return default
-
-    value = value.strip()
-    return value or default
-
-
-def enhance_with_anthropic(prompt: str, api_key: str) -> str:
-    """Enhance prompt using Anthropic API."""
+def resolve_prompt(args: argparse.Namespace) -> str:
+    prompt = args.prompt.strip() if args.prompt else ""
+    if prompt:
+        return prompt
+    joined = " ".join(args.prompt_parts).strip()
+    if joined:
+        return joined
+    raise ValueError("Missing prompt. Pass --prompt \"...\" or a positional prompt.")
+
+
+def first_non_empty(*values: str) -> str:
+    for value in values:
+        stripped = value.strip()
+        if stripped:
+            return stripped
+    return ""
+
+
+def env_value(*names: str) -> str:
+    return first_non_empty(*(os.environ.get(name, "") for name in names))
+
+
+def resolve_config(args: argparse.Namespace) -> Tuple[str, str, str, str]:
+    api_url = (args.api_url or os.environ.get("PE_API_URL", "")).strip()
+    api_key = (args.api_key or os.environ.get("PE_API_KEY", "")).strip()
+    model = (args.model or os.environ.get("PE_MODEL", "")).strip()
+
+    missing = []
+    if not api_url:
+        missing.append("url")
+    if not api_key:
+        missing.append("apiKey")
+    if not model:
+        missing.append("model")
+    if missing:
+        has_openai_compatible_transport = bool(api_url or api_key)
+        if has_openai_compatible_transport:
+            raise ValueError(
+                "Missing third-party OpenAI-compatible config: "
+                + ", ".join(missing)
+                + ". If these fields are unavailable, use the current agent directly."
+            )
+
+        legacy_anthropic_key = env_value("ANTHROPIC_API_KEY")
+        if legacy_anthropic_key:
+            return "anthropic", "", legacy_anthropic_key, first_non_empty(model, "claude-sonnet-4-20250514")
+
+        legacy_openai_key = env_value("OPENAI_API_KEY")
+        if legacy_openai_key:
+            return "openai", "", legacy_openai_key, first_non_empty(model, "gpt-4o")
+
+        raise ValueError(
+            "Missing third-party OpenAI-compatible config: "
+            + ", ".join(missing)
+            + ". If these fields are unavailable, use the current agent directly."
+        )
+    return "openai-compatible", api_url, api_key, model
+
+
+def enhance_with_anthropic(prompt: str, api_key: str, model: str) -> str:
     try:
         import anthropic
     except ImportError:
-        raise RuntimeError(
-            "Missing dependency: anthropic. Install dependencies for the configured provider."
-        ) from None
+        raise RuntimeError("Missing dependency: anthropic. Install dependencies for the configured provider.") from None
 
     client = anthropic.Anthropic(api_key=api_key)
     message = client.messages.create(
-        model=get_env_or_default("PE_MODEL", "claude-sonnet-4-20250514"),
+        model=model,
         max_tokens=2048,
         system=SYSTEM_PROMPT,
-        messages=[{"role": "user", "content": prompt}]
+        messages=[{"role": "user", "content": prompt}],
     )
     return message.content[0].text
 
 
-def enhance_with_openai(prompt: str, api_key: str) -> str:
-    """Enhance prompt using OpenAI API."""
+def _extract_response_text(response) -> str:
+    content = response.choices[0].message.content
+    if isinstance(content, str):
+        return content
+    if content is None:
+        raise RuntimeError("The provider returned an empty response.")
+    return str(content)
+
+
+def enhance_with_openai(prompt: str, api_key: str, model: str, api_url: str = "") -> str:
     try:
-        import openai
+        from openai import OpenAI
     except ImportError:
-        raise RuntimeError(
-            "Missing dependency: openai. Install dependencies for the configured provider."
-        ) from None
+        raise RuntimeError("Missing dependency: openai. Install dependencies for the configured provider.") from None
 
-    client = openai.OpenAI(api_key=api_key)
+    kwargs = {"api_key": api_key}
+    if api_url:
+        kwargs["base_url"] = api_url
+    client = OpenAI(**kwargs)
     response = client.chat.completions.create(
-        model=get_env_or_default("PE_MODEL", "gpt-4o"),
+        model=model,
         messages=[
             {"role": "system", "content": SYSTEM_PROMPT},
-            {"role": "user", "content": prompt}
-        ]
+            {"role": "user", "content": prompt},
+        ],
     )
-    return response.choices[0].message.content
-
-
-def enhance_locally(prompt: str) -> str:
-    """Enhance prompt using local template (no API)."""
-    return f"""# Context
-[Add only the known repo, file, stack, or runtime context. If unknown, use placeholders like [files], [stack], or [environment].]
-
-# Objective
-{prompt}
+    return _extract_response_text(response)
 
-# Step-by-Step Instructions
-1. Restate the task precisely without changing the user's intent.
-2. Carry forward every explicit constraint from the original prompt.
-3. Add only the minimum missing execution context needed to act.
-4. If important details are unknown, leave placeholders instead of inventing requirements.
-5. Return the rewritten prompt in this structure.
-
-# Constraints
-- Preserve the user's intent and explicit constraints.
-- Do not invent product, compatibility, or implementation requirements.
-- Keep the result concise, specific, and actionable for a coding agent.
-"""
-
-
-def main():
-    if len(sys.argv) < 2:
-        print("Usage: prompt_enhancer_entry.py <prompt>", file=sys.stderr)
-        print("Example: prompt_enhancer_entry.py 'Write a login component'", file=sys.stderr)
-        print("Environment: ANTHROPIC_API_KEY | OPENAI_API_KEY | PE_MODEL", file=sys.stderr)
-        sys.exit(1)
-
-    prompt = " ".join(sys.argv[1:])
-
-    # Try Anthropic first, then OpenAI, then local
-    anthropic_key = os.environ.get("ANTHROPIC_API_KEY")
-    openai_key = os.environ.get("OPENAI_API_KEY")
 
+def main() -> None:
     try:
-        if anthropic_key:
-            result = enhance_with_anthropic(prompt, anthropic_key)
-        elif openai_key:
-            result = enhance_with_openai(prompt, openai_key)
+        args = parse_args()
+        prompt = resolve_prompt(args)
+        provider, api_url, api_key, model = resolve_config(args)
+        if provider == "anthropic":
+            print(enhance_with_anthropic(prompt, api_key, model))
         else:
-            result = enhance_locally(prompt)
-
-        print(result)
-    except Exception as e:
+            print(enhance_with_openai(prompt, api_key, model, api_url))
+    except Exception as exc:
         if debug_enabled():
-            print(f"Error: {e}", file=sys.stderr)
-            print("\nFalling back to local template...", file=sys.stderr)
-        print(enhance_locally(prompt))
+            print(f"Error: {exc}", file=sys.stderr)
+        else:
+            msg = str(exc)
+            if "Missing third-party OpenAI-compatible config" in msg:
+                print("Missing API configuration. Use the current agent directly instead, or set PE_API_URL, PE_API_KEY, PE_MODEL.", file=sys.stderr)
+            else:
+                print(msg, file=sys.stderr)
+        sys.exit(1)
 
 
 if __name__ == "__main__":