td-ai-tools 1.0.2 → 1.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "td-ai-tools",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Install agent skills and packs into your project",
   "scripts": {
     "smoke:install": "./scripts/smoke-install.sh"

package/skills/basecamp/SKILL.md

@@ -0,0 +1,651 @@
+---
+name: basecamp
+description: |
+    Interact with Basecamp via the Basecamp CLI. Full API coverage: projects, todos, cards,
+    messages, files, schedule, check-ins, timeline, recordings, templates, webhooks,
+    subscriptions, lineup, and campfire. Use for ANY Basecamp question or action.
+invocable: true
+argument-hint: '[action] [args...]'
+---
+
+# /basecamp - Basecamp Workflow Command
+
+Full CLI coverage: 130 endpoints across todos, cards, messages, files, schedule, check-ins, timeline, recordings, templates, webhooks, subscriptions, lineup, and campfire.
+
+## Agent Invariants
+
+**MUST follow these rules:**
+
+1. **Choose the right output mode** — `--json` when you need to parse data; `--md` when presenting results to a human (see Output Modes below)
+2. **Parse URLs first** with `basecamp url parse "<url>"` to extract IDs
+3. **Comments are flat** - reply to parent recording, not to comments
+4. **Check context** via `.basecamp/config.json` before assuming project
+5. **Content fields accept Markdown** — message body and comment content accept Markdown syntax; the CLI converts to HTML automatically. Use Markdown formatting (lists, bold, links, code blocks) for rich content. For todos, documents, and cards, content is sent as-is — use plain text or HTML directly.
+6. **Project scope is mandatory for most commands** — via `--in <project>` or `.basecamp/config.json`. Cross-project exceptions: `basecamp reports assigned` for assigned work, `basecamp reports overdue` for overdue todos, `basecamp recordings <type>` for browsing by type.
+
+### Output Modes
+
+**Choosing a mode:**
+
+| Goal                   | Flag          | Format                                                                                        |
+| ---------------------- | ------------- | --------------------------------------------------------------------------------------------- |
+| Parse data, pipe to jq | `--json`      | JSON envelope: `{ok, data, summary, breadcrumbs, meta}`                                       |
+| Show results to a user | `--md` / `-m` | GFM tables, task lists, structured Markdown                                                   |
+| Automation / scripting | `--agent`     | Success: raw JSON data (no envelope); errors: `{ok:false,...}` object; no interactive prompts |
+
+Always pass `--json` or `--md` explicitly — auto-detection depends on config and may not produce the format you expect. Use `--md` when composing reports, summarizing data, or displaying results inline. `--agent` is for headless integration scripts.
+
+**Other modes:** `--quiet` (success: raw JSON, no envelope; errors: `{ok:false,...}`), `--ids-only`, `--count`, `--stats` (session statistics), `--styled` (force ANSI), `-v` / `-vv` (verbose/trace).
+
+### CLI Introspection
+
+Navigate unfamiliar commands with `--agent --help` — returns structured JSON describing any command:
+
+```bash
+basecamp todos --agent --help
+```
+
+```json
+{
+    "command": "todos",
+    "path": "basecamp todos",
+    "short": "...",
+    "long": "...",
+    "usage": "...",
+    "notes": ["..."],
+    "subcommands": [{ "name": "sweep", "short": "...", "path": "basecamp todos sweep" }],
+    "flags": [{ "name": "assignee", "type": "string", "default": "", "usage": "..." }],
+    "inherited_flags": [
+        { "name": "json", "shorthand": "j", "type": "bool", "default": "false", "usage": "..." }
+    ]
+}
+```
+
+Walk the tree: start at `basecamp --agent --help` for top-level commands, then drill into any subcommand. Commands include `notes` with domain-specific agent hints (e.g., "Cards do NOT support --assignee filtering").
+
+### Pagination
+
+```bash
+basecamp <cmd> --limit 50   # Cap results (default varies by resource)
+basecamp <cmd> --all        # Fetch all (may be slow for large datasets)
+basecamp <cmd> --page 1     # First page only, no auto-pagination
+```
+
+`--all` and `--limit` are mutually exclusive. `--page` cannot combine with either.
+
+### Smart Defaults
+
+- `--assignee me` resolves to current user
+- `--due tomorrow` / `--due +3` / `--due "next week"` - natural date parsing
+- Project from `.basecamp/config.json` if `--in` not specified
+
+## Quick Reference
+
+> **Note:** Most queries require project scope (via `--in <project>` or `.basecamp/config.json`). Cross-project exceptions: `basecamp reports assigned`, `basecamp reports overdue`, `basecamp recordings <type>`.
+
+| Task                          | Command                                                                         |
+| ----------------------------- | ------------------------------------------------------------------------------- |
+| List projects                 | `basecamp projects list --json`                                                 |
+| My todos (in project)         | `basecamp todos list --assignee me --in <project> --json`                       |
+| My todos (cross-project)      | `basecamp reports assigned --json` (defaults to "me")                           |
+| All todos (cross-project)     | `basecamp recordings todos --json` (no assignee data — cannot filter by person) |
+| Overdue todos (in project)    | `basecamp todos list --overdue --in <project> --json`                           |
+| Overdue todos (cross-project) | `basecamp reports overdue --json`                                               |
+| Assign todo                   | `basecamp assign <id> --to <person> --in <project> --json`                      |
+| Create todo                   | `basecamp todo "Task" --in <project> --list <list> --json`                      |
+| Create todolist               | `basecamp todolists create "Name" --in <project> --json`                        |
+| Complete todo                 | `basecamp done <id> --json`                                                     |
+| List cards                    | `basecamp cards list --in <project> --json`                                     |
+| Create card                   | `basecamp card "Title" --in <project> --json`                                   |
+| Move card                     | `basecamp cards move <id> --to <column> --in <project> --json`                  |
+| Post message                  | `basecamp message "Title" "Body" --in <project> --json`                         |
+| Post silently                 | `basecamp message "Title" "Body" --no-subscribe --in <project> --json`          |
+| Post to campfire              | `basecamp campfire post "Message" --in <project> --json`                        |
+| Add comment                   | `basecamp comment <recording_id> "Text" --in <project> --json`                  |
+| Search                        | `basecamp search "query" --json`                                                |
+| Parse URL                     | `basecamp url parse "<url>" --json`                                             |
+| Download file                 | `basecamp files download <id> --in <project>`                                   |
+| Watch timeline                | `basecamp timeline --watch`                                                     |
+
+## URL Parsing
+
+**Always parse URLs before acting on them:**
+
+```bash
+basecamp url parse "https://3.basecamp.com/2914079/buckets/41746046/messages/9478142982#__recording_9488783598" --json
+```
+
+Returns: `account_id`, `project_id`, `type`, `recording_id`, `comment_id` (from fragment).
+
+**URL patterns:**
+
+- `/buckets/27/messages/123` - Message 123 in project 27
+- `/buckets/27/messages/123#__recording_456` - Comment 456 on message 123
+- `/buckets/27/card_tables/cards/789` - Card 789
+- `/buckets/27/card_tables/columns/456` - Column 456 (for creating cards)
+- `/buckets/27/todos/101` - Todo 101
+- `/buckets/27/uploads/202` - Upload/file 202
+- `/buckets/27/documents/303` - Document 303
+- `/buckets/27/schedule_entries/404` - Schedule entry 404
+
+**Replying to comments:**
+
+```bash
+# Comments are flat - reply to the parent recording_id, not the comment_id
+basecamp url parse "https://...messages/123#__recording_456" --json
+# Returns recording_id: 123 (parent), comment_id: 456 (fragment) - comment on 123, not 456
+basecamp comment 123 "Reply" --in <project>
+```
+
+## Decision Trees
+
+### Finding Content
+
+```
+Need to find something?
+├── Know the type + project? → basecamp <type> list --in <project> --json
+│   (some groups have default list behavior; use --agent --help if unsure)
+├── My assigned work? → basecamp reports assigned --json (defaults to "me")
+├── Overdue across projects? → basecamp reports overdue --json
+├── Browse by type cross-project? → basecamp recordings <type> --json
+│   (types: todos, messages, documents, comments, cards, uploads)
+│   Note: Defaults to active status; use --status archived for archived items
+│   ⚠ No assignee data — cannot filter by person; use reports assigned instead
+├── Full-text search? → basecamp search "query" --json
+└── Have a URL? → basecamp url parse "<url>" --json
+```
+
+### Modifying Content
+
+```
+Want to change something?
+├── Have URL? → basecamp url parse "<url>" → use extracted IDs
+├── Have ID? → basecamp <resource> update <id> --field value
+├── Change status? → basecamp recordings trash|archive|restore <id>
+└── Complete todo? → basecamp done <id>
+```
+
+## Common Workflows
+
+### Link Code to Basecamp Todo
+
+```bash
+# Get commit info and comment on todo (use printf %q for safe quoting)
+COMMIT=$(git rev-parse --short HEAD)
+MSG=$(git log -1 --format=%s)
+basecamp comment <todo_id> "Commit $COMMIT: $(printf '%s' "$MSG")" --in <project>
+
+# Complete when done
+basecamp done <todo_id>
+```
+
+### Track PR in Basecamp
+
+```bash
+# Create todo for PR work
+basecamp todo "Review PR #42" --in <project> --assignee me --due tomorrow
+
+# When merged
+basecamp done <todo_id>
+basecamp campfire post "Merged PR #42" --in <project>
+```
+
+### Bulk Process Overdue Todos
+
+```bash
+# Preview overdue todos
+basecamp todos sweep --overdue --dry-run --in <project>
+
+# Complete all with comment
+basecamp todos sweep --overdue --complete --comment "Cleaning up" --in <project>
+```
+
+### Move Card Through Workflow
+
+```bash
+# List columns to get IDs
+basecamp cards columns --in <project> --json
+
+# Move card to column
+basecamp cards move <card_id> --to <column_id> --in <project>
+```
+
+### Download File from Basecamp
+
+```bash
+basecamp files download <upload_id> --in <project> --out ./downloads
+```
+
+## Resource Reference
+
+### Projects
+
+```bash
+basecamp projects list --json               # List all
+basecamp projects show <id> --json          # Show details
+basecamp projects create "Name" --json      # Create
+basecamp projects update <id> --name "New"  # Update
+```
+
+### Todos
+
+```bash
+basecamp todos list --in <project> --json               # List in project
+basecamp todos list --assignee me --in <project>        # My todos
+basecamp todos list --overdue --in <project>            # Overdue only
+basecamp todos list --status completed --in <project>   # Completed
+basecamp todos list --list <todolist_id> --in <project> # In specific list
+basecamp todo "Task" --in <project> --list <list> --assignee me --due tomorrow
+basecamp done <id> [id...]                              # Complete (multiple OK)
+basecamp reopen <id>                                    # Uncomplete
+basecamp assign <id> --to <person> --in <project>       # Assign (person: ID, email, or "me")
+basecamp unassign <id> --from <person> --in <project>   # Remove assignee
+basecamp todos position <id> --to 1                     # Move to top
+basecamp todos sweep --overdue --complete --comment "Done" --in <project>
+```
+
+**Flags:** `--assignee` (todos only - not available on cards/messages), `--status` (completed/pending), `--overdue`, `--list`, `--due`, `--limit`, `--all`
+
+### Todolists
+
+Todolists are containers for todos. Create a todolist before adding todos.
+
+```bash
+basecamp todolists list --in <project> --json              # List todolists
+basecamp todolists show <id> --in <project>                # Show details
+basecamp todolists create "Name" --in <project> --json     # Create
+basecamp todolists create "Name" --description "Desc" --in <project>
+basecamp todolists update <id> --name "New" --in <project> # Update
+```
+
+### Cards (Kanban)
+
+**Note:** Cards do NOT support `--assignee` filtering like todos. Fetch all cards and filter client-side if needed. If a project has multiple card tables, you must specify `--card-table <id>`. When you get an "Ambiguous card table" error, the hint shows available table IDs and names.
+
+```bash
+basecamp cards list --in <project> --json             # All cards
+basecamp cards list --card-table <id> --in <project>  # Specific table (required if multiple)
+basecamp cards list --column <id> --in <project>      # Cards in column
+basecamp cards columns --in <project> --json          # List columns (needs --card-table if multiple)
+basecamp cards show <id> --in <project>               # Card details
+basecamp card "Title" "<p>Body</p>" --in <project> --column <id>
+basecamp cards update <id> --title "New" --due tomorrow --assignee me
+basecamp cards move <id> --to <column_id>             # Move to column (numeric ID)
+basecamp cards move <id> --to "Done" --card-table <table_id>  # Move by name (needs table)
+```
+
+**Identifying completed cards:** Cards in Done columns have `parent.type: "Kanban::DoneColumn"` and `completed: true`. Use this to identify completed cards that haven't been archived.
+
+**Limitation:** Basecamp does not track when cards are moved between columns. The `updated_at` field updates on any modification and cannot reliably indicate when a card was completed.
+
+**Card Steps (checklists):**
+
+```bash
+basecamp cards steps <card_id> --in <project>     # List steps
+basecamp cards step create "Step" --card <id> --in <project>
+basecamp cards step complete <step_id> --in <project>
+basecamp cards step uncomplete <step_id>
+```
+
+**Column management:**
+
+```bash
+basecamp cards column show <id> --in <project>
+basecamp cards column create "Name" --in <project>
+basecamp cards column update <id> --title "New"
+basecamp cards column move <id> --position 2
+basecamp cards column color <id> --color blue
+basecamp cards column on-hold <id>                # Enable on-hold section
+basecamp cards column watch <id>                  # Subscribe to column
+```
+
+### Messages
+
+```bash
+basecamp messages list --in <project> --json  # List messages
+basecamp messages show <id> --in <project>    # Show message
+basecamp message "Title" "Body" --in <project>
+basecamp messages update <id> --title "New" --body "Updated"
+basecamp messages pin <id> --in <project>     # Pin to top
+basecamp messages unpin <id>                  # Unpin
+```
+
+**Flags:** `--draft` (create as draft), `--no-subscribe` (silent, no notifications), `--subscribe "people"` (comma-separated names, emails, IDs, or "me"; mutually exclusive with `--no-subscribe`), `--message-board <id>` (if multiple boards)
+
+```bash
+basecamp message "Bot update" "Done" --no-subscribe --in <project>
+basecamp message "FYI" "Note" --subscribe "Alice,bob@x.com" --in <project>
+```
+
+### Comments
+
+```bash
+basecamp comments list <recording_id> --in <project> --json
+basecamp comment <recording_id> "Text" --in <project>
+basecamp comments update <id> "Updated" --in <project>
+```
+
+### Files & Documents
+
+```bash
+basecamp files list --in <project> --json               # List all (folders, files, docs)
+basecamp files list --vault <folder_id> --in <project>  # List folder contents
+basecamp files show <id> --in <project>                 # Show item (auto-detects type)
+basecamp files download <id> --in <project>             # Download file
+basecamp files download <id> --out ./dir                # Download to specific dir
+basecamp files folder create "Folder" --in <project>
+basecamp files doc create "Doc" "Body" --in <project>
+basecamp files doc create "Draft" --draft --in <project>
+basecamp files doc create "Notes" "..." --no-subscribe --in <project>
+basecamp files update <id> --title "New" --content "Updated"
+```
+
+**Subcommands:** `folders`, `uploads`, `documents` (each with pagination flags)
+
+### Schedule
+
+```bash
+basecamp schedule --in <project> --json           # Schedule info
+basecamp schedule entries --in <project> --json   # List entries
+basecamp schedule show <id> --in <project>        # Entry details
+basecamp schedule show <id> --date 20240315       # Specific occurrence (recurring)
+basecamp schedule create "Event" --starts-at "2024-03-15T09:00:00Z" --ends-at "2024-03-15T10:00:00Z" --in <project>
+basecamp schedule create "Meeting" --all-day --notify --participants 1,2,3 --in <project>
+basecamp schedule create "Sync" --starts-at "..." --ends-at "..." --no-subscribe --in <project>
+basecamp schedule update <id> --summary "New title" --starts-at "..."
+basecamp schedule settings --include-due --in <project>  # Include todos/cards due dates
+```
+
+**Flags:** `--all-day`, `--notify`, `--participants <ids>`, `--no-subscribe`, `--subscribe "people"` (mutually exclusive), `--status` (active/archived/trashed)
+
+### Check-ins
+
+```bash
+basecamp checkins --in <project> --json           # Questionnaire info
+basecamp checkins questions --in <project>        # List questions
+basecamp checkins question <id> --in <project>    # Question details
+basecamp checkins answers <question_id> --in <project>  # List answers
+basecamp checkins answer <id> --in <project>      # Answer details
+basecamp checkins question create "What did you work on?" --in <project>
+basecamp checkins question update <id> "New question" --frequency every_week
+basecamp checkins answer create <question-id> "My answer" --in <project>
+basecamp checkins answer update <id> "Updated" --in <project>
+```
+
+**Schedule options:** `--frequency` (every_day, every_week, every_other_week, every_month, on_certain_days), `--days 1,2,3,4,5` (0=Sun), `--time "5:00pm"`
+
+### Timeline
+
+```bash
+basecamp timeline --json                          # Account-wide activity
+basecamp timeline --in <project> --json           # Project activity
+basecamp timeline me --json                       # Your activity
+basecamp timeline --person <id> --json            # Person's activity
+basecamp timeline --watch                         # Live monitoring (TUI)
+basecamp timeline --watch --interval 60           # Poll every 60 seconds
+```
+
+**Note:** `basecamp timeline` (account-wide) works reliably. The `--limit` flag is not supported on timeline commands.
+
+### Recordings (Cross-project)
+
+Use `basecamp recordings <type>` for cross-project type browsing. **For assigned todos, prefer `basecamp reports assigned`** — recordings do not include assignee data and cannot be filtered by person.
+
+```bash
+basecamp recordings todos --json                  # All todos across projects
+basecamp recordings todos --all --json            # All todos (paginate through all)
+basecamp recordings messages --in <project>       # Messages in project
+basecamp recordings documents --status archived   # Archived docs
+basecamp recordings cards --sort created_at --direction asc
+basecamp recordings cards --status archived --all --json  # Include archived cards
+```
+
+**Types:** `todos`, `messages`, `documents`, `comments`, `cards`, `uploads`
+
+**Status filtering:** By default, only `active` recordings are returned. Use `--status archived` or `--status trashed` to query other statuses. You may need separate queries to get complete data (e.g., active + archived).
+
+**Status management:**
+
+```bash
+basecamp recordings trash <id> --in <project>     # Move to trash
+basecamp recordings archive <id> --in <project>   # Archive
+basecamp recordings restore <id> --in <project>   # Restore to active
+basecamp recordings visibility <id> --visible --in <project>  # Show to clients
+basecamp recordings visibility <id> --hidden      # Hide from clients
+```
+
+### Templates
+
+```bash
+basecamp templates --json                         # List templates
+basecamp templates show <id> --json               # Template details
+basecamp templates create "Template Name"         # Create empty template
+basecamp templates update <id> --name "New Name"
+basecamp templates delete <id>                    # Trash template
+basecamp templates construct <id> --name "New Project"  # Create project (async)
+basecamp templates construction <template_id> <construction_id>  # Check status
+```
+
+**Construct returns construction_id - poll until status="completed" to get project.**
+
+### Webhooks
+
+```bash
+basecamp webhooks list --in <project> --json  # List webhooks
+basecamp webhooks show <id> --in <project>    # Webhook details
+basecamp webhooks create "https://..." --in <project>
+basecamp webhooks create "https://..." --types "Todo,Comment" --in <project>
+basecamp webhooks update <id> --active --in <project>
+basecamp webhooks update <id> --inactive      # Disable
+basecamp webhooks delete <id> --in <project>
+```
+
+**Event types:** Todo, Todolist, Message, Comment, Document, Upload, Vault, Schedule::Entry, Kanban::Card, Question, Question::Answer
+
+### Subscriptions
+
+```bash
+basecamp subscriptions <recording_id>              # Who's subscribed
+basecamp subscriptions subscribe <id>              # Subscribe yourself
+basecamp subscriptions unsubscribe <id>            # Unsubscribe
+basecamp subscriptions add <id> --people 1,2,3     # Add people
+basecamp subscriptions remove <id> --people 1,2,3  # Remove people
+```
+
+### Lineup (Account-wide Markers)
+
+```bash
+basecamp lineup create "Milestone" "2024-03-15"   # Create marker
+basecamp lineup create "Launch" tomorrow          # Natural date parsing
+basecamp lineup update <id> "New Name" "+7"
+basecamp lineup delete <id>
+```
+
+**Note:** Lineup markers are account-wide, not project-scoped.
+
+### Campfire
+
+```bash
+basecamp campfire --in <project> --json           # List campfires
+basecamp campfire messages --in <project> --json  # List messages
+basecamp campfire post "Hello!" --in <project>
+basecamp campfire line <line_id> --in <project>   # Show line
+basecamp campfire delete <line_id> --in <project> # Delete line
+```
+
+### People
+
+```bash
+basecamp people list --json                          # All people in account
+basecamp people list --project <project> --json    # People on project
+basecamp me --json                                 # Current user
+basecamp people show <id> --json                   # Person details
+basecamp people add <id> --project <project>       # Add to project
+basecamp people remove <id> --project <project>    # Remove from project
+```
+
+### Search
+
+```bash
+basecamp search "query" --json                    # Full-text search
+basecamp search "query" --sort updated_at --limit 20
+basecamp search metadata --json                   # Available search scopes
+```
+
+### Generic Show
+
+```bash
+basecamp show <type> <id> --in <project> --json   # Show any recording type
+# Types: todo, todolist, message, comment, card, card-table, document (or omit <type> for generic lookup)
+```
+
+## Configuration
+
+The CLI uses two directory namespaces: `basecamp` for your Basecamp identity and project relationships, `basecamp` for tool-specific operational data.
+
+```
+~/.config/basecamp/           # Basecamp identity (DO NOT read credentials)
+├── credentials.json          #   OAuth tokens — NEVER read or log
+├── client.json               #   DCR client registration
+└── config.json               #   Global preferences (account_id, base_url, format)
+
+~/.cache/basecamp/            # Tool cache (ephemeral, auto-managed)
+├── completion.json           #   Tab completion cache
+└── resilience/               #   Circuit breaker state
+
+.basecamp/                    # Per-repo config (committed to git)
+└── config.json               #   Project defaults (project_id, account_id, todolist_id)
+```
+
+**Per-repo config:** `.basecamp/config.json`
+
+```json
+{
+    "project_id": "12345",
+    "todolist_id": "67890"
+}
+```
+
+**Initialize:**
+
+```bash
+basecamp config init
+basecamp config set project_id <id>
+basecamp config set todolist_id <id>
+```
+
+**Config Trust:**
+
+Authority keys (`base_url`, `default_profile`, `profiles`) in local/repo configs are blocked until explicitly trusted. This prevents a cloned repo's config from redirecting OAuth tokens.
+
+```bash
+basecamp config trust                    # Trust nearest .basecamp/config.json
+basecamp config trust /path/to/.basecamp/config.json  # Trust specific config file
+basecamp config trust --list             # Show all trusted configs
+basecamp config untrust                  # Revoke trust for nearest config
+basecamp config untrust /path/to/.basecamp/config.json  # Revoke trust for specific path
+```
+
+**Check context:**
+
+```bash
+cat .basecamp/config.json 2>/dev/null || echo "No project configured"
+```
+
+**Global config:** `~/.config/basecamp/config.json` (account_id, base_url, format preferences)
+
+## Error Handling
+
+**General diagnostics:**
+
+```bash
+basecamp doctor --json                            # Check CLI health, auth, connectivity
+```
+
+**Rate limiting (429):** The CLI handles backoff automatically. If you see 429 errors, reduce request frequency.
+
+**Authentication errors:**
+
+```bash
+basecamp auth status                              # Check auth
+basecamp auth login                               # Re-authenticate
+basecamp auth login --scope full                  # Full access (BC3 OAuth only)
+```
+
+**Network errors / localhost URLs:**
+
+```bash
+# Check for dev config
+cat ~/.config/basecamp/config.json
+# Should only contain: {"account_id": "<id>"}
+# Remove base_url/api_url if pointing to localhost
+```
+
+**Not found errors:**
+
+```bash
+basecamp auth status                              # Verify auth working
+cat ~/.config/basecamp/accounts.json              # Check available accounts
+```
+
+**Required arguments are positional (not flags):**
+
+- `basecamp todo "Buy milk"` (not `--content`)
+- `basecamp card "New feature"` (not `--title`)
+- `basecamp message "Subject" "Body"` (not `--subject`)
+- `basecamp campfire post "Hello"` (not `--content`)
+- `basecamp comment <id> "Text"` (not a flag)
+- `basecamp webhooks create "https://..." --in <project>` (not `--url`)
+- `basecamp checkins answer create <question-id> "content"` (not `--question`)
+
+**Missing argument errors (code: "usage"):**
+When a required positional argument is missing, the CLI returns a structured error naming
+the specific argument. Use this for elicitation:
+
+```bash
+$ basecamp todo --json
+{"ok": false, "error": "<content> required", "code": "usage",
+ "hint": "Usage: basecamp todo <content>"}
+
+$ basecamp comments create 123 --json
+{"ok": false, "error": "<content> required", "code": "usage", ...}
+```
+
+The `error` field names the missing `<arg>` — use it to prompt the user for the specific value.
+
+**URL malformed (curl exit 3):** Special characters in content. Use plain text or properly escaped HTML.
+
+## jq Patterns
+
+Common data extraction patterns for the output envelope:
+
+```bash
+# Extract fields from data array
+basecamp todos list --in <project> --json | jq '.data[] | select(.completed == false) | .title'
+basecamp todos list --in <project> --json | jq '.data | length'
+basecamp todos list --in <project> --json | jq '.data[] | {id, title, status}'
+
+# Access envelope metadata
+basecamp todos list --in <project> --json | jq '.breadcrumbs[0].cmd'
+basecamp todos list --in <project> --json | jq '.meta.stats.requests'
+```
+
+## Exit Codes
+
+| Exit | Meaning       | Fix                                                                 |
+| ---- | ------------- | ------------------------------------------------------------------- |
+| 0    | OK            | —                                                                   |
+| 1    | Usage error   | Check `basecamp <cmd> --help`                                       |
+| 2    | Not found     | Verify ID/URL exists                                                |
+| 3    | Auth error    | `basecamp auth login`                                               |
+| 4    | Forbidden     | Check account/project permissions                                   |
+| 5    | Rate limit    | Wait and retry (resilience layer handles Retry-After automatically) |
+| 6    | Network error | Check connectivity, `basecamp doctor`                               |
+| 7    | API error     | Retry; if persistent, check `basecamp doctor`                       |
+| 8    | Ambiguous     | Be more specific (use ID instead of name)                           |
+
+## Learn More
+
+- API concepts: https://github.com/basecamp/bc3-api#key-concepts
+- CLI repo: https://github.com/basecamp/basecamp-cli
+- API coverage: See API-COVERAGE.md in the CLI repo

package/skills/everhour-basecamp-estimates/SKILL.md

@@ -56,6 +56,7 @@ python3 .agents/skills/everhour-basecamp-estimates/scripts/update_estimates.py \
 - A scalar estimate is applied to each active todo.
 - A JSON estimate array is applied in active-todo order and must match the active todo count exactly.
 - It matches Basecamp titles against Everhour task names inside the configured project.
+- If multiple Everhour tasks have the same normalized title, it selects the task whose Everhour task id or URL maps to the Basecamp todo id.
 - Matching is exact after normalization:
   - trim whitespace
   - collapse repeated spaces
@@ -67,7 +68,7 @@ python3 .agents/skills/everhour-basecamp-estimates/scripts/update_estimates.py \
 ## Guardrails
 
 - If any Basecamp title has no Everhour match, stop and report it.
-- If any Basecamp title matches more than one Everhour task, stop and report the ambiguity.
+- If any Basecamp title matches more than one Everhour task and the Basecamp todo id cannot resolve one task, stop and report the ambiguity.
 - If an estimate array length does not match the active todo count, stop before any updates.
 - If the provided todo URL is already completed, stop without updating anything.
 - Do not update Basecamp titles before Everhour updates complete.

package/skills/everhour-basecamp-estimates/scripts/update_estimates.py

@@ -27,6 +27,7 @@ WHITESPACE_RE = re.compile(r"\s+")
 class TodoItem:
     id: str
     title: str
+    api_url: str | None = None
 
 
 @dataclass(frozen=True)
@@ -200,6 +201,13 @@ def extract_title(record: dict[str, Any]) -> str:
     raise ScriptError(f"Could not determine a title from Basecamp payload: {record}")
 
 
+def extract_api_url(record: dict[str, Any]) -> str | None:
+    value = record.get("url")
+    if isinstance(value, str) and value.strip():
+        return value.strip()
+    return None
+
+
 def extract_todo_objects(payload: Any) -> list[dict[str, Any]]:
     if isinstance(payload, list):
         candidates = [item for item in payload if is_todo_like(item)]
@@ -258,17 +266,46 @@ def is_todo_completed(record: dict[str, Any]) -> bool:
 def load_basecamp_todos(basecamp_bin: str, basecamp_url: str) -> TodoSelection:
     parsed = run_basecamp_json(basecamp_bin, "url", "parse", basecamp_url)
     resource_type = str(parsed.get("type", "")).strip().lower()
+    project_id = str(parsed.get("project_id", "")).strip()
+    recording_id = str(parsed.get("recording_id", "")).strip()
 
     if resource_type in {"todo", "todos"}:
         payload = run_basecamp_json(basecamp_bin, "todos", "show", basecamp_url)
-        todo = TodoItem(id=str(payload["id"]), title=extract_title(payload))
+        todo = TodoItem(
+            id=str(payload["id"]),
+            title=extract_title(payload),
+            api_url=extract_api_url(payload),
+        )
         if is_todo_completed(payload):
             return TodoSelection(active=[], skipped_completed=[todo])
         return TodoSelection(active=[todo], skipped_completed=[])
 
     if resource_type in {"todolist", "todolists"}:
-        payload = run_basecamp_json(basecamp_bin, "todolists", "show", basecamp_url)
-        todo_objects = extract_todo_objects(payload)
+        payload: Any = None
+        todo_objects: list[dict[str, Any]] = []
+        try:
+            payload = run_basecamp_json(basecamp_bin, "todolists", "show", basecamp_url)
+        except ScriptError:
+            payload = None
+
+        if payload is not None:
+            todo_objects = extract_todo_objects(payload)
+
+        # Some Basecamp CLI versions return an empty payload for todolists show even
+        # though the list exists. Fall back to listing todos scoped to the parsed
+        # project and todolist IDs.
+        if not todo_objects and project_id and recording_id:
+            fallback_payload = run_basecamp_json(
+                basecamp_bin,
+                "todos",
+                "list",
+                "--in",
+                project_id,
+                "--todolist",
+                recording_id,
+            )
+            todo_objects = extract_todo_objects(fallback_payload)
+
         if not todo_objects:
             raise ScriptError(
                 "The Basecamp todolist payload did not include any todo items. "
@@ -277,7 +314,11 @@ def load_basecamp_todos(basecamp_bin: str, basecamp_url: str) -> TodoSelection:
         active: list[TodoItem] = []
         skipped_completed: list[TodoItem] = []
         for item in todo_objects:
-            todo = TodoItem(id=str(item["id"]), title=extract_title(item))
+            todo = TodoItem(
+                id=str(item["id"]),
+                title=extract_title(item),
+                api_url=extract_api_url(item),
+            )
             if is_todo_completed(item):
                 skipped_completed.append(todo)
             else:
@@ -370,14 +411,12 @@ class EverhourClient:
             raise ScriptError("Everhour task search response was not a list.")
         return [task for task in tasks if isinstance(task, dict)]
 
-    def match_task(self, title: str) -> dict[str, Any]:
+    def match_task(self, title: str, source_id: str) -> dict[str, Any]:
         normalized = normalize_title(title)
         open_matches = self.list_open_tasks().get(normalized, [])
-        if len(open_matches) == 1:
-            return open_matches[0]
-        if len(open_matches) > 1:
-            matches = ", ".join(str(task.get("id")) for task in open_matches)
-            raise ScriptError(f"Ambiguous Everhour matches for '{title}': {matches}")
+        open_match = select_single_task_match(title, open_matches, source_id)
+        if open_match is not None:
+            return open_match
 
         search_matches = [
             task
@@ -385,13 +424,12 @@ class EverhourClient:
             if normalize_title(str(task.get("name", ""))) == normalized
         ]
         if not search_matches:
-            raise ScriptError(
-                f"No Everhour task match found for Basecamp title '{title}' in project {self.project_id}."
-            )
-        if len(search_matches) > 1:
-            matches = ", ".join(str(task.get("id")) for task in search_matches)
-            raise ScriptError(f"Ambiguous Everhour matches for '{title}': {matches}")
-        return search_matches[0]
+            raise ScriptError(format_missing_match_error(title, self.project_id))
+        search_match = select_single_task_match(title, search_matches, source_id)
+        if search_match is not None:
+            return search_match
+
+        raise ScriptError(format_ambiguous_match_error(title, search_matches, source_id))
 
     def update_task_estimate(self, task_id: str, total_seconds: int) -> None:
         self._request(
@@ -401,8 +439,106 @@ class EverhourClient:
         )
 
 
-def update_basecamp_title(basecamp_bin: str, todo_id: str, title: str) -> None:
-    run_basecamp_json(basecamp_bin, "todos", "update", todo_id, "--title", title)
+def task_matches_source_id(task: dict[str, Any], source_id: str) -> bool:
+    normalized_source_id = str(source_id).strip()
+    if not normalized_source_id:
+        return False
+
+    task_id = str(task.get("id", "")).strip()
+    if task_id == normalized_source_id or task_id.endswith(f":{normalized_source_id}"):
+        return True
+
+    url = str(task.get("url", "")).strip().rstrip("/")
+    return bool(url) and url.endswith(f"/{normalized_source_id}")
+
+
+def select_single_task_match(
+    title: str,
+    tasks: list[dict[str, Any]],
+    source_id: str,
+) -> dict[str, Any] | None:
+    if len(tasks) == 1:
+        return tasks[0]
+    if len(tasks) == 0:
+        return None
+
+    source_matches = [task for task in tasks if task_matches_source_id(task, source_id)]
+    if len(source_matches) == 1:
+        return source_matches[0]
+    if len(source_matches) > 1:
+        raise ScriptError(format_ambiguous_match_error(title, source_matches, source_id))
+    return None
+
+
+def format_ambiguous_match_error(
+    title: str,
+    matches: list[dict[str, Any]],
+    source_id: str,
+) -> str:
+    match_ids = ", ".join(str(task.get("id")) for task in matches)
+    return (
+        f"Ambiguous Everhour matches for '{title}': {match_ids}. "
+        f"None could be uniquely matched to Basecamp todo {source_id}."
+    )
+
+
+def format_missing_match_error(title: str, project_id: str) -> str:
+    return f"No Everhour task match found for Basecamp title '{title}' in project {project_id}."
+
+
+def update_basecamp_title(basecamp_bin: str, todo: TodoItem, title: str) -> None:
+    if not todo.api_url:
+        raise ScriptError(f"Basecamp todo {todo.id} payload did not include an API URL.")
+    current = run_basecamp_json(basecamp_bin, "api", "get", todo.api_url)
+    if not isinstance(current, dict):
+        raise ScriptError(
+            f"Basecamp todo {todo.id} GET did not return a JSON object: {current!r}"
+        )
+    payload = build_basecamp_update_payload(current, title)
+    run_basecamp_json(
+        basecamp_bin,
+        "api",
+        "put",
+        todo.api_url,
+        "-d",
+        json.dumps(payload),
+    )
+
+
+def build_basecamp_update_payload(current: dict[str, Any], title: str) -> dict[str, Any]:
+    # Basecamp's PUT to a todo replaces all writable fields, so any field omitted
+    # here gets cleared. Carry over the assignees, completion subscribers, notes
+    # (description), and dates from the current record so we only change `content`.
+    payload: dict[str, Any] = {"content": title}
+
+    description = current.get("description")
+    if isinstance(description, str) and description:
+        payload["description"] = description
+
+    assignee_ids = _extract_person_ids(current.get("assignees"))
+    if assignee_ids:
+        payload["assignee_ids"] = assignee_ids
+
+    subscriber_ids = _extract_person_ids(current.get("completion_subscribers"))
+    if subscriber_ids:
+        payload["completion_subscriber_ids"] = subscriber_ids
+
+    for key in ("due_on", "starts_on"):
+        value = current.get(key)
+        if isinstance(value, str) and value:
+            payload[key] = value
+
+    return payload
+
+
+def _extract_person_ids(people: Any) -> list[Any]:
+    if not isinstance(people, list):
+        return []
+    ids: list[Any] = []
+    for person in people:
+        if isinstance(person, dict) and "id" in person:
+            ids.append(person["id"])
+    return ids
 
 
 def build_plan(
@@ -430,7 +566,7 @@ def build_plan(
             )
         seen_titles[normalized_title] = todo
 
-        task = everhour.match_task(todo.title)
+        task = everhour.match_task(todo.title, source_id=todo.id)
         task_id = str(task.get("id", "")).strip()
         task_name = str(task.get("name", "")).strip()
         if not task_id or not task_name:
@@ -504,7 +640,7 @@ def main() -> int:
         everhour.update_task_estimate(plan.everhour_task_id, plan.seconds)
 
     for plan in plans:
-        update_basecamp_title(args.basecamp_bin, plan.todo.id, plan.new_basecamp_title)
+        update_basecamp_title(args.basecamp_bin, plan.todo, plan.new_basecamp_title)
 
     print("Completed Everhour estimate updates and Basecamp title updates.")
     return 0

package/skills/everhour-basecamp-estimates/tests/test_update_estimates.py

@@ -1,4 +1,5 @@
 import importlib.util
+import json
 import sys
 import unittest
 from decimal import Decimal
@@ -65,7 +66,7 @@ class BuildPlanTest(unittest.TestCase):
             MODULE.build_plan(todos, estimates, everhour)
 
         self.assertIn("duplicates todo 1", str(caught.exception))
-        everhour.match_task.assert_called_once_with("Ship estimate")
+        everhour.match_task.assert_called_once_with("Ship estimate", source_id="1")
 
     def test_rejects_duplicate_everhour_task_matches(self) -> None:
         todos = [
@@ -88,6 +89,198 @@ class BuildPlanTest(unittest.TestCase):
         self.assertIn("todo 1 and todo 2", str(caught.exception))
         self.assertEqual(everhour.match_task.call_count, 2)
 
+    def test_passes_basecamp_todo_id_to_everhour_matcher(self) -> None:
+        todos = [MODULE.TodoItem(id="1", title="Ship estimate")]
+        estimates = [(Decimal("1"), 3600)]
+        everhour = mock.Mock()
+        everhour.match_task.return_value = {
+            "id": "abc123",
+            "name": "Ship estimate",
+        }
+
+        plans = MODULE.build_plan(todos, estimates, everhour)
+
+        everhour.match_task.assert_called_once_with("Ship estimate", source_id="1")
+        self.assertEqual(plans[0].everhour_task_id, "abc123")
+
+
+class EverhourClientMatchTaskTest(unittest.TestCase):
+    def test_duplicate_open_matches_are_resolved_by_basecamp_todo_id(self) -> None:
+        client = MODULE.EverhourClient(api_key="key", project_id="project")
+        client.list_open_tasks = mock.Mock(
+            return_value={
+                "ship estimate": [
+                    {"id": "b3:1", "name": "Ship estimate"},
+                    {"id": "b3:2", "name": "Ship estimate"},
+                ],
+            }
+        )
+        client.search_tasks = mock.Mock(return_value=[])
+
+        task = client.match_task("Ship estimate", source_id="2")
+
+        self.assertEqual(task["id"], "b3:2")
+        client.search_tasks.assert_not_called()
+
+    def test_duplicate_open_matches_still_fail_without_todo_id_match(self) -> None:
+        client = MODULE.EverhourClient(api_key="key", project_id="project")
+        client.list_open_tasks = mock.Mock(
+            return_value={
+                "ship estimate": [
+                    {"id": "b3:1", "name": "Ship estimate"},
+                    {"id": "b3:2", "name": "Ship estimate"},
+                ],
+            }
+        )
+        client.search_tasks = mock.Mock(
+            return_value=[
+                {"id": "b3:1", "name": "Ship estimate"},
+                {"id": "b3:2", "name": "Ship estimate"},
+            ]
+        )
+
+        with self.assertRaises(MODULE.ScriptError) as caught:
+            client.match_task("Ship estimate", source_id="3")
+
+        self.assertIn("Basecamp todo 3", str(caught.exception))
+
+    def test_duplicate_search_matches_are_resolved_by_basecamp_todo_id(self) -> None:
+        client = MODULE.EverhourClient(api_key="key", project_id="project")
+        client.list_open_tasks = mock.Mock(return_value={})
+        client.search_tasks = mock.Mock(
+            return_value=[
+                {"id": "b3:1", "name": "Ship estimate"},
+                {"id": "b3:2", "name": "Ship estimate"},
+            ]
+        )
+
+        task = client.match_task("Ship estimate", source_id="2")
+
+        self.assertEqual(task["id"], "b3:2")
+        client.search_tasks.assert_called_once_with("Ship estimate")
+
+    def test_basecamp_todo_id_can_match_task_url(self) -> None:
+        task = {
+            "id": "opaque",
+            "name": "Ship estimate",
+            "url": "https://3.basecamp.com/1/buckets/2/todos/123",
+        }
+
+        self.assertTrue(MODULE.task_matches_source_id(task, "123"))
+
+
+class UpdateBasecampTitleTest(unittest.TestCase):
+    def test_fetches_current_todo_then_puts_with_only_changed_content(self) -> None:
+        todo = MODULE.TodoItem(
+            id="123",
+            title="Ship estimate",
+            api_url="https://3.basecampapi.com/1/buckets/2/todos/123.json",
+        )
+        current_payload = {
+            "id": 123,
+            "content": "Ship estimate",
+            "description": "<div>Original notes with image</div>",
+            "assignees": [{"id": 7}, {"id": 8}],
+            "completion_subscribers": [{"id": 9}],
+            "due_on": "2026-05-01",
+            "starts_on": None,
+        }
+
+        with mock.patch.object(MODULE, "run_basecamp_json") as run_basecamp_json:
+            run_basecamp_json.side_effect = [current_payload, {}]
+            MODULE.update_basecamp_title("basecamp", todo, "Ship estimate [2h]")
+
+        self.assertEqual(run_basecamp_json.call_count, 2)
+        get_call, put_call = run_basecamp_json.call_args_list
+
+        self.assertEqual(
+            get_call.args,
+            (
+                "basecamp",
+                "api",
+                "get",
+                "https://3.basecampapi.com/1/buckets/2/todos/123.json",
+            ),
+        )
+
+        self.assertEqual(put_call.args[:5], (
+            "basecamp",
+            "api",
+            "put",
+            "https://3.basecampapi.com/1/buckets/2/todos/123.json",
+            "-d",
+        ))
+        body = json.loads(put_call.args[5])
+        self.assertEqual(body["content"], "Ship estimate [2h]")
+        self.assertEqual(body["description"], "<div>Original notes with image</div>")
+        self.assertEqual(body["assignee_ids"], [7, 8])
+        self.assertEqual(body["completion_subscriber_ids"], [9])
+        self.assertEqual(body["due_on"], "2026-05-01")
+        self.assertNotIn("starts_on", body)
+
+    def test_omits_fields_absent_from_current_todo(self) -> None:
+        todo = MODULE.TodoItem(
+            id="123",
+            title="Ship estimate",
+            api_url="https://3.basecampapi.com/1/buckets/2/todos/123.json",
+        )
+        current_payload = {
+            "id": 123,
+            "content": "Ship estimate",
+            "description": "",
+            "assignees": [],
+            "completion_subscribers": [],
+            "due_on": None,
+            "starts_on": None,
+        }
+
+        with mock.patch.object(MODULE, "run_basecamp_json") as run_basecamp_json:
+            run_basecamp_json.side_effect = [current_payload, {}]
+            MODULE.update_basecamp_title("basecamp", todo, "Ship estimate [2h]")
+
+        put_call = run_basecamp_json.call_args_list[1]
+        body = json.loads(put_call.args[5])
+        self.assertEqual(body, {"content": "Ship estimate [2h]"})
+
+    def test_rejects_missing_basecamp_api_url(self) -> None:
+        todo = MODULE.TodoItem(id="123", title="Ship estimate")
+
+        with self.assertRaises(MODULE.ScriptError) as caught:
+            MODULE.update_basecamp_title("basecamp", todo, "Ship estimate [2h]")
+
+        self.assertIn("did not include an API URL", str(caught.exception))
+
+
+class BuildBasecampUpdatePayloadTest(unittest.TestCase):
+    def test_extracts_assignee_and_subscriber_ids_and_preserves_dates(self) -> None:
+        current = {
+            "content": "Old",
+            "description": "<p>note</p>",
+            "assignees": [{"id": 1}, {"id": 2}],
+            "completion_subscribers": [{"id": 3}],
+            "due_on": "2026-05-01",
+            "starts_on": "2026-04-01",
+        }
+
+        payload = MODULE.build_basecamp_update_payload(current, "New title")
+
+        self.assertEqual(
+            payload,
+            {
+                "content": "New title",
+                "description": "<p>note</p>",
+                "assignee_ids": [1, 2],
+                "completion_subscriber_ids": [3],
+                "due_on": "2026-05-01",
+                "starts_on": "2026-04-01",
+            },
+        )
+
+    def test_skips_empty_or_missing_fields(self) -> None:
+        payload = MODULE.build_basecamp_update_payload({"content": "Old"}, "New title")
+
+        self.assertEqual(payload, {"content": "New title"})
+
 
 if __name__ == "__main__":
     unittest.main()

package/skills/pull-request/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: pull request
+name: pull-request
 description: Generates well-structured GitHub pull request descriptions for Shopify theme development teams by analyzing git diffs and gathering context. Use this skill whenever a developer asks to create a PR, open a pull request, write a PR description, or submit code for review — even if they just say "make a PR" or "create a pull request". Also trigger when someone mentions needing a PR title, PR summary, or PR testing steps.
 ---
 

package/skills/pull-request-statamic/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: pull-request-statamic
+description: Generates GitHub pull request descriptions for Statamic and Laravel development by analyzing git diffs and gathering context.
+---
+
+# PR Description Generator
+
+Helps Statamic and Laravel developers create well-structured pull request descriptions by analyzing code changes and collecting context. Follow these steps in order.
+
+---
+
+## Step 1: Get Branch Info
+
+Ask the developer for:
+
+1. **Source branch** — the feature/fix branch with their changes
+2. **Target branch** — the branch to merge into (e.g. `main`, `develop`, `release/x.x`)
+
+---
+
+## Step 2: Analyze the Diff
+
+Run this command to fetch and diff the branches:
+
+```bash
+git fetch origin && git diff origin/{target_branch}...origin/{source_branch}
+```
+
+Analyze the diff for:
+
+- Files changed, added, or deleted
+- Nature of changes (feature, bug fix, refactor, styling, etc.)
+- Key implementation details and patterns
+- Potential impacts or side effects
+- Testable and user-facing changes
+
+### Statamic-Specific Analysis Guide
+
+| File Type | What to Look For | Testing Implications |
+| --------- | ---------------- | -------------------- |
+| `resources/views/**/*.antlers.html` | Template conditionals, partial usage, cascade values, collection/global references | Tests cover each affected page type and content state |
+| `resources/fieldsets/*.yaml`, `resources/blueprints/**/*.yaml` | New fields, validation rules, display conditions, defaults | Render tests confirm content |
+| `config/*.php`, `routes/*.php` | Environment-sensitive behavior, routing changes, feature flags | Test affected routes and relevant config-dependent scenarios |
+| `app/**/*.php` | Controllers, listeners, view models, tags, commands, queries | Exercise the feature path and likely failure states |
+| `resources/js/**/*`, `resources/css/**/*`, `vite.config.*` | Interactive behavior, asset bundling, responsive styling | Test interactions, breakpoints |
+| `lang/**/*`, `resources/lang/**/*` | New translation keys or copy changes | Verify translated strings appear correctly in each locale |
+
+---
+
+## Step 3: Generate PR Content
+
+Based on the diff, generate:
+
+### PR Title
+
+Concise and descriptive. Use conventional commit style where appropriate (`feat:`, `fix:`, `refactor:`, `chore:`).
+
+### PR Summary
+
+1–2 sentences in plain, non-technical language describing what the changes accomplish from a user/business perspective.
+
+### Approach
+
+Technical description covering:
+
+- Key files modified and why
+- Implementation strategy
+- Notable patterns or techniques
+- Trade-offs or decisions made
+
+### Testing Steps
+
+Generate comprehensive, grouped testing steps as checkboxes. Cover all relevant categories:
+
+**Functional Testing**
+
+- New features or modified behavior
+- Form inputs, buttons, interactive elements
+- Conditional logic and different states
+
+**Visual/UI Testing**
+
+- Layout across breakpoints (mobile, tablet, desktop)
+- New or modified CSS
+- Template output across affected entry types and content states
+- Hover states, transitions, animations
+
+**Control Panel Testing**
+
+- New blueprint or fieldset fields
+- Validation rules and default values
+- Replicator/grid/set add/remove/reorder behavior
+
+**Edge Cases**
+
+- Empty states (no content, no images)
+- Maximum content (long text, many items)
+- Missing or broken assets
+
+**Accessibility**
+
+- Keyboard navigation
+- Screen reader compatibility
+- Focus states and tab order
+- Color contrast
+
+**Browser/Device**
+
+- Cross-browser compatibility
+- Mobile touch interactions
+
+Format example:
+
+```markdown
+**Feature Functionality**
+
+- [ ] Verify the "Show price" toggle appears in the relevant blueprint in the Control Panel
+- [ ] Confirm integration and unit tests pass
+- [ ] Confirm integration and unit tests cover the new feature and any edge cases
+
+**Responsive Behavior**
+
+- [ ] Test on mobile (< 768px) — items should stack vertically
+- [ ] Test on desktop (≥ 768px) — items should display in a grid
+```
+
+---
+
+## Step 4: Collect Additional Info
+
+Ask the developer for the following (cannot be inferred from code):
+
+1. **Basecamp Links** — Links to relevant Basecamp Cards or Todos
+2. **Other Considerations** — Edge cases, known limitations, notes for reviewers
+3. **Demo Links** — Preview URL
+
+Then present the generated testing steps and ask:
+
+- Any steps to remove (not applicable)?
+- Any additional scenarios to add?
+- Any specific test data or configuration needed?
+
+---
+
+## Step 5: Review & Confirm
+
+Present the complete PR description to the developer for final review. Ask them to confirm it's accurate or request changes.
+
+---
+
+## Step 6: Create the Pull Request
+
+Once confirmed, create the PR with GitHub CLI:
+
+```bash
+gh pr create \
+  --base "{target_branch}" \
+  --head "{source_branch}" \
+  --title "{auto_generated_title}" \
+  --body "{generated_pr_body}"
+```
+
+- **On success**: Share the PR URL with the developer.
+- **On failure**: Display the error and troubleshoot:
+    - Not authenticated → `gh auth status` / `gh auth login`
+    - Branch not pushed → `git push -u origin {source_branch}`
+    - No commits between branches → inform developer
+    - PR already exists → provide link to existing PR
+
+---
+
+## PR Body Template
+
+Use this exact format for the `--body` parameter:
+
+```markdown
+### PR Summary:
+
+{auto_generated_summary}
+
+### Tasks Included?
+
+{basecamp_links}
+
+### What approach did you take?
+
+{auto_generated_approach}
+
+### Other considerations
+
+{considerations}
+
+### Testing steps/scenarios
+
+{auto_generated_and_reviewed_testing_steps_as_checkboxes}
+
+### Demo links
+
+- [Site]({site_url})
+- [Editor]({site_url/cp})
+
+### Additional Information
+
+{additional_info}
+```
+
+---
+
+## Workflow Summary
+
+1. Ask for source and target branches
+2. Fetch and analyze the diff
+3. Generate title, summary, approach, and testing steps
+4. Collect Basecamp links, demo URLs, and other info; review testing steps
+5. Present complete PR for final confirmation
+6. Create the PR with `gh pr create` and share the URL

package/skills/pull-request-statamic/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+    display_name: 'Pull Request (Statamic)'
+    short_description: 'Create a pull request'
+    default_prompt: 'Use $pull-request to create a pull request.'