diff --git a/README.md b/README.md index 07a0ea8..94d3077 100644 --- a/README.md +++ b/README.md @@ -116,6 +116,33 @@ All kit agents are namespaced under `kei-*` so they won't collide with your own | `kei-patent-researcher` | Prior-art, FTO, novelty — never leaks unfiled IP to public search | | `kei-patent-compliance` | Pre-filing cross-reference gate and defensive-language helper | +## Cross-tool bridges + +KeiSeiKit ships 11 verified tool-bridge templates under `_bridges/`. Render them into any project and the same Constructor-Pattern ruleset is visible to every AI coding tool you use — no drift, one source of truth. + +**Tools covered:** + +| Tool | Output file | +|---|---| +| Cursor (legacy) | `.cursorrules` | +| Cursor (modern MDC) | `.cursor/rules/main.mdc` | +| Codex CLI / Warp / Zed / Antigravity fallback | `AGENTS.md` | +| GitHub Copilot | `.github/copilot-instructions.md` | +| Windsurf | `.windsurf/rules/main.md` | +| JetBrains Junie | `.junie/guidelines.md` | +| Continue.dev | `.continue/rules/main.md` | +| Google Antigravity / Gemini CLI | `GEMINI.md` | +| Aider | `CONVENTIONS.md` + `.aider.conf.yml` | +| Replit Agent | `replit.md` | + +**Two ways to generate:** + +1. **At install time** — `./install.sh --with-bridges` renders all 11 into `$PWD` after the normal install completes. Skipped if `$PWD` is the KeiSeiKit repo itself. +2. **From the `/new-agent` wizard** — Phase 8 asks click-only whether to generate all 11, just `AGENTS.md`, or skip. +3. **Manually, any time** — `~/.claude/agents/_bridges/emit.sh ` (the install copies `_bridges/` into your agent fleet dir). Add `--only ` to restrict to a single file. + +All paths are idempotent: existing bridge files in the project are skipped, never overwritten. See `_bridges/README.md` for the full template→output-path table. + ## License MIT. See `LICENSE` in this directory. diff --git a/_bridges/README.md b/_bridges/README.md new file mode 100644 index 0000000..7470877 --- /dev/null +++ b/_bridges/README.md @@ -0,0 +1,21 @@ +# `_bridges/` — Cross-tool bridge templates + +Tool-agnostic coding-rules templates, rendered into any project via `_bridges/emit.sh`. Placeholders: `{{PROJECT_NAME}}`, `{{PROJECT_DESCRIPTION}}`, `{{YEAR}}`, `{{MONTH}}`, `{{DATE}}`. + +| Template | Output path | +|---|---| +| `cursorrules.tmpl` | `.cursorrules` | +| `agents-md.tmpl` | `AGENTS.md` | +| `copilot.tmpl` | `.github/copilot-instructions.md` | +| `cursor-mdc.tmpl` | `.cursor/rules/main.mdc` | +| `windsurf.tmpl` | `.windsurf/rules/main.md` | +| `junie.tmpl` | `.junie/guidelines.md` | +| `continue.tmpl` | `.continue/rules/main.md` | +| `gemini.tmpl` | `GEMINI.md` | +| `aider-conventions.tmpl` | `CONVENTIONS.md` | +| `aider-conf.tmpl` | `.aider.conf.yml` | +| `replit.tmpl` | `replit.md` | + +Render: `_bridges/emit.sh [project-name] [project-description]`. Idempotent — existing files are skipped. + +Cross-ref: KeiAgent is the personal-CLI predecessor that also ships these templates (verified against vendor docs 2026-04). diff --git a/_bridges/agents-md.tmpl b/_bridges/agents-md.tmpl new file mode 100644 index 0000000..b506a4a --- /dev/null +++ b/_bridges/agents-md.tmpl @@ -0,0 +1,24 @@ +# AGENTS.md + +> Read by Codex CLI (OpenAI spec), Copilot, Aider (when referenced), Windsurf, Warp, Zed, Antigravity (since v1.20.3, 2026-03-05), JetBrains Junie. See also: CLAUDE.md / .cursor/rules/ / GEMINI.md / .junie/guidelines.md / replit.md. + +## {{PROJECT_NAME}} + +{{PROJECT_DESCRIPTION}} + +## Before You Start +1. Read `DECISIONS.md` — architectural choices already made +2. Read `TODO.md` (if exists) — current priorities +3. Read `CLAUDE.md` (if exists) — project-specific rules + +## Rules +- **Constructor Pattern**: 1 file = 1 class. File <200 lines. Function <30 lines. +- **Root cause**: fix causes, not symptoms +- **SSOT**: types, routes, enums defined in ONE place +- **Tests**: write WITH code, never defer + +## Do NOT +- Rewrite working code without reason +- Add abstractions for one-time operations +- Skip reading DECISIONS.md before architectural changes +- Commit .env, credentials, API keys diff --git a/_bridges/aider-conf.tmpl b/_bridges/aider-conf.tmpl new file mode 100644 index 0000000..bb0b60b --- /dev/null +++ b/_bridges/aider-conf.tmpl @@ -0,0 +1,5 @@ +# Aider config — auto-reads project rules on every session +# See: https://aider.chat/docs/config/aider_conf.html +read: + - CONVENTIONS.md + - AGENTS.md diff --git a/_bridges/aider-conventions.tmpl b/_bridges/aider-conventions.tmpl new file mode 100644 index 0000000..55070c5 --- /dev/null +++ b/_bridges/aider-conventions.tmpl @@ -0,0 +1,27 @@ +# {{PROJECT_NAME}} — Aider Conventions + +> Auto-loaded by Aider via `.aider.conf.yml` (`read: CONVENTIONS.md`). + +{{PROJECT_DESCRIPTION}} + +## Before You Start +1. Read `DECISIONS.md` — architectural choices already made +2. Read `TODO.md` (if exists) — current priorities +3. Read `CLAUDE.md` (if exists) — project-specific rules + +## Constructor Pattern +- 1 file = 1 class = 1 responsibility +- File <200 lines, function <30 lines +- Types/interfaces BEFORE implementation +- Tests WITH code, never "later" + +## Core Rules +- No patching — fix root cause, not symptoms +- Don't rewrite working code without reason +- Single Source of Truth — types, routes, enums in ONE place + +## Forbidden +- Mixins, abstract factories, DI containers +- Rewriting working code without reason +- Committing .env, credentials, API keys +- Adding abstractions for one-time operations diff --git a/_bridges/continue.tmpl b/_bridges/continue.tmpl new file mode 100644 index 0000000..18b2a0d --- /dev/null +++ b/_bridges/continue.tmpl @@ -0,0 +1,29 @@ +--- +name: {{PROJECT_NAME}} +alwaysApply: true +--- + +# {{PROJECT_NAME}} — Continue.dev Rules + +{{PROJECT_DESCRIPTION}} + +## Constructor Pattern +1 file = 1 class = 1 responsibility. Function >30 lines = split. File >200 lines = decompose. + +## Core Rules +- No patching — fix root cause, not symptoms +- Don't rewrite working code without reason +- Single Source of Truth — types, routes, enums in ONE place +- Types/interfaces BEFORE implementation +- Tests WITH code, never "later" + +## Project Context +- Architecture decisions: see `DECISIONS.md` +- Project rules: see `CLAUDE.md` +- Current priorities: see `TODO.md` + +## Forbidden +- Mixins, abstract factories, DI containers +- Rewriting working code without reason +- Committing .env, credentials, API keys +- Adding abstractions for one-time operations diff --git a/_bridges/copilot.tmpl b/_bridges/copilot.tmpl new file mode 100644 index 0000000..835d973 --- /dev/null +++ b/_bridges/copilot.tmpl @@ -0,0 +1,16 @@ +# {{PROJECT_NAME}} — Copilot Instructions + +## Architecture +Read DECISIONS.md before making architectural choices. Document new decisions there. + +## Code Style +- Constructor Pattern: 1 file = 1 class = 1 responsibility +- File <200 lines, function <30 lines +- Types/interfaces BEFORE implementation +- Tests WITH code, never "later" + +## Forbidden +- Mixins, abstract factories, DI containers +- Rewriting working code without reason +- Committing .env, credentials, API keys +- Adding abstractions for one-time operations diff --git a/_bridges/cursor-mdc.tmpl b/_bridges/cursor-mdc.tmpl new file mode 100644 index 0000000..f370891 --- /dev/null +++ b/_bridges/cursor-mdc.tmpl @@ -0,0 +1,34 @@ +--- +description: {{PROJECT_NAME}} constructor-pattern coding rules +globs: **/* +alwaysApply: true +--- + +# {{PROJECT_NAME}} — Cursor Rules (MDC) + +{{PROJECT_DESCRIPTION}} + +## Constructor Pattern +1 file = 1 class = 1 responsibility. Function >30 lines = split. File >200 lines = decompose. + +## Core Rules +- No patching — fix root cause, not symptoms +- Don't rewrite working code without reason +- Single Source of Truth — types, routes, enums in ONE place +- Types/interfaces BEFORE implementation +- Tests WITH code, never "later" + +## Project Context +- Architecture decisions: see `DECISIONS.md` +- Project rules: see `CLAUDE.md` +- Current priorities: see `TODO.md` + +## Forbidden +- Mixins, abstract factories, DI containers +- Rewriting working code without reason +- Committing .env, credentials, API keys +- Adding abstractions for one-time operations + +## Session Protocol +- Read `DECISIONS.md` before making architectural choices +- Document new decisions in `DECISIONS.md` diff --git a/_bridges/cursorrules.tmpl b/_bridges/cursorrules.tmpl new file mode 100644 index 0000000..d7e198a --- /dev/null +++ b/_bridges/cursorrules.tmpl @@ -0,0 +1,23 @@ +# {{PROJECT_NAME}} — Cursor Rules + +## Constructor Pattern +1 file = 1 class = 1 responsibility. Function >30 lines = split. File >200 lines = decompose. + +## Core Rules +- No patching — fix root cause, not symptoms +- Don't rewrite working code without reason +- Single Source of Truth — types, routes, enums in ONE place +- Root cause first — never fix symptoms + +## Project Context +- Architecture decisions: see DECISIONS.md +- Known issues: see TODO.md (if exists) + +## Code Style +- Types/interfaces BEFORE implementation +- Tests WITH code, never "later" +- No mixins, no abstract factories, no DI containers + +## Session Protocol +- Read DECISIONS.md before making architectural choices +- Document new decisions in DECISIONS.md diff --git a/_bridges/emit.sh b/_bridges/emit.sh new file mode 100755 index 0000000..8fede69 --- /dev/null +++ b/_bridges/emit.sh @@ -0,0 +1,77 @@ +#!/usr/bin/env bash +# _bridges/emit.sh — render cross-tool bridge templates into a target dir. +# Usage: +# emit.sh [project-name] [project-description] +# emit.sh --only [project-name] [project-description] +# Idempotent: files that already exist are skipped, not overwritten. + +set -euo pipefail + +BRIDGES_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" + +ONLY="" +if [ "${1:-}" = "--only" ]; then + ONLY="${2:-}" + [ -n "$ONLY" ] || { echo "error: --only requires an output path" >&2; exit 2; } + shift 2 +fi + +TARGET="${1:-}" +[ -n "$TARGET" ] || { echo "usage: emit.sh [--only ] [name] [description]" >&2; exit 2; } +[ -d "$TARGET" ] || { echo "error: target dir does not exist: $TARGET" >&2; exit 2; } +TARGET="$(cd "$TARGET" && pwd)" + +NAME="${2:-$(basename "$TARGET")}" +DESC="${3:-}" +if [ -z "$DESC" ]; then + for f in "$TARGET/CLAUDE.md" "$TARGET/README.md"; do + if [ -f "$f" ]; then + DESC="$(grep -m1 -E '^[[:space:]]*[^#[:space:]].*' "$f" | sed 's/^[[:space:]]*//' || true)" + [ -n "$DESC" ] && break + fi + done + [ -n "$DESC" ] || DESC="No description" +fi + +YEAR="$(date +%Y)"; MONTH="$(date +%m)"; DATE="$(date +%Y-%m-%d)" + +# tmpl|output-rel-path (11 entries, matches _bridges/README.md table) +MAP="cursorrules.tmpl|.cursorrules +agents-md.tmpl|AGENTS.md +copilot.tmpl|.github/copilot-instructions.md +cursor-mdc.tmpl|.cursor/rules/main.mdc +windsurf.tmpl|.windsurf/rules/main.md +junie.tmpl|.junie/guidelines.md +continue.tmpl|.continue/rules/main.md +gemini.tmpl|GEMINI.md +aider-conventions.tmpl|CONVENTIONS.md +aider-conf.tmpl|.aider.conf.yml +replit.tmpl|replit.md" + +# sed-escape a replacement string (handles & / \ newlines) +sed_escape() { printf '%s' "$1" | sed -e 's/[\\&/]/\\&/g' -e 's/$/\\/' -e '$ s/\\$//'; } + +created=0; skipped=0 +while IFS='|' read -r tmpl out; do + [ -n "$tmpl" ] || continue + [ -n "$ONLY" ] && [ "$out" != "$ONLY" ] && continue + src="$BRIDGES_DIR/$tmpl" + dst="$TARGET/$out" + [ -f "$src" ] || { echo "error: missing template $src" >&2; exit 3; } + if [ -e "$dst" ]; then + echo "skipped: $out (exists)" + skipped=$((skipped+1)) + continue + fi + mkdir -p "$(dirname "$dst")" + sed -e "s/{{PROJECT_NAME}}/$(sed_escape "$NAME")/g" \ + -e "s/{{PROJECT_DESCRIPTION}}/$(sed_escape "$DESC")/g" \ + -e "s/{{YEAR}}/$YEAR/g" \ + -e "s/{{MONTH}}/$MONTH/g" \ + -e "s/{{DATE}}/$DATE/g" \ + "$src" > "$dst" + echo "created: $out" + created=$((created+1)) +done <<< "$MAP" + +echo "bridges: $created created, $skipped skipped" diff --git a/_bridges/gemini.tmpl b/_bridges/gemini.tmpl new file mode 100644 index 0000000..a295b26 --- /dev/null +++ b/_bridges/gemini.tmpl @@ -0,0 +1,27 @@ +# {{PROJECT_NAME}} — Gemini / Antigravity Instructions + +> Primary memory file for Google Antigravity (also reads `AGENTS.md` since v1.20.3, 2026-03-05). + +{{PROJECT_DESCRIPTION}} + +## Before You Start +1. Read `DECISIONS.md` — architectural choices already made +2. Read `TODO.md` (if exists) — current priorities +3. Read `CLAUDE.md` (if exists) — project-specific rules + +## Constructor Pattern +- 1 file = 1 class = 1 responsibility +- File <200 lines, function <30 lines +- Types/interfaces BEFORE implementation +- Tests WITH code, never "later" + +## Core Rules +- No patching — fix root cause, not symptoms +- Don't rewrite working code without reason +- Single Source of Truth — types, routes, enums in ONE place + +## Forbidden +- Mixins, abstract factories, DI containers +- Rewriting working code without reason +- Committing .env, credentials, API keys +- Adding abstractions for one-time operations diff --git a/_bridges/junie.tmpl b/_bridges/junie.tmpl new file mode 100644 index 0000000..fc3269c --- /dev/null +++ b/_bridges/junie.tmpl @@ -0,0 +1,27 @@ +# {{PROJECT_NAME}} — Junie Guidelines + +> Read by JetBrains Junie. Supplementary to `AGENTS.md` (Junie precedence: `.junie/AGENTS.md` > `AGENTS.md` > `.junie/guidelines.md`). + +{{PROJECT_DESCRIPTION}} + +## Before You Start +1. Read `DECISIONS.md` — architectural choices already made +2. Read `TODO.md` (if exists) — current priorities +3. Read `CLAUDE.md` (if exists) — project-specific rules + +## Constructor Pattern +- 1 file = 1 class = 1 responsibility +- File <200 lines, function <30 lines +- Types/interfaces BEFORE implementation +- Tests WITH code, never "later" + +## Core Rules +- No patching — fix root cause, not symptoms +- Don't rewrite working code without reason +- Single Source of Truth — types, routes, enums in ONE place + +## Forbidden +- Mixins, abstract factories, DI containers +- Rewriting working code without reason +- Committing .env, credentials, API keys +- Adding abstractions for one-time operations diff --git a/_bridges/replit.tmpl b/_bridges/replit.tmpl new file mode 100644 index 0000000..ac04924 --- /dev/null +++ b/_bridges/replit.tmpl @@ -0,0 +1,27 @@ +# {{PROJECT_NAME}} — Replit Agent Instructions + +> Read by Replit Agent (does NOT read `AGENTS.md`). + +{{PROJECT_DESCRIPTION}} + +## Before You Start +1. Read `DECISIONS.md` — architectural choices already made +2. Read `TODO.md` (if exists) — current priorities +3. Read `CLAUDE.md` (if exists) — project-specific rules + +## Constructor Pattern +- 1 file = 1 class = 1 responsibility +- File <200 lines, function <30 lines +- Types/interfaces BEFORE implementation +- Tests WITH code, never "later" + +## Core Rules +- No patching — fix root cause, not symptoms +- Don't rewrite working code without reason +- Single Source of Truth — types, routes, enums in ONE place + +## Forbidden +- Mixins, abstract factories, DI containers +- Rewriting working code without reason +- Committing .env, credentials, API keys +- Adding abstractions for one-time operations diff --git a/_bridges/windsurf.tmpl b/_bridges/windsurf.tmpl new file mode 100644 index 0000000..518357b --- /dev/null +++ b/_bridges/windsurf.tmpl @@ -0,0 +1,32 @@ +--- +trigger: always_on +--- + +# {{PROJECT_NAME}} — Windsurf Rules + +{{PROJECT_DESCRIPTION}} + +## Constructor Pattern +1 file = 1 class = 1 responsibility. Function >30 lines = split. File >200 lines = decompose. + +## Core Rules +- No patching — fix root cause, not symptoms +- Don't rewrite working code without reason +- Single Source of Truth — types, routes, enums in ONE place +- Types/interfaces BEFORE implementation +- Tests WITH code, never "later" + +## Project Context +- Architecture decisions: see `DECISIONS.md` +- Project rules: see `CLAUDE.md` +- Current priorities: see `TODO.md` + +## Forbidden +- Mixins, abstract factories, DI containers +- Rewriting working code without reason +- Committing .env, credentials, API keys +- Adding abstractions for one-time operations + +## Session Protocol +- Read `DECISIONS.md` before making architectural choices +- Document new decisions in `DECISIONS.md` diff --git a/install.sh b/install.sh index 05dde0c..9a3a60c 100755 --- a/install.sh +++ b/install.sh @@ -1,6 +1,14 @@ #!/usr/bin/env bash # KeiSeiKit — Constructor-Pattern Agent Kit installer # Idempotent: safe to re-run. Never overwrites settings.json or existing user manifests. +# +# Usage: +# ./install.sh # install agents + hooks + skills + bridges/ +# ./install.sh --with-bridges # also render cross-tool bridges into $PWD +# (AGENTS.md, .cursorrules, .cursor/rules/main.mdc, +# .github/copilot-instructions.md, Windsurf, Junie, +# Continue, Gemini, Aider, Replit — 11 files total) +# Skipped if $PWD is the KeiSeiKit repo itself. set -euo pipefail @@ -12,16 +20,23 @@ SKILLS_DIR="$HOME_DIR/.claude/skills" # --- flag parsing ---------------------------------------------------------- ACTIVATE_HOOKS=0 +WITH_BRIDGES=0 for arg in "$@"; do case "$arg" in --activate-hooks) ACTIVATE_HOOKS=1 ;; + --with-bridges) WITH_BRIDGES=1 ;; --help|-h) cat < $AGENTS_DIR/_blocks/" backup_dir "$AGENTS_DIR/_blocks" cp -f "$KIT_DIR/_blocks/"*.md "$AGENTS_DIR/_blocks/" +# --- copy bridges (overwrite; templates are SSoT from kit) ----------------- +if [[ -d "$KIT_DIR/_bridges" ]]; then + say "copying bridge templates -> $AGENTS_DIR/_bridges/" + mkdir -p "$AGENTS_DIR/_bridges" + backup_dir "$AGENTS_DIR/_bridges" + cp -f "$KIT_DIR/_bridges/"*.tmpl "$AGENTS_DIR/_bridges/" + cp -f "$KIT_DIR/_bridges/README.md" "$AGENTS_DIR/_bridges/" + cp -f "$KIT_DIR/_bridges/emit.sh" "$AGENTS_DIR/_bridges/emit.sh" + chmod +x "$AGENTS_DIR/_bridges/emit.sh" +fi + # --- copy generic manifests, DO NOT overwrite user's existing manifests ----- say "copying generic manifests -> $AGENTS_DIR/_manifests/ (skip if exists)" copied=0; skipped=0 @@ -305,6 +331,16 @@ elif [ -t 0 ] && [ -t 1 ]; then esac fi +# --- optional: render cross-tool bridges into $PWD ------------------------- +if [[ "$WITH_BRIDGES" == "1" ]]; then + if [[ -f "./install.sh" && -d "./_bridges" ]]; then + warn "not generating bridges — you are in the KeiSeiKit repo, not a project directory" + else + say "rendering cross-tool bridges into $PWD" + "$KIT_DIR/_bridges/emit.sh" "$PWD" + fi +fi + # --- done ----------------------------------------------------------------- echo say "install complete" diff --git a/skills/new-agent/SKILL.md b/skills/new-agent/SKILL.md index 3a9dc18..beaa40e 100644 --- a/skills/new-agent/SKILL.md +++ b/skills/new-agent/SKILL.md @@ -384,6 +384,52 @@ Edit the MANIFEST, not the .md — the no-hand-edit-agents hook will block direc --- +## Phase 8 — Project bridges (optional, click-only) + +After reporting the new agent, offer to generate cross-tool bridge files for the project's working tree (so Cursor, Copilot, Aider, Windsurf, Junie, Continue, Gemini/Antigravity, Replit, Codex CLI, Warp, Zed all see the same Constructor-Pattern ruleset). Send this `AskUserQuestion`: + +```json +{ + "questions": [ + { + "question": "Generate cross-tool bridges for this project?", + "header": "Bridges", + "multiSelect": false, + "options": [ + {"label": "Yes — all 11", "description": "Cursor (legacy + MDC), Copilot, Codex, Windsurf, Junie, Continue, Aider, Replit, Antigravity/Gemini, Warp, Zed — one Constructor-Pattern ruleset across every AI coding tool"}, + {"label": "Yes — AGENTS.md only", "description": "Minimal — only the universal AGENTS.md that most modern tools read"}, + {"label": "No — skip", "description": "Agent-only install; user will generate bridges later via install.sh --with-bridges or _bridges/emit.sh"} + ] + } + ] +} +``` + +Resolve: + +- **Yes — all 11** — invoke: + ```bash + ~/.claude/agents/_bridges/emit.sh "" + ``` + Use the project path the user gave in Phase 2. The helper auto-derives `PROJECT_NAME` from the directory basename and `PROJECT_DESCRIPTION` from the first non-blank line of the project's `CLAUDE.md` or `README.md`. + +- **Yes — AGENTS.md only** — invoke the same helper with the `--only` filter: + ```bash + ~/.claude/agents/_bridges/emit.sh --only AGENTS.md "" + ``` + +- **No — skip** — print the exact command the user can run later and fall through to Phase 7: + ``` + To generate bridges later: + cd && ~/.claude/agents/_bridges/emit.sh "$PWD" + Or at install time: + cd && /install.sh --with-bridges + ``` + +All three options are idempotent — existing bridge files in the project are skipped, never overwritten. Report which files were created / skipped verbatim from `emit.sh` output. + +--- + ## Phase 7 — Suggested next steps (print, do NOT execute without ask) Offer as a final block the user can copy-paste: