@event4u/agent-config 1.9.1

package/scripts/update_counts.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""Sync package-content counts (skills/rules/commands/guidelines) across docs.
+
+Source of truth: `.agent-src.uncompressed/`.
+
+Target files have explicit regex patterns for each count mention — no
+fuzzy matching, no risk of touching unrelated numbers.
+
+Modes:
+  update (default)  Rewrite each target to match the true counts.
+  --check           Exit 1 if any target is stale.
+
+Run as part of `task sync` (update) and `task ci` (check).
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+SRC = REPO_ROOT / ".agent-src.uncompressed"
+
+
+def count(kind: str) -> int:
+    if kind == "skills":
+        return sum(1 for _ in (SRC / "skills").rglob("SKILL.md"))
+    if kind == "guidelines":
+        # guidelines are grouped by topic subdirectory
+        return sum(1 for _ in (SRC / "guidelines").rglob("*.md"))
+    if kind == "personas":
+        # personas live as flat .md files, README excluded
+        pdir = SRC / "personas"
+        if not pdir.exists():
+            return 0
+        return sum(1 for f in pdir.glob("*.md") if f.name != "README.md")
+    return sum(1 for _ in (SRC / kind).glob("*.md"))
+
+
+# file → list of (regex, kind)
+# Each regex MUST use three capture groups: (prefix)(number)(suffix).
+TARGETS: list[tuple[str, list[tuple[str, str]]]] = [
+    (
+        "README.md",
+        [
+            (r"(Browse all )(\d+)( commands\])", "commands"),
+            (r"(package \(rules \+ )(\d+)( skills)", "skills"),
+            (r"(skills \+ )(\d+)( native commands)", "commands"),
+            # Hero line: **NNN Skills** · **NNN Rules** · **NNN Commands** · **NNN Guidelines**
+            (r"(<strong>)(\d+)( Skills</strong>)", "skills"),
+            (r"(<strong>)(\d+)( Rules</strong>)", "rules"),
+            (r"(<strong>)(\d+)( Commands</strong>)", "commands"),
+            (r"(<strong>)(\d+)( Guidelines</strong>)", "guidelines"),
+        ],
+    ),
+    (
+        "AGENTS.md",
+        [
+            (r"(skills/\s+\()(\d+)( skills\))", "skills"),
+            (r"(rules/\s+\()(\d+)( rules\))", "rules"),
+            (r"(commands/\s+\()(\d+)( commands\))", "commands"),
+            (r"(guidelines/\s+\()(\d+)( guidelines\))", "guidelines"),
+            (r"(personas/\s+\()(\d+)( personas\))", "personas"),
+        ],
+    ),
+    (
+        "docs/getting-started.md",
+        [
+            (r"(automatically by )(\d+)( rules)", "rules"),
+            (r"(Browse all )(\d+)( commands\])", "commands"),
+        ],
+    ),
+    # Note: ``agents/roadmaps/road-to-stronger-skills.md`` was previously
+    # tracked here with a living ``baseline N as of`` pattern. The roadmap
+    # was moved to ``skipped/`` on 2026-04-23 (Q35 superseded), so its
+    # baseline is frozen as a historical snapshot and is no longer
+    # auto-synced.
+]
+
+
+def apply_to_text(text: str, patterns: list[tuple[str, str]], counts: dict[str, int]) -> tuple[str, list[tuple[str, int, int]]]:
+    """Return (new_text, drifts). Each drift is (kind, old, new)."""
+    drifts: list[tuple[str, int, int]] = []
+    new_text = text
+    for pattern, kind in patterns:
+        compiled = re.compile(pattern)
+        matches = list(compiled.finditer(new_text))
+        if not matches:
+            print(f"  ⚠️  pattern missed: /{pattern}/ (kind={kind})", file=sys.stderr)
+            continue
+        for m in matches:
+            old = int(m.group(2))
+            new = counts[kind]
+            if old != new:
+                drifts.append((kind, old, new))
+        new_text = compiled.sub(
+            lambda m, k=kind: f"{m.group(1)}{counts[k]}{m.group(3)}",
+            new_text,
+        )
+    return new_text, drifts
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--check", action="store_true", help="exit 1 on drift instead of rewriting")
+    args = parser.parse_args()
+
+    counts = {k: count(k) for k in ("skills", "rules", "commands", "guidelines", "personas")}
+    print(f"📊  Truth: skills={counts['skills']} rules={counts['rules']} "
+          f"commands={counts['commands']} guidelines={counts['guidelines']} "
+          f"personas={counts['personas']}")
+
+    any_drift = False
+    any_change = False
+    for rel, patterns in TARGETS:
+        path = REPO_ROOT / rel
+        if not path.exists():
+            print(f"❌  Missing target: {rel}", file=sys.stderr)
+            return 1
+        text = path.read_text(encoding="utf-8")
+        new_text, drifts = apply_to_text(text, patterns, counts)
+        if drifts:
+            any_drift = True
+            for kind, old, new in drifts:
+                print(f"  {'🔴' if args.check else '🔧'}  {rel}: {kind} {old} → {new}")
+        if new_text != text and not args.check:
+            path.write_text(new_text, encoding="utf-8")
+            any_change = True
+
+    if args.check:
+        if any_drift:
+            print("\n❌  Stale counts detected. Run `task counts-update` to fix.", file=sys.stderr)
+            return 1
+        print("✅  All counts in sync.")
+        return 0
+
+    if any_change:
+        print("✅  Counts updated.")
+    else:
+        print("✅  Counts already in sync.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/validate_frontmatter.py

@@ -0,0 +1,424 @@
+#!/usr/bin/env python3
+"""
+Frontmatter validator (stdlib-only Draft-07 subset).
+
+Validates the YAML frontmatter of an agent artefact (skill, rule, command,
+persona) against its JSON-Schema in ``scripts/schemas/``.
+
+Supported keywords: ``type``, ``required``, ``properties``,
+``additionalProperties``, ``enum``, ``pattern``, ``items``, ``minLength``,
+``maxLength``, ``minItems``, ``minimum``. No ``$ref``, no ``allOf``/``anyOf``
+— the schemas in this repo deliberately stay flat.
+
+The goal is a **better error surface**: each violation comes back as a
+``SchemaError`` with ``path`` (dotted JSON pointer), ``rule`` (the schema
+keyword that failed), and a human-readable message.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+__all__ = [
+    "SchemaError",
+    "validate",
+    "load_schema",
+    "parse_frontmatter",
+]
+
+_FRONTMATTER_RE = re.compile(r"^---\n(.*?)\n---\n", re.DOTALL)
+
+
+@dataclass(frozen=True)
+class SchemaError:
+    path: str
+    rule: str
+    message: str
+
+    def format(self, file: str | None = None, line: int | None = None) -> str:
+        prefix = file or "<data>"
+        if line is not None:
+            prefix = f"{prefix}:{line}"
+        return f"{prefix} – {self.rule} at {self.path} – {self.message}"
+
+
+# --- Frontmatter parser (stdlib-only, YAML subset) -------------------------
+
+def parse_frontmatter(text: str) -> tuple[dict[str, Any] | None, int]:
+    """Extract and parse the YAML frontmatter block.
+
+    Returns (parsed_dict, line_offset). ``line_offset`` is the 1-based line
+    number where the frontmatter body begins (so error lines can be mapped
+    back to the source file).
+    Supports: scalar key/value (quoted or bare), booleans (``true``/``false``),
+    integers, inline lists (``[a, b]``), block lists (``- a``), and nested
+    one-level blocks (``execution:``).
+    """
+    match = _FRONTMATTER_RE.search(text)
+    if not match:
+        return None, 0
+    body = match.group(1)
+    line_offset = text[: match.start()].count("\n") + 2  # +2 for `---\n`
+    return _parse_yaml_block(body), line_offset
+
+
+def _coerce(value: str) -> Any:
+    value = value.strip()
+    if value == "":
+        return ""
+    if (value.startswith('"') and value.endswith('"')) or (
+        value.startswith("'") and value.endswith("'")
+    ):
+        return value[1:-1]
+    if value.lower() == "true":
+        return True
+    if value.lower() == "false":
+        return False
+    if re.fullmatch(r"-?[0-9]+", value):
+        return int(value)
+    return value
+
+
+def _parse_inline_list(value: str) -> list[Any]:
+    inner = value.strip()[1:-1].strip()
+    if not inner:
+        return []
+    return [_coerce(item) for item in _split_commas(inner)]
+
+
+def _split_commas(text: str) -> list[str]:
+    """Split on commas that aren't inside quotes. Stdlib-only."""
+    parts: list[str] = []
+    buf: list[str] = []
+    quote: str | None = None
+    for ch in text:
+        if quote:
+            buf.append(ch)
+            if ch == quote:
+                quote = None
+        elif ch in ('"', "'"):
+            quote = ch
+            buf.append(ch)
+        elif ch == ",":
+            parts.append("".join(buf).strip())
+            buf = []
+        else:
+            buf.append(ch)
+    if buf:
+        parts.append("".join(buf).strip())
+    return parts
+
+
+def _parse_yaml_block(body: str) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    lines = body.splitlines()
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+        stripped = line.rstrip()
+        if not stripped.strip() or stripped.lstrip().startswith("#"):
+            i += 1
+            continue
+        if line[0].isspace():  # orphan indented line — skip
+            i += 1
+            continue
+        m = re.match(r"^([\w-]+):\s*(.*)$", stripped)
+        if not m:
+            i += 1
+            continue
+        key, raw = m.group(1), m.group(2).strip()
+        if raw == "":
+            # Nested block or block list — peek ahead.
+            peek = lines[i + 1] if i + 1 < len(lines) else ""
+            if peek.lstrip().startswith("- "):
+                items, consumed = _consume_block_list(lines, i + 1)
+                result[key] = items
+                i += 1 + consumed
+                continue
+            if peek and peek[0].isspace():
+                nested, consumed = _consume_nested_block(lines, i + 1)
+                result[key] = nested
+                i += 1 + consumed
+                continue
+            result[key] = ""
+        elif raw.startswith("[") and raw.endswith("]"):
+            result[key] = _parse_inline_list(raw)
+        else:
+            result[key] = _coerce(raw)
+        i += 1
+    return result
+
+
+def _consume_block_list(lines: list[str], start: int) -> tuple[list[Any], int]:
+    items: list[Any] = []
+    i = start
+    while i < len(lines):
+        line = lines[i]
+        if not line.strip():
+            i += 1
+            continue
+        stripped = line.lstrip()
+        if not stripped.startswith("- "):
+            break
+        items.append(_coerce(stripped[2:]))
+        i += 1
+    return items, i - start
+
+
+# --- Schema loader ---------------------------------------------------------
+
+_SCHEMA_DIR = Path(__file__).resolve().parent / "schemas"
+_SCHEMA_CACHE: dict[str, dict[str, Any]] = {}
+
+
+def load_schema(artefact_type: str) -> dict[str, Any]:
+    """Load and cache a schema by artefact type (skill, rule, command, persona)."""
+    if artefact_type in _SCHEMA_CACHE:
+        return _SCHEMA_CACHE[artefact_type]
+    path = _SCHEMA_DIR / f"{artefact_type}.schema.json"
+    if not path.exists():
+        raise FileNotFoundError(f"No schema for artefact type '{artefact_type}' at {path}")
+    data = json.loads(path.read_text(encoding="utf-8"))
+    _SCHEMA_CACHE[artefact_type] = data
+    return data
+
+
+# --- Validator core (Draft-07 subset) --------------------------------------
+
+_JSON_TYPES: dict[str, tuple[type, ...]] = {
+    "object": (dict,),
+    "array": (list,),
+    "string": (str,),
+    "integer": (int,),
+    "number": (int, float),
+    "boolean": (bool,),
+    "null": (type(None),),
+}
+
+
+def validate(data: Any, schema: dict[str, Any]) -> list[SchemaError]:
+    """Validate ``data`` against ``schema``; return a list of errors (empty = pass)."""
+    errors: list[SchemaError] = []
+    _validate_node(data, schema, "$", errors)
+    return errors
+
+
+def _validate_node(data: Any, schema: dict[str, Any], path: str, errors: list[SchemaError]) -> None:
+    # type
+    expected_type = schema.get("type")
+    if expected_type is not None:
+        allowed = _JSON_TYPES.get(expected_type)
+        if allowed is None:
+            errors.append(SchemaError(path, "type", f"Unsupported schema type '{expected_type}'"))
+            return
+        # Booleans are a subtype of int in Python — exclude them from integer/number.
+        if expected_type in ("integer", "number") and isinstance(data, bool):
+            errors.append(SchemaError(path, "type", f"Expected {expected_type}, got boolean"))
+            return
+        if not isinstance(data, allowed):
+            errors.append(SchemaError(
+                path, "type",
+                f"Expected {expected_type}, got {_typename(data)}",
+            ))
+            return
+
+    if isinstance(data, dict):
+        _validate_object(data, schema, path, errors)
+    elif isinstance(data, list):
+        _validate_array(data, schema, path, errors)
+    elif isinstance(data, str):
+        _validate_string(data, schema, path, errors)
+    elif isinstance(data, int) and not isinstance(data, bool):
+        _validate_integer(data, schema, path, errors)
+
+    # enum is type-independent
+    if "enum" in schema and data not in schema["enum"]:
+        errors.append(SchemaError(
+            path, "enum",
+            f"Value {data!r} is not one of {schema['enum']}",
+        ))
+
+
+def _validate_object(data: dict[str, Any], schema: dict[str, Any], path: str, errors: list[SchemaError]) -> None:
+    required = schema.get("required", [])
+    for key in required:
+        if key not in data:
+            errors.append(SchemaError(f"{path}.{key}", "required", f"Missing required property '{key}'"))
+
+    properties = schema.get("properties", {})
+    additional = schema.get("additionalProperties", True)
+
+    for key, value in data.items():
+        child_path = f"{path}.{key}"
+        if key in properties:
+            _validate_node(value, properties[key], child_path, errors)
+        elif additional is False:
+            errors.append(SchemaError(
+                child_path, "additionalProperties",
+                f"Unknown property '{key}' not allowed",
+            ))
+
+
+def _validate_array(data: list[Any], schema: dict[str, Any], path: str, errors: list[SchemaError]) -> None:
+    items_schema = schema.get("items")
+    if items_schema is not None:
+        for index, item in enumerate(data):
+            _validate_node(item, items_schema, f"{path}[{index}]", errors)
+    min_items = schema.get("minItems")
+    if min_items is not None and len(data) < min_items:
+        errors.append(SchemaError(path, "minItems", f"Array has {len(data)} items, need ≥ {min_items}"))
+
+
+def _validate_string(data: str, schema: dict[str, Any], path: str, errors: list[SchemaError]) -> None:
+    pattern = schema.get("pattern")
+    if pattern is not None and not re.search(pattern, data):
+        errors.append(SchemaError(path, "pattern", f"Value {data!r} does not match /{pattern}/"))
+    min_len = schema.get("minLength")
+    if min_len is not None and len(data) < min_len:
+        errors.append(SchemaError(path, "minLength", f"String length {len(data)} < {min_len}"))
+    max_len = schema.get("maxLength")
+    if max_len is not None and len(data) > max_len:
+        errors.append(SchemaError(path, "maxLength", f"String length {len(data)} > {max_len}"))
+
+
+def _validate_integer(data: int, schema: dict[str, Any], path: str, errors: list[SchemaError]) -> None:
+    minimum = schema.get("minimum")
+    if minimum is not None and data < minimum:
+        errors.append(SchemaError(path, "minimum", f"{data} < {minimum}"))
+
+
+def _typename(value: Any) -> str:
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "boolean"
+    if isinstance(value, int):
+        return "integer"
+    if isinstance(value, float):
+        return "number"
+    if isinstance(value, str):
+        return "string"
+    if isinstance(value, list):
+        return "array"
+    if isinstance(value, dict):
+        return "object"
+    return type(value).__name__
+
+
+def _consume_nested_block(lines: list[str], start: int) -> tuple[dict[str, Any], int]:
+    nested: dict[str, Any] = {}
+    i = start
+    # Lock in the indent of the outer nested block from the first content
+    # line so we know when the block ends.
+    block_indent: int | None = None
+    while i < len(lines):
+        line = lines[i]
+        if not line.strip():
+            i += 1
+            continue
+        if not line[0].isspace():
+            break
+        indent = len(line) - len(line.lstrip())
+        if block_indent is None:
+            block_indent = indent
+        elif indent < block_indent:
+            break
+        stripped = line.strip()
+        if stripped.startswith("#"):
+            i += 1
+            continue
+        m = re.match(r"^([\w-]+):\s*(.*)$", stripped)
+        if not m:
+            i += 1
+            continue
+        key, raw = m.group(1), m.group(2).strip()
+        if raw.startswith("[") and raw.endswith("]"):
+            nested[key] = _parse_inline_list(raw)
+        elif raw == "":
+            # Value continues on the next line(s). Peek ahead: a block list
+            # at deeper indent means this key holds a list; anything else
+            # treated as empty string (one-level nesting only).
+            peek = lines[i + 1] if i + 1 < len(lines) else ""
+            peek_stripped = peek.lstrip()
+            peek_indent = len(peek) - len(peek_stripped) if peek_stripped else -1
+            if peek_stripped.startswith("- ") and peek_indent > indent:
+                items, consumed = _consume_block_list(lines, i + 1)
+                nested[key] = items
+                i += 1 + consumed
+                continue
+            nested[key] = ""
+        else:
+            nested[key] = _coerce(raw)
+        i += 1
+    return nested, i - start
+
+
+# --- CLI entry point -------------------------------------------------------
+
+def _iter_artefacts(root: Path) -> list[tuple[str, Path]]:
+    """Yield ``(artefact_type, path)`` pairs for all lintable artefacts."""
+    targets: list[tuple[str, Path]] = []
+    mapping = (
+        ("skill",   sorted(root.joinpath("skills").rglob("SKILL.md"))),
+        ("rule",    sorted(root.joinpath("rules").rglob("*.md"))),
+        ("command", sorted(root.joinpath("commands").rglob("*.md"))),
+        ("persona", [
+            f for f in sorted(root.joinpath("personas").glob("*.md"))
+            if f.name.lower() != "readme.md"
+        ]),
+    )
+    for artefact_type, files in mapping:
+        for f in files:
+            if f.is_symlink():
+                continue
+            targets.append((artefact_type, f))
+    return targets
+
+
+def _main() -> int:
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="Validate agent-artefact frontmatter against JSON-Schema.",
+    )
+    parser.add_argument(
+        "--root",
+        default=".agent-src.uncompressed",
+        help="Source root to scan (default: .agent-src.uncompressed).",
+    )
+    args = parser.parse_args()
+
+    root = Path(args.root)
+    if not root.is_dir():
+        print(f"error: source root not found: {root}", file=sys.stderr)
+        return 2
+
+    total = 0
+    failing = 0
+    for artefact_type, path in _iter_artefacts(root):
+        total += 1
+        text = path.read_text(encoding="utf-8")
+        data, _offset = parse_frontmatter(text)
+        if data is None:
+            # Other tooling flags missing frontmatter; don't double-report.
+            continue
+        schema = load_schema(artefact_type)
+        errors = validate(data, schema)
+        if errors:
+            failing += 1
+            for error in errors:
+                print(f"[{artefact_type}] {path}: {error.rule} at "
+                      f"{error.path} – {error.message}")
+
+    print(f"\n== Frontmatter schema: {total} artefacts, "
+          f"{failing} failing ==")
+    return 1 if failing else 0
+
+
+if __name__ == "__main__":
+    sys.exit(_main())

package/templates/consumer-settings/README.md

@@ -0,0 +1,46 @@
+# Consumer Settings Templates
+
+These templates show how to configure your project to use `agent-config` as a native plugin
+instead of copying files via `install.sh`.
+
+## Quick Setup by Tool
+
+### Augment CLI
+
+1. Add marketplace: `auggie plugin marketplace add event4u-app/agent-config`
+2. Install plugin: `auggie plugin install agent-conf@event4u`
+3. Optional: Copy `augment-settings.json` into your project's `.augment/settings.json` to auto-recommend for your team.
+
+### Claude Code
+
+1. Add marketplace: `claude plugin marketplace add event4u-app/agent-config`
+2. Install plugin: `claude plugin install agent-conf@event4u`
+3. Optional: Copy `claude-settings.json` into your project's `.claude/settings.json`.
+
+### Copilot CLI
+
+1. Add marketplace: `copilot plugin marketplace add event4u-app/agent-config`
+2. Install plugin: `copilot plugin install agent-conf@event4u`
+3. Optional: Copy `copilot-settings.json` into your project's `.github/copilot/settings.json`.
+
+### Cursor / Cline / Windsurf / Augment VSCode
+
+These tools do **not** support plugins yet. Use the classic `install.sh` approach:
+
+```bash
+bash vendor/event4u/agent-config/scripts/install.sh --target .
+```
+
+## What the plugin provides
+
+When installed as a plugin, the agent gets access to:
+
+- **Rules** — Always-active behavior constraints (`.augment/rules/`)
+- **Skills** — On-demand domain expertise (`.augment/skills/`)
+- **Commands** — Workflow automations (`.augment/commands/`)
+- **Guidelines** — Coding standards (`.augment/guidelines/`)
+
+## Auto-updates
+
+Plugin marketplaces auto-update in the background (Augment CLI and Claude Code).
+No manual `git pull` or `install.sh` re-runs needed.

package/templates/consumer-settings/augment-settings.json

@@ -0,0 +1,12 @@
+{
+  "// Instructions": "Copy this into your project's .augment/settings.json to auto-recommend the agent-config marketplace.",
+  "// After install": "Run: auggie plugin marketplace add event4u-app/agent-config",
+  "// Then enable": "Run: auggie plugin install agent-conf@event4u",
+
+  "recommendedMarketplaces": [
+    "event4u-app/agent-config"
+  ],
+  "enabledPlugins": {
+    "agent-conf@event4u": true
+  }
+}

package/templates/consumer-settings/claude-settings.json

@@ -0,0 +1,9 @@
+{
+  "// Instructions": "Copy this into your project's .claude/settings.json to auto-enable the agent-config plugin.",
+  "// After setup": "Claude Code will load the plugin when the marketplace is installed.",
+  "// Install marketplace": "Run: claude plugin marketplace add event4u-app/agent-config",
+
+  "enabledPlugins": {
+    "agent-conf@event4u": true
+  }
+}

package/templates/consumer-settings/copilot-settings.json

@@ -0,0 +1,14 @@
+{
+  "// Instructions": "Copy this into your project's .github/copilot/settings.json to auto-recommend the agent-config plugin.",
+  "// After setup": "Copilot CLI will auto-install the marketplace and enable the plugin on startup.",
+
+  "extraKnownMarketplaces": [
+    {
+      "name": "event4u-agent-config",
+      "source": "event4u-app/agent-config"
+    }
+  ],
+  "enabledPlugins": {
+    "agent-conf@event4u": true
+  }
+}