@samirosamsam/aim 0.1.0

package/skills/aim/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: aim
+description: Install and manage deterministic AIM guardrails for Codex tool calls. Use when the user asks Codex to block, prevent, deny, or enforce precise behavior around Bash, file edits, or MCP tools.
+---
+
+# AIM
+
+Use the public `aim` CLI as the source of truth for installing Codex hooks, adding guardrail rules, and proving those rules block matching tool calls. Run it through `npx -y @samirosamsam/aim@latest` so the workflow works from any Codex workspace. When developing AIM itself, use `node ./bin/aim.js` from the repo root. Do not invent final guardrail JSON by hand when the CLI can compile, install, or validate it.
+
+## Workflow
+
+1. Install or refresh the Codex `PreToolUse` hook before claiming enforcement is active:
+
+```bash
+npx -y @samirosamsam/aim@latest setup --json
+```
+
+If Codex reports that hooks need review, tell the user to run `/hooks`, inspect the AIM hook, and trust it. Do not claim active enforcement until the hook is trusted and a proof call blocks.
+
+2. Add the user's requested block as a Codex guardrail rule:
+
+```bash
+npx -y @samirosamsam/aim@latest rule add "<what the user wants to prevent>" --json
+```
+
+Examples:
+
+```bash
+npx -y @samirosamsam/aim@latest rule add "empêche git push" --json
+npx -y @samirosamsam/aim@latest rule add "empêche de modifier package.json" --json
+npx -y @samirosamsam/aim@latest rule add "empêche les calls GitHub qui ajoutent des collaborators" --json
+```
+
+3. Prove the guardrail with a representative hook input before reporting success. Pick the proof that matches the rule:
+
+```bash
+printf '%s' '{"tool_name":"Bash","tool_input":{"command":"git push origin main"}}' \
+  | npx -y @samirosamsam/aim@latest hook pre-tool-use
+```
+
+```bash
+printf '%s' '{"tool_name":"apply_patch","tool_input":{"command":"*** Begin Patch\n*** Update File: package.json\n@@\n*** End Patch\n"}}' \
+  | npx -y @samirosamsam/aim@latest hook pre-tool-use
+```
+
+```bash
+printf '%s' '{"tool_name":"mcp__github__add_collaborator","tool_input":{"owner":"tototozip","repo":"AIM","username":"someone"}}' \
+  | npx -y @samirosamsam/aim@latest hook pre-tool-use
+```
+
+The proof must return `permissionDecision: "deny"` for the blocked case. If it does not, report the blocker instead of saying the rule is installed.
+
+4. Use `rule list` when you need to show what is active:
+
+```bash
+npx -y @samirosamsam/aim@latest rule list --json
+```
+
+## Advanced Commands
+
+Use `capture`, `authorize`, `compile`, `add`, or `check` only for lower-level policy debugging. The normal public workflow is `setup`, `rule add`, proof, report.
+
+```bash
+npx -y @samirosamsam/aim@latest capture \
+  --provider github \
+  --tool list_repository_collaborators \
+  --args '{"owner":"tototozip","repo":"AIM"}' \
+  --effect deny \
+  --agent codex \
+  --connection github:prod \
+  --json
+```
+
+If a command returns `questions`, ask for the missing command, file path, provider, resource pattern, or access level before writing enforceable policy. Use `--force` only when the user explicitly accepts a broad or ambiguous rule.
+
+## Scope
+
+- For Codex enforcement, prefer `rule add` over `compile`/`add`; it writes rules intended for the `PreToolUse` hook.
+- Prefer narrow resource patterns over `*`.
+- Codex hook guardrails are default-allow: no matching block means the tool call proceeds.
+- Treat `deny` as higher priority than `approval`, and `approval` as higher priority than `allow`.
+- For write, delete, admin, private, finance, HR, legal, or shared-secret access, prefer `approval` or `deny` unless the user explicitly asks for allow.
+- Do not request or store SaaS tokens. AIM policy rows reference agent UIDs, connection IDs or patterns, tools, resources, access, and effects only.
+- AIM currently guards supported Codex `PreToolUse` surfaces: Bash, `apply_patch`, and MCP tools. Do not claim it blocks browser, WebSearch, or unsupported tool paths.
+
+## Output Shape
+
+When reporting results to a user, show the hook path, policy path, and grant rows that matter: `agentUid`, `connectionId`, `toolPattern`, `resourcePattern`, `access`, `effect`, and `reason`. Call out any broad wildcard, unresolved question, or hook trust requirement before suggesting the rule is active. Never say enforcement is active unless a representative hook test returned `permissionDecision: "deny"`.

package/skills/aim/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "AIM"
+  short_description: "Compile agent access intents into MCP grant rules."
+  default_prompt: "Create precise MCP grants for this agent."