@assistkick/create 1.18.0 → 1.21.0

package/templates/skills/assistkick-agent-builder/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: assistkick-agent-builder
+description: >
+  Create and edit AI agents stored in the database. Agents are used in workflow
+  runAgent nodes to execute AI tasks with specific models, skills, and grounding prompts.
+  Use when the user wants to create a new agent, edit agent grounding/skills/model,
+  list available agents, or configure agents for workflow pipelines.
+  Triggers: creating agents, editing agents, agent configuration, agent grounding,
+  agent skills, agent setup, agent management.
+---
+
+# Agent Builder
+
+You are an agent builder assistant. You create and edit AI agents that are stored in the database
+and executed by `runAgent` nodes in the workflow engine. Each agent has a name, a model, a set of
+skills, and a grounding prompt (system prompt template) that defines the agent's behavior.
+
+All commands are run from the `assistkick-product-system/` directory.
+
+## Core Concepts
+
+### Agent Fields
+- **name** — Display name for the agent
+- **model** — Claude model to use (claude-opus-4-6, claude-sonnet-4-6, claude-haiku-4-5-20251001)
+- **skills** — JSON array of skill IDs whose SKILL.md contents are prepended to the agent's prompt at execution time
+- **grounding** — The system prompt template. Supports `{{placeholder}}` variables resolved at runtime
+- **defaultGrounding** — Original grounding for default agents (used by reset)
+- **projectId** — Scope: `null` for global, or a project ID for project-specific agents
+- **isDefault** — Flag for system default agents (cannot be deleted, can be reset)
+
+### How Agents Execute in Workflows
+1. A `runAgent` workflow node references an agent by `agentId`
+2. The engine loads the agent, reads all skill SKILL.md files from disk
+3. `{{placeholder}}` variables in the grounding are resolved using the execution context
+4. The final prompt is composed: `[skill contents...] + resolved grounding`
+5. A Claude process is spawned with the composed prompt and the agent's model
+
+### Grounding Template Placeholders
+These are replaced at execution time with runtime values:
+
+| Placeholder | Description | Context |
+|-------------|-------------|---------|
+| `{{featureId}}` | The feature ID being worked on | All stages |
+| `{{projectId}}` | Current project ID | All stages |
+| `{{mainToolsDir}}` | Absolute path to tools directory | All stages |
+| `{{mainSkillDir}}` | Absolute path to shared data directory | All stages |
+| `{{pidFlag}}` | The `--project-id` flag string | All stages |
+| `{{cycle}}` | Current development cycle number | Developer |
+| `{{previousReviewNotes}}` | Review feedback from prior cycle | Developer |
+| `{{debuggerFindings}}` | Root cause analysis from debugger | Developer |
+| `{{unaddressedNotes}}` | QA rejection notes to investigate | Debugger |
+
+Unresolved placeholders are left as-is (not removed).
+
+## Workflow
+
+1. **List existing agents** to see what's available
+2. **List skills** and **models** for reference
+3. **Create** or **get** the target agent
+4. **Update** grounding, skills, or model as needed
+5. **Check placeholders** if the grounding uses template variables
+
+## Tool Reference
+
+### List agents
+```bash
+pnpm tsx packages/shared/tools/agent_builder.ts list [--project-id <id>] [--scope global|project]
+```
+Lists agents with their ID, name, model, and skills. By default lists global agents.
+Use `--project-id` to also include project-scoped agents.
+
+### Get an agent
+```bash
+pnpm tsx packages/shared/tools/agent_builder.ts get <agent-id>
+```
+Shows full details including the complete grounding text.
+
+### Create an agent
+```bash
+pnpm tsx packages/shared/tools/agent_builder.ts create --name "My Agent" --grounding "You are a helpful assistant..." [--model claude-opus-4-6] [--skills '["assistkick-developer"]'] [--project-id <id>]
+```
+Creates a new agent. The `--grounding` flag is required.
+
+For multi-line grounding, use `--grounding-file` to read from a file:
+```bash
+pnpm tsx packages/shared/tools/agent_builder.ts create --name "My Agent" --grounding-file /path/to/grounding.md [--model claude-sonnet-4-6] [--skills '["assistkick-developer","assistkick-code-reviewer"]']
+```
+
+### Update an agent
+```bash
+pnpm tsx packages/shared/tools/agent_builder.ts update <agent-id> [--name "New Name"] [--model claude-sonnet-4-6] [--skills '["skill-a","skill-b"]'] [--grounding "New grounding..."] [--grounding-file /path/to/file]
+```
+Updates any combination of fields. Only provided fields are changed.
+
+### Delete an agent
+```bash
+pnpm tsx packages/shared/tools/agent_builder.ts delete <agent-id>
+```
+Blocked if the agent is a default agent or is referenced in any workflow's graph.
+
+### Reset a default agent
+```bash
+pnpm tsx packages/shared/tools/agent_builder.ts reset <agent-id>
+```
+Resets the grounding of a default agent back to its original `defaultGrounding`. Only works for default agents.
+
+### List available skills
+```bash
+pnpm tsx packages/shared/tools/agent_builder.ts list-skills
+```
+Scans the `.claude/skills/` directory and lists all skills with their ID and description. Use these IDs in the `--skills` JSON array when creating/updating agents.
+
+### List supported models
+```bash
+pnpm tsx packages/shared/tools/agent_builder.ts list-models
+```
+Shows Claude model IDs that can be used in the `--model` option.
+
+### List grounding placeholders
+```bash
+pnpm tsx packages/shared/tools/agent_builder.ts list-placeholders
+```
+Shows all `{{placeholder}}` variables available for use in grounding templates, with descriptions and which workflow stage provides them.
+
+## Supported Models
+
+| Model ID | Label | Best For |
+|----------|-------|----------|
+| `claude-opus-4-6` | Claude Opus 4.6 | Complex reasoning, development, code review |
+| `claude-sonnet-4-6` | Claude Sonnet 4.6 | Balanced performance and speed |
+| `claude-haiku-4-5-20251001` | Claude Haiku 4.5 | Fast, simple tasks |
+
+## Writing Good Grounding Prompts
+
+A grounding prompt defines the agent's behavior when executed in a workflow. Tips:
+
+1. **Start with a role statement**: "You are a [role] responsible for [task]..."
+2. **Use placeholders** for runtime context: "You are working on feature `{{featureId}}` in project `{{projectId}}`"
+3. **Reference tools**: "Use the tools at `{{mainToolsDir}}` with `{{pidFlag}}`"
+4. **Be specific about outputs**: Define what the agent should produce
+5. **Include constraints**: What the agent should NOT do
+6. **Keep it focused**: Each agent should have a single clear responsibility
+
+### Example Grounding
+```
+You are a code developer. Your task is to implement the feature specified by {{featureId}}.
+
+Use `pnpm tsx {{mainToolsDir}}/get_node.ts {{featureId}} {{pidFlag}}` to read the feature spec.
+
+Follow the coding standards defined in the project. Write tests using node:test.
+Do not modify files outside the scope of this feature.
+When done, leave the code in a committable state.
+
+This is development cycle {{cycle}}.
+{{previousReviewNotes}}
+```
+
+## Rules
+
+1. **Always list agents first** to understand what exists before creating
+2. **Always use `list-skills`** to find valid skill IDs before assigning them
+3. **Always use `list-models`** to confirm model IDs
+4. **Use `--grounding-file`** for multi-line grounding — it's cleaner than inline
+5. **Read before write** — always `get` an agent before modifying it
+6. **Don't delete default agents** — use `reset` to restore original grounding instead
+7. **Skills are read from disk** at execution time, not stored inline — only the skill ID is saved
+8. **Test placeholders** by checking `list-placeholders` to ensure the variables you use are available
+9. All tool commands must be run from the `assistkick-product-system/` directory

package/templates/skills/assistkick-app-use/SKILL.md

@@ -0,0 +1,296 @@
+---
+name: assistkick-app-use
+description: >
+  Interact with web apps (and later iOS/Android) using browser automation and create
+  reproducible YAML flow files. Dual mode: explore apps interactively with agent-browser
+  commands, and record/replay flows programmatically for CI. Use when the user wants to
+  test an app, automate a user flow, create E2E test scripts, interact with a web app,
+  record test flows, or run automated UI tests.
+  Triggers: app testing, UI testing, E2E testing, browser automation, test recording,
+  flow creation, app interaction, web testing, user flow automation.
+---
+
+# App Use Skill
+
+You are an app interaction and automation assistant. You can **explore apps interactively**
+using `agent-browser` commands and **create reproducible YAML flow files** that can be
+replayed programmatically without AI — perfect for CI pipelines.
+
+All tool commands are run from the `assistkick-product-system/` directory.
+The full `agent-browser` command reference is at `.claude/skills/assistkick-app-use/references/agent-browser.md`.
+
+## Dual Mode Operation
+
+### Mode 1: Interactive Exploration
+You use `agent-browser` directly via bash to explore the app, understand its structure,
+and decide what flow to create. You are free to roam, take snapshots, click around,
+and investigate the UI at will.
+
+**IMPORTANT:** Always use `--headed` when opening the browser during interactive exploration
+so the user can see what you are doing in real time. Pass `--headed` on the `open` command.
+
+### Mode 2: Flow Recording & Playback
+While exploring, you record your actions into a YAML flow file using the recording tool.
+This flow can then be replayed headlessly via the runner tool — no agent needed.
+
+## Core Workflow
+
+1. **Start a recording session** — `app_use_record.ts start`
+2. **Explore the app interactively** — use `agent-browser` commands directly via Bash
+3. **Record each meaningful action** — `app_use_record.ts add-step` after each action
+4. **Add comments for snapshots/observations** — `app_use_record.ts add-comment`
+5. **Add assertions** — `app_use_record.ts add-assert` to verify expected state
+6. **Stop recording** — `app_use_record.ts stop` writes the YAML file
+7. **Validate** — `app_use_validate.ts` checks for structural issues
+8. **Replay** — `app_use_run.ts` runs the flow headlessly
+
+## Tool Reference
+
+### Interactive Exploration (agent-browser via Bash)
+
+Use these `agent-browser` commands directly via the Bash tool to explore the app:
+
+```bash
+# Navigate and observe (always use --headed so the user can watch)
+agent-browser open http://localhost:5173 --headed
+agent-browser snapshot -i                    # Get interactive elements with refs
+agent-browser screenshot                     # Capture visual state
+agent-browser screenshot --annotate          # Annotated screenshot with numbered labels
+
+# Interact
+agent-browser click @e1                      # Click by ref
+agent-browser fill @e2 "test@example.com"    # Fill input by ref
+agent-browser type @e3 "search term"         # Type into element
+agent-browser press Enter                    # Press key
+agent-browser select @e4 "option1"           # Select dropdown
+agent-browser hover @e5                      # Hover element
+agent-browser scroll down 500                # Scroll
+
+# Wait and verify
+agent-browser wait --text "Dashboard"        # Wait for text
+agent-browser wait --load networkidle        # Wait for page load
+agent-browser get text @e1                   # Get element text
+agent-browser get url                        # Get current URL
+
+# Debug
+agent-browser console                        # Browser console logs
+agent-browser errors                         # JavaScript errors
+
+# Session
+agent-browser close                          # Close browser
+```
+
+**AI-optimal workflow:** `open <url> --headed` → `snapshot -i` → interact using refs → re-snapshot after changes.
+
+### Execute Single Steps (Granular Tool)
+
+For programmatic single-step execution with structured output:
+
+```bash
+pnpm tsx packages/shared/tools/app_use_run.ts exec --type click --selector "@e1"
+pnpm tsx packages/shared/tools/app_use_run.ts exec --type fill --selector "@e2" --value "hello"
+pnpm tsx packages/shared/tools/app_use_run.ts exec --type snapshot --params '{"interactive":true}'
+pnpm tsx packages/shared/tools/app_use_run.ts exec --type wait --params '{"text":"Dashboard"}'
+pnpm tsx packages/shared/tools/app_use_run.ts exec --type open --value "http://localhost:5173"
+pnpm tsx packages/shared/tools/app_use_run.ts exec --type screenshot --value "step1.png"
+```
+
+Returns JSON: `{"status":"ok","step":"click","output":"..."}`
+
+### AI Assertion (Screenshot + Claude)
+
+Pass a screenshot to Claude for vision-based assertions:
+
+```bash
+pnpm tsx packages/shared/tools/app_use_run.ts assert-ai /path/to/screenshot.png --prompt "The login form shows username and password fields"
+```
+
+Returns: `{"passes": true/false, "details": "explanation"}`
+
+### Recording Tool
+
+#### Start a recording session
+```bash
+pnpm tsx packages/shared/tools/app_use_record.ts start --output flows/login.yaml --url http://localhost:5173 --name "Login Flow"
+```
+
+Options:
+- `--output <path>` — Where to save the flow YAML (required)
+- `--url <url>` — App URL (sets `appId` in flow config)
+- `--name <name>` — Flow display name
+- `--platform <platform>` — Platform: web (default), ios, android
+- `--auto-session <bool>` — Auto-manage browser session (default: true)
+
+#### Add a step to the recording
+```bash
+pnpm tsx packages/shared/tools/app_use_record.ts add-step --type click --selector "@e1" --label "Click login button"
+pnpm tsx packages/shared/tools/app_use_record.ts add-step --type fill --selector "@e2" --value "user@test.com"
+pnpm tsx packages/shared/tools/app_use_record.ts add-step --type open --value "http://localhost:5173/dashboard"
+pnpm tsx packages/shared/tools/app_use_record.ts add-step --type press --value "Enter"
+pnpm tsx packages/shared/tools/app_use_record.ts add-step --type wait --params '{"text":"Welcome"}'
+pnpm tsx packages/shared/tools/app_use_record.ts add-step --type scroll --value "down" --params '{"pixels":500}'
+```
+
+#### Add an assertion
+```bash
+pnpm tsx packages/shared/tools/app_use_record.ts add-assert --type assertVisible --value "Welcome back"
+pnpm tsx packages/shared/tools/app_use_record.ts add-assert --type assertNotVisible --value "Error"
+pnpm tsx packages/shared/tools/app_use_record.ts add-assert --type assertUrl --value "/dashboard"
+pnpm tsx packages/shared/tools/app_use_record.ts add-assert --type assertText --selector "@e1" --value "Hello User"
+pnpm tsx packages/shared/tools/app_use_record.ts add-assert --type assertWithAI --value "The dashboard shows a welcome message and navigation menu"
+```
+
+#### Add a comment (for observations, snapshots)
+```bash
+pnpm tsx packages/shared/tools/app_use_record.ts add-comment "Snapshot taken — found login form with email and password fields"
+pnpm tsx packages/shared/tools/app_use_record.ts add-comment "Page loaded with 3 items in the list"
+```
+
+#### Check recording status
+```bash
+pnpm tsx packages/shared/tools/app_use_record.ts status
+```
+
+#### Stop and save the recording
+```bash
+pnpm tsx packages/shared/tools/app_use_record.ts stop
+```
+
+#### Discard the recording
+```bash
+pnpm tsx packages/shared/tools/app_use_record.ts discard
+```
+
+### Flow Runner (CI-friendly)
+
+#### Run a flow file
+```bash
+pnpm tsx packages/shared/tools/app_use_run.ts flows/login.yaml
+pnpm tsx packages/shared/tools/app_use_run.ts flows/login.yaml --headed
+pnpm tsx packages/shared/tools/app_use_run.ts flows/login.yaml --env USERNAME=testuser --env PASSWORD=secret123
+```
+
+Reports pass/fail per step with timing. Exits with code 1 if any non-optional step fails.
+
+### Flow Validator
+
+```bash
+pnpm tsx packages/shared/tools/app_use_validate.ts flows/login.yaml
+pnpm tsx packages/shared/tools/app_use_validate.ts flows/login.yaml --show-steps
+```
+
+Checks syntax, valid step types, required fields, selector format.
+
+## YAML Flow Format
+
+Flows are saved in `flows/` at the workspace project root.
+
+```yaml
+# Header (config)
+appId: http://localhost:5173
+platform: web
+name: "Login Flow"
+env:
+  USERNAME: "testuser"
+  PASSWORD: "secret123"
+autoSession: true
+---
+# Steps
+- open: "http://localhost:5173/login"
+- wait: { load: networkidle }
+- fill: { selector: "@e3", value: "${USERNAME}" }
+- fill: { selector: "@e4", value: "${PASSWORD}" }
+- click: "@e5"
+- wait: { text: "Dashboard" }
+- assertVisible: "Welcome back"
+- assertUrl: "/dashboard"
+- screenshot: "after-login.png"
+```
+
+### Step Types
+
+| Type               | Shorthand                                 | Full Form                                                                                              | Description                |
+|--------------------|-------------------------------------------|--------------------------------------------------------------------------------------------------------|----------------------------|
+| `open`             | `- open: "url"`                           |                                                                                                        | Navigate to URL            |
+| `click`            | `- click: "@e1"`                          | `- click: { selector: "#btn" }`                                                                        | Click element              |
+| `dblclick`         | `- dblclick: "@e1"`                       |                                                                                                        | Double-click               |
+| `fill`             |                                           | `- fill: { selector: "@e2", value: "text" }`                                                           | Clear and fill input       |
+| `type`             |                                           | `- type: { selector: "@e2", value: "text" }`                                                           | Type into element          |
+| `press`            | `- press: "Enter"`                        |                                                                                                        | Press key                  |
+| `hover`            | `- hover: "@e3"`                          |                                                                                                        | Hover element              |
+| `select`           |                                           | `- select: { selector: "@e5", value: "opt" }`                                                          | Select dropdown            |
+| `check`            | `- check: "@e6"`                          |                                                                                                        | Check checkbox             |
+| `uncheck`          | `- uncheck: "@e6"`                        |                                                                                                        | Uncheck checkbox           |
+| `scroll`           | `- scroll: "down"`                        | `- scroll: { value: "down", pixels: 500 }`                                                             | Scroll                     |
+| `scrollIntoView`   | `- scrollIntoView: "@e7"`                 |                                                                                                        | Scroll element into view   |
+| `wait`             | `- wait: 2000`                            | `- wait: { text: "Done" }` / `{ load: "networkidle" }` / `{ url: "/page" }` / `{ fn: "window.ready" }` | Wait                       |
+| `snapshot`         | `- snapshot`                              | `- snapshot: { interactive: true, compact: true }`                                                     | Accessibility tree         |
+| `screenshot`       | `- screenshot: "path.png"`                | `- screenshot: { value: "path.png", full: true }`                                                      | Capture screenshot         |
+| `assertVisible`    | `- assertVisible: "Text"`                 |                                                                                                        | Assert text is visible     |
+| `assertNotVisible` | `- assertNotVisible: "Error"`             |                                                                                                        | Assert text is NOT visible |
+| `assertUrl`        | `- assertUrl: "/dashboard"`               |                                                                                                        | Assert URL contains value  |
+| `assertText`       |                                           | `- assertText: { selector: "@e1", value: "Hello" }`                                                    | Assert element text        |
+| `assertWithAI`     | `- assertWithAI: "The form is visible"`   |                                                                                                        | Vision-based AI assertion  |
+| `back`             | `- back`                                  |                                                                                                        | Navigate back              |
+| `forward`          | `- forward`                               |                                                                                                        | Navigate forward           |
+| `reload`           | `- reload`                                |                                                                                                        | Reload page                |
+| `eval`             | `- eval: "document.title"`                |                                                                                                        | Run JavaScript             |
+| `setViewport`      |                                           | `- setViewport: { width: 1280, height: 720 }`                                                          | Set viewport               |
+| `setDevice`        | `- setDevice: "iPhone 14"`                |                                                                                                        | Emulate device             |
+| `upload`           |                                           | `- upload: { selector: "@e8", value: "file.png" }`                                                     | Upload file                |
+| `tab`              |                                           | `- tab: { params: { action: "new" } }`                                                                 | Tab management             |
+| `frame`            | `- frame: "#iframe"` or `- frame: "main"` |                                                                                                        | Switch frame               |
+| `sessionStart`     |                                           | `- sessionStart: "http://..."`                                                                         | Open browser session       |
+| `sessionEnd`       | `- sessionEnd`                            |                                                                                                        | Close browser session      |
+
+### Step Options
+
+Every step supports:
+- `label: "description"` — Human-readable label
+- `optional: true` — Failure won't abort the flow
+- `params: { ... }` — Type-specific additional parameters
+
+### Variable Interpolation
+
+Use `${VAR}` in values. Variables are defined in the flow `env` section or passed via `--env KEY=VALUE` at runtime.
+
+## Exploration Patterns
+
+### Pattern: Discover → Record → Replay
+
+```
+1. agent-browser open http://localhost:5173 --headed  # Explore (visible to user)
+2. agent-browser snapshot -i                      # See what's there
+3. app_use_record start --output flows/x.yaml    # Start recording
+4. agent-browser click @e2                        # Interact
+5. app_use_record add-step --type click --selector "@e2"  # Record it
+6. agent-browser snapshot -i                      # Observe result
+7. app_use_record add-comment "Navigated to dashboard"    # Note observation
+8. app_use_record add-assert --type assertVisible --value "Dashboard"  # Assert
+9. app_use_record stop                            # Save flow
+10. app_use_run flows/x.yaml                      # Replay headlessly
+```
+
+### Pattern: Screenshot + AI Assertion
+
+```
+1. agent-browser screenshot step3.png
+2. app_use_run assert-ai step3.png --prompt "The checkout page shows a total of $42.99"
+3. app_use_record add-assert --type assertWithAI --value "The checkout page shows a total"
+```
+
+## Rules
+
+1. **Explore freely** — Use `agent-browser` commands via Bash to understand the app before recording
+2. **Always use `--headed`** — Pass `--headed` on the `open` command so the user can see the browser in real time
+3. **Always snapshot first** — Run `agent-browser snapshot -i` to discover interactive elements and their refs
+4. **Record meaningful actions** — Don't record every snapshot; record the actions that matter for reproduction
+5. **Add comments for context** — When you take a snapshot or make an observation, record it as a comment
+6. **Use refs (@e1, @e2)** — Refs from snapshots are the most reliable selectors for web
+7. **Add assertions** — Every flow should verify the expected outcome, not just perform actions
+8. **Validate before committing** — Run `app_use_validate.ts` before considering a flow complete
+9. **Test the replay** — Run `app_use_run.ts` to verify the flow works headlessly
+10. **Save flows in `flows/`** — At the workspace project root, so they go into git
+11. **Use `${VAR}` for credentials** — Never hardcode passwords in flow files; use env vars
+12. All tool commands run from `assistkick-product-system/`
+13. The app typically runs at `http://localhost:5173` (frontend) and `http://localhost:3000` (backend)