rulesync

Rulesync follows specific logic to combine multiple rule files into tool-specific outputs:

1. Root Rules: Files with root: true are used to generate the primary configuration file. Unsafe collisions (multiple root: true rules for the same target) cause failure.
2. Local Rules: Rules with localRoot: true are ordered lexicographically by source file path and composed before non-overridden .curated/ rules.
3. Composition Order: Within sets, filename prefixes like 10- and 20- control the composition order.
4. Modular Rules: Non-root rules are combined in deterministic source-discovery order. If a rule fragment generates its own frontmatter block (e.g., Amp's globs: gate), it is treated as a separate file and not composed.
5. Collisions: Exact or case-insensitive modular collisions that result in the same output path are kept separate, and a warning is issued stating that the last write wins.

Rulesync supports the Agent Skills specification. While it accepts legacy rulesync spellings on input, it always emits the required spec shapes:

• allowed-tools: Emitted as a space-separated scalar (YAML lists are joined).
• compatibility: Emitted as a string (objects are flattened to key: value pairs).
• metadata: Emitted as a string (values are stringified to maintain a string→string map).

Constraints & Warnings: Rulesync warns (but does not fail) if:

• name is empty, > 64 chars, or contains invalid characters (only lowercase, digits, and single hyphens allowed).
• description is empty or > 1024 chars.
• compatibility > 500 chars.
• allowed-tools entries contain whitespace.

Note on Replit and Pi: These tools accept both spec-compliant strings and legacy rulesync forms. On import, allowed-tools is normalized back to a list. For pi, an empty allowed-tools list is dropped from the emitted file.

The rulesync install command supports three distinct modes via the --mode <mode> flag. Choosing the correct mode determines which manifest file is read, which lockfile is used, and where the output files are written.

• rulesync (default): Uses rulesync.jsonc and sources. Writes to .rulesync/rules/.curated/ and .rulesync/skills/.curated/.
• apm: Uses apm.yml and dependencies.apm. Writes to .github/instructions/ and .github/skills/ (APM v1 layout).
• gh: Uses rulesync.jsonc and sources. Writes to agent-specific directories (e.g., .agents/skills or .claude/skills) to match gh skill install compatibility.

| Mode       | Manifest input               | Lockfile                                                     | Output layout                                                                                                      |
| ---------- | ---------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| `rulesync` | `rulesync.jsonc` `sources`   | `rulesync.lock` (+ `rulesync-npm.lock.json` for npm sources) | `.rulesync/rules/.curated/<name>.md`, `.rulesync/skills/.curated/<name>/` (then re-emitted by `rulesync generate`) |
| `apm`      | `apm.yml` `dependencies.apm` | `rulesync-apm.lock.yaml`                                     | `.github/instructions/`, `.github/skills/` (APM v1 layout)                                                         |
| `gh`       | `rulesync.jsonc` `sources`   | `rulesync-gh.lock.yaml`                                     | Per-agent / per-scope dirs (matching `gh skill install`) |

The generated [permissions.rulesync] profile in Codex always extends one of Codex's built-in permission profiles using the extends key. The baseline is determined by the codexcli.base_permission_profile setting.

Available Baselines:

• ":workspace" (Default): Grants read access to the whole filesystem and write access to the workspace root, /tmp, and $TMPDIR. Rulesync adds specific allow/deny rules on top of this.
• ":read-only": Keeps command execution read-only.
• ":danger-full-access": This is a special case. Rulesync does not use the [permissions.rulesync] profile for this. Instead, it emits default_permissions = ":danger-full-access" directly and prunes any managed profile. Canonical read/edit/write/webfetch rules are ignored for Codex CLI in this mode.

Round-tripping: When importing, the value of extends in the Codex config is mapped back to codexcli.base_permission_profile in Rulesync. If a custom parent profile is used, it is replaced by the managed baseline during regeneration.

The rulesync.lock file (at the project root) ensures reproducible builds by recording resolved commit SHAs, rule selection metadata, and integrity hashes for every artifact. It is safe and recommended to commit this file to Git.

For npm transport sources, a separate rulesync-npm.lock.json is used to lock resolved package versions and tarball integrity instead of commit SHAs.

To update the locked references, run rulesync install --update.

{
  "lockfileVersion": 1,
  "sources": {
    "owner/skill-repo": {
      "requestedRef": "main",
      "resolvedRef": "abc123def456...",
      "resolvedAt": "2025-01-15T12:00:00.000Z",
      "skills": {
        "my-skill": { "integrity": "sha256-abcdef..." },
        "another-skill": { "integrity": "sha256-123456..." }
      },
      "rules": {
        "testing-guidelines": { "integrity": "sha256-789abc..." }
      },
      "ruleSelection": ["*"],
      "rulesPath": "rules",
      "resolvedRuleNames": ["testing-guidelines"]
    }
  }
}

While the shared permission block applies to all tools, you can scope rules to a specific tool by adding a tool-scoped block (e.g., claudecode or opencode).

• Merging Behavior: Categories are merged per category. A tool-scoped category replaces the shared category wholesale for that tool. Shared categories not named in the tool-scoped block still apply.
• Supported Keys: Any permissions-capable --targets name is accepted. kiro-cli/kiro-ide alias to kiro, and hermesagent aliases to hermes.
• Tool-Specific Semantics: Tools like OpenCode, Kilo, and Vibe have unique override semantics that are handled by their respective translators.

{
  "permission": {
    "bash": { "git *": "allow", "*": "ask" },
  },
  "claudecode": {
    "permission": {
      // Replaces the shared `bash` category for Claude Code only.
      "bash": { "git *": "allow", "git push *": "deny", "*": "ask" },
    },
  },
}