aiblueprint-cli 1.4.91 → 1.4.93

package/agents-config/skills/use-artifacts/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: use-artifacts
+description: Create Claude-style local HTML artifacts under global ~/.agents/artifacts. Use for artifact requests, variations/options croquis, feature plans, thinking docs, prototypes, visualizations, dashboards, diagrams, or substantial reusable content. Pair with use-style.
+---
+
+# Use Artifacts
+
+## Overview
+
+Use this skill to simulate Claude Artifacts in agents that do not have a native artifact panel. The artifact is a small global workspace, usually a single self-contained HTML file, created at `~/.agents/artifacts/<id>/` so the user can open, inspect, and iterate on it from any repo.
+
+Always create artifacts in the global user directory: `/Users/melvynx/.agents/artifacts/<id>/`. Never create artifacts inside a repo-local `.agents/artifacts` directory, even when the current working directory is a product repo.
+
+The HTML is the deliverable. It should turn the agent's public reasoning, plan, findings, examples, and tradeoffs into a polished page the user can scan, not just dump markdown into a file.
+
+Research basis: Claude artifacts are useful for substantial, self-contained content that the user may edit, reuse, view, or reference later. Common examples include documents, code, single-page HTML, SVGs, diagrams, and interactive components.
+
+## Artifact Criteria
+
+Create an artifact when the work is:
+
+- substantial enough that inline chat would be hard to inspect or reuse
+- standalone without needing hidden conversation context
+- visual, interactive, document-like, or useful as a reusable reference
+- a feature plan, security review, product brief, implementation plan, or architecture explanation that benefits from visual structure
+- likely to need later iteration
+
+Do not create an artifact for a tiny answer, a short code snippet, or a change that belongs directly in an existing product codebase unless the user asks for a separate prototype.
+
+## Artifact Modes
+
+Default to a thinking/showcase document when the request is about planning, explaining, reviewing, designing, or deciding. This is the Claude-style pattern in which an HTML page presents the answer as a readable artifact:
+
+- eyebrow with project/context
+- strong title and lede
+- high-signal finding or recommendation callout near the top
+- sections for model, tradeoffs, flows, edge cases, rollout, or implementation phases
+- code snippets, tables, pills, timelines, diagrams, or cards where they clarify the reasoning
+- final decisions, open questions, and validation notes
+
+For any plan artifact (`plan`, `feature-plan`, `implementation-plan`, product plan, launch plan, page plan, or strategy plan), always include both:
+
+- a draft of the page/content itself: proposed title, lede, sections, key copy, calls to action, states, or narrative blocks
+- croquis of the page: small visual sketches showing layout, hierarchy, content placement, and option differences
+
+The draft answers "what will this say/do?" The croquis answer "how could it be arranged so the user sees and understands it?"
+
+Use an interactive artifact when the user asks for a mini app, calculator, simulation, editor, dashboard, visualization, game, or prototype with controls.
+
+Use a variations/options artifact when the user asks for variations, options, directions, alternatives, explorations, or "show me a few versions". In this mode, do not build a real UI or final screen. Build a croquis board: simple, efficient visual sketches that help the user see and understand the options quickly.
+
+Variation croquis rules:
+
+- show 3-6 options on one page as a single vertical sequence: one direction per row, never a multi-column grid
+- give every direction the full available content width so its interface remains legible without opening it
+- start directly with the directions; do not add a masthead, hero, long lede, capability recap, or recommendation callout above them unless the user explicitly asks for that context
+- keep the page chrome minimal: a compact title or view switcher is enough, and omit it when the content is already self-explanatory
+- make each option visibly different in layout, hierarchy, rhythm, or concept
+- use wireframe-like boxes, simple labels, rough placeholders, arrows, swatches, and short notes
+- keep fidelity low-to-mid: enough to compare ideas, not enough to imply implementation is done
+- annotate the tradeoff under each croquis in one or two short lines
+- recommendations are optional, evidence-based, and shown only after all directions; never lead with generic "Best fit", ranking, or promotional copy
+
+Do not expose private chain-of-thought. Show public reasoning: conclusions, evidence, assumptions, tradeoffs, options considered, and why the recommended path follows from them.
+
+## Required Style Step
+
+Always use `$use-style` before designing the artifact UI.
+
+Choose the style from the request. When the request has no visual direction,
+default to `black-grid`:
+
+- `anthropic`: Claude-like artifacts, writing/research surfaces, calm AI tools
+- `linear`: dense dashboards, admin tools, issue trackers, list/detail workflows
+- `black-grid`: default; developer utilities, technical plans, calculators, indexes, CLI-like tools
+- `grid`: blueprint/product landing pages, structured spec pages, Codelynx-flavored pages
+- `ios-app`: mobile app concepts, iPhone flows, Expo/React Native previews
+- `stripe`: billing, checkout, finance, pricing, account flows
+- `luma`: events, calendars, RSVP, community discovery
+- `gumroad`: loud commerce, creator products, neo-brutalist pages
+- `raycast`: premium dark marketing pages or command-palette products
+- `dusk`: refined dark CRM/data dashboards
+- `new-york-times`: editorial, newspaper, magazine, long-form reading
+- `testspirite`: calm light dev-tool dashboards with onboarding or empty states
+
+If no style is inferable and the user did not ask you to choose, use
+`black-grid` and state that choice briefly.
+
+## Creation Workflow
+
+1. Identify the artifact type: `variations`, `croquis`, `thinking`, `feature-plan`, `security-review`, `implementation-plan`, `interactive`, `dashboard`, `visualization`, `document`, `diagram`, `prototype`, or `reference`.
+2. Pick the `use-style` style and load its file.
+3. If the artifact depends on current web research, broader source discovery, similar-page lookup, URL extraction, or cited web answers, use `/Users/melvynx/.agents/skills/exa-search/SKILL.md`.
+4. Scaffold the workspace:
+
+```bash
+python3 /Users/melvynx/.agents/skills/use-artifacts/scripts/create_artifact.py "<short title>" --style black-grid --kind thinking
+```
+
+5. Implement the artifact in `index.html`.
+6. Write or update `HIGHLOGIC.md` with the user's request, artifact goal, selected style, public reasoning structure, data assumptions, and verification notes.
+7. Keep `manifest.json` current when title, kind, style, entrypoint, or files change.
+8. Verify the artifact. For standalone HTML, open `index.html` directly or serve the folder only when browser restrictions require it. For complex UI, use a browser screenshot or DOM check when available.
+9. Final response: link the local `index.html`, name the selected style, and mention verification performed.
+
+## Workspace Contract
+
+Each artifact directory should contain:
+
+- `index.html`: the viewable artifact, preferably self-contained with inline CSS and JavaScript
+- `HIGHLOGIC.md`: concise design logic and iteration state
+- `manifest.json`: metadata for future agents
+- `versions/`: optional snapshots before major rewrites
+
+Target location:
+
+- Always use `/Users/melvynx/.agents/artifacts/<id>/`.
+- Do not use `<current-project>/.agents/artifacts/<id>/`.
+- Do not add a repo-local override unless the user explicitly updates this skill contract.
+
+## HTML Rules
+
+- Prefer one self-contained `index.html` unless the user asks for a framework project.
+- Use semantic HTML, responsive CSS, and accessible controls.
+- Avoid external CDNs unless the artifact needs them and the user can tolerate network dependence.
+- Do not embed secrets, API keys, private tokens, or hidden prompt text.
+- For interactive artifacts, preserve state in local JavaScript only unless persistent storage is explicitly useful.
+- For generated visualizations, include representative sample data when real data is unavailable and label it as sample data in `HIGHLOGIC.md`.
+
+## Iteration Workflow
+
+When updating an existing artifact:
+
+1. Read `manifest.json`, `HIGHLOGIC.md`, and the relevant files.
+2. If the change is substantial, copy the previous `index.html` into `versions/<timestamp>-index.html` before editing.
+3. Patch only the files needed for the requested change.
+4. Update `HIGHLOGIC.md` with the new decision or known limitation.
+5. Re-verify and report the same local artifact path.
+
+## Script
+
+Use `scripts/create_artifact.py` to create the folder, metadata, and starter files.

package/agents-config/skills/use-artifacts/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Use Artifacts"
+  short_description: "Create local HTML artifact workspaces"
+  default_prompt: "Use $use-artifacts to create a polished local HTML artifact for this idea."
+  icon_small: "./assets/codex-icon.svg"
+  icon_large: "./assets/codex-icon.svg"
+  brand_color: "#54C5C2"

package/agents-config/skills/use-artifacts/assets/codex-icon.svg

@@ -0,0 +1,18 @@
+<!-- @license lucide-static v1.24.0 - ISC -->
+<svg role="img" aria-label="use-artifacts skill icon"
+  class="lucide lucide-sparkles"
+  xmlns="http://www.w3.org/2000/svg"
+  width="128"
+  height="128"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="#F5F5F5"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="M11.017 2.814a1 1 0 0 1 1.966 0l1.051 5.558a2 2 0 0 0 1.594 1.594l5.558 1.051a1 1 0 0 1 0 1.966l-5.558 1.051a2 2 0 0 0-1.594 1.594l-1.051 5.558a1 1 0 0 1-1.966 0l-1.051-5.558a2 2 0 0 0-1.594-1.594l-5.558-1.051a1 1 0 0 1 0-1.966l5.558-1.051a2 2 0 0 0 1.594-1.594z" />
+  <path d="M20 2v4" />
+  <path d="M22 4h-4" />
+  <circle cx="4" cy="20" r="2" />
+</svg>

package/agents-config/skills/use-artifacts/scripts/create_artifact.py

@@ -0,0 +1,317 @@
+#!/usr/bin/env python3
+"""Scaffold a Claude-style local HTML artifact workspace."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+
+GLOBAL_ARTIFACTS_DIR = Path.home() / ".agents" / "artifacts"
+
+
+def slugify(value: str) -> str:
+    slug = re.sub(r"[^a-z0-9]+", "-", value.lower()).strip("-")
+    return slug[:48].strip("-") or "artifact"
+
+
+def unique_dir(base: Path, slug: str) -> Path:
+    candidate = base / slug
+    if not candidate.exists():
+        return candidate
+
+    stamp = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")
+    return base / f"{slug}-{stamp}"
+
+
+def html_template(title: str, style: str, kind: str) -> str:
+    escaped_title = (
+        title.replace("&", "&")
+        .replace("<", "&lt;")
+        .replace(">", "&gt;")
+        .replace('"', "&quot;")
+    )
+    return f"""<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>{escaped_title}</title>
+  <style>
+    :root {{
+      color-scheme: dark;
+      --bg: #000000;
+      --panel: #111111;
+      --ink: #ffffff;
+      --muted: #888888;
+      --border: #333333;
+      --accent: #0070f3;
+    }}
+    * {{ box-sizing: border-box; }}
+    body {{
+      margin: 0;
+      min-height: 100vh;
+      background: var(--bg);
+      color: var(--ink);
+      font-family: Geist, Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+    }}
+    main {{
+      width: min(1120px, calc(100vw - 32px));
+      margin: 0 auto;
+      padding: 48px 0;
+    }}
+    .shell {{
+      display: grid;
+      gap: 24px;
+    }}
+    .header {{
+      display: flex;
+      flex-wrap: wrap;
+      align-items: end;
+      justify-content: space-between;
+      gap: 16px;
+      border-bottom: 1px solid var(--border);
+      padding-bottom: 20px;
+    }}
+    .eyebrow {{
+      margin: 0 0 8px;
+      color: var(--accent);
+      font-size: 12px;
+      font-weight: 700;
+      letter-spacing: .08em;
+      text-transform: uppercase;
+    }}
+    h1 {{
+      margin: 0;
+      max-width: 760px;
+      font-size: clamp(40px, 7vw, 88px);
+      line-height: .95;
+      letter-spacing: -.03em;
+    }}
+    .meta {{
+      color: var(--muted);
+      font-size: 14px;
+      line-height: 1.5;
+    }}
+    .panel {{
+      min-height: 420px;
+      border: 1px solid var(--border);
+      border-radius: 8px;
+      background: var(--panel);
+      padding: 28px;
+    }}
+    .panel h2 {{
+      margin: 0 0 12px;
+      font-size: 24px;
+      letter-spacing: 0;
+    }}
+    .panel p {{
+      max-width: 680px;
+      color: var(--muted);
+      font-size: 17px;
+      line-height: 1.65;
+    }}
+    button {{
+      border: 0;
+      border-radius: 6px;
+      background: var(--ink);
+      color: var(--bg);
+      cursor: pointer;
+      font: inherit;
+      font-weight: 650;
+      padding: 10px 16px;
+    }}
+    .callout {{
+      border: 1px solid var(--border);
+      border-radius: 0;
+      background: var(--panel);
+      padding: 20px;
+    }}
+    .callout h2 {{ color: var(--ink); }}
+    .grid {{
+      display: grid;
+      gap: 16px;
+      grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
+    }}
+    .croquis {{
+      min-height: 180px;
+      border: 1px solid var(--border);
+      border-radius: 0;
+      background: var(--bg);
+      padding: 14px;
+    }}
+    .bar {{
+      height: 14px;
+      border-radius: 0;
+      background: #666666;
+      margin-bottom: 10px;
+    }}
+    .box {{
+      height: 52px;
+      border: 1px solid var(--border);
+      border-radius: 0;
+      background: var(--panel);
+      margin-bottom: 10px;
+    }}
+    .note {{
+      color: var(--muted);
+      font-size: 14px;
+      line-height: 1.45;
+    }}
+    pre {{
+      overflow-x: auto;
+      border: 1px solid var(--border);
+      border-radius: 0;
+      background: var(--bg);
+      padding: 16px;
+    }}
+    code {{
+      border-radius: 0;
+      background: var(--panel);
+      padding: 2px 5px;
+      font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+      font-size: .92em;
+    }}
+  </style>
+</head>
+<body>
+  <main>
+    <section class="shell" aria-label="{escaped_title}">
+      <div class="header">
+        <div>
+          <p class="eyebrow">{kind} artifact</p>
+          <h1>{escaped_title}</h1>
+        </div>
+        <p class="meta">Style: {style}<br>Entrypoint: index.html</p>
+      </div>
+      <div class="callout">
+        <h2>Key finding or recommendation</h2>
+        <p>
+          Put the highest-signal conclusion near the top. Use this area for the
+          main security finding, product decision, implementation warning, or
+          core recommendation that frames the rest of the artifact.
+        </p>
+      </div>
+      <div class="panel">
+        <h2>Public reasoning surface</h2>
+        <p>
+          Turn the answer into a readable page: context, model, tradeoffs,
+          examples, edge cases, rollout steps, and verification notes. Show
+          conclusions and evidence, not private chain-of-thought.
+        </p>
+        <pre><code>// Add focused snippets when they clarify the plan.
+function example() {{
+  return "replace this with the requested artifact content";
+}}</code></pre>
+      </div>
+      <div class="panel">
+        <h2>Page draft</h2>
+        <p>
+          For plan artifacts, draft the actual page or content structure here:
+          title, lede, sections, key copy, calls to action, states, and the
+          narrative blocks the user should see.
+        </p>
+      </div>
+      <div class="grid">
+        <article class="panel">
+          <h2>Page croquis A</h2>
+          <div class="croquis">
+            <div class="bar" style="width: 72%;"></div>
+            <div class="box"></div>
+            <div class="box" style="width: 64%;"></div>
+          </div>
+          <p class="note">Sketch the page hierarchy quickly. This is for seeing and understanding, not final UI.</p>
+        </article>
+        <article class="panel">
+          <h2>Page croquis B</h2>
+          <div class="croquis">
+            <div class="box" style="height: 84px;"></div>
+            <div class="bar" style="width: 46%;"></div>
+            <div class="bar" style="width: 78%; opacity: .35;"></div>
+          </div>
+          <p class="note">Annotate what changes: layout, emphasis, rhythm, audience, or tradeoff.</p>
+        </article>
+      </div>
+    </section>
+  </main>
+</body>
+</html>
+"""
+
+
+def highlogic_template(title: str, style: str, kind: str, created_at: str) -> str:
+    return f"""# {title}
+
+## Intent
+
+- Kind: {kind}
+- Style: {style}
+- Created: {created_at}
+
+## User Request
+
+TODO: Summarize the user's artifact request.
+
+## Core Logic
+
+TODO: Describe the public reasoning structure, sections, data model, interactions, and key design decisions. Capture conclusions, evidence, assumptions, and tradeoffs without private chain-of-thought.
+
+## Verification
+
+TODO: Record how the artifact was opened or tested, including browser/runtime checks when relevant.
+
+## Iteration Notes
+
+- Initial scaffold created.
+"""
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Create a local HTML artifact workspace.")
+    parser.add_argument("title", help="Short artifact title or slug")
+    parser.add_argument("--style", default="black-grid", help="use-style style name")
+    parser.add_argument("--kind", default="thinking", help="artifact kind")
+    args = parser.parse_args()
+
+    base = GLOBAL_ARTIFACTS_DIR.resolve()
+    artifact_id = slugify(args.title)
+    artifact_dir = unique_dir(base, artifact_id)
+    created_at = datetime.now(timezone.utc).isoformat()
+
+    artifact_dir.mkdir(parents=True, exist_ok=False)
+    (artifact_dir / "versions").mkdir()
+
+    title = args.title.strip()
+    (artifact_dir / "index.html").write_text(
+        html_template(title, args.style, args.kind),
+        encoding="utf-8",
+    )
+    (artifact_dir / "HIGHLOGIC.md").write_text(
+        highlogic_template(title, args.style, args.kind, created_at),
+        encoding="utf-8",
+    )
+    manifest = {
+        "id": artifact_dir.name,
+        "title": title,
+        "kind": args.kind,
+        "style": args.style,
+        "created_at": created_at,
+        "entrypoint": "index.html",
+        "files": ["index.html", "HIGHLOGIC.md", "manifest.json"],
+    }
+    (artifact_dir / "manifest.json").write_text(
+        json.dumps(manifest, indent=2) + "\n",
+        encoding="utf-8",
+    )
+
+    index_path = artifact_dir / "index.html"
+    print(f"created={artifact_dir}")
+    print(f"index={index_path}")
+    print(f"url={index_path.as_uri()}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/dist/cli.js

@@ -34045,6 +34045,7 @@ var import_fs_extra8 = __toESM(require_lib4(), 1);
 import path12 from "path";
 var GENERATED_MARKER = "# Generated by aiblueprint-cli from Markdown agents.";
 var IGNORED_ENTRY_NAMES = new Set([".DS_Store", "node_modules"]);
+var DEFAULT_CODEX_SUBAGENT_MODEL = "gpt-5.6-terra";
 function parseFrontmatterValue(rawValue) {
   const value = rawValue.trim();
   if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
@@ -34105,20 +34106,27 @@ function normalizeCodexAgentName(value) {
     return `agent_${normalized}`;
   return normalized;
 }
-function mapModel(model) {
+function resolveCodexModelSettings(model) {
   switch (model?.trim().toLowerCase()) {
+    case "opus":
+      return {
+        model: DEFAULT_CODEX_SUBAGENT_MODEL,
+        reasoningEffort: "high"
+      };
     case "haiku":
-      return "gpt-5.4-mini";
     case "sonnet":
-      return "gpt-5.4";
-    case "opus":
-      return "gpt-5.5";
     case "inherit":
     case "":
     case undefined:
-      return null;
+      return {
+        model: DEFAULT_CODEX_SUBAGENT_MODEL,
+        reasoningEffort: "medium"
+      };
     default:
-      return model ?? null;
+      return {
+        model,
+        reasoningEffort: "medium"
+      };
   }
 }
 function tomlString(value) {
@@ -34158,16 +34166,15 @@ function renderToml(agent) {
     return null;
   }
   const name = normalizeCodexAgentName(rawName);
-  const model = mapModel(agent.frontmatter.model);
+  const modelSettings = resolveCodexModelSettings(agent.frontmatter.model);
   const lines = [
     GENERATED_MARKER,
     `# Source: ${agent.sourcePath}`,
     `name = ${tomlString(name)}`,
-    `description = ${tomlString(description)}`
+    `description = ${tomlString(description)}`,
+    `model = ${tomlString(modelSettings.model)}`,
+    `model_reasoning_effort = ${tomlString(modelSettings.reasoningEffort)}`
   ];
-  if (model) {
-    lines.push(`model = ${tomlString(model)}`);
-  }
   lines.push(`developer_instructions = ${tomlMultilineLiteral(buildDeveloperInstructions(agent))}`);
   lines.push("");
   return {

package/package.json

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