abelworkflow 1.0.0-rc.1 → 1.0.0

package/lib/templates/workflow/commands/abel-plan.md

@@ -1,82 +0,0 @@
----
-name: abel-plan
-description: Refine approved change into a zero-decision executable plan.
-category: abel
-tags: [abel, plan, PBT]
-argument-hint: [change_name]
----
-<!-- ABEL:START -->
-**Guardrails**
-- Strictly adhere to **OpenSpec** rules when writing **standardized spec-structured projects**.
-- The goal of this phase is to eliminate ALL decision points from the task flow—implementation should be pure mechanical execution.
-- Do not proceed to implementation until every ambiguity is resolved and every constraint is explicitly documented.
-- Every requirement must have Property-Based Testing (PBT) properties defined—focus on invariants, not just example-based tests.
-- If constraints cannot be fully specified, escalate back to the user or return to the research phase rather than making assumptions.
-- Refer to `openspec/AGENTS.md` for additional conventions; run `openspec update` if the file is missing.
-
-**Skill Integration**: See `Stage Skill Matrix` (Plan column)
-
-**FORBIDDEN**: Direct implementation code generation
-
-**Steps**
-1. Run `openspec view` to display all **Active Changes**, then confirm with the user which change folder (`<change_name>`) they wish to refine into a zero-decision plan.
-
-2. Navigate to `openspec/changes/<change_name>/` and review existing artifacts:
-   - Check `openspec status --change <change_name>` for artifact completion
-   - Use `openspec instructions specs --change <change_name>` for specs guidance
-
-3. **Implementation Analysis**: Perform systematic analysis to derive a plan. If the proposal has 3+ interconnected requirements, first break it down into components, identify dependencies, evaluate architectural trade-offs, and surface potential conflicts. Then invoke `/context7-auto-research` to validate framework/library choices:
-   ```
-   /context7-auto-research: "For each technology mentioned in change <change_name>, retrieve official documentation patterns and best practices."
-   ```
-   Produce a consolidated, constraint-complete plan and list any missing constraints as questions to the user.
-
-4. **Uncertainty Elimination Audit**: Invoke skills to detect and eliminate remaining ambiguities:
-   ```
-   # First, validate against existing codebase patterns
-   {{CODEBASE_RETRIEVAL_PATTERN_AUDIT}}
-   # Then audit for ambiguities directly and list them explicitly
-   Review change <change_name> for decision points that remain unspecified. For each: [AMBIGUITY] <description> → [REQUIRED CONSTRAINT] <what must be specified>.
-   Identify implicit assumptions in change <change_name>. For each: [ASSUMPTION] <description> → [EXPLICIT CONSTRAINT NEEDED] <concrete specification>.
-   ```
-   
-   **Anti-Pattern Detection** (flag and reject):
-   - Information collection without decision boundaries (e.g., "JWT vs OAuth2 vs session—all viable")
-   - Technical comparisons without selection criteria
-   - Deferred decisions marked as "to be determined during implementation"
-   
-   **Target Pattern** (required for approval):
-   - Explicit technology choices with parameters (e.g., "JWT with accessToken TTL=15min, refreshToken TTL=7days")
-   - Concrete algorithm selections with configurations (e.g., "bcrypt with cost factor=12")
-   - Precise behavioral rules (e.g., "Lock account for 30min after 5 failed login attempts")
-   
-   Iterate with user until ALL ambiguities are resolved into explicit constraints.
-
-5. **PBT Property Extraction**: Invoke skills to derive testable invariants:
-   ```
-   "Extract Property-Based Testing properties from change <change_name>. For each requirement: [INVARIANT] <must always hold> → [FALSIFICATION STRATEGY] <how to generate counterexamples>."
-   "Define system properties for change <change_name>: [PROPERTY] <name> | [DEFINITION] <formal description> | [BOUNDARY CONDITIONS] <edge cases> | [COUNTEREXAMPLE GENERATION] <approach>."
-   ```
-   
-   **PBT Property Categories to Extract**:
-   - **Commutativity/Associativity**: Order-independent operations
-   - **Idempotency**: Repeated operations yield same result
-   - **Round-trip**: Encode→Decode returns original
-   - **Invariant Preservation**: State constraints maintained across operations
-   - **Monotonicity**: Ordering guarantees (e.g., timestamps always increase)
-   - **Bounds**: Value ranges, size limits, rate constraints
-
-**Reference**
-- Use `openspec show <change_name> --json --deltas-only` to inspect proposal structure when validation fails.
-- 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.
-- 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:
-- [ ] Zero ambiguities remain (verified by step 4 audit)
-- [ ] All PBT properties documented with falsification strategies
-- [ ] `openspec validate <change_name> --strict` returns zero issues
-- [ ] User has explicitly approved all constraint decisions
-<!-- ABEL:END -->

package/lib/templates/workflow/commands/abel-research.md

@@ -1,126 +0,0 @@
----
-name: abel-research
-description: Transform user requirements into constraint sets via structured exploration (NO implementation)
-category: abel
-tags: [abel, research, constraints, exploration, subagents]
----
-
-<!-- ABEL:RESEARCH:START -->
-
-# abel-research — Operating Mode (Constraints & Specs Only)
-
-## Non‑Negotiable Rules (Highest Priority)
-1. RESEARCH MODE ONLY.
-   - You MUST NOT generate code.
-2. WRITE SCOPE IS RESTRICTED.
-   - You MAY create/edit files ONLY under: openspec/changes/<change-name>/** (and only after passing the confirmation gates).
-   - You MUST NOT write anywhere else.
-3. Output must be constraint sets + verifiable success criteria, not an information dump.
-
-## Goal
-Produce constraint sets that narrow the solution space, plus measurable success criteria.
-
----
-
-
-
-## Phase 0 — Requirement Intake Gate (MANDATORY)
-- **MUST** confirm the user’s requirement exists and is clear **before** any research/action.
-- 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.
-
----
-
-## Phase 1 — Initialize OpenSpec Change Folder
-1) Run: /opsx:new <change-name>
-2) From now on, you may write ONLY under openspec/changes/<change-name>/**.
-
----
-
-## Phase 2 — Initial Codebase Assessment (Read‑Only)
-- {{CODEBASE_RETRIEVAL_POLICY}}
-- If technical research needed (architectural patterns, best practices), invoke `/grok-search` skill
-- If the codebase spans multiple modules/directories, dispatch parallel explore subagents by context boundary.
-
----
-
-## Phase 3 — Define Exploration Boundaries (Context-Based Division Only)
-- Identify natural context boundaries in the codebase (NOT functional roles).
-- Example divisions:
-  * Subagent 1: User domain code (user models, user services, user UI)
-  * Subagent 2: Authentication & authorization code (auth middleware, session, tokens)
-  * Subagent 3: Configuration & infrastructure (configs, deployments, build scripts)
-- Each boundary should be self-contained: no cross-communication needed between subagents.
-- Define exploration scope and expected output for each subagent.
-
----
-
-## Phase 4 — Subagent Output Template (MANDATORY JSON)
-All explore subagents MUST return valid JSON using this schema:
-{
-  "module_name": "字符串 - 所探索的上下文边界",
-  "existing_structures": ["发现的关键结构/模式列表"],
-  "existing_conventions": ["当前使用的约定/标准列表"],
-  "constraints_discovered": ["限制解决方案空间的硬约束列表"],
-  "open_questions": ["需要用户输入的歧义问题列表"],
-  "dependencies": ["对其他模块/系统的依赖列表"],
-  "risks": ["潜在风险或阻碍列表"],
-  "success_criteria_hints": ["指示成功的可观察行为列表"]
-}
-
----
-
-## Phase 5 — Parallel Subagent Dispatch
-- Monitor subagent execution and collect structured reports.
-- For each boundary, spawn an Explore subagent with:
-  - {{CODEBASE_RETRIEVAL_MANDATORY_RULE}}
-  - Clear scope
-  - self-contained with independent output
-  - Required output template (from Phase 4)
-  - If boundary involves 3+ interconnected components, require explicit step-by-step dependency analysis
-  - Clear success criteria: complete analysis of assigned boundary
-
-
----
-
-## Phase 6 — Aggregate & Synthesize
-- Collect all subagent JSON outputs.
-- Merge findings into unified constraint sets:
-  * **Hard constraints**: Technical limitations, existing patterns that cannot be violated.
-  * **Soft constraints**: Conventions, preferences, style guides.
-  * **Dependencies**: Cross-module relationships that affect implementation order.
-  * **Risks**: Potential blockers that need mitigation.
-- Identify **open questions** from all reports that require user clarification.
-- Synthesize **success criteria** from scenario hints across all contexts.
-
----
-
-## Phase 7 — User Interaction for Ambiguity Resolution
-- Compile prioritized list of open questions from aggregated reports.
-- 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.
-- Capture user responses as additional constraints.
-- Update constraint sets with confirmed decisions.
-
----
-
-## Phase 8 — Generate OpenSpec Artifacts
-- Transform finalized constraint sets into OpenSpec proposal/specs/design/tasks.
-- Every requirement MUST have a verifiable scenario and success criteria.
-- Keep all writes inside openspec/changes/<change-name>/**.
-
-## Reference
-- Review existing constraints: `rg -n "Constraint:|MUST|MUST NOT" openspec/specs`
-- {{CODEBASE_RETRIEVAL_STRUCTURE_REFERENCE}}
-
-- Check prior research outputs: `ls openspec/changes/*/`
-- OpenSpec CLI commands:
-  - `openspec view` - Interactive dashboard to browse changes
-  - `openspec list --changes` - List all active changes
-  - `openspec status --change <name>` - Check artifact completion status
-  - `openspec instructions proposal --change <name>` - Get proposal instructions
-- Validate subagent outputs conform to template before aggregation.
-- Ask the user directly for ANY ambiguity—do not assume or guess.
-<!-- ABEL:RESEARCH:END -->

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

@@ -1,12 +0,0 @@
-# Prompt Enhancer CLI configuration
-# Copy this file to .env and fill in the values you want to use.
-
-# Optional: third-party OpenAI-compatible base URL
-PE_API_URL=
-
-# Optional: third-party OpenAI-compatible API key
-PE_API_KEY=
-
-# 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

@@ -1,103 +0,0 @@
-# Advanced Usage
-
-## Using the Python Script Directly
-
-Use the bootstrap entrypoint from the installed skill directory:
-
-```bash
-# 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"
-```
-
-`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 |
-|----------|-------------|---------|
-| `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` | - |
-| `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
-
-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
-
-# Pipe to file
-python "<SKILL_DIR>/scripts/prompt_enhancer_entry.py" "my prompt" > enhanced.md
-
-# Chain with other commands
-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 (Current Agent)
-
-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)
-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
-   - Constraints
-
-## Troubleshooting
-
-### Script Not Found
-Verify the canonical entrypoint exists:
-```bash
-ls "$HOME/.agents/skills/prompt-enhancer/scripts/prompt_enhancer_entry.py"
-```
-
-### Permission Denied
-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
-python "$HOME/.agents/skills/prompt-enhancer/scripts/prompt_enhancer_entry.py"
-```
-
-### 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 or configuration diagnostics on `stderr`.

package/skills/prompt-enhancer/requirements.txt

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

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

@@ -1,32 +0,0 @@
-"""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:
-        seen_keys = set()
-        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 not key or key in seen_keys:
-                    continue
-                seen_keys.add(key)
-                if not os.environ.get(key):
-                    os.environ[key] = value
-        return True
-    except IOError:
-        return False

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

@@ -1,144 +0,0 @@
-#!/usr/bin/env python3
-"""Prompt Enhancer CLI for OpenAI-compatible endpoints."""
-
-import argparse
-import os
-import sys
-from typing import Tuple
-
-from _dotenv import load_dotenv
-
-load_dotenv()
-
-
-SYSTEM_PROMPT = """
-You are an expert Prompt Engineer for Coding Agents (Claude Code, Codex, Gemini CLI).
-Your goal is to rewrite the user's raw input into a structured, high-context prompt that maximizes the agent's effectiveness.
-
-Guidelines:
-1. Structure: Use a clear Markdown structure with headers.
-2. Chain of Thought: Explicitly ask the agent to "Think step-by-step" or "Analyze the file structure first".
-3. Context: If the user's prompt is vague, add placeholders like "[Insert relevant file(s)]" or "[Specify tech stack]" in the rewritten prompt, or simply infer them if obvious.
-4. Format:
-   - Context: What is the current state? What files are involved?
-   - Objective: What exactly should be done?
-   - Constraints: specific libraries, coding styles, or "no placeholders".
-   - Response Format: e.g., "Return only the code block" or "Explain step-by-step".
-
-Output Template:
-
-# Context
-[Refined context description]
-
-# Objective
-[Precise task definition]
-
-# Step-by-Step Instructions
-1. [Step 1]
-2. [Step 2]
-...
-
-# Constraints
-- [Constraint 1]
-- [Constraint 2]
-"""
-
-
-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:
-    value = os.environ.get("PE_DEBUG", "")
-    return value.strip().lower() in {"1", "true", "yes", "on"}
-
-
-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 resolve_config(args: argparse.Namespace) -> Tuple[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:
-        raise ValueError(
-            "Missing third-party OpenAI-compatible config: "
-            + ", ".join(missing)
-            + ". If these fields are unavailable, use the current agent directly."
-        )
-    return api_url, api_key, model
-
-
-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:
-        from openai import OpenAI
-    except ImportError:
-        raise RuntimeError("Missing dependency: openai. Install dependencies for the configured provider.") from None
-
-    kwargs = {"api_key": api_key}
-    if api_url:
-        kwargs["base_url"] = api_url
-    client = OpenAI(**kwargs)
-    response = client.chat.completions.create(
-        model=model,
-        messages=[
-            {"role": "system", "content": SYSTEM_PROMPT},
-            {"role": "user", "content": prompt},
-        ],
-    )
-    return _extract_response_text(response)
-
-
-def main() -> None:
-    try:
-        args = parse_args()
-        prompt = resolve_prompt(args)
-        api_url, api_key, model = resolve_config(args)
-        print(enhance_with_openai(prompt, api_key, model, api_url))
-    except Exception as exc:
-        if debug_enabled():
-            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__":
-    main()