aiblueprint-cli 1.4.59 → 1.4.60

package/agents-config/skills/skill-manager/references/codex.md

@@ -0,0 +1,288 @@
+# OpenAI Codex Skills
+
+Official docs: https://developers.openai.com/codex/skills
+Examples: https://github.com/openai/skills
+
+## Layout
+
+```
+skill-name/
+├── SKILL.md            # required
+├── agents/
+│   └── openai.yaml     # optional: UI metadata, MCP deps, default prompt
+├── assets/             # icons referenced by openai.yaml, output templates
+├── references/         # loaded on demand
+└── scripts/            # executable code
+```
+
+## Storage locations (scan order)
+
+| Scope    | Path                            | Use                                  |
+| :------- | :------------------------------ | :----------------------------------- |
+| REPO     | `$CWD/.agents/skills`           | Skill scoped to working folder       |
+| REPO     | `$CWD/../.agents/skills`        | Shared across nested module          |
+| REPO     | `$REPO_ROOT/.agents/skills`     | Repo-wide for everyone               |
+| USER     | `~/.agents/skills`              | Personal, any repo                   |
+| ADMIN    | `/etc/codex/skills`             | Machine/container-wide               |
+| SYSTEM   | bundled with Codex              | Built-ins                            |
+
+Codex walks CWD up to repo root collecting `.agents/skills` at each level. Symlinks are followed. Same `name` in two scopes is NOT merged - both appear in the selector.
+
+## SKILL.md (required, minimal)
+
+```markdown
+---
+name: skill-name
+description: Explain exactly when this skill should and should not trigger.
+---
+
+Imperative instructions for Codex.
+```
+
+Only `name` and `description` are required. The description is what triggers implicit invocation - front-load the use case and trigger words. Codex caps the initial skill list at ~2% of context (or ~8000 chars); descriptions get shortened first, so the important phrases must come first.
+
+## Invocation
+
+- **Explicit**: user types `$skill-name` in CLI/IDE, or `/skills` to browse.
+- **Implicit**: Codex picks the skill when the user's prompt matches the description.
+
+To block implicit picking (e.g., for side-effecting skills), set `policy.allow_implicit_invocation: false` in `openai.yaml`. `$skill-name` still works.
+
+---
+
+# `agents/openai.yaml` - the optional UX layer
+
+`openai.yaml` is product-specific config the **harness** reads, not the model. It controls how the skill appears in the Codex app/IDE (icon, name, color, blurb), how it can be invoked, and what MCP servers it needs to function. The skill still works without it - this layer makes it feel native.
+
+## When to add it
+
+- **Skip** for a personal, instruction-only skill in your own repo. SKILL.md alone is fine.
+- **Add it** when you want the skill to look polished in the Codex app skill picker (real icon, brand color, friendly name).
+- **Required** if the skill needs an MCP server (Figma, Notion, Linear, GitHub, etc.) to function - that's how Codex knows to connect.
+- **Required** if you want to disable implicit invocation for safety.
+
+## Full schema with constraints
+
+```yaml
+interface:
+  display_name: "Optional user-facing name"
+  short_description: "Optional user-facing description"
+  icon_small: "./assets/small-400px.png"
+  icon_large: "./assets/large-logo.svg"
+  brand_color: "#3B82F6"
+  default_prompt: "Use $skill-name to draft a concise weekly status update."
+
+policy:
+  allow_implicit_invocation: false
+
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "github"
+      description: "GitHub MCP server"
+      transport: "streamable_http"
+      url: "https://api.githubcopilot.com/mcp/"
+```
+
+**Top-level rules**
+
+- Quote every string value. Leave keys unquoted.
+- Paths in `icon_small` / `icon_large` are relative to the skill directory. Convention: put icons under `./assets/`.
+
+### `interface` fields (UI metadata)
+
+| Field               | Purpose                                       | Notes                                                                                |
+| :------------------ | :-------------------------------------------- | :----------------------------------------------------------------------------------- |
+| `display_name`      | Human-facing title in skill lists/chips       | Keep short. Don't repeat the `name` slug.                                            |
+| `short_description` | One-line blurb for skill picker               | **25-64 chars**. Skim-readable.                                                      |
+| `icon_small`        | Small icon path                               | Use `./assets/<file>`. PNG or SVG. Used in chips/lists.                              |
+| `icon_large`        | Large logo path                               | Used on the skill detail card.                                                       |
+| `brand_color`       | Hex color for UI accents                      | Format `"#RRGGBB"`. Picks badge / pill color.                                        |
+| `default_prompt`    | Example prompt inserted when invoking         | **Must mention the skill as `$skill-name`** (e.g., "Use `$weekly-status` to draft…") |
+
+### `policy` field
+
+- `allow_implicit_invocation` (default: `true`). Set to `false` for skills with side effects (deploy, post, write). Users can still trigger with `$skill-name`.
+
+### `dependencies.tools` (MCP)
+
+Only `type: "mcp"` is supported today. Each entry:
+
+| Field         | Required | Description                                                              |
+| :------------ | :------- | :----------------------------------------------------------------------- |
+| `type`        | yes      | Always `"mcp"` for now                                                   |
+| `value`       | yes      | Server identifier. Must match `[mcp_servers.<value>]` in `config.toml`   |
+| `description` | yes      | Human-readable purpose                                                   |
+| `transport`   | yes      | Always `"streamable_http"` for remote MCP servers                        |
+| `url`         | yes      | HTTPS endpoint of the MCP server                                         |
+
+---
+
+## Wiring an MCP-backed skill end-to-end
+
+Two files have to agree:
+
+**1. Skill declares the dependency** (`<skill>/agents/openai.yaml`)
+
+```yaml
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "figma"
+      description: "Figma MCP server for design-to-code"
+      transport: "streamable_http"
+      url: "https://mcp.figma.com/mcp"
+```
+
+**2. User configures the server** (`~/.codex/config.toml`)
+
+```toml
+rmcp_client = true   # required feature flag for remote MCP
+
+[mcp_servers.figma]
+url = "https://mcp.figma.com/mcp"
+bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
+# optional:
+# http_headers = { "X-Figma-Region" = "us" }
+# startup_timeout_sec = 10
+# tool_timeout_sec = 30
+```
+
+The token itself lives in the environment:
+
+```bash
+export FIGMA_OAUTH_TOKEN="…"
+```
+
+Restart Codex after editing `config.toml` or the env var.
+
+**Real-world reference table**
+
+| Skill                          | MCP `value` | URL                          | Env var               |
+| :----------------------------- | :---------- | :--------------------------- | :-------------------- |
+| `figma`                        | `figma`     | `https://mcp.figma.com/mcp`  | `FIGMA_OAUTH_TOKEN`   |
+| `notion-knowledge-capture`     | `notion`    | `https://mcp.notion.com/mcp` | `NOTION_OAUTH_TOKEN`  |
+| `notion-meeting-intelligence`  | `notion`    | `https://mcp.notion.com/mcp` | `NOTION_OAUTH_TOKEN`  |
+| `notion-spec-to-implementation`| `notion`    | `https://mcp.notion.com/mcp` | `NOTION_OAUTH_TOKEN`  |
+
+---
+
+## Enable/disable a skill without deleting
+
+`~/.codex/config.toml`:
+
+```toml
+[[skills.config]]
+path = "/absolute/path/to/skill/SKILL.md"
+enabled = false
+```
+
+Restart Codex after editing.
+
+## Distribution
+
+For sharing beyond one repo, bundle as a **plugin**. Plugins can hold one or more skills plus MCP server config and app mappings. `.agents/skills/` is for local authoring; plugins are for distribution. `$skill-installer <name>` pulls curated skills locally.
+
+---
+
+## Recipes
+
+### Pure instruction-only skill (no UI polish, no MCP)
+
+```
+weekly-status/
+└── SKILL.md
+```
+
+```markdown
+---
+name: weekly-status
+description: Draft a concise weekly status update. Use when the user asks to "write my weekly status", "summarize the week", or "draft a standup update".
+---
+
+Draft a 4-bullet status:
+1. Shipped this week (link PRs)
+2. In progress with current blockers
+3. Coming next week
+4. Asks / decisions needed
+
+Keep each bullet under 20 words. No emoji. No filler.
+```
+
+### Polished skill with branded UI
+
+```
+weekly-status/
+├── SKILL.md
+├── agents/openai.yaml
+└── assets/
+    ├── small-400px.png
+    └── large-logo.svg
+```
+
+```yaml
+interface:
+  display_name: "Weekly Status"
+  short_description: "Draft a concise weekly status update"
+  icon_small: "./assets/small-400px.png"
+  icon_large: "./assets/large-logo.svg"
+  brand_color: "#7C3AED"
+  default_prompt: "Use $weekly-status to draft this week's update from my recent PRs."
+```
+
+### Side-effecting skill (block implicit)
+
+```yaml
+interface:
+  display_name: "Deploy Production"
+  short_description: "Ship the current branch to prod"
+  brand_color: "#DC2626"
+  default_prompt: "Use $deploy-prod to release the current branch."
+
+policy:
+  allow_implicit_invocation: false   # user must type $deploy-prod
+```
+
+### MCP-backed skill (Figma example)
+
+```yaml
+interface:
+  display_name: "Figma"
+  short_description: "Implement designs from Figma nodes"
+  icon_small: "./assets/figma-small.svg"
+  icon_large: "./assets/figma.png"
+  brand_color: "#F24E1E"
+  default_prompt: "Use $figma to implement the selected node."
+
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "figma"
+      description: "Figma design context"
+      transport: "streamable_http"
+      url: "https://mcp.figma.com/mcp"
+```
+
+Skill body then calls the MCP tools in a deterministic sequence (e.g., for Figma: `get_design_context` → `get_metadata` if truncated → `get_screenshot` for parity).
+
+---
+
+## Common mistakes
+
+- **Description is a label, not a trigger.** "Figma helper" → "Use when the user asks to implement a Figma design, build UI from a Figma node, or convert a Figma URL to code."
+- **Forgot to quote string values** in YAML. Unquoted hex colors / URLs blow up parsing.
+- **`default_prompt` doesn't reference `$skill-name`**. Per the schema constraint, it must.
+- **MCP `value` mismatch.** The string in `openai.yaml` must match the `[mcp_servers.<value>]` block in `config.toml` exactly.
+- **Forgot `rmcp_client = true`** in `config.toml` - MCP connections silently fail.
+- **Bearer token has quotes.** `bearer_token_env_var` resolves to the raw env value; if you wrap it in quotes when exporting, OAuth errors out.
+- **Adding `openai.yaml` for a personal skill that nobody else sees.** It's overhead. Skip it.
+- **Putting README/CHANGELOG/INSTALL files next to SKILL.md.** Codex doesn't read them, they're clutter.
+
+## Best practices
+
+- One job per skill. Split rather than bloat.
+- Instructions over scripts unless determinism matters.
+- Imperative steps with explicit inputs and outputs.
+- Re-read the `description`: would it actually match the prompts you have in mind? Test against 3 real phrasings.
+- Keep `short_description` skim-readable (25-64 chars).
+- Pre-size icons before shipping: small ~400px, large ~1024px square. Match `brand_color` to the icon for cohesion.

package/agents-config/skills/skill-manager/references/cursor.md

@@ -0,0 +1,125 @@
+# Cursor Rules
+
+Official docs: https://cursor.com/docs/rules.md
+
+Cursor calls them "rules", not skills. Same idea: persistent instructions injected into the model context. Four kinds:
+
+| Kind          | Location                   | Notes                              |
+| :------------ | :------------------------- | :--------------------------------- |
+| Project Rules | `.cursor/rules/*.md(c)`    | Version-controlled, scoped to repo |
+| User Rules    | Cursor Settings → Rules    | Global, chat-only                  |
+| Team Rules    | Cursor dashboard           | Team/Enterprise plans              |
+| AGENTS.md     | project root + subdirs     | Plain markdown, no frontmatter     |
+
+Precedence when merging: **Team Rules → Project Rules → User Rules**. Earlier source wins on conflict.
+
+## Project rule file: `.cursor/rules/<name>.mdc`
+
+Use `.mdc` when you need frontmatter, `.md` for content-only. Frontmatter has three fields:
+
+| `alwaysApply` | `description` | `globs`   | Behavior                                                |
+| :------------ | :------------ | :-------- | :------------------------------------------------------ |
+| `true`        | -             | -         | Always included. `description`/`globs` ignored.         |
+| `false`       | -             | provided  | Auto-attached when a matching file is in context.       |
+| `false`       | provided      | omitted   | Agent reads description, pulls in when relevant.        |
+| `false`       | omitted       | omitted   | Manual only - included when `@`-mentioned in chat.      |
+
+### Four templates
+
+**Always applied**
+
+```md
+---
+alwaysApply: true
+---
+
+- All source files must include the company copyright header
+- Never modify generated files in `dist/` or `build/`
+```
+
+**Auto-attached by file pattern**
+
+```md
+---
+globs: src/components/**/*.tsx
+alwaysApply: false
+---
+
+- Use named exports, not default exports
+- Co-locate styles in a CSS module next to the component
+- Keep components under 200 lines
+```
+
+**Agent-selected by description**
+
+```md
+---
+description: RPC service conventions and patterns for the backend
+alwaysApply: false
+---
+
+- Define each service in its own file under `src/services/`
+- Validate inputs at the service boundary
+- Reference `@service-template.ts` for boilerplate
+```
+
+**Manual via @-mention**
+
+```md
+---
+alwaysApply: false
+---
+
+- Every database migration must have `up` and `down`
+- Never alter a column type in-place
+
+@migration-template.sql
+```
+
+### Glob examples
+
+| Pattern                          | Matches                              |
+| :------------------------------- | :----------------------------------- |
+| `*.ts`                           | `.ts` files at root                  |
+| `**/*.ts`                        | `.ts` files anywhere                 |
+| `src/**`                         | everything under `src/`              |
+| `src/**/*.tsx`                   | `.tsx` files anywhere under `src/`   |
+| `docs/**/*.md, docs/**/*.mdx`    | comma-separate multiple patterns     |
+| `tailwind.config.*`              | any extension                        |
+
+### Referencing files
+
+`@filename.ts` inside a rule attaches that file to the context when the rule fires. Use this to point at canonical templates instead of copying code.
+
+## AGENTS.md (no frontmatter)
+
+Plain markdown in project root or subdirectories. No fields, no globs - just instructions.
+
+```markdown
+# Project Instructions
+
+## Code Style
+- Use TypeScript for all new files
+- Prefer functional components in React
+```
+
+Nested support: `frontend/AGENTS.md` applies inside `frontend/`, combined with the root file. More specific wins.
+
+## User Rules
+
+Free-form global preferences set in Cursor Settings. Chat-only (not Inline Edit / Cmd-K).
+
+## Best practices
+
+- Keep rules under 500 lines; split into composable rules instead.
+- Concrete examples beat vague guidance.
+- Reference files with `@name.ts` rather than copying code (stays in sync).
+- Skip style guides Cursor already knows. Add a rule when you see the same mistake twice.
+- Check rules into git so the team benefits.
+
+## Common mistakes
+
+- Using `alwaysApply: true` for rules that only matter in one directory - use `globs` instead.
+- Description that's a label, not a trigger ("Backend stuff" → "RPC service conventions and patterns for the backend").
+- Copying entire style guides instead of using a linter.
+- Manual rule (no globs, no description, `alwaysApply: false`) without telling the user it must be `@`-mentioned.

package/agents-config/skills/ultrathink/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: ultrathink
 description: Deep thinking mode - approach problems like a craftsman, obsess over details, and create elegant solutions
+disable-model-invocation: true
+allow_implicit_invocation: false
 ---
 
 # Ultrathink

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiblueprint-cli",
-  "version": "1.4.59",
+  "version": "1.4.60",
   "description": "AIBlueprint CLI for setting up AI coding configurations",
   "author": "AIBlueprint",
   "license": "MIT",

package/agents-config/claude-config/scripts/statusline/data/.gitignore

@@ -1,8 +0,0 @@
-# Ignore all data files
-*.db
-*.json
-
-# But keep this .gitignore
-!.gitignore
-
-last_payload.txt

package/agents-config/claude-config/scripts/statusline/docs/ARCHITECTURE.md

@@ -1,166 +0,0 @@
-# Statusline Architecture - Session & Period Tracking
-
-## Concepts Fondamentaux
-
-### Session Claude Code
-
-Une **session** est créée chaque fois qu'on ouvre un chat avec Claude Code.
-
-Caractéristiques:
-- **ID unique**: `session_id` (UUID)
-- **Coût cumulatif**: Le coût total de la session qui AUGMENTE au fil du temps
-- **Persistance**: Une session peut durer des heures/jours
-- **Commande /clear**: Efface la conversation mais GARDE la même session
-- **Le coût ne reset jamais**: Si une session a coûté $10, puis on fait /clear, le coût reste $10 et continue d'augmenter
-
-```
-Session "abc-123"
-├── Début: $0
-├── Après 1h: $5
-├── /clear (conversation effacée)
-├── Après 2h: $12 (coût continue d'augmenter)
-├── Fermeture terminal
-├── Réouverture (même session)
-└── Après 3h: $18 (toujours cumulatif)
-```
-
-### Période (5 heures)
-
-Une **période** est une fenêtre de 5 heures pour le rate limiting d'Anthropic.
-
-Caractéristiques:
-- **resets_at**: Timestamp de fin de période (ex: "2025-12-09T10:00:00.000Z")
-- **Durée fixe**: 5 heures
-- **Indépendant des sessions**: Les sessions peuvent traverser plusieurs périodes
-
-```
-Période A (05:00-10:00)     Période B (10:00-15:00)
-├────────────────────┤     ├────────────────────┤
-   Session 1: +$5              Session 1: +$3 (continue)
-   Session 2: +$8              Session 3: +$10 (nouvelle)
-   ─────────────               ─────────────
-   Total: $13                  Total: $13
-```
-
-## Le Problème Actuel
-
-### Bug: Double Comptage
-
-Quand on calcule le coût d'une période en sommant les coûts totaux des sessions:
-
-```
-Session X: coût total = $24
-Session X: last_resets_at = période actuelle
-
-getCurrentPeriodCost() retourne $24 ❌ FAUX!
-```
-
-Mais si la session X avait déjà $10 AVANT cette période:
-- Coût réel de cette période = $24 - $10 = $14
-- On affiche $24 au lieu de $14 = **double comptage**
-
-### Scénario Réel
-
-```
-1. Période A: Session X coûte $10, on compte $10 ✓
-2. Période B commence
-3. Session X continue, coût monte à $24
-4. On calcule période B: on voit session X = $24
-5. On affiche $24 pour période B ❌
-6. Mais on avait déjà compté $10 en période A!
-7. Total affiché: $10 + $24 = $34
-8. Total réel: $24
-```
-
-## Solution: Tracking des Deltas par Session
-
-### Nouvelle Structure de Données
-
-On doit tracker pour chaque session:
-- Combien on a DÉJÀ compté
-- Dans quelle période on l'a compté
-
-```sql
--- Table: sessions
-session_id    TEXT PRIMARY KEY
-total_cost    REAL        -- Coût total actuel de la session
-cwd           TEXT
-date          TEXT
-duration_ms   INTEGER
-lines_added   INTEGER
-lines_removed INTEGER
-
--- Table: session_period_tracking
-session_id    TEXT
-period_id     TEXT        -- resets_at normalisé
-counted_cost  REAL        -- Combien on a compté pour cette période
-last_update   INTEGER     -- Timestamp
-PRIMARY KEY (session_id, period_id)
-
--- Table: periods
-period_id     TEXT PRIMARY KEY  -- resets_at normalisé
-total_cost    REAL              -- Somme des deltas de toutes les sessions
-utilization   INTEGER
-date          TEXT
-```
-
-### Algorithme Correct
-
-```
-Quand saveSession(session_id, new_cost, current_period):
-  1. Chercher session dans DB
-  2. Si existe:
-       old_cost = session.total_cost
-       delta = new_cost - old_cost
-     Sinon:
-       delta = new_cost
-
-  3. Chercher tracking pour (session_id, current_period)
-  4. Si existe:
-       // Déjà compté dans cette période, calculer le vrai delta
-       already_counted = tracking.counted_cost
-       period_delta = delta  // Le delta depuis la dernière update
-     Sinon:
-       // Nouvelle session dans cette période
-       period_delta = delta
-
-  5. Mettre à jour:
-     - session.total_cost = new_cost
-     - tracking.counted_cost += period_delta
-     - period.total_cost += period_delta
-```
-
-### Exemple Concret
-
-```
-Session X traverse 2 périodes:
-
-Période A:
-  - Session X: $0 → $10
-  - tracking(X, A).counted_cost = $10
-  - period(A).total_cost = $10
-
-Période B:
-  - Session X: $10 → $24
-  - delta = $24 - $10 = $14
-  - tracking(X, B).counted_cost = $14
-  - period(B).total_cost = $14
-
-Calcul période B:
-  - On lit period(B).total_cost = $14 ✓ CORRECT!
-```
-
-## Avantages SQLite
-
-1. **Transactions ACID**: Pas de corruption de données
-2. **Requêtes complexes**: Agrégations, joins faciles
-3. **Index**: Performance pour les lookups par session_id
-4. **Single file**: Toujours portable
-5. **Intégrité référentielle**: FK entre tables
-
-## Migration
-
-1. Créer nouveau fichier `statusline.db`
-2. Migrer données existantes de spend.json et daily-usage.json
-3. Recalculer les period_costs correctement
-4. Supprimer les anciens fichiers JSON