aiblueprint-cli 1.4.59 → 1.4.61

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

@@ -0,0 +1,191 @@
+---
+name: rules-manager
+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>
+Rules consume tokens on every agent run. Keep them minimal, specific, and discoverable.
+
+**Two-tier system:**
+
+- **AGENTS.md** — Always loaded. Acts as the **index** + universal rules.
+- **.agents/rules/\*.md** — Modular rule files for focused topics (changelog, testing, deployment, etc.).
+
+**CRITICAL invariant:** Every file in `.agents/rules/` must be referenced in AGENTS.md so agents know it exists. AGENTS.md without a reference = orphaned rule = invisible to agents.
+</core_principle>
+
+<file_layout>
+
+```
+project-root/
+├── AGENTS.md                  # Index + universal rules (always loaded)
+└── .agents/
+    └── rules/
+        ├── changelog.md       # Rule for changelog management
+        ├── testing.md         # Rule for tests
+        └── deployment.md      # Rule for deployment
+```
+
+**AGENTS.md must contain a `## Rules` section listing each `.agents/rules/*.md` file with a one-line description.**
+</file_layout>
+
+<agents_md_template>
+Minimal AGENTS.md with rules index:
+
+```markdown
+# Project Name
+
+Short description (1-2 lines).
+
+## Tech Stack
+
+- [Non-obvious tech only]
+
+## Commands
+
+- `[dev]` - Dev server
+- `[test]` - Run tests
+
+## Rules
+
+The detailed rules live in `.agents/rules/`. Read the relevant file before acting:
+
+- **Changelog** - [.agents/rules/changelog.md](.agents/rules/changelog.md) - When/how to update CHANGELOG.md
+- **Testing** - [.agents/rules/testing.md](.agents/rules/testing.md) - Test conventions and coverage
+- **Deployment** - [.agents/rules/deployment.md](.agents/rules/deployment.md) - Deploy checklist
+
+## Universal Rules
+
+- [2-3 critical rules that apply everywhere]
+```
+
+The `## Rules` section is the index. Each bullet = one file in `.agents/rules/`. The `## Universal Rules` section holds short, project-wide constraints that don't deserve their own file.
+</agents_md_template>
+
+<rule_file_template>
+Each `.agents/rules/<name>.md` should be focused, short, and actionable.
+
+```markdown
+# [Rule Title]
+
+Short purpose statement (1 line).
+
+## When this applies
+
+- [Specific triggers - what task/context loads this rule]
+
+## Rules
+
+- [Specific, actionable rule]
+- [Another rule with example if format matters]
+
+## Example
+
+[3-5 line concrete example, only if needed]
+```
+
+**Size target:** 20-60 lines per rule file. If longer, split into multiple files.
+</rule_file_template>
+
+<writing_rules>
+**Be specific, never vague:**
+
+```
+NO: "Update changelog properly"
+YES: "Append entry to CHANGELOG.md under ## Unreleased before every PR. Format: - [type] description (#PR)"
+```
+
+**Prohibitions beat positive guidance:**
+
+```
+NO: "Try to write tests"
+YES: "NEVER merge without a passing test for the changed behavior"
+```
+
+**Emphasis hierarchy:** CRITICAL > NEVER > ALWAYS > IMPORTANT
+
+- Lead each section with the most critical rule
+- Use **bold + keyword** for non-negotiables: `**CRITICAL**: Never commit secrets`
+
+**Do NOT include:**
+
+- Generic best practices ("write clean code", "DRY", "SOLID")
+- Linter-enforced rules (ESLint, Prettier, Biome already do this)
+- Things the agent discovers from the code (file structure, framework defaults)
+- Marketing or vision statements
+- Verbose paragraphs - one line is almost always enough
+  </writing_rules>
+
+<workflows>
+
+## `/rules-manager init` - Bootstrap AGENTS.md + .agents/rules/
+
+When the argument contains `init`:
+
+1. **Detect project context** - Read `package.json` or equivalent for name, stack, scripts.
+2. **Check existing files** - If `AGENTS.md` or `.agents/rules/` already exists, read them and ASK before overwriting.
+3. **Create skeleton** - Write AGENTS.md with empty `## Rules` index, ready to populate.
+4. **Create `.agents/rules/` directory** - Empty for now. New rules added via `add` workflow.
+
+Target AGENTS.md size at init: under 40 lines.
+
+## `/rules-manager add <name>` - Add a new rule
+
+When the argument starts with `add`:
+
+1. **Confirm name** - Slugify (e.g., "changelog management" -> `changelog`). Ask user if unclear.
+2. **Read existing AGENTS.md** - Confirm it exists. If not, run `init` first.
+3. **Ask the user for rule content** - What does the rule enforce? When does it apply? Any examples?
+4. **Write `.agents/rules/<name>.md`** - Use the rule file template. Keep it 20-60 lines.
+5. **Update AGENTS.md `## Rules` section** - Add a one-line bullet pointing to the new file:
+   ```
+   - **<Title>** - [.agents/rules/<name>.md](.agents/rules/<name>.md) - <one-line purpose>
+   ```
+6. **Verify the link** - Make sure the path in AGENTS.md exactly matches the created file.
+
+**CRITICAL:** Step 5 is non-negotiable. A rule file without an index entry is invisible.
+
+## `/rules-manager optimize` - Audit and clean up
+
+When the argument contains `optimize`:
+
+1. **Inventory** - List AGENTS.md and every file in `.agents/rules/`.
+2. **Check the index** - For each file in `.agents/rules/`, verify there's a matching bullet in AGENTS.md `## Rules`. Flag missing entries.
+3. **Check for orphans** - For each AGENTS.md bullet, verify the file exists. Flag broken links.
+4. **Apply bloat removal** - For each rule file, remove:
+   - Linter-enforced rules
+   - Generic best practices
+   - Verbose explanations (compress to one line)
+   - Things derivable from code
+5. **Compress** - Paragraphs to bullets, multi-line rules to single lines.
+6. **Show diff and ask before applying.**
+
+Target sizes:
+
+- AGENTS.md: under 80 lines
+- Each rule file: under 60 lines
+
+## Default - Add a rule based on description
+
+When the argument is a free-form task (e.g., "add a rule about how we tag releases"):
+
+1. Treat as `add` with auto-derived name.
+2. Ask the user 1-2 clarifying questions if the rule scope is unclear.
+3. Follow the `add` workflow.
+   </workflows>
+
+<rules_for_this_skill>
+
+- ALWAYS update AGENTS.md `## Rules` index when creating a file in `.agents/rules/`
+- NEVER create a rule file without confirming with the user what it should contain
+- NEVER overwrite existing AGENTS.md or rule files without asking
+- Default to short rule files (20-60 lines). Split if larger.
+- When user asks "create a rule", default to creating a file in `.agents/rules/` (not inline in AGENTS.md), unless the rule is 1-2 lines and fits the universal section.
+  </rules_for_this_skill>
+
+<reference_guides>
+
+- **Examples**: [references/examples.md](references/examples.md) - Sample rule files (changelog, testing, deployment)
+- **AGENTS.md vs CLAUDE.md**: [references/agents-vs-claude.md](references/agents-vs-claude.md) - When to use which format
+  </reference_guides>

package/agents-config/skills/rules-manager/references/agents-vs-claude.md

@@ -0,0 +1,66 @@
+# AGENTS.md vs CLAUDE.md - When to use which
+
+Both files serve the same purpose: telling AI agents how to work in your project. They differ in audience and convention.
+
+## Quick decision
+
+| You are setting up rules for... | Use |
+|---------------------------------|-----|
+| Multiple AI agents (Claude, Codex, Cursor, etc.) | `AGENTS.md` + `.agents/rules/` |
+| Claude Code only | `CLAUDE.md` + `.claude/rules/` |
+| Both, on the same project | Both files; symlink or duplicate carefully |
+
+`AGENTS.md` has emerged as a cross-tool convention. `CLAUDE.md` is Claude-specific. Use the broader one if uncertain.
+
+## Structural parity
+
+Both follow the same two-tier pattern:
+
+```
+AGENTS.md                   <->  CLAUDE.md
+.agents/rules/<name>.md     <->  .claude/rules/<name>.md
+```
+
+The index-pattern is identical: the root file lists every modular file, with a one-line description and a link.
+
+## Key differences
+
+### Path conventions
+- AGENTS.md: rules live in `.agents/rules/`
+- CLAUDE.md: rules live in `.claude/rules/`
+
+### Path-scoped rules
+- `.claude/rules/` supports YAML frontmatter `paths:` for glob-scoped rules (loads only when relevant files are touched)
+- `.agents/rules/` does not have a defined path-scoping spec across all tools - keep rules globally relevant or document scoping in plain text
+
+### Discovery
+- Claude Code auto-loads `CLAUDE.md` and recurses through subtrees
+- AGENTS.md loading depends on the agent. Be explicit in the file about how rules are organized so any agent can navigate.
+
+## Recommended pattern when supporting both
+
+Pick one as the source of truth and reference from the other:
+
+**Option A** - AGENTS.md is canonical:
+```markdown
+# CLAUDE.md
+See [AGENTS.md](AGENTS.md) for project rules and the rule index.
+```
+
+**Option B** - Symlink (cleanest if the tool follows symlinks):
+```bash
+ln -s AGENTS.md CLAUDE.md
+ln -s .agents/rules .claude/rules
+```
+
+**Option C** - Duplicate both files, accept drift risk. Run `/rules-manager optimize` periodically to catch divergence.
+
+## Migration
+
+Going from CLAUDE.md to AGENTS.md:
+1. Rename `CLAUDE.md` -> `AGENTS.md`
+2. Rename `.claude/rules/` -> `.agents/rules/`
+3. Update every link in the index
+4. Drop `paths:` frontmatter from rule files (or document scoping inline) if your other agents do not support it
+
+Going from AGENTS.md to CLAUDE.md: do the reverse.

package/agents-config/skills/rules-manager/references/examples.md

@@ -0,0 +1,117 @@
+# Sample Rule Files
+
+Concrete examples of well-formed `.agents/rules/*.md` files. Copy and adapt.
+
+---
+
+## Example 1: `.agents/rules/changelog.md`
+
+```markdown
+# Changelog Rule
+
+How and when to update CHANGELOG.md.
+
+## When this applies
+- Before opening any PR that changes user-facing behavior
+- After merging a release branch
+
+## Rules
+- **ALWAYS** append entries under `## Unreleased` at the top of CHANGELOG.md
+- Use the format: `- [type] description (#PR)` where type is `feat | fix | chore | docs | breaking`
+- **NEVER** edit historical entries below `## Unreleased`
+- On release, rename `## Unreleased` to `## vX.Y.Z - YYYY-MM-DD`
+
+## Example
+```
+## Unreleased
+- [feat] Add dark mode toggle (#142)
+- [fix] Crash on empty search input (#145)
+```
+```
+
+---
+
+## Example 2: `.agents/rules/testing.md`
+
+```markdown
+# Testing Rule
+
+Test conventions for this project.
+
+## When this applies
+- Writing new code
+- Fixing bugs (write a failing test first)
+
+## Rules
+- **NEVER** merge a behavior change without a passing test
+- Tests live next to the source: `src/foo.ts` -> `src/foo.test.ts`
+- Use Vitest. Run with `pnpm test`
+- Mock external APIs at the network layer (msw), not at the function level
+- Coverage gate: 80% for new files, no regression on existing files
+```
+
+---
+
+## Example 3: `.agents/rules/deployment.md`
+
+```markdown
+# Deployment Rule
+
+Pre-deploy checklist and rollback policy.
+
+## When this applies
+- Promoting a build to production
+- Tagging a release
+
+## Rules
+- **CRITICAL**: Run `pnpm build && pnpm test` locally before tagging
+- Tags follow semver: `v1.2.3` (no `v1.2.3-final-final`)
+- Migrations must be backward-compatible for one release cycle
+- **NEVER** deploy on Friday after 3pm or weekends without sign-off
+
+## Rollback
+- `pnpm deploy:rollback <previous-tag>` reverts in under 2 minutes
+- Always announce in #deploys before and after
+```
+
+---
+
+## Example 4: `.agents/rules/git-workflow.md`
+
+```markdown
+# Git Workflow Rule
+
+Branching, commits, and PR conventions.
+
+## When this applies
+- Every code change
+
+## Rules
+- Branch from `main`. Name: `<type>/<short-description>` (e.g. `feat/dark-mode`)
+- Conventional commits: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`
+- **NEVER** force-push to `main` or shared branches
+- PRs need 1 approval + green CI before merge
+- Squash merge by default. Merge commit only for release branches.
+```
+
+---
+
+## Index entries in AGENTS.md
+
+After creating any of the above, AGENTS.md must include a matching bullet:
+
+```markdown
+## Rules
+
+The detailed rules live in `.agents/rules/`. Read the relevant file before acting:
+
+- **Changelog** - [.agents/rules/changelog.md](.agents/rules/changelog.md) - When/how to update CHANGELOG.md
+- **Testing** - [.agents/rules/testing.md](.agents/rules/testing.md) - Test conventions and coverage gates
+- **Deployment** - [.agents/rules/deployment.md](.agents/rules/deployment.md) - Pre-deploy checklist and rollback
+- **Git workflow** - [.agents/rules/git-workflow.md](.agents/rules/git-workflow.md) - Branching, commits, PRs
+```
+
+The bullet does three things at once:
+1. Tells the agent the rule exists
+2. Gives it a one-line summary so it knows when to load it
+3. Provides the exact path to read

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

@@ -0,0 +1,101 @@
+---
+name: skill-manager
+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
+
+Authoring guide for skills/rules across three agent platforms. All three share the same idea: a small markdown file with frontmatter, optional references, optional scripts. The discovery rules and frontmatter fields differ.
+
+| Platform     | File                                          | Frontmatter fields                                       | Optional config              |
+| :----------- | :-------------------------------------------- | :------------------------------------------------------- | :--------------------------- |
+| Claude Code  | `<scope>/skills/<name>/SKILL.md`              | `name`, `description`, plus invocation/execution fields  | -                            |
+| Codex        | `<scope>/.agents/skills/<name>/SKILL.md`      | `name`, `description`                                    | `agents/openai.yaml`         |
+| Cursor       | `.cursor/rules/<name>.md` or `.mdc`           | `description`, `globs`, `alwaysApply`                    | `AGENTS.md` (no frontmatter) |
+
+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/`.
+
+## Core principles (all platforms)
+
+### Concise is key
+
+The context window is shared with the system prompt, conversation, other skills' metadata, and the user request. Only add context the agent doesn't already have. Challenge each line: does it justify its tokens?
+
+### Match freedom to fragility
+
+- **High freedom** (prose instructions): multiple valid approaches, decisions depend on context.
+- **Medium freedom** (pseudocode, scripts with parameters): preferred pattern exists, some variation OK.
+- **Low freedom** (specific scripts, few parameters): fragile, error-prone, must run a fixed sequence.
+
+### Progressive disclosure
+
+Three loading levels:
+
+1. **Metadata** (name + description): always in context. Keep tight.
+2. **SKILL.md body**: loaded when the skill triggers. Aim under ~500 lines.
+3. **References**: loaded on demand. Move variant-specific detail, schemas, and long examples here.
+
+Keep references one level deep. Reference them by name in SKILL.md so the agent knows when to open them.
+
+### Skill anatomy
+
+```
+skill-name/
+├── SKILL.md            # required: frontmatter + instructions
+├── references/         # optional: docs loaded on demand
+├── scripts/            # optional: deterministic code
+└── assets/             # optional: templates/icons used in output
+```
+
+Do NOT add README, CHANGELOG, INSTALLATION_GUIDE, etc. Only files the agent needs at runtime.
+
+## Authoring workflow
+
+1. **Pin down the use case.** Get 2-3 concrete example prompts that should trigger the skill. Confirm with the user.
+2. **List reusable parts.** What scripts, references, or assets recur? Add only those.
+3. **Write SKILL.md.** Frontmatter first (description is what triggers it - front-load keywords). Then imperative-form body.
+4. **Test the description.** The description has to read like a trigger phrase, not a label. Examples in each reference file.
+5. **Iterate after real use.** Note what the agent got wrong; refine the relevant section.
+
+## 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. 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:
+
+- **Claude Code**: `~/.claude/skills/` (personal) or `.claude/skills/` (project). Higher scope wins on name collision.
+- **Codex**: `.agents/skills/` walks up from CWD to repo root, then `~/.agents/skills/`, then `/etc/codex/skills`, then system bundled.
+- **Cursor**: `.cursor/rules/` (project, version-controlled) or `AGENTS.md` files in project subdirectories.

package/agents-config/skills/skill-manager/references/claude-code.md

@@ -0,0 +1,81 @@
+# Claude Code Skills
+
+Official docs: https://code.claude.com/docs/llms.txt
+
+## Layout
+
+```
+skill-name/
+├── SKILL.md            # required
+├── references/         # loaded on demand
+├── scripts/            # executable code
+└── assets/             # templates, icons, fonts used in output
+```
+
+## Storage locations
+
+| Location   | Path                                     | Applies to             |
+| :--------- | :--------------------------------------- | :--------------------- |
+| Personal   | `~/.claude/skills/<name>/SKILL.md`       | All your projects      |
+| Project    | `.claude/skills/<name>/SKILL.md`         | This project only      |
+| Plugin     | `<plugin>/skills/<name>/SKILL.md`        | Where plugin enabled   |
+| Enterprise | Managed settings                         | Whole org              |
+
+Precedence on name collision: enterprise > personal > project. Nested `.claude/skills/` under subdirectories is auto-discovered (monorepos).
+
+## SKILL.md frontmatter
+
+**Core**
+
+- `name` (optional, defaults to directory name): lowercase, hyphens, max 64 chars.
+- `description` (recommended): what it does + when to use. Front-load trigger keywords.
+
+**Invocation control**
+
+- `disable-model-invocation: true` - only the user can invoke. Use for side-effecting commands like `/deploy`.
+- `user-invocable: false` - only Claude can invoke. Use for background knowledge.
+- `argument-hint: "[issue-number]"` - shown in autocomplete.
+
+**Execution control**
+
+- `allowed-tools: [Read, Edit, Bash]` - tools usable without permission prompts.
+- `model: claude-sonnet-4-6` - override active model.
+- `context: fork` - run in a forked subagent context (no conversation history).
+- `agent: Explore` - subagent type when `context: fork` is set.
+- `hooks` - lifecycle hooks scoped to this skill.
+
+**Substitutions in body**
+
+- `$ARGUMENTS` - args passed when invoking.
+- `${CLAUDE_SESSION_ID}` - current session ID.
+
+**Dynamic context injection**: prefix a shell command with `!` and wrap in backticks; output replaces the placeholder before the body is sent to the model.
+
+## Example: subagent-forked skill
+
+```markdown
+---
+name: deep-research
+description: Research a topic thoroughly. Use when the user asks to research, investigate, or deeply explore a topic that requires multiple file reads and web searches.
+context: fork
+agent: Explore
+---
+
+Research $ARGUMENTS thoroughly:
+1. Find relevant files using Glob and Grep
+2. Read and analyze the code
+3. Summarize findings with file references
+```
+
+## Bundled resources
+
+- **`scripts/`**: deterministic code (Python, Bash, TS). Run without loading into context. Include only when the same code would be rewritten repeatedly.
+- **`references/`**: docs loaded on demand. Schemas, API specs, long examples, domain glossaries. Keep one level deep.
+- **`assets/`**: files used in output (templates, fonts, boilerplate). Not loaded into context.
+
+## Common mistakes
+
+- Description that labels instead of triggers ("Helper for X" → "Use when the user asks to X...").
+- SKILL.md > 500 lines without splitting into references.
+- README/CHANGELOG files next to SKILL.md.
+- Duplicating the same content in SKILL.md and references.