@event4u/agent-config 1.39.0 → 1.40.0

package/docs/setup/per-ide/codex.md

@@ -0,0 +1,46 @@
+# OpenAI Codex CLI Setup
+
+OpenAI's Codex CLI (the `codex` command) reads `AGENTS.md` from the
+repo root for project context.
+
+## Prerequisites
+
+- Codex CLI installed: <https://github.com/openai/codex>.
+- Node.js ≥ 18 (for the install entrypoints).
+
+## Install
+
+```bash
+npx @event4u/create-agent-config init --tools=codex
+```
+
+Populates:
+
+- `AGENTS.md`             — agent self-orientation (Codex auto-loads)
+- `.agent-settings.yml`   — per-project knobs
+
+Codex CLI reads `AGENTS.md` automatically when invoked from the repo
+root. No additional configuration needed.
+
+## Verification
+
+```bash
+test -f AGENTS.md
+codex --help            # confirm CLI installed
+```
+
+In a Codex CLI session, the loaded `AGENTS.md` content informs every
+turn — verify by asking *"what is this repo?"* and confirming the
+answer matches `AGENTS.md`'s emergency-triage block.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| Codex ignores `AGENTS.md` | Run from repo root, not a subdirectory. |
+| Out-of-date context | `codex` re-reads on each session start — quit and restart. |
+
+## Cross-references
+
+- [`AGENTS.md`](../../../AGENTS.md) — canonical agent self-orientation.
+- [`docs/installation.md`](../../installation.md) — install matrix index.

package/docs/setup/per-ide/copilot.md

@@ -0,0 +1,80 @@
+# GitHub Copilot Setup
+
+GitHub Copilot Chat (VS Code, JetBrains, Neovim, `gh copilot` CLI)
+reads `.github/copilot-instructions.md` for project-level guidance and
+falls back to `AGENTS.md` where supported.
+
+## Prerequisites
+
+- GitHub Copilot subscription (Individual, Business, or Enterprise).
+- Copilot Chat enabled in your IDE.
+- Node.js ≥ 18 for the install entrypoints.
+
+## Install
+
+```bash
+npx @event4u/create-agent-config init --tools=copilot
+```
+
+Populates:
+
+- `.github/copilot-instructions.md` — Copilot's project-level prompt
+- `AGENTS.md`                       — canonical agent self-orientation
+- `.agent-settings.yml`             — per-project knobs
+
+The package keeps `.github/copilot-instructions.md` deliberately thin
+(it points back to `AGENTS.md`) so all surfaces share a single source
+of truth.
+
+## VS Code Copilot Chat
+
+Auto-loads `.github/copilot-instructions.md` once you reload the VS
+Code window after install. Verify in the Copilot Chat panel —
+*"What is this repo?"* should answer using the AGENTS.md emergency
+triage block.
+
+## JetBrains Copilot
+
+JetBrains Copilot 1.5+ reads the same `.github/copilot-instructions.md`
+file. No extra steps; reload the project after install.
+
+## Neovim Copilot
+
+`copilot.lua` and `CopilotChat.nvim` honor
+`.github/copilot-instructions.md`. No extra config needed.
+
+## `gh copilot` CLI
+
+The `gh copilot` plugin (`gh extension install github/gh-copilot`)
+reads the repo context including `AGENTS.md` and
+`.github/copilot-instructions.md` when invoked from the repo root.
+
+## Suppressing Copilot PR review noise
+
+Copilot's PR auto-review can flag the package's own kernel rules as
+"unusual phrasing". The package ships a Copilot-suppression rule
+([`augment-portability`](../../../.augment/rules/augment-portability.md))
+that documents this trade-off.
+
+## Verification
+
+```bash
+test -f .github/copilot-instructions.md
+test -f AGENTS.md
+gh copilot --version             # if you want CLI plugin
+```
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| Copilot ignores the file | Reload the IDE window after install. |
+| File missing after install | Re-run `npx @event4u/create-agent-config init --tools=copilot`. |
+| Copilot PR review too noisy | See the `copilot-config` skill for suppression patterns. |
+
+## Cross-references
+
+- [`AGENTS.md`](../../../AGENTS.md) — canonical agent self-orientation.
+- [`.augment/skills/copilot-config/SKILL.md`](../../../.augment/skills/copilot-config/SKILL.md)
+  — tuning Copilot output and suppressing review noise.
+- [`docs/installation.md`](../../installation.md) — install matrix index.

package/docs/setup/per-ide/cursor.md

@@ -0,0 +1,125 @@
+# Cursor Setup
+
+Cursor reads two rule formats:
+
+- **Modern (`.mdc`)** — `.cursor/rules/<rule>.mdc` with YAML frontmatter
+  (`description`, `globs`, `alwaysApply`). Preferred for any 2025+
+  Cursor build.
+- **Legacy (`.cursorrules`)** — single-file aggregate at the repo root.
+  Still read by older Cursor versions; the package keeps it for
+  backward compatibility.
+
+The package ships **both** so you don't have to pick.
+
+## Prerequisites
+
+- Cursor 0.45+ (any 2025/2026 build): <https://cursor.com>.
+- Node.js ≥ 18.
+
+## Project install
+
+```bash
+npx @event4u/create-agent-config init --tools=cursor
+```
+
+This populates:
+
+- `.cursor/rules/*.mdc`     — one file per rule, modern frontmatter format
+- `.cursor/commands/*.md`   — slash commands mirrored from `.agent-src/commands/`
+- `.cursorrules`            — legacy single-file aggregate
+- `.agent-settings.yml`     — per-project knobs
+
+Combine surfaces if you use both Cursor and Claude Code:
+
+```bash
+npx @event4u/create-agent-config init --tools=cursor,claude-code
+```
+
+## Global install
+
+```bash
+npx @event4u/agent-config global --tools=cursor
+```
+
+Seeds `~/.cursor/rules/imported/event4u/` with the curated kernel +
+top-N skills. Cursor merges global + workspace rules — workspace wins
+on conflicts.
+
+## Modern `.mdc` frontmatter
+
+Each `.mdc` file has the Cursor-shaped header:
+
+```mdc
+---
+description: Scope control — no unsolicited architectural changes
+globs:
+alwaysApply: true
+---
+
+# Scope Control
+...
+```
+
+- `alwaysApply: true` ↔ source `type: "always"` (kernel rules).
+- `alwaysApply: false` ↔ Cursor model decides per turn (auto rules).
+- `globs:` is intentionally empty in the package's projection — apply
+  per-rule if you need path-scoped rules in your fork.
+
+## Cursor commands
+
+`.cursor/commands/<slug>.md` mirrors `.claude/commands/`. Nested
+clusters (e.g. `council/default.md`) flatten to `council-default.md` so
+Cursor's command palette stays flat.
+
+## Marketplace install (planned — Phase 7 / S35)
+
+The Cursor marketplace listing is filed in
+`road-to-simplicity-and-everywhere.md` Phase 7. Once accepted you'll
+be able to install via Cursor's Extensions panel without `npx`.
+
+## MCP block (when MCP Phase 3 ships)
+
+Add to `.cursor/mcp.json` (Cursor's project-scoped MCP config):
+
+```json
+{
+  "mcpServers": {
+    "event4u-agent-config": {
+      "command": "npx",
+      "args": ["-y", "@event4u/agent-config-mcp"]
+    }
+  }
+}
+```
+
+Track <https://github.com/event4u-app/agent-config> for the actual
+release tag — until `road-to-mcp-full-coverage` Phase 3 ships, this
+block is informational.
+
+## Verification
+
+```bash
+ls -la .cursor/rules/   | head -5      # *.mdc files exist
+ls -la .cursor/commands/| head -5      # *.md command files exist
+test -f .cursorrules                   # legacy aggregate exists
+```
+
+In Cursor itself: open the chat panel — settings should show the rules
+under **Project Rules**.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| Rules not picked up | Cursor < 0.45 — upgrade or rely on `.cursorrules`. |
+| Modern + legacy duplicate triggers | Disable `.cursorrules` in Cursor settings. |
+| Command missing in palette | `task generate-tools` then reload Cursor window. |
+| Global rules ignored | Cursor needs `~/.cursor/rules/` — check OS path expansion. |
+
+## Cross-references
+
+- [`docs/installation.md`](../../installation.md) — install matrix index.
+- [`AGENTS.md`](../../../AGENTS.md) — package self-orientation; Cursor
+  reads it via the projected rules.
+- [`templates/cursor-rule.mdc.j2`](../../../templates/cursor-rule.mdc.j2) —
+  template used by the projection generator.

package/docs/setup/per-ide/gemini-cli.md

@@ -0,0 +1,45 @@
+# Gemini CLI Setup
+
+Google's Gemini CLI reads `GEMINI.md` (which is a symlink to `AGENTS.md`
+in the package's projection) for project context.
+
+## Prerequisites
+
+- Gemini CLI installed: <https://github.com/google-gemini/gemini-cli>.
+- Node.js ≥ 18 (for the install entrypoints).
+
+## Install
+
+```bash
+npx @event4u/create-agent-config init --tools=gemini
+```
+
+Populates:
+
+- `GEMINI.md` → `AGENTS.md` — symlink so Gemini CLI loads the same
+  self-orientation as Codex / Aider / Augment.
+- `AGENTS.md`             — canonical content (single source of truth).
+- `.agent-settings.yml`   — per-project knobs.
+
+## Verification
+
+```bash
+test -L GEMINI.md && readlink GEMINI.md   # → AGENTS.md
+gemini --version                           # confirm CLI installed
+```
+
+In a Gemini CLI session: `GEMINI.md` informs every turn — verify by
+asking *"what is this repo?"* and confirming the answer matches
+`AGENTS.md`'s emergency-triage block.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| Gemini CLI doesn't see `GEMINI.md` | Some Gemini versions require absolute paths — `gemini --context $(pwd)/GEMINI.md`. |
+| Symlink broken on Windows | Re-run installer; on Windows the projection may emit a copy instead of a symlink. |
+
+## Cross-references
+
+- [`AGENTS.md`](../../../AGENTS.md) — canonical agent self-orientation.
+- [`docs/installation.md`](../../installation.md) — install matrix index.

package/docs/setup/per-ide/windsurf.md

@@ -0,0 +1,120 @@
+# Windsurf Setup
+
+Windsurf reads two rule formats:
+
+- **Wave-8 (`.windsurf/rules/`)** — per-rule `.md` files with
+  `trigger`, `description`, `globs` frontmatter. Preferred for
+  Windsurf 1.5+.
+- **Legacy (`.windsurfrules`)** — single-file aggregate at the repo
+  root. Older Windsurf builds and the Cascade chat fallback both still
+  read it.
+
+The package ships **both**.
+
+## Prerequisites
+
+- Windsurf 1.0+ (Codeium): <https://codeium.com/windsurf>.
+- Node.js ≥ 18.
+
+## Project install
+
+```bash
+npx @event4u/create-agent-config init --tools=windsurf
+```
+
+Populates:
+
+- `.windsurf/rules/*.md`        — modern Wave-8 per-rule files
+- `.windsurf/workflows/*.md`    — slash-command workflows
+- `.windsurfrules`              — legacy single-file aggregate
+- `.agent-settings.yml`         — per-project knobs
+
+Combine with other surfaces:
+
+```bash
+npx @event4u/create-agent-config init --tools=windsurf,claude-code,cursor
+```
+
+## Global install
+
+```bash
+npx @event4u/agent-config global --tools=windsurf
+```
+
+Seeds `~/.codeium/windsurf/global_workflows/` with the curated
+workflow set (see [`templates/global-install-manifest.yml`](../../../templates/global-install-manifest.yml)).
+Available across every project; per-workspace `.windsurf/workflows/`
+takes precedence on slug collisions.
+
+## Wave-8 frontmatter
+
+Each rule under `.windsurf/rules/` has the Windsurf-shaped header:
+
+```md
+---
+trigger: always_on
+description: Scope control — no unsolicited architectural changes
+globs:
+---
+
+# Scope Control
+...
+```
+
+- `trigger: always_on` ↔ source `type: "always"` (kernel rules).
+- `trigger: model_decision` ↔ Cascade decides per turn (auto rules).
+- `globs:` is intentionally empty in the package's projection — set
+  per-rule in your fork if you want path-scoped triggering.
+
+## Workflows
+
+`.windsurf/workflows/<slug>.md` mirrors `.claude/commands/`. Cluster
+commands flatten to `<cluster>-<name>.md`. Cascade lists all workflow
+files in its workflow palette.
+
+## Cascade integration
+
+Cascade (Windsurf's built-in agent) reads `.windsurf/rules/` and
+`.windsurf/workflows/` automatically. No separate registration step is
+needed once the files are on disk.
+
+When Cascade asks a clarifying question, the package's `user-interaction`
+rule (kernel, `always_on`) applies — Cascade will surface numbered
+options with a single recommendation.
+
+## Workspace vs global precedence
+
+| Layer | Path | Precedence |
+|---|---|---|
+| Workspace | `.windsurf/rules/` + `.windsurf/workflows/` | wins on conflicts |
+| Global | `~/.codeium/windsurf/global_workflows/` | falls back when workspace silent |
+
+Reuse the same `--tools=windsurf` flag for both — `init` writes
+workspace, `global` writes user-level.
+
+## Verification
+
+```bash
+ls .windsurf/rules/     | head -5      # *.md per-rule files
+ls .windsurf/workflows/ | head -5      # *.md workflow files
+test -f .windsurfrules                 # legacy aggregate exists
+```
+
+In Windsurf itself: open Cascade → Workflows panel — listed workflows
+should match `ls .windsurf/workflows/`.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| Rules not picked up | Windsurf < 1.0 — upgrade or rely on `.windsurfrules`. |
+| Workflow not in Cascade panel | Reload window after `task generate-tools`. |
+| Global workflows missing | Check `~/.codeium/windsurf/global_workflows/` exists. |
+| Frontmatter parse error | Re-run `python3 scripts/compress.py --generate-tools`. |
+
+## Cross-references
+
+- [`docs/installation.md`](../../installation.md) — install matrix index.
+- [`templates/windsurf-rule.md.j2`](../../../templates/windsurf-rule.md.j2)
+  — template used by the projection generator.
+- [`AGENTS.md`](../../../AGENTS.md) — package self-orientation.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "1.39.0",
+    "version": "1.40.0",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,

package/scripts/compress.py

@@ -26,6 +26,8 @@ import shutil
 import sys
 from pathlib import Path
 
+import yaml
+
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 from _lib.script_output import info, success, flush_summary, resolve_level  # noqa: E402
 
@@ -503,6 +505,149 @@ def generate_windsurfrules() -> int:
     return len(rules)
 
 
+# ── Modern editor formats (road-to-simplicity-and-everywhere Phase 5) ─
+# Cursor `.cursor/rules/*.mdc` (frontmatter: description, globs,
+# alwaysApply) and Windsurf `.windsurf/rules/*.md` (frontmatter:
+# trigger, description, globs) are the formats current editors prefer.
+# Legacy `.windsurfrules` aggregate stays for users who prefer it.
+
+CURSOR_RULES_MDC_DIR = PROJECT_ROOT / ".cursor" / "rules"
+WINDSURF_RULES_DIR = PROJECT_ROOT / ".windsurf" / "rules"
+WINDSURF_WORKFLOWS_DIR = PROJECT_ROOT / ".windsurf" / "workflows"
+CURSOR_COMMANDS_DIR = PROJECT_ROOT / ".cursor" / "commands"
+
+
+def _parse_frontmatter(content: str) -> tuple[dict, str]:
+    """Split a `---`-delimited YAML frontmatter from the body."""
+    if not content.startswith("---"):
+        return {}, content
+    end = content.find("\n---", 3)
+    if end == -1:
+        return {}, content
+    raw = content[3:end].strip()
+    body = content[end + 4:].lstrip("\n")
+    try:
+        meta = yaml.safe_load(raw) or {}
+    except yaml.YAMLError:
+        meta = {}
+    return meta if isinstance(meta, dict) else {}, body
+
+
+def _emit_cursor_mdc(source: Path, target: Path) -> None:
+    """Write a Cursor `.mdc` file with Cursor-shaped frontmatter."""
+    meta, body = _parse_frontmatter(source.read_text())
+    description = (meta.get("description") or "").replace("\n", " ").strip()
+    always_apply = bool(meta.get("alwaysApply") or meta.get("type") == "always")
+    lines = [
+        "---",
+        f"description: {description}",
+        "globs: ",
+        f"alwaysApply: {'true' if always_apply else 'false'}",
+        "---",
+        "",
+        body.rstrip() + "\n",
+    ]
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text("\n".join(lines))
+
+
+def _emit_windsurf_rule(source: Path, target: Path) -> None:
+    """Write a Windsurf rule with Wave-8 frontmatter (trigger/description/globs)."""
+    meta, body = _parse_frontmatter(source.read_text())
+    description = (meta.get("description") or "").replace("\n", " ").strip()
+    always_apply = bool(meta.get("alwaysApply") or meta.get("type") == "always")
+    trigger = "always_on" if always_apply else "model_decision"
+    lines = [
+        "---",
+        f"trigger: {trigger}",
+        f"description: {description}",
+        "globs: ",
+        "---",
+        "",
+        body.rstrip() + "\n",
+    ]
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text("\n".join(lines))
+
+
+def _clean_modern_dir(target_dir: Path, valid_names: set[str]) -> None:
+    """Drop files in `target_dir` whose names are not in `valid_names`."""
+    if not target_dir.exists():
+        return
+    for item in target_dir.iterdir():
+        if item.name == "README.md":
+            continue
+        if item.name not in valid_names:
+            if item.is_dir() and not item.is_symlink():
+                shutil.rmtree(item)
+            else:
+                item.unlink()
+
+
+def generate_cursor_mdc_rules() -> int:
+    """Emit `.cursor/rules/*.mdc` per source rule (alongside legacy `.md` symlinks)."""
+    rules = sorted(RULES_SOURCE.glob("*.md"))
+    valid = {f"{r.stem}.mdc" for r in rules}
+    _clean_modern_dir(CURSOR_RULES_MDC_DIR, valid | {r.name for r in rules})
+    for rule in rules:
+        _emit_cursor_mdc(rule, CURSOR_RULES_MDC_DIR / f"{rule.stem}.mdc")
+    info(f"  ✅  Wrote {len(rules)} `.cursor/rules/*.mdc` files")
+    return len(rules)
+
+
+def generate_windsurf_modern_rules() -> int:
+    """Emit `.windsurf/rules/*.md` per source rule (Wave-8 frontmatter)."""
+    rules = sorted(RULES_SOURCE.glob("*.md"))
+    valid = {r.name for r in rules}
+    _clean_modern_dir(WINDSURF_RULES_DIR, valid)
+    for rule in rules:
+        _emit_windsurf_rule(rule, WINDSURF_RULES_DIR / rule.name)
+    info(f"  ✅  Wrote {len(rules)} `.windsurf/rules/*.md` files")
+    return len(rules)
+
+
+def generate_cursor_commands() -> int:
+    """Symlink `.cursor/commands/<slug>.md` per source command."""
+    if not COMMANDS_SOURCE.exists():
+        return 0
+    cmds = list(_iter_commands())
+    valid = {f"{slug}.md" for _, slug in cmds}
+    _clean_modern_dir(CURSOR_COMMANDS_DIR, valid)
+    CURSOR_COMMANDS_DIR.mkdir(parents=True, exist_ok=True)
+    count = 0
+    for source_file, slug in cmds:
+        link = CURSOR_COMMANDS_DIR / f"{slug}.md"
+        if link.exists() or link.is_symlink():
+            link.unlink()
+        rel = Path("../../.agent-src/commands") / source_file.relative_to(COMMANDS_SOURCE)
+        link.symlink_to(rel)
+        count += 1
+    info(f"  ✅  Linked {count} `.cursor/commands/*.md` files")
+    return count
+
+
+def generate_windsurf_workflows() -> int:
+    """Symlink `.windsurf/workflows/<slug>.md` per source command."""
+    if not COMMANDS_SOURCE.exists():
+        return 0
+    cmds = list(_iter_commands())
+    valid = {f"{slug}.md" for _, slug in cmds}
+    _clean_modern_dir(WINDSURF_WORKFLOWS_DIR, valid)
+    WINDSURF_WORKFLOWS_DIR.mkdir(parents=True, exist_ok=True)
+    count = 0
+    for source_file, slug in cmds:
+        link = WINDSURF_WORKFLOWS_DIR / f"{slug}.md"
+        if link.exists() or link.is_symlink():
+            link.unlink()
+        rel = Path("../../.agent-src/commands") / source_file.relative_to(COMMANDS_SOURCE)
+        link.symlink_to(rel)
+        count += 1
+    info(f"  ✅  Linked {count} `.windsurf/workflows/*.md` files")
+    return count
+
+
+
+
 def generate_gemini_md() -> None:
     """Create GEMINI.md symlink to AGENTS.md."""
     link = PROJECT_ROOT / "GEMINI.md"
@@ -695,9 +840,15 @@ def generate_tools() -> None:
     skills = generate_claude_skills()
     commands = generate_claude_commands()
     personas = generate_persona_symlinks()
+    cursor_mdc = generate_cursor_mdc_rules()
+    windsurf_modern = generate_windsurf_modern_rules()
+    cursor_cmds = generate_cursor_commands()
+    windsurf_wf = generate_windsurf_workflows()
     summary = (
         f"✅  generate-tools — rules={rules} skills={skills} "
-        f"commands={commands} personas={personas}"
+        f"commands={commands} personas={personas} "
+        f"cursor_mdc={cursor_mdc} windsurf_rules={windsurf_modern} "
+        f"cursor_commands={cursor_cmds} windsurf_workflows={windsurf_wf}"
     )
     if resolve_level() == "verbose":
         print(f"\n{summary}")
@@ -806,6 +957,7 @@ def clean_tools() -> None:
         PROJECT_ROOT / ".claude",
         PROJECT_ROOT / ".cursor",
         PROJECT_ROOT / ".clinerules",
+        PROJECT_ROOT / ".windsurf",
         PROJECT_ROOT / ".windsurfrules",
         PROJECT_ROOT / "GEMINI.md",
     ]