@event4u/agent-config 1.13.0 → 1.14.0

package/scripts/lint_marketplace.py

@@ -10,6 +10,8 @@ shape used by anthropics/skills:
   - metadata must have description + version
   - metadata.version must match package.json (single source of truth)
   - every plugins[].skills[] entry must exist on disk and carry a SKILL.md
+  - every SKILL.md on disk under .claude/skills/ must be listed in some
+    plugin's skills[] (drift detection)
 
 Exit codes: 0 = clean, 1 = problems found, 3 = internal error.
 """
@@ -23,6 +25,7 @@ from pathlib import Path
 ROOT = Path(".")
 MARKETPLACE = ROOT / ".claude-plugin" / "marketplace.json"
 PACKAGE_JSON = ROOT / "package.json"
+CLAUDE_SKILLS_DIR = ROOT / ".claude" / "skills"
 
 
 def fail(errors: list[str]) -> int:
@@ -121,6 +124,30 @@ def main() -> int:
             if not skill_md.exists():
                 errors.append(f"{entry} has no SKILL.md: `{path}`")
 
+    # Reverse-completeness: every SKILL.md on disk under .claude/skills/
+    # must appear in some plugin's skills[]. Catches the drift where new
+    # skills are generated but never added to the marketplace manifest.
+    listed: set[str] = set()
+    for plugin in plugins:
+        if not isinstance(plugin, dict):
+            continue
+        for path in plugin.get("skills", []):
+            if isinstance(path, str):
+                listed.add(path.removeprefix("./"))
+
+    if CLAUDE_SKILLS_DIR.exists():
+        for skill_dir in sorted(CLAUDE_SKILLS_DIR.iterdir()):
+            if not skill_dir.is_dir():
+                continue
+            if not (skill_dir / "SKILL.md").exists():
+                continue
+            rel = f".claude/skills/{skill_dir.name}"
+            if rel not in listed:
+                errors.append(
+                    f"skill exists on disk but is not listed in marketplace.json: "
+                    f"`./{rel}`"
+                )
+
     if errors:
         return fail(errors)
 

package/scripts/migrate_command_suggestions.py

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+"""One-shot migration: inject the `suggestion:` frontmatter block into every
+command under `.agent-src.uncompressed/commands/`.
+
+Source-of-truth table: `agents/contexts/command-suggestion-eligibility.md`
+(locked at end of road-to-context-aware-command-suggestion Phase 1).
+
+Idempotent: if `suggestion:` is already present for a command, the file is
+left untouched. Re-runnable.
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+COMMANDS_DIR = ROOT / ".agent-src.uncompressed" / "commands"
+
+INELIGIBLE: dict[str, str] = {
+    "agent-handoff": "Explicit fresh-chat handoff — must be deliberate, never inferred from prose.",
+    "agent-status": "Pure status display; no natural-language trigger distinct from idle small-talk.",
+    "agents-cleanup": "Consumes prior audit output; only meaningful right after /agents-audit.",
+    "agents-prepare": "One-shot project scaffolding; only run during initial setup.",
+    "chat-history": "Status display only; no NL trigger distinct from 'show status'.",
+    "chat-history-clear": "Destructive log wipe — must be deliberate.",
+    "chat-history-resume": "Explicit resume mechanic with foreign/returning state machine.",
+    "compress": "Package-internal tooling; only the event4u/agent-config repo runs this.",
+    "copilot-agents-init": "Project init — only deliberately during onboarding.",
+    "copilot-agents-optimize": "Maintenance refactor; only when the maintainer chooses to run it.",
+    "do-and-judge": "Subagent orchestration — overlaps /work and judge skills; keep explicit.",
+    "do-in-steps": "Subagent orchestration — overlaps /work and /roadmap-execute; keep explicit.",
+    "fix-portability": "Package-internal — only the event4u/agent-config repo runs this.",
+    "fix-references": "Package-internal — only the event4u/agent-config repo runs this.",
+    "judge": "Sibling of /review-changes — eligibility routed there; keep this explicit.",
+    "memory-full": "Description states 'never auto-triggered' — opt-in deep-load only.",
+    "memory-promote": "Curation pipeline — overlaps /memory-add; keep explicit.",
+    "mode": "Role-mode switch is a deliberate context change.",
+    "onboard": "Gated by the onboarding-gate rule already; never inferred from prose.",
+    "optimize-augmentignore": "Niche maintenance tool with no recurring NL trigger.",
+    "optimize-rtk-filters": "Niche maintenance tool with no recurring NL trigger.",
+    "package-reset": "Package-internal destructive reset.",
+    "package-test": "Package-internal — only the event4u/agent-config repo runs this.",
+    "propose-memory": "Programmatic intake fallback — overlaps /memory-add; keep explicit.",
+    "set-cost-profile": "Settings mutation — must be deliberate.",
+    "sync-agent-settings": "Settings sync — must be deliberate.",
+    "sync-gitignore": "Settings sync — must be deliberate.",
+}
+
+# (trigger_description, trigger_context)
+ELIGIBLE: dict[str, tuple[str, str]] = {
+    "agents-audit": ("audit my agent docs, check the state of the agents/ directory", "stale files under agents/ or recent edits to .augment/ without doc updates"),
+    "analyze-reference-repo": ("look at how X does this, compare with that other repo, study this competitor's approach", "external repo URL or path mentioned in the prompt"),
+    "bug-fix": ("fix this bug, patch the issue, resolve this error", "branch name matches fix/* or bug/*"),
+    "bug-investigate": ("why is this broken, investigate this error, trace the root cause", "Sentry URL, Jira bug ticket key, or stack trace pasted in the prompt"),
+    "commit": ("commit my changes, save this to git, create commits for these changes", "git status shows uncommitted changes"),
+    "commit-in-chunks": ("commit everything autonomously, split and commit without confirmation", "autonomous mode active and uncommitted changes present"),
+    "context-create": ("document this part of the codebase, create a context doc for X", "working in a module without an agents/contexts/ doc"),
+    "context-refactor": ("update the context doc, refresh this context document", "existing agents/contexts/*.md referenced in the prompt"),
+    "create-pr": ("open a PR, create a pull request, make a PR for this branch", "branch is ahead of base and not yet on a PR"),
+    "create-pr-description": ("write a PR description, draft the PR text", "PR exists or branch ready for review without description"),
+    "e2e-heal": ("fix the failing E2E tests, playwright tests are red", "failing test output from tests/e2e/"),
+    "e2e-plan": ("plan E2E tests for this feature, what should we cover in playwright", "new feature or page added without tests/e2e/ coverage"),
+    "estimate-ticket": ("how big is this ticket, estimate PROJ-123, should we split this", "ticket key matching [A-Z]+-[0-9]+ in the prompt and no plan yet"),
+    "feature-dev": ("build this feature end-to-end, run the full feature workflow", "long-form feature description spanning multiple components"),
+    "feature-explore": ("brainstorm this idea, explore this feature concept", "open-ended feature idea without acceptance criteria"),
+    "feature-plan": ("plan this feature, create a feature spec for X", "feature idea referenced and no plan doc exists"),
+    "feature-refactor": ("update the feature plan, refine the feature spec", "existing agents/features/*.md referenced in the prompt"),
+    "feature-roadmap": ("turn this feature into a roadmap, generate the implementation roadmap", "existing feature plan without linked roadmap"),
+    "fix-ci": ("CI is failing, fix the GitHub Actions errors, the pipeline is red", "open PR with failing checks"),
+    "fix-pr-bot-comments": ("address the Copilot/Greptile comments, fix the bot review feedback", "open PR with bot review comments unresolved"),
+    "fix-pr-comments": ("fix all PR review comments, resolve the review feedback", "open PR with unresolved comments (bot + human)"),
+    "fix-pr-developer-comments": ("fix the human reviewer comments, address the developer feedback", "open PR with unresolved human-reviewer comments"),
+    "fix-seeder": ("the seeder is broken, foreign key errors in seeders", "seeder error output or recent edits in database/seeders/"),
+    "implement-ticket": ("implement this ticket, setze ticket X um, build PROJ-123", "ticket key matching [A-Z]+-[0-9]+ in branch name or prompt"),
+    "jira-ticket": ("implement the ticket on this branch, work on the Jira ticket from the branch", "branch name matching feat/PROJ-123-* or similar"),
+    "memory-add": ("remember this for later, add this to engineering memory, capture this learning", "post-incident or post-decision conversation"),
+    "module-create": ("create a new module, scaffold a module for X", "prompt mentions a new domain area without an existing module"),
+    "module-explore": ("show me the X module, load the module context", "existing Modules/<Name>/ referenced in the prompt"),
+    "optimize-agents": ("audit agent infrastructure, tune the agent setup", "maintainer working on .augment/ files"),
+    "optimize-skills": ("audit my skills, find duplicate skills", "maintainer working on .augment/skills/ files"),
+    "override-create": ("override this skill for the project, customize this rule locally", "prompt names a shared skill/rule needing project-specific behavior"),
+    "override-manage": ("review my overrides, update the project overrides", "existing entries under agents/overrides/"),
+    "prepare-for-review": ("get this branch ready for review, rebase and prep for PR", "branch behind base or part of a PR chain"),
+    "project-analyze": ("analyze the project structure, do a full project audit", "new project or after a major refactor"),
+    "project-health": ("check project health, what's the state of my docs and modules", "routine health check, no destructive intent"),
+    "quality-fix": ("fix the quality errors, run PHPStan and fix issues, fix code style", "PHPStan/Rector/ECS output in recent tool results"),
+    "refine-ticket": ("refine PROJ-123, tighten the acceptance criteria, is this ticket clear", "ticket key in prompt with vague acceptance criteria"),
+    "review-changes": ("self-review my changes, judge this diff before PR", "uncommitted or staged changes pre-PR"),
+    "review-routing": ("who should review this, suggest reviewers for this PR", "PR open without assigned reviewers"),
+    "roadmap-create": ("create a roadmap for X, plan this work as a roadmap", "multi-phase work without an existing agents/roadmaps/*.md"),
+    "roadmap-execute": ("execute the roadmap, work through the roadmap step by step", "existing agents/roadmaps/*.md referenced in the prompt"),
+    "rule-compliance-audit": ("audit my rules, check rule trigger quality", "maintainer working on .augment/rules/ files"),
+    "tests-create": ("write tests for these changes, add tests for this branch", "code changes on the branch without matching test changes"),
+    "tests-execute": ("run the tests, execute the test suite", "code changes pending verification"),
+    "threat-model": ("threat model this change, what could go wrong security-wise", "changes touching auth, webhooks, uploads, secrets, or public endpoints"),
+    "update-form-request-messages": ("sync the form request messages, update the validation messages", "edits to app/Http/Requests/*.php referencing rules without messages"),
+    "upstream-contribute": ("contribute this back to agent-config, upstream this learning", "project-local skill/rule that fits the shared package"),
+    "work": ("build this, implement this, drive this end-to-end", "free-form prompt without a ticket key"),
+}
+
+FRONTMATTER_RE = re.compile(r"^(---\n)(.*?)(\n---\n)", re.DOTALL)
+
+
+def build_block(name: str) -> str:
+    if name in INELIGIBLE:
+        rationale = INELIGIBLE[name].replace('"', '\\"')
+        return f'suggestion:\n  eligible: false\n  rationale: "{rationale}"'
+    if name in ELIGIBLE:
+        td, tc = ELIGIBLE[name]
+        td_e = td.replace('"', '\\"')
+        tc_e = tc.replace('"', '\\"')
+        return (f'suggestion:\n  eligible: true\n'
+                f'  trigger_description: "{td_e}"\n'
+                f'  trigger_context: "{tc_e}"')
+    raise SystemExit(f"command not classified: {name}")
+
+
+def migrate_one(path: Path) -> str:
+    name = path.stem
+    text = path.read_text(encoding="utf-8")
+    if "\nsuggestion:" in text.split("\n---\n", 1)[0]:
+        return "skip"
+    m = FRONTMATTER_RE.search(text)
+    if not m:
+        return "no-frontmatter"
+    body = m.group(2)
+    block = build_block(name)
+    new_body = body.rstrip() + "\n" + block
+    new_text = text[: m.start()] + m.group(1) + new_body + m.group(3) + text[m.end():]
+    path.write_text(new_text, encoding="utf-8")
+    return "ok"
+
+
+def main() -> int:
+    files = sorted(COMMANDS_DIR.glob("*.md"))
+    counts = {"ok": 0, "skip": 0, "no-frontmatter": 0}
+    for f in files:
+        status = migrate_one(f)
+        counts[status] += 1
+    print(f"migrated {counts['ok']}, skipped {counts['skip']}, "
+          f"no-frontmatter {counts['no-frontmatter']}, total {len(files)}")
+    expected = len(INELIGIBLE) + len(ELIGIBLE)
+    if len(files) != expected:
+        print(f"WARNING: file count {len(files)} != table count {expected}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/schemas/command.schema.json

@@ -27,6 +27,47 @@
         "type": "string",
         "pattern": "^[a-z][a-z0-9-]*$"
       }
+    },
+    "suggestion": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["eligible"],
+      "description": "Context-aware command-suggestion metadata. The suggestion layer is read-only and never auto-executes; see road-to-context-aware-command-suggestion.",
+      "properties": {
+        "eligible": {
+          "type": "boolean",
+          "description": "true → suggestion layer may surface this command; false → never suggest (still works when typed explicitly)."
+        },
+        "rationale": {
+          "type": "string",
+          "minLength": 0,
+          "maxLength": 240,
+          "description": "Why the command is ineligible. Required when eligible: false (enforced by linter)."
+        },
+        "trigger_description": {
+          "type": "string",
+          "minLength": 0,
+          "maxLength": 240,
+          "description": "Natural-language pattern trigger. Required when eligible: true (enforced by linter)."
+        },
+        "trigger_context": {
+          "type": "string",
+          "minLength": 0,
+          "maxLength": 240,
+          "description": "Concrete signal trigger (branch name, file pattern, recent tool output). Required when eligible: true (enforced by linter)."
+        },
+        "confidence_floor": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Optional per-command override of the global confidence floor (0.0–1.0). Defaults to settings."
+        },
+        "cooldown": {
+          "type": "string",
+          "minLength": 0,
+          "maxLength": 16,
+          "description": "Optional per-command override of the global cooldown duration (e.g. '10m'). Defaults to settings."
+        }
+      }
     }
   }
 }

package/scripts/skill_linter.py

@@ -772,6 +772,70 @@ def lint_rule(path: Path, text: str) -> LintResult:
     )
 
 
+def _lint_command_suggestion_block(text: str) -> List[Issue]:
+    """Validate the suggestion frontmatter block (road-to-context-aware-command-suggestion).
+
+    Schema-shape is enforced upstream by validate_frontmatter; this function adds the
+    *conditional* content rules that JSON Schema (Draft-07 subset used here) cannot
+    express: trigger fields must be non-empty when eligible, rationale must be
+    non-empty when ineligible.
+    """
+    issues: List[Issue] = []
+    data, _offset = parse_frontmatter_for_schema(text)
+    if data is None:
+        return issues
+    suggestion = data.get("suggestion")
+    if suggestion is None:
+        issues.append(Issue(
+            "warning", "missing_suggestion_block",
+            "Command frontmatter is missing the 'suggestion' block — required by "
+            "road-to-context-aware-command-suggestion Phase 2.",
+        ))
+        return issues
+    if not isinstance(suggestion, dict):
+        issues.append(Issue("error", "invalid_suggestion_block", "'suggestion' must be a mapping"))
+        return issues
+    eligible = suggestion.get("eligible")
+    if eligible is True:
+        td = (suggestion.get("trigger_description") or "").strip()
+        tc = (suggestion.get("trigger_context") or "").strip()
+        if not td:
+            issues.append(Issue(
+                "error", "missing_trigger_description",
+                "suggestion.eligible=true requires a non-empty 'trigger_description'.",
+            ))
+        elif len(td) < 10:
+            issues.append(Issue(
+                "warning", "trigger_description_too_short",
+                "suggestion.trigger_description is suspiciously short (<10 chars); "
+                "linter rejects empty or overly generic patterns.",
+            ))
+        if not tc:
+            issues.append(Issue(
+                "error", "missing_trigger_context",
+                "suggestion.eligible=true requires a non-empty 'trigger_context'.",
+            ))
+        elif len(tc) < 10:
+            issues.append(Issue(
+                "warning", "trigger_context_too_short",
+                "suggestion.trigger_context is suspiciously short (<10 chars); "
+                "linter rejects empty or overly generic patterns.",
+            ))
+    elif eligible is False:
+        rationale = (suggestion.get("rationale") or "").strip()
+        if not rationale:
+            issues.append(Issue(
+                "error", "missing_suggestion_rationale",
+                "suggestion.eligible=false requires a non-empty 'rationale'.",
+            ))
+    else:
+        issues.append(Issue(
+            "error", "invalid_suggestion_eligible",
+            "suggestion.eligible must be true or false.",
+        ))
+    return issues
+
+
 def lint_command(path: Path, text: str) -> LintResult:
     issues: List[Issue] = []
     suggestions: List[str] = []
@@ -800,6 +864,9 @@ def lint_command(path: Path, text: str) -> LintResult:
         if not description:
             issues.append(Issue("warning", "missing_description", "Frontmatter description is missing"))
 
+        # suggestion block (road-to-context-aware-command-suggestion Phase 2)
+        issues.extend(_lint_command_suggestion_block(text))
+
     # --- Structure checks ---
     if not H1_PATTERN.search(text):
         issues.append(Issue("error", "missing_h1", "Command is missing an H1 heading (# Title)"))

package/scripts/sync_agent_settings.py

@@ -47,29 +47,48 @@ DEFAULT_PROFILE_DIR = Path(__file__).resolve().parent.parent / "config" / "profi
 
 
 def _flatten(data: dict, prefix: str = "") -> dict[str, object]:
-    """Flatten nested dicts to dotted keys — one level of nesting supported."""
+    """Flatten nested dicts to dotted keys — recurses to all leaves.
+
+    Lists, scalars, and ``None`` are leaves. Dicts are walked and their
+    keys folded into the dotted path.
+    """
     out: dict[str, object] = {}
     for key, value in data.items():
         path = f"{prefix}{key}"
         if isinstance(value, dict):
-            for sub_key, sub_val in value.items():
-                out[f"{path}.{sub_key}"] = sub_val
+            out.update(_flatten(value, prefix=f"{path}."))
         else:
             out[path] = value
     return out
 
 
-def _as_scalar_text(value: object) -> str:
-    """Normalize a parsed YAML value to the raw string form expected by
-    `install._replace_template_value` — which re-quotes via `_yaml_scalar`
-    internally, so we must pass the *unquoted* payload here."""
+def _as_yaml_value(value: object) -> str | None:
+    """Format *value* as an inline-YAML literal.
+
+    Returns ``None`` when the value cannot be safely represented as a
+    scalar / flow-style sequence (e.g. unsupported types). Callers
+    must skip those keys so the template default sticks instead of
+    producing malformed YAML.
+    """
     if isinstance(value, bool):
         return "true" if value else "false"
     if isinstance(value, int):
         return str(value)
+    if isinstance(value, float):
+        return repr(value)
     if value is None:
-        return ""
-    return str(value)
+        return "~"
+    if isinstance(value, list):
+        items: list[str] = []
+        for item in value:
+            rendered = _as_yaml_value(item)
+            if rendered is None:
+                return None
+            items.append(rendered)
+        return "[" + ", ".join(items) + "]"
+    if isinstance(value, str):
+        return _install._yaml_scalar(value)
+    return None
 
 
 def _template_keys(template_body: str) -> set[str]:
@@ -81,10 +100,18 @@ def _template_keys(template_body: str) -> set[str]:
 
 
 def _apply_user_values(template_body: str, user_flat: dict[str, object]) -> str:
-    """Overlay every known user value on the rendered template body."""
+    """Overlay every known user value on the rendered template body.
+
+    Keys whose value cannot be rendered inline (see :func:`_as_yaml_value`)
+    are skipped so the template default survives instead of corrupting
+    the file.
+    """
     body = template_body
     for dotted, value in user_flat.items():
-        body = _install._replace_template_value(body, dotted, _as_scalar_text(value))
+        rendered = _as_yaml_value(value)
+        if rendered is None:
+            continue
+        body = _install._replace_template_value_raw(body, dotted, rendered)
     return body
 
 
@@ -100,7 +127,10 @@ def _append_unknown(body: str, user_flat: dict[str, object], known: set[str]) ->
         "_user:",
     ]
     for key in unknown:
-        lines.append(f"  {key}: {_install._yaml_scalar(_as_scalar_text(user_flat[key]))}")
+        rendered = _as_yaml_value(user_flat[key])
+        if rendered is None:
+            continue
+        lines.append(f"  {key}: {rendered}")
     suffix = "\n".join(lines) + "\n"
     return body + (suffix if body.endswith("\n") else "\n" + suffix)
 

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

@@ -0,0 +1,54 @@
+{
+  "// Instructions": "OPTIONAL: merge this into ~/.augment/settings.json (user-scope, NOT project-scope) to wire chat-history hooks for the Augment CLI.",
+  "// Why user-scope": "The Augment CLI reads hooks from ~/.augment/settings.json (per https://docs.augmentcode.com/cli/hooks.md). Project-scoped .augment/settings.json belongs to the IDE plugin, which has no documented hook surface as of 2026-04-30.",
+  "// IDE plugin": "Use the /chat-history-checkpoint command at phase boundaries instead — see rules/chat-history.md.",
+  "// Wrapper": "The command assumes the project-root ./agent-config wrapper is on PATH or invoked with a project-relative cwd. Adjust to absolute paths if your shell does not chdir into the project.",
+
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./agent-config chat-history:hook --platform augment",
+            "timeout": 5000
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./agent-config chat-history:hook --platform augment",
+            "timeout": 3000
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./agent-config chat-history:hook --platform augment",
+            "timeout": 3000
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./agent-config chat-history:hook --platform augment",
+            "timeout": 3000
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -1,9 +1,63 @@
 {
-  "// Instructions": "Copy this into your project's .claude/settings.json to auto-enable the agent-config plugin.",
+  "// Instructions": "Copy this into your project's .claude/settings.json to auto-enable the agent-config plugin and chat-history hooks.",
   "// After setup": "Claude Code will load the plugin when the marketplace is installed.",
   "// Install marketplace": "Run: claude plugin marketplace add event4u-app/agent-config",
+  "// Hooks": "Hooks call ./agent-config (the wrapper installed at the project root) which dispatches to scripts/chat_history.py hook-dispatch. They are no-ops when chat_history.enabled is false in .agent-settings.yml.",
 
   "enabledPlugins": {
     "agent-conf@event4u": true
+  },
+
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./agent-config chat-history:hook --platform claude"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./agent-config chat-history:hook --platform claude"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./agent-config chat-history:hook --platform claude"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./agent-config chat-history:hook --platform claude"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./agent-config chat-history:hook --platform claude"
+          }
+        ]
+      }
+    ]
   }
 }