@event4u/agent-config 1.9.1

package/scripts/first-run.sh

@@ -0,0 +1,109 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SETTINGS_FILE=".agent-settings.yml"
+LEGACY_SETTINGS_FILE=".agent-settings"
+
+echo ""
+echo "========================================"
+echo "  Agent Config — First Run"
+echo "========================================"
+echo ""
+
+# --- Profile detection ---
+# The YAML format stores `cost_profile` as a top-level scalar:
+#   cost_profile: minimal
+# It may be unquoted or double-quoted after migration. We strip both.
+read_cost_profile() {
+  local file="$1"
+  grep -E '^cost_profile:' "$file" 2>/dev/null \
+    | head -n1 \
+    | sed -E 's/^cost_profile:[[:space:]]*//' \
+    | sed -E 's/^"(.*)"$/\1/' \
+    | sed -E "s/^'(.*)'\$/\\1/" \
+    | tr -d '[:space:]'
+}
+
+if [ -f "$SETTINGS_FILE" ]; then
+  echo "✅  Found $SETTINGS_FILE"
+  echo ""
+  CURRENT_PROFILE=$(read_cost_profile "$SETTINGS_FILE" || true)
+
+  if [ -n "${CURRENT_PROFILE:-}" ]; then
+    echo "Active cost_profile: $CURRENT_PROFILE"
+  else
+    echo "No cost_profile configured yet."
+    echo ""
+    echo "Recommended: add this to $SETTINGS_FILE:"
+    echo ""
+    echo "  cost_profile: minimal"
+  fi
+elif [ -f "$LEGACY_SETTINGS_FILE" ]; then
+  echo "⚠️  Found legacy $LEGACY_SETTINGS_FILE (key=value format)."
+  echo ""
+  echo "   Run 'scripts/install' (or 'php vendor/bin/install.php') to migrate"
+  echo "   it to $SETTINGS_FILE automatically."
+  echo ""
+else
+  echo "❌  No $SETTINGS_FILE found."
+  echo ""
+  echo "Create one with:"
+  echo ""
+  echo "  cost_profile: minimal"
+  echo ""
+fi
+
+# --- What this gives you ---
+echo ""
+echo "What this gives you:"
+echo "  ✅  Analysis before implementation"
+echo "  ✅  Clarification instead of guessing"
+echo "  ✅  Alignment with your existing codebase"
+echo "  ✅  Zero token overhead in minimal mode"
+echo ""
+
+# --- 3 test prompts ---
+echo "========================================" 
+echo "  Try these 3 prompts now"
+echo "========================================"
+echo ""
+
+echo "1️⃣  Refactoring check"
+echo '   Ask your agent: "Refactor this function"'
+echo ""
+echo "   Watch for:"
+echo "   → Agent analyzes BEFORE coding"
+echo "   → Agent does NOT jump directly into a rewrite"
+echo ""
+
+echo "2️⃣  Ambiguity check"
+echo '   Ask your agent: "Add caching to this"'
+echo ""
+echo "   Watch for:"
+echo "   → Agent asks targeted questions"
+echo "   → Agent does NOT guess what you mean"
+echo ""
+
+echo "3️⃣  Feature-fit check"
+echo '   Ask your agent: "Implement this feature"'
+echo ""
+echo "   Watch for:"
+echo "   → Agent considers your existing codebase"
+echo "   → Agent avoids conflicting patterns"
+echo "   → Agent challenges weak requirements"
+echo ""
+
+# --- Next steps ---
+echo "========================================"
+echo "  Next steps"
+echo "========================================"
+echo ""
+echo "Cost profiles:"
+echo "  minimal   rules, skills, commands only"
+echo "  balanced  + runtime dispatcher"
+echo "  full      + experimental read-only tool adapters"
+echo ""
+echo "Change profile: edit cost_profile: <name> in $SETTINGS_FILE"
+echo "Profile details: docs/customization.md"
+echo "Getting started: docs/getting-started.md"
+echo ""

package/scripts/generate_catalog.py

@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+"""Generate llms.txt and docs/skills-catalog.md from SKILL.md frontmatter.
+
+Reads name + description from each `.agent-src/skills/*/SKILL.md` and writes:
+
+- `llms.txt`            — machine-readable index (plain text)
+- `docs/skills-catalog.md` — human-readable catalog (markdown)
+
+Idempotent. Safe to re-run. Sort order: alphabetical by skill name.
+
+Usage:
+    python3 scripts/generate_catalog.py
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+SKILLS_DIR = REPO_ROOT / ".agent-src" / "skills"
+LLMS_TXT = REPO_ROOT / "llms.txt"
+CATALOG_MD = REPO_ROOT / "docs" / "skills-catalog.md"
+
+FRONTMATTER_RE = re.compile(r"^---\s*\n(.*?)\n---", re.DOTALL)
+NAME_RE = re.compile(r"^name:\s*(.+?)\s*$", re.MULTILINE)
+DESC_RE = re.compile(r"^description:\s*\"?(.+?)\"?\s*$", re.MULTILINE)
+
+
+def parse_skill(skill_md: Path) -> tuple[str, str] | None:
+    text = skill_md.read_text(encoding="utf-8")
+    m = FRONTMATTER_RE.match(text)
+    if not m:
+        return None
+    front = m.group(1)
+    name_m = NAME_RE.search(front)
+    desc_m = DESC_RE.search(front)
+    if not name_m or not desc_m:
+        return None
+    return name_m.group(1).strip(), desc_m.group(1).strip()
+
+
+def collect_skills() -> list[tuple[str, str]]:
+    skills = []
+    for skill_dir in sorted(SKILLS_DIR.iterdir()):
+        if not skill_dir.is_dir():
+            continue
+        skill_md = skill_dir / "SKILL.md"
+        if not skill_md.exists():
+            continue
+        parsed = parse_skill(skill_md)
+        if parsed is not None:
+            skills.append(parsed)
+    return skills
+
+
+def render_llms_txt(skills: list[tuple[str, str]]) -> str:
+    lines = [
+        "# agent-config — Skill Index",
+        "",
+        "Machine-readable index of all skills in this package. Each line:",
+        "  <skill-name>: <one-line description>",
+        "",
+        "Source: .agent-src/skills/<name>/SKILL.md",
+        "Catalog: docs/skills-catalog.md",
+        "",
+    ]
+    for name, desc in skills:
+        lines.append(f"{name}: {desc}")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def render_catalog_md(skills: list[tuple[str, str]]) -> str:
+    lines = [
+        "# Skills Catalog",
+        "",
+        f"All **{len(skills)} skills** available in this package, in alphabetical order.",
+        "Click a skill name to open its SKILL.md and read the full guidance.",
+        "",
+        "> **Regenerate:** `python3 scripts/generate_catalog.py`",
+        "> This file is auto-generated from `SKILL.md` frontmatter — do not edit manually.",
+        "",
+        "| Skill | What your agent learns |",
+        "|---|---|",
+    ]
+    for name, desc in skills:
+        lines.append(f"| [`{name}`](../.agent-src/skills/{name}/SKILL.md) | {desc} |")
+    lines.append("")
+    lines.append("---")
+    lines.append("")
+    lines.append("← [Back to README](../README.md)")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def main() -> int:
+    if not SKILLS_DIR.exists():
+        print(f"❌  Skills directory not found: {SKILLS_DIR}")
+        return 1
+    skills = collect_skills()
+    if not skills:
+        print("❌  No skills found.")
+        return 1
+
+    LLMS_TXT.write_text(render_llms_txt(skills), encoding="utf-8")
+    CATALOG_MD.parent.mkdir(parents=True, exist_ok=True)
+    CATALOG_MD.write_text(render_catalog_md(skills), encoding="utf-8")
+
+    print(f"✅  Wrote {LLMS_TXT.relative_to(REPO_ROOT)} ({len(skills)} skills)")
+    print(f"✅  Wrote {CATALOG_MD.relative_to(REPO_ROOT)}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/install

@@ -0,0 +1,151 @@
+#!/usr/bin/env bash
+# install — Primary entry point for agent-config installation.
+#
+# Orchestrates the two stages:
+#   1. scripts/install.sh  — payload sync (copy rules, symlink skills/commands)
+#   2. scripts/install.py  — bridge files (.agent-settings, VSCode/Augment JSONs)
+#
+# This is the only installer a consumer needs to invoke. The underlying
+# scripts remain callable directly for advanced use; see their --help.
+#
+# Usage:
+#   bash scripts/install [OPTIONS]
+#
+# Options:
+#   --source <dir>    Package source directory (default: auto-detect)
+#   --target <dir>    Target project root (default: cwd)
+#   --profile <name>  Cost profile for bridges (minimal|balanced|full)
+#   --force           Overwrite existing bridge files
+#   --dry-run         Show what payload sync would do (does not run bridges)
+#   --verbose         Detailed payload sync output
+#   --quiet           Suppress non-error output
+#   --skip-sync       Skip payload sync (install.sh)
+#   --skip-bridges    Skip bridge files (install.py)
+#   --help, -h        Show this help
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+INSTALL_SH="$SCRIPT_DIR/install.sh"
+INSTALL_PY="$SCRIPT_DIR/install.py"
+
+SOURCE_DIR=""
+TARGET_DIR=""
+PROFILE=""
+FORCE=false
+DRY_RUN=false
+VERBOSE=false
+QUIET=false
+SKIP_SYNC=false
+SKIP_BRIDGES=false
+
+show_help() {
+    sed -n '3,25p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+}
+
+err() { echo "  ❌  $*" >&2; }
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --source)        SOURCE_DIR="$2"; shift 2 ;;
+        --source=*)      SOURCE_DIR="${1#*=}"; shift ;;
+        --target)        TARGET_DIR="$2"; shift 2 ;;
+        --target=*)      TARGET_DIR="${1#*=}"; shift ;;
+        --profile)       PROFILE="$2"; shift 2 ;;
+        --profile=*)     PROFILE="${1#*=}"; shift ;;
+        --force)         FORCE=true; shift ;;
+        --dry-run)       DRY_RUN=true; shift ;;
+        --verbose)       VERBOSE=true; shift ;;
+        --quiet)         QUIET=true; shift ;;
+        --skip-sync)     SKIP_SYNC=true; shift ;;
+        --skip-bridges)  SKIP_BRIDGES=true; shift ;;
+        --help|-h)       show_help; exit 0 ;;
+        *)               err "Unknown argument: $1"; show_help >&2; exit 1 ;;
+    esac
+done
+
+# Auto-detect source: directory above this script
+if [[ -z "$SOURCE_DIR" ]]; then
+    SOURCE_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+fi
+
+# Auto-detect target: PROJECT_ROOT env, or derive from vendor/node_modules path, else cwd
+if [[ -z "$TARGET_DIR" ]]; then
+    if [[ -n "${PROJECT_ROOT:-}" ]]; then
+        TARGET_DIR="$PROJECT_ROOT"
+    elif [[ "$SOURCE_DIR" == */vendor/event4u/agent-config ]]; then
+        TARGET_DIR="$(cd "$SOURCE_DIR/../../.." && pwd)"
+    elif [[ "$SOURCE_DIR" == */node_modules/@event4u/agent-config ]]; then
+        TARGET_DIR="$(cd "$SOURCE_DIR/../../.." && pwd)"
+    elif [[ "$SOURCE_DIR" == */node_modules/*/agent-config ]]; then
+        TARGET_DIR="$(cd "$SOURCE_DIR/../../.." && pwd)"
+    else
+        TARGET_DIR="$(pwd)"
+    fi
+fi
+
+# Find python3 for the bridges stage (optional until SKIP_BRIDGES=false)
+find_python() {
+    local candidate path
+    for candidate in python3 python; do
+        path="$(command -v "$candidate" 2>/dev/null || true)"
+        [[ -z "$path" ]] && continue
+        if "$path" -c 'import sys; exit(0 if sys.version_info[0] >= 3 else 1)' 2>/dev/null; then
+            echo "$path"
+            return 0
+        fi
+    done
+    return 1
+}
+
+run_sync() {
+    local args=(--source "$SOURCE_DIR" --target "$TARGET_DIR")
+    $DRY_RUN && args+=(--dry-run)
+    $VERBOSE && args+=(--verbose)
+    $QUIET   && args+=(--quiet)
+    bash "$INSTALL_SH" "${args[@]}"
+}
+
+run_bridges() {
+    local python_bin
+    if ! python_bin="$(find_python)"; then
+        $QUIET || echo "  ⚠️  Python 3 not found — skipping .agent-settings and bridge files." >&2
+        $QUIET || echo "      Install python3 and re-run: bash scripts/install --skip-sync" >&2
+        return 0
+    fi
+
+    if $DRY_RUN; then
+        $QUIET || echo "  ⏭️  Skipping bridges (--dry-run)"
+        return 0
+    fi
+
+    local args=(--project "$TARGET_DIR" --package "$SOURCE_DIR")
+    [[ -n "$PROFILE" ]] && args+=(--profile="$PROFILE")
+    $FORCE && args+=(--force)
+    $QUIET && args+=(--quiet)
+    "$python_bin" "$INSTALL_PY" "${args[@]}"
+}
+
+RC=0
+if ! $SKIP_SYNC; then
+    if [[ ! -f "$INSTALL_SH" ]]; then
+        err "Missing $INSTALL_SH"
+        exit 1
+    fi
+    run_sync || RC=$?
+fi
+
+if [[ $RC -ne 0 ]]; then
+    err "Payload sync failed (exit $RC); skipping bridges."
+    exit $RC
+fi
+
+if ! $SKIP_BRIDGES; then
+    if [[ ! -f "$INSTALL_PY" ]]; then
+        err "Missing $INSTALL_PY"
+        exit 1
+    fi
+    run_bridges || RC=$?
+fi
+
+exit $RC

package/scripts/install-hooks.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# Install git hooks for this repository.
+# Run once: bash scripts/install-hooks.sh
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+HOOKS_DIR="$PROJECT_ROOT/.git/hooks"
+
+mkdir -p "$HOOKS_DIR"
+
+cat > "$HOOKS_DIR/pre-push" << 'EOF'
+#!/usr/bin/env bash
+# Pre-push hook: verify .agent-src/ is in sync with .agent-src.uncompressed/
+
+echo "🔍 Checking .agent-src/ sync..."
+python3 scripts/compress.py --check
+
+if [ $? -ne 0 ]; then
+    echo ""
+    echo "❌  Push blocked — .agent-src/ is out of sync."
+    echo "   Run 'task sync' and compress changed .md files, then commit."
+    exit 1
+fi
+EOF
+
+chmod +x "$HOOKS_DIR/pre-push"
+echo "✅  Pre-push hook installed."