aiblueprint-cli 1.4.60 → 1.4.62

package/agents-config/codex-config/config.toml

@@ -5,6 +5,15 @@
 approval_policy = "never"
 sandbox_mode = "danger-full-access"
 
+[[hooks.PreToolUse]]
+matcher = "^Bash$"
+
+[[hooks.PreToolUse.hooks]]
+type = "command"
+command = "/usr/bin/env node \"$HOME/.codex/hooks/command-deny-list.ts\""
+timeout = 5
+statusMessage = "Checking command safety"
+
 [tui]
 status_line = [
   "model-with-reasoning",

package/agents-config/codex-config/hooks/command-deny-list.ts

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+type HookPayload = {
+  tool_input?: {
+    command?: unknown;
+  };
+};
+
+type ClaudeSettings = {
+  permissions?: {
+    deny?: unknown;
+  };
+};
+
+const CLAUDE_SETTINGS_PATH = join(homedir(), ".claude", "settings.json");
+const FALLBACK_DENY_PATTERNS = [
+  "Bash(rm -rf *)",
+  "Bash(sudo *)",
+  "Bash(mkfs *)",
+  "Bash(dd *)",
+  "Bash(git push --force *)",
+  "Bash(git reset --hard *)",
+  "Bash(*prisma reset*)",
+  "Bash(curl * | bash)",
+  "Bash(wget * | bash)",
+];
+
+const BLOCK_REASON =
+  "Blocked by Codex command safety rules. Use a safer alternative or ask the user.";
+const TOKEN_BOUNDARY = String.raw`(?:^|[\s"'([{<])`;
+const GH_COMMAND_PREFIX = String.raw`(?:(?:command|builtin|env)\s+(?:[A-Za-z_][A-Za-z0-9_]*=(?:\S+)\s+)*)?`;
+const EXECUTABLE_PATH_PREFIX = String.raw`(?:\S*/)?`;
+
+function getCommand(payload: HookPayload): string {
+  const command = payload.tool_input?.command;
+  return typeof command === "string" ? command : "";
+}
+
+function readClaudeDenyPatterns(): string[] {
+  try {
+    const settings = JSON.parse(
+      readFileSync(CLAUDE_SETTINGS_PATH, "utf8"),
+    ) as ClaudeSettings;
+    const deny = settings.permissions?.deny;
+
+    if (Array.isArray(deny)) {
+      return deny.filter((pattern): pattern is string => typeof pattern === "string");
+    }
+  } catch {
+    return FALLBACK_DENY_PATTERNS;
+  }
+
+  return FALLBACK_DENY_PATTERNS;
+}
+
+function extractBashPattern(pattern: string): string | null {
+  const match = pattern.match(/^Bash\((.*)\)$/);
+  return match?.[1] ?? null;
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
+}
+
+function globPatternToRegExp(pattern: string): RegExp {
+  const normalized = normalizeWhitespace(pattern);
+  const regex = normalized
+    .split("*")
+    .map(escapeRegExp)
+    .join(".*")
+    .replaceAll(" ", "\\s+");
+
+  return new RegExp(`^${regex}$`, "i");
+}
+
+function normalizeWhitespace(value: string): string {
+  return value.replace(/\\\n/g, " ").replace(/\s+/g, " ").trim();
+}
+
+function commandCandidates(command: string): string[] {
+  const normalized = normalizeWhitespace(command);
+  const segments = normalized
+    .split(/\s*(?:&&|\|\||;)\s*/g)
+    .map((segment) => segment.trim())
+    .filter(Boolean);
+
+  return [...new Set([normalized, ...segments])];
+}
+
+function containsForcedRecursiveRm(command: string): boolean {
+  const rmInvocations = normalizeWhitespace(command).matchAll(
+    /\brm\b(?<args>[^\n;&|()]*)/gi,
+  );
+
+  for (const match of rmInvocations) {
+    const args = match.groups?.args ?? "";
+    const shortOptions = [...args.matchAll(/(?<!\S)-([A-Za-z]+)\b/g)].map(
+      (optionMatch) => optionMatch[1] ?? "",
+    );
+
+    let hasRecursive = shortOptions.some((option) =>
+      option.toLowerCase().includes("r"),
+    );
+    let hasForce = shortOptions.some((option) =>
+      option.toLowerCase().includes("f"),
+    );
+
+    const longOptions = new Set(
+      [...args.matchAll(/--([A-Za-z-]+)\b/g)].map(
+        (optionMatch) => optionMatch[1] ?? "",
+      ),
+    );
+
+    hasRecursive ||= longOptions.has("recursive") || longOptions.has("dir");
+    hasForce ||= longOptions.has("force");
+
+    if (hasRecursive && hasForce) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function containsPullRequestMergeCommand(command: string): boolean {
+  const matcher = new RegExp(
+    `${TOKEN_BOUNDARY}${GH_COMMAND_PREFIX}${EXECUTABLE_PATH_PREFIX}gh\\s+pr\\s+merge(?:\\s|$)`,
+    "i",
+  );
+
+  return commandCandidates(command).some((candidate) => matcher.test(candidate));
+}
+
+function matchesImportedDenyPattern(command: string, patterns: string[]): boolean {
+  const candidates = commandCandidates(command);
+
+  for (const pattern of patterns) {
+    const bashPattern = extractBashPattern(pattern);
+    if (!bashPattern) {
+      continue;
+    }
+
+    const matcher = globPatternToRegExp(bashPattern);
+    if (candidates.some((candidate) => matcher.test(candidate))) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function deny(): void {
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "deny",
+        permissionDecisionReason: BLOCK_REASON,
+      },
+      decision: "block",
+      reason: BLOCK_REASON,
+    }),
+  );
+}
+
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+async function main(): Promise<void> {
+  const input = await readStdin();
+  if (!input.trim()) {
+    return;
+  }
+
+  let payload: HookPayload;
+  try {
+    payload = JSON.parse(input) as HookPayload;
+  } catch {
+    return;
+  }
+
+  const command = getCommand(payload);
+  if (
+    containsForcedRecursiveRm(command) ||
+    containsPullRequestMergeCommand(command) ||
+    matchesImportedDenyPattern(command, readClaudeDenyPatterns())
+  ) {
+    deny();
+  }
+}
+
+await main();

package/agents-config/skills/environments-manager/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: environments-manager
-description: Set up a per-worktree environment for one or more IDEs (Claude Code, Cursor, Codex) in a single pass. Generates shared scripts/worktree-up.sh, scripts/worktree-down.sh, and scripts/dev.sh, then wires them into each selected IDE's config. Use whenever the user asks to "set up a worktree environment", "configure worktrees", "make this repo worktree-ready", or mentions any of .codex/environments/environment.toml, .cursor/worktrees.json, .claude/settings.json SessionStart, $CODEX_WORKTREE_PATH, $ROOT_WORKTREE_PATH, or $CLAUDE_PROJECT_DIR.
+description: Set up per-worktree environments for Claude Code, Cursor, or Codex. Use for worktree-ready repos, IDE environment config, worktree-up/down scripts, or dev.sh wiring.
 disable-model-invocation: false
 allow_implicit_invocation: true
 ---

package/agents-config/skills/rules-manager/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: rules-manager
-description: Create and maintain agent rules in AGENTS.md and .agents/rules/. Use when adding project rules, conventions, or constraints for AI agents. AGENTS.md acts as the index - it must reference every rule file living in .agents/rules/. Triggers - "create a rule", "add a rule", "agents rule", "AGENTS.md", ".agents/rules", "new rule for", "rules-manager".
-argument-hint: [init | add <rule-name> | optimize | task description]
+description: Create and maintain agent rules in AGENTS.md and .agents/rules/. Use for project rules, conventions, constraints, rule indexes, or requests to add or optimize agent rules.
+argument-hint: "[init | add <rule-name> | optimize | task description]"
 ---
 
 <core_principle>

package/agents-config/skills/skill-manager/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: skill-manager
-description: Create and edit skills/rules across Claude Code, OpenAI Codex, and Cursor. Use when the user asks to "create a skill", "build a skill", "write a skill", "make a cursor rule", "add a codex skill", "skill manager", or mentions SKILL.md, .cursor/rules, agents/openai.yaml, or multi-agent rule files. Handles frontmatter, file layout, and discovery rules for each platform.
+description: Create or edit Claude, Codex, and Cursor skills/rules. Use for SKILL.md, .cursor/rules, AGENTS.md, skill prompts, frontmatter, references, scripts, and discovery rules.
 ---
 
 # Skill Manager
@@ -18,6 +18,7 @@ Pick the platform first, then read the matching reference file:
 - Claude Code → see [references/claude-code.md](references/claude-code.md)
 - Codex      → see [references/codex.md](references/codex.md)
 - Cursor     → see [references/cursor.md](references/cursor.md)
+- Description quality → see [references/description-recommandation.md](references/description-recommandation.md)
 
 If unsure which the user wants, ask. Default to Claude Code when working under `~/.claude/` or `.claude/`, Codex when under `~/.agents/` or `.agents/`, Cursor when under `.cursor/`.
 
@@ -65,15 +66,32 @@ Do NOT add README, CHANGELOG, INSTALLATION_GUIDE, etc. Only files the agent need
 
 ## Writing the description
 
-The `description` field is the single most important line in the file - it's what the model uses to decide to load the skill. Write it as:
+The `description` field is the single most important line in the file - it's what the model uses to decide to load the skill. This is a hard rule: descriptions must be between 50 and 300 characters.
+
+Write it as:
 
 - Front-load trigger words ("Use when...", "create a skill", "review a PR").
 - State scope and boundaries explicitly.
 - Mention concrete file names or commands the user might type.
+- Keep it short enough to stay under 300 characters, while still specific enough to trigger reliably.
 
 Bad: `"Helper for skills."`
 Good: `"Create and edit skills/rules across Claude Code, OpenAI Codex, and Cursor. Use when the user asks to 'create a skill'..."`
 
+To validate skill descriptions, frontmatter fields, `agents/openai.yaml`, and skill directory shape, run:
+
+```bash
+bun scripts/inspect-description.ts
+```
+
+By default, this checks `~/.agents/skills` only and follows symlinked skill directories inside that root. Pass one or more roots to inspect a different set. Passing a `.cursor/rules` directory validates Cursor rule frontmatter too:
+
+```bash
+bun scripts/inspect-description.ts .agents/skills
+```
+
+For researched guidance and examples, see [references/description-recommandation.md](references/description-recommandation.md).
+
 ## Where each platform stores skills
 
 See the per-platform reference files. Quick reminders:

package/agents-config/skills/skill-manager/references/description-recommandation.md

@@ -0,0 +1,97 @@
+# Description Recommendations
+
+Use this when writing or refining the `description` field for Claude Code skills, OpenAI Codex skills, or Cursor intelligent rules.
+
+## Sources
+
+- OpenAI Codex Agent Skills: https://developers.openai.com/codex/skills
+- Anthropic Agent Skills best practices: https://console.anthropic.com/docs/en/agents-and-tools/agent-skills/best-practices
+- Anthropic Agent Skills overview: https://console.anthropic.com/docs/en/agents-and-tools/agent-skills/overview
+- Claude Code skills docs: https://docs.anthropic.com/en/docs/claude-code/skills
+- Cursor rules docs: https://cursor.com/help/customization/rules
+
+## Hard Rules
+
+- Keep every description between 50 and 300 characters.
+- Make the first clause useful on its own; skill lists may shorten descriptions.
+- Include both what the skill does and when it should be used.
+- Use third person. Do not write "I can..." or "You can...".
+- Do not include XML tags, markdown tables, long examples, or implementation steps.
+- Do not duplicate the full SKILL.md body. The description is only discovery metadata.
+
+## What Good Descriptions Do
+
+A good description helps the model decide whether to load the skill before it has read the skill body. It should answer three questions:
+
+1. What capability does this skill provide?
+2. Which user requests, file names, commands, or domain terms should trigger it?
+3. What boundary keeps it from triggering on adjacent but wrong tasks?
+
+Prefer concrete nouns, verbs, and file names over generic labels. Use terms a user would actually type: `SKILL.md`, `.cursor/rules`, `commit message`, `invoice`, `wrangler`, `Netlify deploy`, `DOCX`, `.xlsx`.
+
+## Recommended Shape
+
+Use one or two compact sentences:
+
+```yaml
+description: <Primary capability>. Use when <trigger phrases, file types, commands, or task context>.
+```
+
+For reference-only skills:
+
+```yaml
+description: <Domain conventions or reference material>. Use when working on <specific files, modules, APIs, or workflows>.
+```
+
+For side-effecting workflows, be narrower:
+
+```yaml
+description: Prepare and verify production deploys. Use only when the user explicitly asks to deploy, release, publish, or check deployment status.
+```
+
+## Examples
+
+Good:
+
+```yaml
+description: Create or edit Claude, Codex, and Cursor skills/rules. Use for SKILL.md, .cursor/rules, AGENTS.md, frontmatter, references, scripts, and discovery rules.
+```
+
+Good:
+
+```yaml
+description: Review GitHub pull request feedback and implement requested changes. Use when the user asks to address PR comments, review threads, or requested changes.
+```
+
+Too vague:
+
+```yaml
+description: Helps with skills.
+```
+
+Too broad:
+
+```yaml
+description: Manage all developer workflow tasks, docs, rules, automation, repository work, deployment, testing, and issue handling.
+```
+
+Wrong point of view:
+
+```yaml
+description: I can help you write better skill descriptions.
+```
+
+## Checklist
+
+- [ ] 50-300 characters.
+- [ ] First words contain the primary trigger.
+- [ ] Mentions the key files, commands, domains, or user phrases.
+- [ ] Says when to use it, not only what it is.
+- [ ] Specific enough to avoid accidental invocation.
+- [ ] No body-level instructions, setup steps, or long examples.
+
+Run the local inspector after editing:
+
+```bash
+bun scripts/inspect-description.ts
+```