@arthai/agents 1.0.0

package/skills/sync/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: sync
+description: "Sync claude-agents tooling. Usage: /sync (pull latest), /sync status, /sync push <path> (contribute back)"
+user-invocable: true
+---
+
+# /sync — Claude Agents Sync
+
+Manage the shared claude-agents tooling between your project and the central repo.
+
+## Commands
+
+### `/sync` (no args) — Pull & re-sync
+
+Pull the latest from `~/.claude-agents/` and re-sync symlinks into the current project.
+
+Steps:
+1. `cd ~/.claude-agents && git pull --ff-only`
+2. Run `~/.claude-agents/install.sh` on the current project directory
+3. Report what was created, updated, or skipped
+
+### `/sync status` — Show status
+
+Run `~/.claude-agents/install.sh --status` on the current project directory.
+Report which files are symlinked, overridden, or missing.
+
+### `/sync push <target>` — Contribute back
+
+Push a modified agent, skill, or hook from the current project back to `~/.claude-agents/`.
+
+The `<target>` can be:
+- A name: `/sync push pr`, `/sync push onboard`, `/sync push ops`
+- A path: `/sync push skills/pr/SKILL.md`, `/sync push agents/ops.md`
+- Omitted: `/sync push` — auto-detect what changed (see step 1)
+
+#### Step 1: Resolve the target to a file path
+
+| Target | How to resolve |
+|--------|---------------|
+| No target given | Run `git diff --name-only HEAD` in the project repo. Filter for `.claude/agents/`, `.claude/skills/`, `.claude/hooks/`. If multiple, ask user which one. |
+| A name (e.g., `pr`) | Search for it: `.claude/skills/<name>/SKILL.md`, `.claude/agents/<name>.md`, `.claude/hooks/<name>.sh` — use the first that exists as a regular file (not symlink). |
+| A path (e.g., `skills/pr/SKILL.md`) | Prepend `.claude/` if needed → `.claude/skills/pr/SKILL.md` |
+
+The resolved path must be a **regular file** (not a symlink). If it's a symlink pointing to `~/.claude-agents/`, tell the user: "This file is managed by claude-agents. Edit it directly at `~/.claude-agents/<path>` instead."
+
+#### Step 2: Determine the item type and destination
+
+| Source path pattern | Type | Destination in claude-agents |
+|--------------------|------|------------------------------|
+| `.claude/agents/<name>.md` | agent | `agents/<name>.md` |
+| `.claude/skills/<name>/SKILL.md` | skill | `skills/<name>/SKILL.md` |
+| `.claude/skills/<name>/` (directory) | skill-dir | `skills/<name>/` |
+| `.claude/hooks/<name>.sh` | hook | `hooks/<name>.sh` |
+
+#### Step 3: Check for project-specific content
+
+Read the file. Warn if it contains hardcoded paths (`/Users/`, `~/prepme`), project-specific env vars, service names, or URLs. Ask user to clean up or proceed.
+
+#### Step 4: Copy and commit
+
+```bash
+# Determine branch name
+# If destination exists in claude-agents → update/<name>
+# If new → add/<name>
+BRANCH="update/<name>"  # or add/<name>
+
+cd ~/.claude-agents
+git checkout -b "$BRANCH"
+
+# Copy from project to toolkit
+cp <source> <destination>            # single file
+cp -r <source-dir> <destination-dir> # directory
+
+# If new item, add to manifest
+grep -q "<relative-path>" portable.manifest || echo "<type> <relative-path>" >> portable.manifest
+```
+
+#### Step 4b: Register new hooks in install.sh (HOOKS ONLY)
+
+**If the item type is `hook` AND it is a NEW hook** (not already in install.sh), you MUST register it in `install.sh`. Skipping this will cause the `15-manifest-coverage` CI test to fail.
+
+**4b.1: Detect hook metadata from the script**
+
+Read the first 10 lines of the hook script. Look for a comment declaring the hook type:
+- `# SessionEnd hook` → event: `SessionEnd`, matcher: `""`
+- `# SessionStart hook` → event: `SessionStart`, matcher: `""`
+- `# UserPromptSubmit hook` → event: `UserPromptSubmit`, matcher: `""`
+- `# PreToolUse hook (Bash)` → event: `PreToolUse`, matcher: `"Bash"`
+- `# PreToolUse hook (Edit)` → event: `PreToolUse`, matcher: `"Edit"`
+- `# PostToolUse hook (Bash)` → event: `PostToolUse`, matcher: `"Bash"`
+- Pattern: `# <Event> hook` or `# <Event> hook (<Matcher>)`
+
+If no event comment is found, the hook is a **helper script** (called by other hooks, not by Claude Code directly). Helper scripts only need steps 4b.2 and 4b.3 — skip 4b.4, 4b.5, and 4b.6.
+
+**4b.2: Determine the category**
+
+Ask the user which category. Common mappings:
+- `hooks` — routing, delegation, worktree sync (e.g., triage-router, sync-worktree, session-end)
+- `guardrails` — safety guards, linting, bootstrap (e.g., pre-bash-guard, post-edit-lint, session-bootstrap)
+- `core` — sync infrastructure (e.g., sync-agents)
+- `railway` — Railway-specific (e.g., sync-railway-worktree)
+
+**4b.3: Edit `get_category_items()` in install.sh**
+
+Find the case branch for the chosen category and append `hooks/<name>.sh` to the echo string.
+
+Example — adding `session-end.sh` to the `hooks` category:
+```
+# Before:
+hooks)
+    echo "hooks/triage-router.sh hooks/sync-worktree.sh"
+    ;;
+
+# After:
+hooks)
+    echo "hooks/triage-router.sh hooks/sync-worktree.sh hooks/session-end.sh"
+    ;;
+```
+
+Also update `get_category_label()` to increment the count, and `get_category_desc()` to mention the new hook.
+
+**4b.4: Edit `get_category_hooks()` in install.sh** (settings.json hooks only)
+
+Add the hook name (without `hooks/` prefix and `.sh` suffix) to the category's echo string.
+
+Example:
+```
+# Before:
+hooks)      echo "triage-router" ;;
+
+# After:
+hooks)      echo "triage-router session-end" ;;
+```
+
+**4b.5: Add to `HOOK_DEFS` in install.sh**
+
+Find the `HOOK_DEFS = {` Python dict (inside the `merge_settings_hooks` heredoc) and add a new entry before the closing `}`. Use `$CLAUDE_PROJECT_DIR/.claude/hooks/<name>.sh` as the command path. Set timeout to 15 for session hooks, 5 for tool hooks.
+
+Example entry:
+```python
+    "session-end": {
+        "event": "SessionEnd",
+        "entry": {
+            "matcher": "",
+            "hooks": [{
+                "type": "command",
+                "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/session-end.sh",
+                "timeout": 15
+            }]
+        },
+        "fingerprint": "session-end.sh"
+    }
+```
+
+**4b.6: Add to uninstall fallback list**
+
+Find the `hooks_to_remove=` fallback string in `handle_uninstall()` and add the hook name.
+
+#### Step 4c: Commit and push
+
+```bash
+git add <destination> portable.manifest install.sh
+git commit -m "feat: add <name> hook with install.sh registration"
+git push -u origin "$BRANCH"
+gh pr create --title "Add <name> hook" --body "Contributed from <project> repo"
+
+# Return to previous branch
+git checkout -
+```
+
+#### Step 5: Report the PR URL
+
+### `/sync setup` — Re-run interactive setup
+
+Re-run the interactive category selection menu for the current project.
+
+Steps:
+1. Run `~/.claude-agents/install.sh --setup` on the current project directory
+2. The menu will show with current selections pre-populated
+3. User can add or remove categories
+4. Report what changed
+
+## Important Rules
+
+- **Never push directly to main** in claude-agents — always branch + PR
+- **Always check for project-specific content** before contributing
+- **After PR merges**, the file will auto-sync to all projects on next session start
+- The original file in the project stays as a regular file until the next sync converts it to a symlink

package/skills/templates/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: templates
+description: "Generate structured deliverables from templates. Usage: /templates <type> <topic>"
+user-invocable: true
+arguments: "<type> <topic>"
+---
+
+Provides structured templates for common non-engineering deliverables. Each template
+produces a professional, outcome-focused document by bringing in the right specialist.
+
+## Argument Parsing
+
+| Input | Action |
+|---|---|
+| `/templates` | Show selection menu |
+| `/templates product-brief` | Ask for topic, then generate product brief |
+| `/templates product-brief notifications` | Generate product brief for "notifications" |
+| `/templates launch-plan` | Ask for topic, then generate launch plan |
+| `/templates launch-plan dark-mode` | Generate launch plan for "dark-mode" |
+| `/templates status-report` | Generate status report immediately (reads project data automatically) |
+| `/templates design-critique` | Ask what to critique, then generate critique |
+| `/templates design-critique login-page` | Generate design critique for "login-page" |
+| `/templates meeting-briefing` | Ask for meeting topic, then generate pre-meeting briefing |
+| `/templates meeting-briefing sprint-planning` | Generate briefing for "sprint-planning" meeting |
+| `/templates blog-post` | Ask for topic, then generate blog post |
+| `/templates blog-post launch-announcement` | Generate blog post about "launch-announcement" |
+| `/templates user-persona` | Ask for research data source, then generate persona |
+| `/templates user-persona pm-users` | Generate persona for "pm-users" from available data |
+
+## Selection Menu
+
+If no type is provided, present this menu using AskUserQuestion:
+
+```
+What would you like to create?
+  1. Product brief — Define a feature or product for your team
+  2. Launch plan — Plan how to bring something to market
+  3. Status report — Summarize project progress for stakeholders
+  4. Design critique — Evaluate a design against proven principles
+  5. Meeting briefing — Prepare for an upcoming meeting with project context
+  6. Blog post — Write a blog post grounded in your product's real capabilities
+  7. User persona — Generate behavior-based personas from research data
+
+Just type a number or the template name.
+```
+
+## Template Definitions
+
+### 1. Product Brief
+
+**Purpose:** Define a feature or product so the team understands what to build and why.
+
+**Execution:** Spawn the `product-manager` agent with this prompt:
+
+> Write a product brief for: {topic}
+>
+> Read the project's CLAUDE.md for context. Structure the brief with these sections:
+> - **Problem statement** — What pain point does this solve? Who feels it?
+> - **Target user** — Who specifically benefits? Be concrete.
+> - **Desired outcome** — What does success look like from the user's perspective?
+> - **Success metrics** — How will we measure if this worked? (2-3 metrics)
+> - **Scope** — What is included and what is explicitly excluded?
+> - **Open questions** — What do we still need to figure out?
+>
+> Write in plain language. No jargon. Focus on outcomes, not implementation details.
+> Keep it under 500 words.
+
+### 2. Launch Plan
+
+**Purpose:** Plan how to bring a feature or product to market.
+
+**Execution:** Spawn the `gtm-expert` agent with this prompt:
+
+> Write a launch plan for: {topic}
+>
+> Read the project's CLAUDE.md for context. Structure the plan with these sections:
+> - **What is launching** — One-paragraph summary
+> - **Who it is for** — Target audience with specifics
+> - **Positioning** — One sentence: "For [who] who [need], [product] is [category] that [benefit]"
+> - **Channels** — Where and how to reach the audience (3-5 channels, prioritized)
+> - **Timeline** — Week-by-week plan for the first 4 weeks
+> - **Success metrics** — How we know the launch worked (2-3 metrics)
+> - **Risks** — What could go wrong and how to mitigate (2-3 risks)
+>
+> Write in plain language. Be specific and actionable, not generic.
+> Keep it under 600 words.
+
+### 3. Status Report
+
+**Purpose:** Summarize project progress for stakeholders who don't read code.
+
+**Execution:** Spawn the `stakeholder-reporter` agent with this prompt:
+
+> Generate a project status report.
+>
+> Read git history, open PRs, merged PRs, and open issues to produce
+> a plain-English summary of project health. Follow your report format exactly.
+> If a topic or scope was specified, focus on: {topic}
+
+This template requires no input from the user — the agent reads project data automatically.
+
+### 4. Design Critique
+
+**Purpose:** Evaluate a design against proven principles and provide actionable feedback.
+
+**Execution:** Ask the user what to critique if not provided (URL, screenshot path, or description).
+Then spawn the `design-studio-critique` agent with this prompt:
+
+> Critique this design: {topic/input}
+>
+> Structure your critique with these sections:
+> - **Design intent** — What is this design trying to accomplish?
+> - **First impressions** — What works well at first glance?
+> - **Principles evaluation** — Evaluate against Dieter Rams' 10 principles for good design
+> - **Accessibility notes** — Any concerns for users with different abilities?
+> - **Recommendations** — Specific, actionable improvements (prioritized, top 3-5)
+>
+> Write for a non-technical audience. Explain design concepts in plain language.
+> Be constructive — lead with what works before suggesting changes.
+
+### 5. Meeting Briefing
+
+**Purpose:** Prepare for an upcoming meeting with relevant project context and suggested talking points.
+
+**Execution:** Spawn the `meeting-prep` agent with this prompt:
+
+> Generate a pre-meeting briefing for: {topic}
+>
+> Read git history, open PRs, merged PRs, and open issues to gather relevant project context.
+> Classify the meeting type (daily check-in, weekly tactical, monthly strategic, 1:1, or decision meeting).
+> Structure the briefing with: What You Need to Know, What Shipped Recently, What's In Progress,
+> Open Questions for This Meeting, and Suggested Talking Points.
+> Keep it under 500 words. Write in plain language — no engineering jargon.
+
+### 6. Blog Post
+
+**Purpose:** Create a compelling blog post grounded in the product's real capabilities and codebase context.
+
+**Execution:** Spawn the `content-strategist` agent with this prompt:
+
+> Write a blog post about: {topic}
+>
+> Read the project's CLAUDE.md, README.md, and recent git history for context.
+> Ground all claims in real product capabilities — read the actual code if needed.
+> Structure with these sections:
+> - **Headline** — Specific promise, not generic ("How We Cut Deploy Times by 37%" not "Improving Deployments")
+> - **Hook** — Opening that earns the reader's next 30 seconds
+> - **Body** — 3-5 key points with specific examples and data
+> - **Takeaway** — What the reader should do with this information
+> - **CTA** — One clear next step
+>
+> Write for a non-technical audience unless the topic is explicitly technical.
+> Aim for 800-1200 words. Use the PAS or AIDA framework as appropriate.
+
+### 7. User Persona
+
+**Purpose:** Generate behavior-based personas from research data (interview notes, support tickets, survey responses, or product analytics).
+
+**Execution:** Ask the user for research data source if not provided (file path, paste notes, or description of users).
+Then spawn the `user-researcher` agent with this prompt:
+
+> Generate behavior-based user personas from: {topic/input}
+>
+> If research data is provided, synthesize it into personas. If a user segment is described,
+> use available project context (issues, PRs, README) to infer behavioral patterns.
+> Structure each persona with:
+> - **Persona name** — Descriptive verb phrase (e.g., "The Rapid Prototyper"), not a demographic label
+> - **Behavior pattern** — What they do, how often, what tools they use
+> - **Motivation** — Functional, emotional, and social jobs (JTBD)
+> - **Current pain** — Top frustration, workaround, cost
+> - **Trigger** — What prompts them to act
+> - **Success looks like** — Desired outcome in their words
+>
+> Generate 3-5 personas max. Every claim must be grounded in observed behavior, not assumptions.
+
+## Post-Template Flow
+
+After every template output, always present these next steps:
+
+```
+What next?
+  - "share this" to format for your team
+  - "revise [section]" to change something
+  - "try another template" to create a different deliverable
+```
+
+## Rules
+
+- Never show agent names, model names, or cost tiers to the user
+- Say "bringing in a specialist" if you need to explain what is happening, not "spawning the product-manager agent"
+- All output must be jargon-free — translate engineering terms to plain language
+- If the user provides a topic inline, skip the question and go straight to generation
+- Always offer "share this" as a next step (enables the /share skill viral loop)
+- If an agent is unavailable, explain what happened in plain English and suggest an alternative

package/skills/welcome/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: welcome
+description: "Role-aware welcome for non-engineers. Presents intent-based menu instead of blank terminal. Usage: /welcome"
+user-invocable: true
+arguments: ""
+---
+
+# Welcome Skill — Role-Based Intent Router
+
+Presents a role-appropriate welcome screen when a non-engineer opens Claude Code.
+Replaces the blank terminal with a clear, outcome-oriented menu.
+
+**Design principles:**
+- Speak in outcomes, not mechanisms ("Plan a feature" not "Spawn a planning team")
+- Progressive disclosure — show 4-5 options, not 18 agents
+- No jargon — no "agents," "skills," "hooks," "symlinks," or model names
+- The system picks the right specialist; the user describes what they want
+
+## Execution Steps
+
+### 1. Detect Role
+
+Check the project's `.claude/.claude-agents.conf` for `USER_ROLE`. If present, use it.
+If not present, check these signals:
+- If `.claude/agents/gtm-expert.md` exists but no QA agents → likely PM/founder/marketer
+- If design-studio agents exist but no backend agents → likely designer
+- If all agents exist → likely engineer (fall through to /onboard)
+
+If role cannot be determined, ask using AskUserQuestion:
+- "What's your role on this team?"
+- Options: Product Manager, Founder, Designer, Marketer, Operations, Engineer
+
+Store the role in `.claude/.claude-agents.conf` as `USER_ROLE="<role>"` for future sessions.
+
+### 2. Present Role-Based Menu
+
+Based on the detected role, present a welcome screen using AskUserQuestion.
+
+**For Product Managers (`pm`):**
+
+Question: "What would you like to do?"
+Options:
+1. "Plan a feature" — description: "Describe a feature and get a full product brief + architecture plan"
+2. "Check project status" — description: "See what the team is working on, open PRs, and issues"
+3. "Create or review an issue" — description: "Create a GitHub issue or review existing ones"
+4. "Something else" — description: "Describe what you need in plain English"
+
+**For Founders (`founder`):**
+
+Question: "What would you like to do?"
+Options:
+1. "Plan a feature or strategy" — description: "Get a product plan, GTM strategy, or architecture review"
+2. "Check project status" — description: "Full briefing: PRs, issues, deployments, team activity"
+3. "Review positioning or GTM" — description: "Analyze market positioning, competitive landscape, or launch strategy"
+4. "Something else" — description: "Describe what you need in plain English"
+
+**For Designers (`designer`):**
+
+Question: "What would you like to do?"
+Options:
+1. "Design thinking session" — description: "Explore UX goals, user journeys, and design direction"
+2. "Get a design critique" — description: "Review a design against established principles (Rams, Norman, Vignelli)"
+3. "Plan a UI feature" — description: "Get a design brief + architecture plan for a UI change"
+4. "Something else" — description: "Describe what you need in plain English"
+
+**For Marketers (`marketer`):**
+
+Question: "What would you like to do?"
+Options:
+1. "Create a launch strategy" — description: "Full GTM plan: positioning, channels, growth loops, launch brief"
+2. "Analyze positioning" — description: "Positioning canvas, competitive analysis, category definition"
+3. "Plan content or campaign" — description: "Content strategy informed by what the product actually does"
+4. "Something else" — description: "Describe what you need in plain English"
+
+**For Ops/Project Managers (`ops`):**
+
+Question: "What would you like to do?"
+Options:
+1. "Check project status" — description: "PRs, issues, CI status, deployment health"
+2. "Triage open issues" — description: "Prioritize and assign open issues"
+3. "Review recent changes" — description: "What shipped recently, what's in progress"
+4. "Something else" — description: "Describe what you need in plain English"
+
+**For Engineers or unknown roles:**
+Fall through to `/onboard` — the existing onboarding skill handles engineers well.
+
+### 3. Route Based on Choice
+
+Map the user's selection to the appropriate action:
+
+| Selection | Route to |
+|-----------|----------|
+| Plan a feature / Plan a feature or strategy / Plan a UI feature | Ask for feature name + brief, then invoke `/planning` (add `--design` for designers, `--gtm` for founders) |
+| Check project status / Review recent changes | Invoke `/onboard` (brownfield flow) |
+| Create or review an issue | Invoke `/issue list` to show issues, then ask what to do |
+| Review positioning or GTM | Spawn `gtm-expert` agent with the project context |
+| Create a launch strategy | Spawn `gtm-expert` agent with launch-strategy prompt |
+| Analyze positioning | Spawn `gtm-expert` agent with positioning-canvas prompt |
+| Design thinking session | Spawn `design-studio:think` agent |
+| Get a design critique | Spawn `design-studio:critique` agent |
+| Plan content or campaign | Spawn `gtm-expert` agent with content-strategy prompt |
+| Triage open issues | Run `gh issue list`, present prioritized list |
+| Something else | Let the user type what they need; normal triage handles it |
+
+### 4. Post-Action Follow-Up
+
+After the routed action completes, present contextual next steps:
+
+```
+What next?
+  - "share this" to format for sharing with your team
+  - "revise [section]" to change something
+  - "do something else" to go back to the menu
+```
+
+## Integration with Triage Router
+
+The triage router (`hooks/triage-router.sh`) should detect when `/welcome` has been
+invoked and skip injecting the full routing table for that message. The welcome skill
+handles its own routing.
+
+## When This Skill Runs
+
+This skill can be triggered in three ways:
+1. User types `/welcome` explicitly
+2. The triage router detects a non-engineer role AND a vague/greeting first message
+3. An engineer runs `quick-setup.sh` which sets `USER_ROLE` — next session auto-triggers
+
+## Rules
+
+- **Never show agent names** to non-engineers — say "planning team" not "product-manager + architect agents"
+- **Never show model names** — the system picks the right model automatically
+- **Never show cost tiers** — budget optimization is invisible
+- **Max 1 question** before taking action — don't interview the user
+- **If user types something specific**, skip the menu and route directly
+- **Always offer "Something else"** — the menu is a suggestion, not a constraint