From f8487a79c600cad99df5234b437ffb9fa0e69e99 Mon Sep 17 00:00:00 2001 From: Sava Znatnov Date: Mon, 28 Sep 2026 22:46:16 +0700 Subject: [PATCH] chore(ai): migrate project config to a rulesync canon Add .rulesync as the single source for the project's rules, MCP servers and permissions, and generate the Claude, Codex and OpenCode project files from it. Replace the AGENTS.md -> CLAUDE.md symlink with a real file so generation cannot write through it and clobber CLAUDE.md. Ignore .env for direnv-provided project secrets and add .envrc that inherits the parent secrets before loading a local .env. Graphify is the only project MCP server and carries no credential, so the rules and MCP sets import unchanged. OpenCode now reads the server from opencode.jsonc, which is the surface it did not have before. --- .claude/settings.json | 7 +++-- .codex/rules/rulesync.rules | 9 ++++++ .envrc | 2 ++ .gitignore | 3 ++ .rulesync/mcp.jsonc | 14 +++++++++ .rulesync/permissions.jsonc | 63 +++++++++++++++++++++++++++++++++++++ .rulesync/rules/overview.md | 41 ++++++++++++++++++++++++ AGENTS.md | 35 ++++++++++++++++++++- opencode.jsonc | 28 +++++++++++++++++ rulesync.jsonc | 6 ++++ 10 files changed, 204 insertions(+), 4 deletions(-) create mode 100644 .codex/rules/rulesync.rules create mode 100644 .envrc create mode 100644 .rulesync/mcp.jsonc create mode 100644 .rulesync/permissions.jsonc create mode 100644 .rulesync/rules/overview.md mode change 120000 => 100644 AGENTS.md create mode 100644 opencode.jsonc create mode 100644 rulesync.jsonc diff --git a/.claude/settings.json b/.claude/settings.json index da5fed5..3636c13 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -1,10 +1,11 @@ { + "$schema": "https://json.schemastore.org/claude-code-settings.json", "permissions": { "allow": [ - "Read", - "Grep", + "Bash", "Glob", - "Bash" + "Grep", + "Read" ], "_comment": "Committed baseline is deliberately conservative: broad reads (Read/Grep/Glob) plus a scoped, mostly-read-only Bash allowlist. Unscoped Write/Edit/Bash are intentionally NOT granted here so they prompt by default in every clone. Broader per-user permissions (git commit/push, gh pr create/merge, unscoped Write/Edit/Bash, etc.) belong in the gitignored .claude/settings.local.json -- never widen this committed file to grant them repo-wide." }, diff --git a/.codex/rules/rulesync.rules b/.codex/rules/rulesync.rules new file mode 100644 index 0000000..60d79b2 --- /dev/null +++ b/.codex/rules/rulesync.rules @@ -0,0 +1,9 @@ +# Generated by Rulesync from .rulesync/permissions.jsonc (permission.bash) +# https://developers.openai.com/codex/rules + +# * +prefix_rule( + pattern = ["*"], + decision = "allow", + justification = "Generated from Rulesync permission.bash: *", +) diff --git a/.envrc b/.envrc new file mode 100644 index 0000000..43edf50 --- /dev/null +++ b/.envrc @@ -0,0 +1,2 @@ +source_up_if_exists +dotenv_if_exists diff --git a/.gitignore b/.gitignore index 70c8d4e..187cc99 100644 --- a/.gitignore +++ b/.gitignore @@ -12,6 +12,9 @@ dist/ PROMPT.md graphify-out/ +# Project secrets loaded by direnv; never commit. +.env + artifacts/ # Vendored external API docs — local-only research anchor (regenerate via scripts/fetch_docs.py). diff --git a/.rulesync/mcp.jsonc b/.rulesync/mcp.jsonc new file mode 100644 index 0000000..60047a8 --- /dev/null +++ b/.rulesync/mcp.jsonc @@ -0,0 +1,14 @@ +{ + "$schema": "https://github.com/dyoshikawa/rulesync/releases/latest/download/mcp-schema.json", + "mcpServers": { + "graphify": { + "type": "stdio", + "command": "graphify-mcp", + "args": [ + "--transport", + "stdio", + "/home/sava/git/bim-ba/refract/graphify-out/graph.json" + ] + } + } +} diff --git a/.rulesync/permissions.jsonc b/.rulesync/permissions.jsonc new file mode 100644 index 0000000..9457e2e --- /dev/null +++ b/.rulesync/permissions.jsonc @@ -0,0 +1,63 @@ +{ + "permission": { + "read": { + "*": "allow" + }, + "grep": { + "*": "allow" + }, + "glob": { + "*": "allow" + }, + "bash": { + "*": "allow" + } + }, + "claudecode": { + "permissions": { + "_comment": "Committed baseline is deliberately conservative: broad reads (Read/Grep/Glob) plus a scoped, mostly-read-only Bash allowlist. Unscoped Write/Edit/Bash are intentionally NOT granted here so they prompt by default in every clone. Broader per-user permissions (git commit/push, gh pr create/merge, unscoped Write/Edit/Bash, etc.) belong in the gitignored .claude/settings.local.json -- never widen this committed file to grant them repo-wide." + }, + "enabledPlugins": { + "browsing@bim-ba": true, + "claude-md-management@claude-plugins-official": false, + "clickhouse@bim-ba": false, + "context7@context7-marketplace": false, + "core@bim-ba": true, + "documenting@bim-ba": true, + "drifts@bim-ba": true, + "plugin-dev@claude-plugins-official": false, + "skill-creator@claude-plugins-official": false, + "superpowers@claude-plugins-official": true + }, + "extraKnownMarketplaces": { + "claude-plugins-official": { + "source": { + "source": "github", + "repo": "anthropics/claude-plugins-official" + }, + "autoUpdate": true + }, + "superpowers-marketplace": { + "source": { + "source": "github", + "repo": "obra/superpowers-marketplace" + }, + "autoUpdate": true + }, + "context7-marketplace": { + "source": { + "source": "github", + "repo": "upstash/context7" + }, + "autoUpdate": true + }, + "bim-ba": { + "source": { + "source": "github", + "repo": "bim-ba/ai" + }, + "autoUpdate": true + } + } + } +} diff --git a/.rulesync/rules/overview.md b/.rulesync/rules/overview.md new file mode 100644 index 0000000..e97b975 --- /dev/null +++ b/.rulesync/rules/overview.md @@ -0,0 +1,41 @@ +--- +root: true +targets: + - '*' +globs: + - '**/*' +--- +# CLAUDE.md - refract + +refract compiles one neutral YAML API spec (`resource.yaml` + `client.yaml`) into a typed Python SDK, CLI, FastMCP server, models and tests. It is alpha: one target language (Python) and one proving ground, the `examples/ycli-tracker` golden oracle, whose checked-in `out/` the generator must reproduce byte for byte. + +Baseline agent discipline comes from the `core` and `drifts` plugins of the `bim-ba` marketplace; voice, tooling, Git and research defaults come from the personal layer in `~/.claude/CLAUDE.md`. This file carries only what is specific to this repository. + +## Layout + +| Path | Role | +|---|---| +| `src/refract/cli.py`, `generation.py` | the `refract` Typer entry point and the render driver | +| `src/refract/spec/` | `resource.yaml` / `client.yaml` loading and validation | +| `src/refract/ir/` | the typed intermediate representation | +| `src/refract/emitters/` | `ports.py` backend seam, `registry.py`, and `python/`, the one implemented backend | +| `src/refract/runtime/` | what generated code imports at run time (auth, base, request, session) | +| `tests/` | mirrors `src/refract/`; `tests/behavioral/` imports and runs emitted code | +| `examples/ycli-tracker/` | the golden-oracle spec plus its checked-in `out/` | +| `docs/design.md`, `docs/roadmap.md` | the full design and roadmap, ahead of the code in places | + +## Conventions + +- Python >= 3.12; `uv` only (`uv sync`, `uv run`), with `uv.lock` and the `dev` dependency group in `pyproject.toml`. +- ruff is both linter and formatter (`line-length = 100`, an explicit `select` list); `ty` is the type checker, configured with `error-on-warning = true`. +- `examples/` is excluded from ruff and from ty on purpose: it is external source used as a byte-equality target, so linting or reformatting it defeats the test it exists for. +- pytest runs with `--cov-fail-under=100` and `-m 'not behavioral'`; run the slow tests explicitly with `uv run pytest -m behavioral`. +- Versioning and releases are automated by release-please (`release-please-config.json`, `.github/workflows/release-please.yml`) — do not hand-edit the version. + +## Verification + +```sh +uv run ruff format --check . && uv run ruff check . && uv run ty check && uv run pytest +``` + +The same four steps `.github/workflows/ci.yml` runs. `uv run refract generate --check` is the separate drift gate: it renders in memory and fails if `examples/ycli-tracker/out/` has gone stale. diff --git a/AGENTS.md b/AGENTS.md deleted file mode 120000 index 681311e..0000000 --- a/AGENTS.md +++ /dev/null @@ -1 +0,0 @@ -CLAUDE.md \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..79a04b3 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,34 @@ +# CLAUDE.md - refract + +refract compiles one neutral YAML API spec (`resource.yaml` + `client.yaml`) into a typed Python SDK, CLI, FastMCP server, models and tests. It is alpha: one target language (Python) and one proving ground, the `examples/ycli-tracker` golden oracle, whose checked-in `out/` the generator must reproduce byte for byte. + +Baseline agent discipline comes from the `core` and `drifts` plugins of the `bim-ba` marketplace; voice, tooling, Git and research defaults come from the personal layer in `~/.claude/CLAUDE.md`. This file carries only what is specific to this repository. + +## Layout + +| Path | Role | +|---|---| +| `src/refract/cli.py`, `generation.py` | the `refract` Typer entry point and the render driver | +| `src/refract/spec/` | `resource.yaml` / `client.yaml` loading and validation | +| `src/refract/ir/` | the typed intermediate representation | +| `src/refract/emitters/` | `ports.py` backend seam, `registry.py`, and `python/`, the one implemented backend | +| `src/refract/runtime/` | what generated code imports at run time (auth, base, request, session) | +| `tests/` | mirrors `src/refract/`; `tests/behavioral/` imports and runs emitted code | +| `examples/ycli-tracker/` | the golden-oracle spec plus its checked-in `out/` | +| `docs/design.md`, `docs/roadmap.md` | the full design and roadmap, ahead of the code in places | + +## Conventions + +- Python >= 3.12; `uv` only (`uv sync`, `uv run`), with `uv.lock` and the `dev` dependency group in `pyproject.toml`. +- ruff is both linter and formatter (`line-length = 100`, an explicit `select` list); `ty` is the type checker, configured with `error-on-warning = true`. +- `examples/` is excluded from ruff and from ty on purpose: it is external source used as a byte-equality target, so linting or reformatting it defeats the test it exists for. +- pytest runs with `--cov-fail-under=100` and `-m 'not behavioral'`; run the slow tests explicitly with `uv run pytest -m behavioral`. +- Versioning and releases are automated by release-please (`release-please-config.json`, `.github/workflows/release-please.yml`) — do not hand-edit the version. + +## Verification + +```sh +uv run ruff format --check . && uv run ruff check . && uv run ty check && uv run pytest +``` + +The same four steps `.github/workflows/ci.yml` runs. `uv run refract generate --check` is the separate drift gate: it renders in memory and fails if `examples/ycli-tracker/out/` has gone stale. diff --git a/opencode.jsonc b/opencode.jsonc new file mode 100644 index 0000000..2f536ce --- /dev/null +++ b/opencode.jsonc @@ -0,0 +1,28 @@ +{ + "mcp": { + "graphify": { + "type": "local", + "command": [ + "graphify-mcp", + "--transport", + "stdio", + "/home/sava/git/bim-ba/refract/graphify-out/graph.json" + ], + "enabled": true + } + }, + "permission": { + "read": { + "*": "allow" + }, + "grep": { + "*": "allow" + }, + "glob": { + "*": "allow" + }, + "bash": { + "*": "allow" + } + } +} diff --git a/rulesync.jsonc b/rulesync.jsonc new file mode 100644 index 0000000..8a5e9eb --- /dev/null +++ b/rulesync.jsonc @@ -0,0 +1,6 @@ +{ + "$schema": "https://github.com/dyoshikawa/rulesync/releases/latest/download/config-schema.json", + "targets": ["claudecode", "codexcli", "opencode"], + "features": ["rules", "mcp", "commands", "subagents", "skills", "permissions"], + "delete": false +}