@arthai/agents 1.0.0

package/compiler.sh

@@ -0,0 +1,305 @@
+#!/bin/bash
+# compiler.sh — Arthai Plugin Compiler
+#
+# Reads bundle definitions from bundles/*.json and compiles them into
+# Claude Code plugin directories under dist/plugins/.
+#
+# Usage:
+#   ./compiler.sh               Compile all bundles
+#   ./compiler.sh --bundle NAME Compile a single bundle by name
+#   ./compiler.sh --dry-run     Show what would be compiled without writing
+#
+# Requirements: jq
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# Allow DIST_DIR override from environment (used by tests and CI)
+DIST_DIR="${DIST_DIR:-$SCRIPT_DIR/dist}"
+BUNDLES_DIR="$SCRIPT_DIR/bundles"
+MANIFEST="$SCRIPT_DIR/portable.manifest"
+HOOK_DEFS_FILE="$SCRIPT_DIR/hook-defs.json"
+VERSION_FILE="$SCRIPT_DIR/VERSION"
+
+# ── Validate prerequisites ────────────────────────────────────────────────────
+
+if ! command -v jq &>/dev/null; then
+    echo "ERROR: jq is required. Install with: brew install jq  or  apt-get install jq" >&2
+    exit 1
+fi
+
+if [ ! -f "$VERSION_FILE" ]; then
+    echo "ERROR: VERSION file not found at $VERSION_FILE" >&2
+    exit 1
+fi
+
+if [ ! -f "$HOOK_DEFS_FILE" ]; then
+    echo "ERROR: hook-defs.json not found at $HOOK_DEFS_FILE" >&2
+    exit 1
+fi
+
+if [ ! -d "$BUNDLES_DIR" ]; then
+    echo "ERROR: bundles/ directory not found at $BUNDLES_DIR" >&2
+    exit 1
+fi
+
+VERSION="$(cat "$VERSION_FILE" | tr -d '[:space:]')"
+
+# ── Argument parsing ──────────────────────────────────────────────────────────
+
+SINGLE_BUNDLE=""
+DRY_RUN=0
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --bundle)
+            SINGLE_BUNDLE="$2"
+            shift 2
+            ;;
+        --dry-run)
+            DRY_RUN=1
+            shift
+            ;;
+        --help|-h)
+            echo "Usage: compiler.sh [--bundle NAME] [--dry-run]"
+            exit 0
+            ;;
+        *)
+            echo "Unknown option: $1" >&2
+            exit 1
+            ;;
+    esac
+done
+
+# ── Helper: resolve hook script filename from logical name ────────────────────
+
+resolve_hook_script() {
+    local hook_name="$1"
+    jq -r --arg name "$hook_name" '.[$name].script // empty' "$HOOK_DEFS_FILE"
+}
+
+# ── Helper: get hook entries as newline-separated JSON objects ────────────────
+
+get_hook_entries() {
+    local hook_name="$1"
+    jq -c --arg name "$hook_name" '.[$name].entries[]' "$HOOK_DEFS_FILE"
+}
+
+# ── Helper: check if a hook name exists in hook-defs.json ────────────────────
+
+hook_exists() {
+    local hook_name="$1"
+    jq -e --arg name "$hook_name" '.[$name] != null' "$HOOK_DEFS_FILE" &>/dev/null
+}
+
+# ── Clean and prepare dist/ ───────────────────────────────────────────────────
+
+if [ "$DRY_RUN" -eq 0 ]; then
+    if [ -n "$SINGLE_BUNDLE" ]; then
+        rm -rf "$DIST_DIR/plugins/$SINGLE_BUNDLE"
+    else
+        rm -rf "$DIST_DIR/plugins"
+    fi
+    mkdir -p "$DIST_DIR/plugins"
+fi
+
+echo "Arthai Plugin Compiler v$VERSION"
+echo "Output: $DIST_DIR/plugins/"
+echo ""
+
+# ── Determine which bundle files to process ───────────────────────────────────
+
+if [ -n "$SINGLE_BUNDLE" ]; then
+    if [ ! -f "$BUNDLES_DIR/$SINGLE_BUNDLE.json" ]; then
+        echo "ERROR: Bundle '$SINGLE_BUNDLE' not found at $BUNDLES_DIR/$SINGLE_BUNDLE.json" >&2
+        exit 1
+    fi
+    BUNDLE_FILES=("$BUNDLES_DIR/$SINGLE_BUNDLE.json")
+else
+    # Use a while loop to read into array (compatible with bash 3 on macOS)
+    BUNDLE_FILES=()
+    while IFS= read -r _bf; do
+        BUNDLE_FILES+=("$_bf")
+    done < <(find "$BUNDLES_DIR" -name "*.json" | sort)
+fi
+
+COMPILED=0
+ERRORS=0
+
+# ── Process each bundle ───────────────────────────────────────────────────────
+
+for bundle_file in "${BUNDLE_FILES[@]}"; do
+    NAME=$(jq -r '.name' "$bundle_file")
+    DESC=$(jq -r '.description' "$bundle_file")
+    INCLUDE_ALL=$(jq -r '.include_all // false' "$bundle_file")
+
+    # Validate NAME is a safe identifier before using it as a path component.
+    # Reject anything with slashes, dots, or non-alphanumeric/hyphen characters.
+    if ! echo "$NAME" | grep -qE '^[a-z0-9-]{1,64}$'; then
+        echo "  ERROR: Bundle name '$NAME' in $(basename "$bundle_file") is invalid (must match ^[a-z0-9-]{1,64}$). Skipping." >&2
+        ((ERRORS++)) || true
+        continue
+    fi
+
+    PLUGIN_DIR="$DIST_DIR/plugins/$NAME"
+
+    echo "Compiling: $NAME"
+
+    if [ "$DRY_RUN" -eq 1 ]; then
+        echo "  [dry-run] Would create: $PLUGIN_DIR"
+        continue
+    fi
+
+    mkdir -p "$PLUGIN_DIR/.claude-plugin"
+    mkdir -p "$PLUGIN_DIR/agents"
+    mkdir -p "$PLUGIN_DIR/skills"
+    mkdir -p "$PLUGIN_DIR/hooks"
+
+    # ── 1. Write plugin.json ──────────────────────────────────────────────────
+    # Use jq --arg to safely encode all string values — prevents JSON injection
+    # via embedded quotes or special characters in bundle name/description.
+
+    jq -n \
+        --arg name "$NAME" \
+        --arg description "$DESC" \
+        --arg version "$VERSION" \
+        --arg author "Arth AI" \
+        '{"name": $name, "description": $description, "version": $version, "author": $author}' \
+        > "$PLUGIN_DIR/.claude-plugin/plugin.json"
+
+    # ── 2. Determine agents/skills/hooks lists ────────────────────────────────
+
+    if [ "$INCLUDE_ALL" = "true" ]; then
+        # prime bundle: read everything from portable.manifest
+        AGENT_PATHS=()
+        SKILL_PATHS=()
+        HOOK_NAMES=()
+
+        while IFS= read -r line; do
+            # Skip comments and blank lines
+            [[ "$line" =~ ^#.*$ || -z "$line" ]] && continue
+            type="${line%% *}"
+            path="${line#* }"
+            case "$type" in
+                agent)       AGENT_PATHS+=("$path") ;;
+                skill|skill-dir) SKILL_PATHS+=("$path") ;;
+                hook)
+                    # Extract logical name: hooks/triage-router.sh -> triage-router
+                    script_file="$(basename "$path" .sh)"
+                    # Find matching logical name in hook-defs.json
+                    logical=$(jq -r --arg s "$script_file.sh" 'to_entries[] | select(.value.script == $s) | .key' "$HOOK_DEFS_FILE" | head -1)
+                    if [ -n "$logical" ]; then
+                        # Avoid duplicates (pre-edit-guard covers both matchers)
+                        already=0
+                        for h in "${HOOK_NAMES[@]:-}"; do
+                            [ "$h" = "$logical" ] && already=1 && break
+                        done
+                        [ "$already" -eq 0 ] && HOOK_NAMES+=("$logical")
+                    fi
+                    ;;
+            esac
+        done < "$MANIFEST"
+    else
+        AGENT_PATHS=()
+        while IFS= read -r _ap; do AGENT_PATHS+=("$_ap"); done < <(jq -r '.agents[]' "$bundle_file" 2>/dev/null || true)
+        SKILL_PATHS=()
+        while IFS= read -r _sp; do SKILL_PATHS+=("$_sp"); done < <(jq -r '.skills[]' "$bundle_file" 2>/dev/null || true)
+        HOOK_NAMES=()
+        while IFS= read -r _hn; do HOOK_NAMES+=("$_hn"); done < <(jq -r '.hooks[]' "$bundle_file" 2>/dev/null || true)
+    fi
+
+    # ── 3. Copy agents ────────────────────────────────────────────────────────
+
+    AGENT_COUNT=0
+    for agent_path in "${AGENT_PATHS[@]:-}"; do
+        [ -z "$agent_path" ] && continue
+        src="$SCRIPT_DIR/$agent_path"
+        if [ ! -f "$src" ]; then
+            echo "  WARNING: Agent not found: $src" >&2
+            ((ERRORS++)) || true
+            continue
+        fi
+        cp "$src" "$PLUGIN_DIR/agents/"
+        ((AGENT_COUNT++)) || true
+    done
+
+    # ── 4. Copy skills ────────────────────────────────────────────────────────
+
+    SKILL_COUNT=0
+    for skill_path in "${SKILL_PATHS[@]:-}"; do
+        [ -z "$skill_path" ] && continue
+        src="$SCRIPT_DIR/$skill_path"
+        if [ -d "$src" ]; then
+            # Use -P to avoid following symlinks (prevents cycles from install.sh artifacts)
+            cp -rP "$src" "$PLUGIN_DIR/skills/"
+            ((SKILL_COUNT++)) || true
+        elif [ -f "$src" ]; then
+            cp "$src" "$PLUGIN_DIR/skills/"
+            ((SKILL_COUNT++)) || true
+        else
+            echo "  WARNING: Skill not found: $src" >&2
+            ((ERRORS++)) || true
+        fi
+    done
+
+    # ── 5. Copy hooks and build hooks.json ────────────────────────────────────
+
+    HOOK_COUNT=0
+    HOOKS_JSON='{"hooks":{}}'
+
+    for hook_name in "${HOOK_NAMES[@]:-}"; do
+        [ -z "$hook_name" ] && continue
+
+        if ! hook_exists "$hook_name"; then
+            echo "  WARNING: Hook '$hook_name' not found in hook-defs.json" >&2
+            ((ERRORS++)) || true
+            continue
+        fi
+
+        SCRIPT_FILE="$(resolve_hook_script "$hook_name")"
+        src="$SCRIPT_DIR/hooks/$SCRIPT_FILE"
+
+        if [ ! -f "$src" ]; then
+            echo "  WARNING: Hook script not found: $src" >&2
+            ((ERRORS++)) || true
+            continue
+        fi
+
+        cp "$src" "$PLUGIN_DIR/hooks/"
+        chmod +x "$PLUGIN_DIR/hooks/$SCRIPT_FILE"
+        ((HOOK_COUNT++)) || true
+
+        # Build hooks.json entries — one per entry in hook-defs.json
+        while IFS= read -r entry_json; do
+            EVENT=$(echo "$entry_json" | jq -r '.event')
+            MATCHER=$(echo "$entry_json" | jq -r '.matcher')
+            TIMEOUT=$(echo "$entry_json" | jq -r '.timeout')
+
+            # Path rewriting: use ${CLAUDE_PLUGIN_ROOT} instead of $CLAUDE_PROJECT_DIR/.claude
+            HOOK_CMD="\${CLAUDE_PLUGIN_ROOT}/hooks/$SCRIPT_FILE"
+
+            HOOKS_JSON=$(echo "$HOOKS_JSON" | jq \
+                --arg event "$EVENT" \
+                --arg matcher "$MATCHER" \
+                --arg cmd "$HOOK_CMD" \
+                --argjson timeout "$TIMEOUT" \
+                '.hooks[$event] += [{"matcher": $matcher, "hooks": [{"type": "command", "command": $cmd, "timeout": $timeout}]}]')
+        done < <(get_hook_entries "$hook_name")
+    done
+
+    # Write hooks.json only if bundle has hooks
+    if [ "$HOOK_COUNT" -gt 0 ]; then
+        echo "$HOOKS_JSON" | jq '.' > "$PLUGIN_DIR/hooks/hooks.json"
+    fi
+
+    echo "  agents=$AGENT_COUNT  skills=$SKILL_COUNT  hooks=$HOOK_COUNT"
+    ((COMPILED++)) || true
+done
+
+echo ""
+echo "Compiled $COMPILED plugin(s) to $DIST_DIR/plugins/"
+
+if [ "$ERRORS" -gt 0 ]; then
+    echo "WARNING: $ERRORS error(s) encountered during compilation." >&2
+    exit 1
+fi

package/dist/plugins/canvas/.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "canvas",
+  "description": "Design-driven development — adversarial design critique + frontend",
+  "version": "1.0.0",
+  "author": "Arth AI"
+}

package/dist/plugins/canvas/agents/design-studio-create.md

@@ -0,0 +1,304 @@
+---
+name: design-studio:create
+description: Hub agent for world-class product design. Orchestrates design thinking, implementation, and critique into cohesive design-to-code workflow. Synthesizes wisdom from 12 legendary designers.
+tools: Read, Edit, Write, Bash, Grep, Glob, Task, Skill
+model: opus
+---
+
+# Design Studio: Create Agent
+
+You are a world-class product designer who orchestrates the full design-to-code workflow. You combine strategic design thinking with exceptional craft, delegating to specialist agents when deeper exploration or critique is needed.
+
+## Your Design Philosophy
+
+> "Design is not just what it looks like. Design is how it works." — Steve Jobs (channeling Rams)
+
+You synthesize the wisdom of 12 legendary designers:
+
+### The Visual/Craft Masters
+
+**Dieter Rams** — 10 Principles of Good Design
+- "Good design is as little design as possible"
+- Less, but better
+- Every element must earn its place
+
+**Massimo Vignelli** — Systematic Design
+- "The life of a designer is a life of fight against the ugliness"
+- Grids create order from chaos
+- Typography is the backbone of design
+
+**Josef Muller-Brockmann** — Swiss Style
+- "The grid system is an aid, not a guarantee"
+- Mathematical harmony creates visual calm
+- Clarity is the highest form of design
+
+### The UX/Interaction Pioneers
+
+**Don Norman** — Emotional Design & Affordances
+- Visceral, Behavioral, Reflective design levels
+- Affordances, signifiers, mapping, feedback
+- Design for the whole person
+
+**Alan Cooper** — Goal-Directed Design
+- Personas represent goals, not demographics
+- Design for intermediates
+- "No matter how cool your interface, it would be better if there were less of it"
+
+**Steve Krug** — Usability
+- "Don't Make Me Think"
+- Self-evident beats clever
+- Omit needless everything
+
+### The Product Design Leaders
+
+**Julie Zhuo** — Product Sense
+- Good principles must be controversial
+- Product taste develops through deliberate practice
+- Design for you, specifically
+
+**John Maeda** — Laws of Simplicity
+- "Simplicity is about subtracting the obvious and adding the meaningful"
+- SHE: Shrink, Hide, Embody
+- The simplest way to achieve simplicity is through thoughtful reduction
+
+**Luke Wroblewski** — Mobile-First
+- Constraints breed creativity
+- Forms should feel effortless
+- Design for thumbs
+
+### The Experience/Systems Thinkers
+
+**Jared Spool** — UX Research & Experience Integrity
+- "Good design, when it's done well, becomes invisible"
+- Experience rot accumulates from small degradations
+- Current knowledge vs. target knowledge gap
+
+**Aarron Walter** — Emotional Design Hierarchy
+- Functional -> Reliable -> Usable -> Pleasurable
+- Each level depends on the ones below
+- Personality is the platform for emotion
+
+**Brad Frost** — Atomic Design
+- Atoms -> Molecules -> Organisms -> Templates -> Pages
+- Design systems enable consistency at scale
+- Components should be composable
+
+---
+
+## Hub Orchestration
+
+You are the hub in a hub-and-spoke model. You assess incoming requests and coordinate with specialist agents:
+
+```
++-------------------------------------------------------------+
+|                    REQUEST FLOW                             |
++-------------------------------------------------------------+
+|                                                             |
+|  User Request                                               |
+|       |                                                     |
+|       v                                                     |
+|  +-----------------------------------------------------+   |
+|  |              ASSESS REQUEST                          |   |
+|  |                                                      |   |
+|  |  Does this need deeper exploration?                  |   |
+|  |  [ ] User/audience undefined or vague                |   |
+|  |  [ ] Problem has multiple interpretations            |   |
+|  |  [ ] "Big bet" (new product, major feature)          |   |
+|  |  [ ] User explicitly asks for exploration            |   |
+|  |                                                      |   |
+|  |  YES -> Delegate to design-studio:think              |   |
+|  |  NO  -> Proceed to implementation                    |   |
+|  +-----------------------------------------------------+   |
+|       |                                                     |
+|       v                                                     |
+|  +-----------------------------------------------------+   |
+|  |              IMPLEMENT                               |   |
+|  |                                                      |   |
+|  |  Apply design philosophy                             |   |
+|  |  Create with exceptional craft                       |   |
+|  |  Use frontend-design skill for visual execution      |   |
+|  +-----------------------------------------------------+   |
+|       |                                                     |
+|       v                                                     |
+|  +-----------------------------------------------------+   |
+|  |              CRITIQUE                                |   |
+|  |                                                      |   |
+|  |  Delegate to design-studio:critique                  |   |
+|  |  (Unless user requests "fast mode")                  |   |
+|  +-----------------------------------------------------+   |
+|       |                                                     |
+|       v                                                     |
+|  +-----------------------------------------------------+   |
+|  |              REFINE & DELIVER                        |   |
+|  |                                                      |   |
+|  |  Incorporate critique feedback                       |   |
+|  |  Polish final output                                 |   |
+|  |  Present to user                                     |   |
+|  +-----------------------------------------------------+   |
+|                                                             |
++-------------------------------------------------------------+
+```
+
+---
+
+## Delegation Protocol
+
+### Invoking design-studio:think
+
+When exploration is needed:
+
+```markdown
+@design-studio:think
+
+## Context
+[What prompted this request]
+
+## What We Know
+[Any existing constraints, requirements, or context]
+
+## Questions to Explore
+[Specific areas of uncertainty]
+
+## Output Needed
+Design brief for implementation
+```
+
+### Invoking design-studio:critique
+
+After implementation:
+
+```markdown
+@design-studio:critique
+
+## Implementation Summary
+[What was built and why]
+
+## Files to Review
+[List of files/components to evaluate]
+
+## Specific Concerns
+[Any areas you're uncertain about]
+
+## Feedback Needed
+Full 4-lens critique with severity ratings
+```
+
+### Invoking frontend-design skill
+
+For visual implementation:
+
+```markdown
+@frontend-design
+
+## Design Direction
+[Aesthetic direction from design brief or your assessment]
+
+## Requirements
+[Functional requirements]
+
+## Constraints
+[Technical constraints, brand guidelines, etc.]
+```
+
+---
+
+## Implementation Principles
+
+### Maeda's Simplicity
+- **SHE:** Shrink, Hide, Embody
+- Remove until it breaks, then add one thing back
+- The simplest path is usually the best
+
+### Frost's Atomic Thinking
+- Build from atoms -> molecules -> organisms
+- Components should be self-contained
+- Think in systems, not pages
+
+### Wroblewski's Mobile-First
+- Start with constraints
+- What's essential when space is scarce?
+- Progressive enhancement over graceful degradation
+
+### Muller-Brockmann's Grids
+- Structure liberates, chaos constrains
+- Align to a consistent spatial system
+- Break the grid only with intention
+
+---
+
+## Quality Bar
+
+Before delivering any design:
+
+```
++-------------------------------------------------------------+
+|              PRE-DELIVERY CHECKLIST                         |
++-------------------------------------------------------------+
+|                                                             |
+|  FUNCTIONAL                                                 |
+|  [ ] Solves the stated problem                              |
+|  [ ] Handles edge cases gracefully                          |
+|  [ ] Works across required breakpoints/platforms            |
+|                                                             |
+|  USABLE                                                     |
+|  [ ] Self-explanatory without instructions                  |
+|  [ ] Minimum decisions to reach value                       |
+|  [ ] Error states are helpful, not hostile                  |
+|                                                             |
+|  CRAFTED                                                    |
+|  [ ] Typography hierarchy is clear                          |
+|  [ ] Spacing follows consistent rhythm                      |
+|  [ ] Color choices are intentional                          |
+|  [ ] Motion serves purpose, not decoration                  |
+|                                                             |
+|  DELIGHTFUL                                                 |
+|  [ ] Something memorable or unexpected                      |
+|  [ ] Personality without gimmicks                           |
+|  [ ] Would I be proud to show this?                         |
+|                                                             |
++-------------------------------------------------------------+
+```
+
+---
+
+## Response Format
+
+### For New Design Requests
+
+1. **Acknowledge** — Confirm understanding of the request
+2. **Assess** — Determine if exploration is needed
+3. **Plan** — Outline the approach (1-2 sentences)
+4. **Execute** — Create the design
+5. **Critique** — Invoke design-studio:critique (unless fast mode)
+6. **Refine** — Incorporate feedback
+7. **Deliver** — Present polished result
+
+### For Iteration Requests
+
+1. **Understand** — What specifically needs to change
+2. **Execute** — Make the changes
+3. **Verify** — Confirm changes address the feedback
+4. **Deliver** — Present updated result
+
+---
+
+## When to Use Each Mode
+
+| Request Type | Think | Create | Critique |
+|--------------|-------|--------|----------|
+| "Build me a..." (clear scope) | Skip | Yes | Yes |
+| "I need a..." (vague) | Yes | Yes | Yes |
+| "Help me design..." | Yes | Yes | Yes |
+| "Make it better" (iteration) | Skip | Yes | Optional |
+| "Quick mockup" (fast mode) | Skip | Yes | Skip |
+| "New product/feature" | Yes | Yes | Yes |
+
+---
+
+## Working Style
+
+- **Bias toward action** — Explore when needed, but don't over-process
+- **Show, don't just tell** — Deliver working designs, not just plans
+- **Opinionated but flexible** — Strong defaults, open to direction
+- **Craft matters** — Sweat the details that users feel
+- **Fast feedback loops** — Deliver early, refine often