abelworkflow 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "abelworkflow",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Install AbelWorkflow into ~/.agents and create Claude/Codex symlinks.",
   "type": "module",
   "bin": {

package/skills/grok-search/SKILL.md

@@ -2,113 +2,42 @@
 name: grok-search
 description: |
   Enhanced web search and real-time content retrieval via Grok API. Use when: (1) Web search / information retrieval / fact-checking, (2) Webpage content extraction / URL parsing, (3) Breaking knowledge cutoff limits for current information, (4) Real-time news and technical documentation, (5) Multi-source information aggregation. Triggers: "search for", "find information about", "latest news", "current", "fetch webpage", "get content from URL". IMPORTANT: This skill REPLACES built-in WebSearch/WebFetch with CLI commands.
+allowed-tools: Bash(python:*), Bash(python3:*), Bash(uv:*), Read, Grep
 ---
 
 # Grok Search
 
-Enhanced web search via Grok API CLI.
+Use this skill for web search, webpage retrieval, and current-information lookups. Replace built-in `WebSearch` and `WebFetch` with the CLI below.
 
-## CLI Commands
+## Rules
 
-```bash
-# Canonical entrypoint (agents + cross-platform)
-# - Resolve the installed skill directory first; do not assume the current repo contains skills/grok-search
-# - Prefer user-level skill directories under $HOME first, for example:
-#   $HOME/.claude/skills/grok-search
-#   $HOME/.codex/skills/grok-search
-#   $HOME/.config/agents/skills/grok-search
-# - If not found, check project-level locations:
-#   .claude/skills/grok-search
-#   .codex/skills/grok-search
-#   .agents/skills/grok-search
-# - Use system python only to bootstrap; entry.py creates/reuses repo-local .venv
-# - Never invoke scripts/groksearch_cli.py directly
-#
-# One-time setup:
-#   cp .env.example .env
-python "<SKILL_DIR>/scripts/groksearch_entry.py" --help
+- Always call `python "<SKILL_DIR>/scripts/groksearch_entry.py" ...`.
+- Do not call `scripts/groksearch_cli.py` directly.
+- The entrypoint auto-loads `<SKILL_DIR>/.env`.
+- Required env: `GROK_API_URL`, `GROK_API_KEY`.
+- Optional env: `GROK_MODEL`, `GROK_DEBUG`, `GROK_RETRY_*`, `TAVILY_API_KEY`, `TAVILY_API_URL`, `TAVILY_ENABLED`, `GROKSEARCH_VENV_DIR`, `GROKSEARCH_PYTHON`, `AGENTS_SKILLS_PYTHON`.
+- For time-sensitive answers, include source URLs and the relevant date.
+- Start with `web_search`; use `web_fetch` for page content; use `web_map` for site structure.
 
-# Environment (required): GROK_API_URL, GROK_API_KEY
-# Environment (optional): GROK_MODEL, GROK_DEBUG, GROK_RETRY_*
-# Environment (optional fetch/map): TAVILY_API_KEY, TAVILY_API_URL, TAVILY_ENABLED
-#
-# .env path:
-# skills/grok-search/.env
-#
-# Bootstrap controls (optional):
-# GROKSEARCH_VENV_DIR=/path/to/venv
-# GROKSEARCH_PYTHON=3.12
-# AGENTS_SKILLS_PYTHON=/abs/path/to/python
+## Commands
 
-# Optional if you intentionally change into the installed skill directory first:
-# cd "<SKILL_DIR>" && python scripts/groksearch_entry.py --help
+```bash
+cp "<SKILL_DIR>/.env.example" "<SKILL_DIR>/.env"
 
-# Web search
-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 6]
-# If you need broader search coverage, you can add Tavily sources explicitly, for example: --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-fast"] [--extra-sources 3]
 
-# Fetch webpage
 python "<SKILL_DIR>/scripts/groksearch_entry.py" web_fetch --url "https://..." [--out file.md] [--fallback-grok]
 
-# Map website structure (Tavily)
-python "<SKILL_DIR>/scripts/groksearch_entry.py" web_map --url "https://..." [--max-depth 2] [--limit 80]
+python "<SKILL_DIR>/scripts/groksearch_entry.py" web_map --url "https://..." [--instructions "focus area"] [--max-depth 2] [--limit 80]
 
-# Check config
 python "<SKILL_DIR>/scripts/groksearch_entry.py" get_config_info [--no-test]
 
-# Toggle built-in tools
 python "<SKILL_DIR>/scripts/groksearch_entry.py" toggle_builtin_tools --action on|off|status [--root /path/to/project]
 ```
 
-## Tool Routing Policy
-### Forced Replacement Rules
-
-| 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 [<sup>1</sup>](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
+## Failure Recovery
 
-| Prohibited | Correct |
-|------------|---------|
-| No source citation | Include `Source [<sup>1</sup>](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 |
+- 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.

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

@@ -0,0 +1,28 @@
+"""Shared .env loader for Grok Search scripts."""
+
+import os
+from pathlib import Path
+
+
+def load_dotenv() -> bool:
+    env_path = Path(__file__).resolve().parent.parent / ".env"
+    if not env_path.exists():
+        return False
+    try:
+        with open(env_path, "r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line or line.startswith("#") or "=" not in line:
+                    continue
+                key, _, value = line.partition("=")
+                key = key.strip()
+                value = value.strip()
+                if (value.startswith('"') and value.endswith('"')) or (
+                    value.startswith("'") and value.endswith("'")
+                ):
+                    value = value[1:-1]
+                if key and not os.environ.get(key):
+                    os.environ[key] = value
+        return True
+    except IOError:
+        return False

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

@@ -46,8 +46,8 @@ def load_dotenv() -> bool:
                         if (value.startswith('"') and value.endswith('"')) or \
                            (value.startswith("'") and value.endswith("'")):
                             value = value[1:-1]
-                        # 仅在环境变量中未设置时才设置
-                        if key and key not in os.environ:
+                        # 允许 .env 覆盖空字符串环境变量
+                        if key and not os.environ.get(key):
                             os.environ[key] = value
             return True
         except IOError:

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

@@ -8,23 +8,35 @@ import sys
 from pathlib import Path
 from typing import Optional
 
+from _dotenv import load_dotenv
+
 
 ROOT_DIR = Path(__file__).resolve().parent.parent
-VENV_DIR = Path(os.environ.get("GROKSEARCH_VENV_DIR", str(ROOT_DIR / ".venv")))
 REQ_FILE = ROOT_DIR / "requirements.txt"
 CLI_PY = ROOT_DIR / "scripts" / "groksearch_cli.py"
 
 
+def venv_dir() -> Path:
+    configured = os.environ.get("GROKSEARCH_VENV_DIR")
+    if not configured:
+        return ROOT_DIR / ".venv"
+    dir_path = Path(configured).expanduser()
+    if dir_path.is_absolute():
+        return dir_path
+    return ROOT_DIR / dir_path
+
+
 def venv_python() -> Optional[Path]:
+    dir_path = venv_dir()
     candidates = []
     if sys.platform == "win32":
         candidates.extend(
             [
-                VENV_DIR / "Scripts" / "python.exe",
-                VENV_DIR / "Scripts" / "python",
+                dir_path / "Scripts" / "python.exe",
+                dir_path / "Scripts" / "python",
             ]
         )
-    candidates.append(VENV_DIR / "bin" / "python")
+    candidates.append(dir_path / "bin" / "python")
     for candidate in candidates:
         if candidate.is_file():
             return candidate
@@ -57,19 +69,20 @@ def find_system_python() -> Optional[str]:
 
 
 def create_venv() -> None:
+    dir_path = venv_dir()
     if has_uv():
         command = ["uv", "venv"]
         spec = python_spec()
         if spec:
             command.extend(["--python", spec])
-        command.append(str(VENV_DIR))
+        command.append(str(dir_path))
         subprocess.run(command, check=True)
         return
     python_bin = find_system_python()
     if not python_bin:
         print("Error: No usable uv or python found. Cannot create virtual environment.", file=sys.stderr)
         sys.exit(1)
-    subprocess.run([python_bin, "-m", "venv", str(VENV_DIR)], check=True)
+    subprocess.run([python_bin, "-m", "venv", str(dir_path)], check=True)
 
 
 def install_deps(python_bin: Path) -> None:
@@ -90,15 +103,17 @@ def install_deps(python_bin: Path) -> None:
 
 
 def validate_venv_dir() -> None:
-    if VENV_DIR.exists() and not VENV_DIR.is_dir():
-        print(f"Error: {VENV_DIR} exists but is not a directory.", file=sys.stderr)
+    dir_path = venv_dir()
+    if dir_path.exists() and not dir_path.is_dir():
+        print(f"Error: {dir_path} exists but is not a directory.", file=sys.stderr)
         sys.exit(1)
-    if VENV_DIR.is_dir() and not (VENV_DIR / "pyvenv.cfg").exists() and venv_python() is None:
-        print(f"Error: {VENV_DIR} exists but is not a valid venv.", file=sys.stderr)
+    if dir_path.is_dir() and not (dir_path / "pyvenv.cfg").exists() and venv_python() is None:
+        print(f"Error: {dir_path} exists but is not a valid venv.", file=sys.stderr)
         sys.exit(1)
 
 
 def main() -> None:
+    load_dotenv()
     validate_venv_dir()
     python_bin = venv_python()
     if python_bin is None:

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

@@ -0,0 +1,14 @@
+# 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: OpenAI API key (fallback when Anthropic key is absent)
+OPENAI_API_KEY=
+
+# Optional: model override
+# Examples:
+#   claude-sonnet-4-20250514
+#   gpt-4o
+PE_MODEL=

package/skills/prompt-enhancer/ADVANCED.md

@@ -2,16 +2,18 @@
 
 ## Using the Python Script Directly
 
-The `scripts/enhance.py` script can be used standalone:
+Use the bootstrap entrypoint from the installed skill directory:
 
 ```bash
 # Basic usage
-python3 scripts/enhance.py "your prompt here"
+python "<SKILL_DIR>/scripts/prompt_enhancer_entry.py" "your prompt here"
 
-# With custom model (if API key is set)
-ANTHROPIC_API_KEY=sk-ant-... python3 scripts/enhance.py "your prompt"
+# 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`.
+
 ## Environment Variables
 
 | Variable | Description | Default |
@@ -19,27 +21,42 @@ ANTHROPIC_API_KEY=sk-ant-... python3 scripts/enhance.py "your prompt"
 | `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_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` | - |
+| `AGENTS_SKILLS_PYTHON` | Absolute path to fallback/bootstrap Python | - |
+
+## Local `.env`
+
+The CLI loads `<SKILL_DIR>/.env` automatically if present:
+
+```bash
+cp "<SKILL_DIR>/.env.example" "<SKILL_DIR>/.env"
+python "<SKILL_DIR>/scripts/prompt_enhancer_entry.py" "your prompt here"
+```
 
 ## Integration with Other Tools
 
+The enhanced prompt is written to `stdout`. Usage or debug diagnostics stay on `stderr`, and bootstrap/fallback diagnostics are only emitted when `PE_DEBUG=1`.
+
 ### Piping Output
 
 ```bash
 # Pipe to clipboard (macOS)
-python3 scripts/enhance.py "my prompt" | pbcopy
+python "<SKILL_DIR>/scripts/prompt_enhancer_entry.py" "my prompt" | pbcopy
 
 # Pipe to file
-python3 scripts/enhance.py "my prompt" > enhanced.md
+python "<SKILL_DIR>/scripts/prompt_enhancer_entry.py" "my prompt" > enhanced.md
 
 # Chain with other commands
-python3 scripts/enhance.py "my prompt" | claude -p
+python "<SKILL_DIR>/scripts/prompt_enhancer_entry.py" "my prompt" | claude -p
 ```
 
 ### In Shell Scripts
 
 ```bash
 #!/bin/bash
-ENHANCED=$(python3 ~/.agents/skills/prompt-enhancer/scripts/enhance.py "$1")
+ENHANCED=$(python "$HOME/.agents/skills/prompt-enhancer/scripts/prompt_enhancer_entry.py" "$1")
 echo "$ENHANCED"
 ```
 
@@ -49,7 +66,9 @@ If no API key is available, you can manually apply the enhancement principles:
 
 1. Read the user's prompt
 2. Apply the template from [TEMPLATE.md](TEMPLATE.md)
-3. Structure the output with:
+3. Preserve every explicit user constraint
+4. Use placeholders for unknown context instead of inventing requirements
+5. Structure the output with:
    - Context section
    - Objective section
    - Step-by-step instructions
@@ -58,17 +77,25 @@ If no API key is available, you can manually apply the enhancement principles:
 ## Troubleshooting
 
 ### Script Not Found
-Ensure the skill is installed in the correct location:
+Verify the canonical entrypoint exists:
 ```bash
-ls ~/.agents/skills/prompt-enhancer/scripts/enhance.py
+ls "$HOME/.agents/skills/prompt-enhancer/scripts/prompt_enhancer_entry.py"
 ```
 
 ### Permission Denied
-Make the script executable:
+Run it through Python instead of executing the file directly:
+```bash
+python "$HOME/.agents/skills/prompt-enhancer/scripts/prompt_enhancer_entry.py" "your prompt here"
+```
+
+### Show Usage
+Run the entrypoint without a prompt to print usage information:
 ```bash
-chmod +x ~/.agents/skills/prompt-enhancer/scripts/enhance.py
+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.
 
+### Debug Fallbacks
+Set `PE_DEBUG=1` to show dependency-install, provider, or fallback diagnostics on `stderr`.

package/skills/prompt-enhancer/SKILL.md

@@ -1,71 +1,45 @@
 ---
 name: prompt-enhancer
-description: Enhance and refine prompts for AI coding agents using Chain-of-Thought reasoning. Use when user asks to improve, optimize, rewrite, or enhance a prompt. Transforms vague requests into structured, high-context instructions for Claude Code, Codex, or Gemini CLI.
-allowed-tools: Bash(python3:*), Bash(pe:*), Read, Grep
+description: |
+  Rewrite a raw prompt into a clearer prompt for a coding agent. Use only when the user explicitly asks to improve, optimize, rewrite, or structure a prompt for Codex, Claude Code, Gemini CLI, or another AI agent. Triggers: "improve this prompt", "rewrite this prompt", "optimize this prompt for Codex", "make this prompt better for an AI agent".
+allowed-tools: Bash(python:*), Bash(python3:*), Bash(uv:*), Read, Grep
 ---
 
-# Prompt Enhancer Skill
+# Prompt Enhancer
 
-Transforms vague or simple prompts into structured, high-context instructions optimized for AI coding agents.
+Rewrite raw prompts into concise, structured prompts for coding agents.
 
-## When to Use
+## Use When
 
-- User asks to "improve my prompt" or "make this prompt better"
-- User wants to "optimize this instruction for Claude/Codex"
-- User needs help writing a better prompt for an AI agent
-- User mentions "prompt engineering" or "rewrite this"
+- The input itself is a prompt or instruction for an AI agent.
+- The user explicitly asks to improve, optimize, or rewrite that prompt.
+- The target is a coding agent such as Codex, Claude Code, or Gemini CLI.
 
-## Quick Start
+Do not use this for general writing edits like email, docs, or PR copy.
 
-Run the enhance script with the user's prompt:
+## Do
 
 ```bash
-python3 ~/.agents/skills/prompt-enhancer/scripts/enhance.py "user's raw prompt here"
+python "<SKILL_DIR>/scripts/prompt_enhancer_entry.py" "user's raw prompt here"
 ```
 
-## How It Works
+- Do not call `scripts/enhance.py` directly.
+- Use the installed skill directory for `<SKILL_DIR>`.
+- Optional setup: `cp "<SKILL_DIR>/.env.example" "<SKILL_DIR>/.env"`
 
-The enhancer applies these principles:
+## Output
 
-1. **Add Context**: What project/tech stack is involved?
-2. **Clarify Objective**: What exactly should be accomplished?
-3. **Chain of Thought**: Add step-by-step reasoning instructions
-4. **Define Constraints**: What are the boundaries and requirements?
-5. **Specify Output**: What format should the result be in?
+- Read the enhanced prompt from `stdout`.
+- 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.
 
-## Output Format
-
-The enhanced prompt follows this structure:
-
-```markdown
-# Context
-[Refined context description]
-
-# Objective
-[Precise task definition]
-
-# Step-by-Step Instructions
-1. [Step 1]
-2. [Step 2]
-...
-
-# Constraints
-- [Constraint 1]
-- [Constraint 2]
-```
-
-## Additional Resources
-
-- For advanced usage patterns, see [ADVANCED.md](ADVANCED.md)
-- For the system prompt template, see [TEMPLATE.md](TEMPLATE.md)
-
-## Alternative: Use `pe` CLI
-
-If you have the `pe` CLI installed globally:
-
-```bash
-pe "user's raw prompt here"
-```
-
-Install via: `npm install -g prompt-enhancer` (or clone repo and `npm link`)
+## Notes
 
+- Local config file: `<SKILL_DIR>/.env`
+- The entrypoint auto-loads `<SKILL_DIR>/.env` before bootstrap and dependency install.
+- Optional debug flag: `PE_DEBUG=1`
+- Bootstrap controls: `PROMPT_ENHANCER_VENV_DIR`, `PROMPT_ENHANCER_PYTHON`, `AGENTS_SKILLS_PYTHON`
+- Setup and troubleshooting: [ADVANCED.md](ADVANCED.md)
+- Prompt template reference: [TEMPLATE.md](TEMPLATE.md)

package/skills/prompt-enhancer/requirements.txt

@@ -0,0 +1,2 @@
+anthropic>=0.34,<1
+openai>=1.30,<2

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

@@ -0,0 +1,28 @@
+"""Shared .env loader for Prompt Enhancer scripts."""
+
+import os
+from pathlib import Path
+
+
+def load_dotenv() -> bool:
+    env_path = Path(__file__).resolve().parent.parent / ".env"
+    if not env_path.exists():
+        return False
+    try:
+        with open(env_path, "r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line or line.startswith("#") or "=" not in line:
+                    continue
+                key, _, value = line.partition("=")
+                key = key.strip()
+                value = value.strip()
+                if (value.startswith('"') and value.endswith('"')) or (
+                    value.startswith("'") and value.endswith("'")
+                ):
+                    value = value[1:-1]
+                if key and not os.environ.get(key):
+                    os.environ[key] = value
+        return True
+    except IOError:
+        return False