@avantmedia/af 0.0.1

package/router.ts

@@ -0,0 +1,220 @@
+import { handleBunUpgrade } from './commands/bun.ts';
+import { handleChanges } from './commands/changes.ts';
+import { handleE2e } from './commands/e2e.ts';
+import { handleHelp } from './commands/help.ts';
+import { handleInstallExtension } from './commands/install-extension.ts';
+import { handleJira } from './commands/jira.ts';
+import { handleLicenses } from './commands/licenses.ts';
+import { handleNpmUpgrade } from './commands/npm.ts';
+import { handleScaffold } from './commands/scaffold.ts';
+import { handleSetup } from './commands/setup.tsx';
+import {
+    handleCommitApply,
+    handleCommitSave,
+    handleSpecApply,
+    handleSpecArchive,
+    handleSpecPropose,
+} from './commands/spec.ts';
+import { handleStopHook } from './commands/stop-hook.ts';
+import { handleTodo } from './commands/todo.ts';
+import { handleVersionsPush, handleVersionsReset } from './commands/versions.ts';
+import { handleWatch } from './commands/watch.ts';
+import { handleWorktree } from './commands/worktree.ts';
+import { error } from './utils/output.ts';
+
+/**
+ * Route command-line arguments to the appropriate command handler.
+ * Parses the command structure and delegates to command modules.
+ *
+ * @param args - Command-line arguments (excluding node executable and script path)
+ * @returns Exit code (0 for success, 1 for error)
+ */
+export async function route(args: string[]): Promise<number> {
+    // Handle no arguments - show help
+    if (args.length === 0) {
+        return await handleHelp();
+    }
+
+    const [command, subcommand] = args;
+
+    // Handle --help and -h flags
+    if (command === '--help' || command === '-h') {
+        return await handleHelp();
+    }
+
+    // Handle command-specific --help flag
+    if (subcommand === '--help' || subcommand === '-h') {
+        return await handleHelp(command);
+    }
+
+    // Route npm commands
+    if (command === 'npm') {
+        if (subcommand === 'upgrade') {
+            return await handleNpmUpgrade();
+        } else if (!subcommand) {
+            error('Error: npm command requires a subcommand');
+            console.error("Run 'af help npm' for more information.");
+            return 1;
+        } else {
+            error(`Error: Unknown npm subcommand: ${subcommand}`);
+            console.error("Run 'af help npm' for available subcommands.");
+            return 1;
+        }
+    }
+
+    // Route bun commands
+    if (command === 'bun') {
+        if (subcommand === 'upgrade') {
+            return await handleBunUpgrade();
+        } else if (!subcommand) {
+            error('Error: bun command requires a subcommand');
+            console.error("Run 'af help bun' for more information.");
+            return 1;
+        } else {
+            error(`Error: Unknown bun subcommand: ${subcommand}`);
+            console.error("Run 'af help bun' for available subcommands.");
+            return 1;
+        }
+    }
+
+    // Route spec commands
+    if (command === 'spec') {
+        if (subcommand === 'apply') {
+            const changeId = args[2];
+            return await handleSpecApply(changeId);
+        } else if (subcommand === 'archive') {
+            const specId = args[2];
+            return await handleSpecArchive(specId);
+        } else if (subcommand === 'propose') {
+            const proposalText = args.slice(2).join(' ');
+            return await handleSpecPropose(proposalText);
+        } else if (!subcommand) {
+            error('Error: spec command requires a subcommand');
+            console.error("Run 'af help spec' for more information.");
+            return 1;
+        } else {
+            error(`Error: Unknown spec subcommand: ${subcommand}`);
+            console.error("Run 'af help spec' for available subcommands.");
+            return 1;
+        }
+    }
+
+    // Route commit commands
+    if (command === 'commit') {
+        if (subcommand === 'save') {
+            // commit save "<message>" [Key=Value...]
+            const message = args[2];
+            const trailerArgs = args.slice(3);
+            return handleCommitSave(message, trailerArgs);
+        } else if (subcommand === 'apply' || !subcommand) {
+            // Both 'commit apply' and 'commit' (shorthand) do the same thing
+            const changeId = subcommand === 'apply' ? args[2] : args[1];
+            return await handleCommitApply(changeId);
+        } else {
+            error(`Error: Unknown commit subcommand: ${subcommand}`);
+            console.error("Run 'af help commit' for available subcommands.");
+            return 1;
+        }
+    }
+
+    // Route shorthand commands
+    if (command === 'apply') {
+        const changeId = args[1];
+        return await handleSpecApply(changeId);
+    }
+
+    if (command === 'propose') {
+        const proposalText = args.slice(1).join(' ');
+        return await handleSpecPropose(proposalText);
+    }
+
+    if (command === 'archive') {
+        const specId = args[1];
+        return await handleSpecArchive(specId);
+    }
+
+    if (command === 'changes') {
+        // Pass true if any additional arguments were provided
+        const hasArgs = args.length > 1;
+        return await handleChanges(hasArgs);
+    }
+
+    // Route e2e command
+    if (command === 'e2e') {
+        return await handleE2e(args.slice(1));
+    }
+
+    // Route stop-hook command
+    if (command === 'stop-hook') {
+        return await handleStopHook();
+    }
+
+    if (command === 'todo') {
+        // Pass true if any additional arguments were provided
+        const hasArgs = args.length > 1;
+        return await handleTodo(hasArgs);
+    }
+
+    if (command === 'watch') {
+        // Pass true if any additional arguments were provided
+        const hasArgs = args.length > 1;
+        return await handleWatch(hasArgs);
+    }
+
+    // Route jira commands
+    if (command === 'jira') {
+        return await handleJira(args.slice(1));
+    }
+
+    // Route versions commands
+    if (command === 'versions') {
+        if (subcommand === 'reset') {
+            return await handleVersionsReset();
+        } else if (subcommand === 'push') {
+            return await handleVersionsPush();
+        } else if (!subcommand) {
+            error('Error: versions command requires a subcommand');
+            console.error("Run 'af help versions' for more information.");
+            return 1;
+        } else {
+            error(`Error: Unknown versions subcommand: ${subcommand}`);
+            console.error("Run 'af help versions' for available subcommands.");
+            return 1;
+        }
+    }
+
+    // Route help command
+    if (command === 'help') {
+        return await handleHelp(subcommand);
+    }
+
+    // Route licenses command
+    if (command === 'licenses') {
+        return await handleLicenses();
+    }
+
+    // Route scaffold command
+    if (command === 'scaffold') {
+        return handleScaffold(args.slice(1));
+    }
+
+    // Route setup command
+    if (command === 'setup') {
+        return await handleSetup(args.slice(1));
+    }
+
+    // Route install-extension command
+    if (command === 'install-extension') {
+        return await handleInstallExtension();
+    }
+
+    // Route worktree command
+    if (command === 'worktree') {
+        return await handleWorktree(args.slice(1));
+    }
+
+    // Unknown command
+    error(`Error: Unknown command: ${command}`);
+    console.error("Run 'af help' to see all available commands.");
+    return 1;
+}

package/setup/.claude/commands/commit-work.md

@@ -0,0 +1,47 @@
+---
+name: Commit Work
+description: Commit all changes with the OpenSpec proposal title and ID as a trailer.
+category: Workflow
+tags: [git, openspec, workflow]
+---
+
+**Usage**
+
+```
+/commit-work [openspec-id] [title]
+```
+
+Examples:
+- `/commit-work` — Uses the ID and title from context
+- `/commit-work add-user-auth "Add User Authentication"` — Uses provided arguments
+
+**Steps**
+
+1. **Determine OpenSpec ID and title:**
+   - If arguments are provided, use them
+   - If you are currently working on an OpenSpec, use that ID and title
+   - Otherwise:
+     1. Run `openspec list` to find active changes
+     2. If exactly one active change exists, use that ID
+     3. If multiple changes exist, ask the user which one to use
+     4. If no changes exist, ask the user for the ID and title
+     5. Extract the title from the first heading in `openspec/changes/<id>/proposal.md`
+
+2. **Archive the OpenSpec change (if not already archived):**
+   - Check if `openspec/changes/<id>/` directory exists
+   - If it exists, perform the OPSX archive workflow:
+     1. Check artifact completion: `openspec status --change "<id>" --json`
+     2. Check task completion: read `openspec/changes/<id>/tasks.md`, count `- [ ]` vs `- [x]`
+     3. Check for delta specs at `openspec/changes/<id>/specs/` — if they exist, perform agent-driven sync to main specs (same as `/opsx:sync`)
+     4. Archive: `mkdir -p openspec/changes/archive && mv openspec/changes/<id> openspec/changes/archive/YYYY-MM-DD-<id>`
+     5. Ensure everything meets the project's formatting rules (run `bun run format` if needed)
+   - If the directory does not exist (already archived), skip this step
+
+3. Run the following command to stage all changes and create a commit:
+   ```bash
+   af commit save "<title>" OpenSpec-Id=<openspec-id>
+   ```
+
+**Reference**
+
+- Run `af help commit` for commit subcommand options

package/setup/.claude/commands/complete-work.md

@@ -0,0 +1,34 @@
+---
+name: Complete Work
+description: Archive an OpenSpec change and transition the Jira issue to Done.
+category: Workflow
+tags: [jira, openspec, workflow]
+---
+
+**Usage**
+
+```
+/complete-work <issue-key>
+```
+
+Example: `/complete-work MUSH-123`
+
+**Steps**
+
+1. Fetch the issue details using `af jira get <issue-key>` to verify it exists and get the summary.
+2. Find the associated OpenSpec change by searching `openspec/changes/*/proposal.md` files for the issue key using grep or by running `openspec list` and checking which change references this issue.
+3. Archive the OpenSpec change using the OPSX workflow:
+   1. Check artifact completion: `openspec status --change "<change-id>" --json`
+      - If incomplete artifacts, warn but continue
+   2. Check task completion: read `openspec/changes/<change-id>/tasks.md`, count `- [ ]` vs `- [x]`
+      - If incomplete tasks, warn but continue
+   3. Check for delta specs at `openspec/changes/<change-id>/specs/`
+      - If delta specs exist, perform agent-driven sync to main specs (same as `/opsx:sync`)
+   4. Archive: `mkdir -p openspec/changes/archive && mv openspec/changes/<change-id> openspec/changes/archive/YYYY-MM-DD-<change-id>`
+4. Run the following command: `./scripts/create-commit.sh "<issue-summary>" "<issue-key>"` where `<issue-summary>` is derived from the Jira issue. This adds the issue key as a commit trailer.
+6. Transition the issue to "Done" using `af jira transition <issue-key> --to "Done"`. If this fails, run `af jira transitions <issue-key>` to find the correct completion status name.
+
+**Reference**
+
+- See `openspec/AGENTS.md` for OpenSpec conventions (Stage 3: Archiving Changes)
+- Run `af jira --help` for Jira CLI options

package/setup/.claude/commands/e2e.md

@@ -0,0 +1,29 @@
+---
+name: Run E2E tests
+description: Run E2E tests and fix any failures
+category: Testing
+tags: [e2e, playwright]
+---
+
+**Guardrails**
+
+- Run only inside Docker via `af e2e` — never run Playwright directly
+- For specific tests: `af e2e npm run e2e -- --grep "pattern"`
+- For specific files: `af e2e npm run e2e -- tests/Feature.spec.ts`
+
+**Steps**
+
+1. Run `af e2e` (defaults to `--max-failures=1` for fast feedback)
+2. On failure, read the reporter output — it includes error messages, DOM snapshots, and file paths
+3. For deeper debugging, read `./test-results/*/error-context.md` for full page state
+4. Fix the code or test
+5. If the failure is a visual regression from an intentional change, update baselines:
+   `af e2e npm run e2e -- --update-snapshots`
+6. Use `--grep "pattern"` to iterate faster on the specific failing test
+7. Once the targeted test passes, run the full suite without `--grep` to confirm nothing else broke
+
+**Reference**
+
+- Use the `e2e-testing` skill for test patterns, selectors, and debugging tips
+- HTML report: `./playwright-report/index.html`
+- Trace files: `./test-results/*/trace.zip`

package/setup/.claude/commands/start-work.md

@@ -0,0 +1,51 @@
+---
+name: Start Work
+description: Assign a Jira issue to yourself and convert it into an OpenSpec proposal.
+category: Workflow
+tags: [jira, openspec, workflow]
+---
+
+**Usage**
+
+```
+/start-work [issue-key]
+```
+
+Examples:
+- `/start-work` — Takes the topmost issue from the backlog
+- `/start-work MUSH-123` — Uses the specified issue
+
+**Steps**
+
+0. **If no issue-key is provided**, fetch the topmost issue from the backlog:
+   1. Detect project key by running `af jira projects --json`
+      - If single project: use it
+      - If multiple projects: ask the user to choose
+   2. Fetch the topmost backlog issue using:
+      ```bash
+      af jira search "project = <PROJECT> AND status = Backlog ORDER BY priority DESC, created ASC" --limit 1 --json
+      ```
+   3. Display the issue summary and ask the user for confirmation before proceeding
+   4. If no backlog issues found: inform the user the backlog is empty and stop
+1. Fetch the issue details using `af jira get <issue-key>`.
+2. Assign the issue to yourself using `af jira assign <issue-key> --to $(af jira get <issue-key> --json | jq -r '.reporter.emailAddress')` — but first check who the current user is by looking at the Jira config or asking.
+3. Transition the issue to "In Progress" using `af jira transition <issue-key> --to "In Progress"`. If this fails, run `af jira transitions <issue-key>` to find the correct status name.
+4. Create an OpenSpec change using the artifact workflow:
+   - Derive a `change-id` from the issue key and summary (kebab-case, verb-led)
+   - Create the change: `openspec new change "<change-id>"`
+   - Get the artifact status: `openspec status --change "<change-id>" --json`
+   - Get proposal artifact instructions: `openspec instructions proposal --change "<change-id>" --json`
+   - Create the proposal artifact using the template from instructions, enriching it with:
+     - Jira issue link: `**Jira**: [ISSUE-KEY](jira-url)`
+     - Why section derived from Jira issue description
+     - What Changes derived from issue details
+   - Show the updated status
+5. **STOP and hand off to OPSX workflow**
+
+   Suggest: "Proposal created. Run `/opsx:continue` to create the next artifact, or `/opsx:ff` to generate all remaining artifacts."
+
+**Reference**
+
+- See `openspec/AGENTS.md` for OpenSpec conventions
+- Run `af jira --help` for Jira CLI options
+- See `/opsx:new` and `/opsx:ff` for the full artifact workflow

package/setup/.claude/skills/pm/SKILL.md

@@ -0,0 +1,294 @@
+---
+name: pm
+description: Project management workflows for sprint planning, epic breakdowns, progress reporting, and backlog grooming. Uses the jira skill for all Jira operations.
+---
+
+# Project Manager Skill
+
+High-level project management workflows that use the Jira CLI (`jira` skill) for operations.
+
+## When to Use This Skill
+
+Use the PM skill when the user wants to:
+- Plan sprints or prioritize backlog items
+- Break down epics or features into tasks
+- Generate progress reports or standup summaries
+- Identify risks (overdue, blocked, stale issues)
+- Get project context for informed planning decisions
+- Groom or refine the backlog
+
+For individual issue operations (get, update, transition, comment), use the `jira` skill directly.
+
+## Prerequisites
+
+The `jira` skill must be configured. See `.claude/skills/jira/SKILL.md` for setup.
+
+## Sub-Agent Behavior
+
+When acting as a PM sub-agent, follow these guidelines:
+
+### 1. Always Load Context First
+
+Before planning or making recommendations, gather project state:
+
+```bash
+# Get open sprint issues
+af jira search "project = PROJ AND sprint in openSprints() ORDER BY priority DESC"
+
+# Check for blockers
+af jira search "project = PROJ AND (status = Blocked OR labels = blocked)"
+
+# Recent activity (last 48h)
+af jira search "project = PROJ AND updated >= -2d ORDER BY updated DESC"
+```
+
+### 2. Use Templates for Consistency
+
+When breaking down work, use templates from `.claude/skills/pm/templates/`:
+- `api-endpoint.md` - REST/GraphQL endpoint implementation
+- `ui-component.md` - React component development
+- `bug-fix.md` - Bug investigation and fix
+- `feature.md` - General feature implementation
+
+### 3. Validate Before Executing
+
+For bulk operations (creating multiple issues, updating priorities):
+1. Show the user what will be created/modified
+2. Wait for confirmation before executing
+3. Execute one operation at a time, reporting progress
+
+### 4. Track Dependencies
+
+When creating related tasks, use Jira linking:
+- Parent/subtask relationships via `--parent` flag
+- Note blocking relationships in descriptions
+
+### 5. Report on Completion
+
+After multi-step workflows, provide a summary:
+- What was created/modified
+- Any issues encountered
+- Next recommended actions
+
+## Workflows
+
+### Load Project Context
+
+Gather comprehensive project state before planning:
+
+```bash
+# 1. Active sprint overview
+af jira search "project = PROJ AND sprint in openSprints() ORDER BY status ASC, priority DESC" --limit 50
+
+# 2. Blocked issues requiring attention
+af jira search "project = PROJ AND (status = Blocked OR labels = blocked) ORDER BY priority DESC"
+
+# 3. Upcoming deadlines (next 7 days)
+af jira search "project = PROJ AND duedate >= now() AND duedate <= 7d AND status != Done ORDER BY duedate ASC"
+
+# 4. Unassigned high-priority items
+af jira search "project = PROJ AND assignee IS EMPTY AND priority in (Highest, High) ORDER BY created ASC"
+```
+
+Present findings organized by:
+- Sprint progress (done/in-progress/todo counts)
+- Blockers requiring attention
+- Upcoming deadlines
+- Unassigned work
+
+### Sprint Planning
+
+Help plan upcoming sprints:
+
+```bash
+# 1. Check current sprint velocity (completed in last sprint)
+af jira search "project = PROJ AND sprint in closedSprints() AND status = Done ORDER BY resolutiondate DESC" --limit 30
+
+# 2. Get backlog candidates (not in any sprint, prioritized)
+af jira search "project = PROJ AND sprint IS EMPTY AND status = Backlog ORDER BY priority DESC, created ASC" --limit 30
+
+# 3. Check team capacity (assigned work)
+af jira search "project = PROJ AND assignee IS NOT EMPTY AND status != Done"
+```
+
+Planning steps:
+1. Calculate velocity from recent sprints
+2. Present top backlog items with estimates
+3. Suggest sprint composition based on capacity
+4. Create issues or move items to sprint after confirmation
+
+### Epic Breakdown
+
+Break down an epic into implementable tasks:
+
+```bash
+# 1. Get epic details
+af jira get PROJ-123
+
+# 2. Check for existing subtasks
+af jira search "parent = PROJ-123"
+```
+
+Breakdown process:
+1. Read the epic description and acceptance criteria
+2. Select appropriate template from `.claude/skills/pm/templates/`
+3. Generate subtask list with estimates
+4. Present for review
+5. Create subtasks after confirmation:
+
+```bash
+af jira create --project PROJ --type Sub-task --summary "Task title" --parent PROJ-123
+```
+
+### Progress Report
+
+Generate status reports:
+
+**Daily Report:**
+```bash
+# Completed yesterday
+af jira search "project = PROJ AND status changed to Done AFTER -1d"
+
+# In progress today
+af jira search "project = PROJ AND status = 'In Progress' ORDER BY assignee"
+
+# Blocked
+af jira search "project = PROJ AND (status = Blocked OR labels = blocked)"
+```
+
+**Weekly Report:**
+```bash
+# Completed this week
+af jira search "project = PROJ AND status changed to Done AFTER -7d ORDER BY resolutiondate DESC"
+
+# Created this week
+af jira search "project = PROJ AND created >= -7d ORDER BY created DESC"
+
+# Scope changes (added to sprint mid-week)
+af jira search "project = PROJ AND sprint in openSprints() AND created >= -7d"
+```
+
+**Sprint Report:**
+```bash
+# Sprint completion
+af jira search "project = PROJ AND sprint in openSprints()" --limit 100
+
+# Calculate: done / total issues
+# Identify: carried over items, added mid-sprint items
+```
+
+### Standup Summary
+
+Generate daily standup content from Jira activity:
+
+```bash
+# Done (status changed to Done in last 24h)
+af jira search "project = PROJ AND status changed to Done AFTER -1d"
+
+# In Progress (currently being worked on)
+af jira search "project = PROJ AND status = 'In Progress' AND assignee = currentUser()"
+
+# Blockers
+af jira search "project = PROJ AND (status = Blocked OR labels = blocked) AND assignee = currentUser()"
+```
+
+Format as:
+- **Done**: [list of completed items]
+- **Today**: [list of in-progress items]
+- **Blockers**: [list of blocked items with reasons]
+
+### Risk Identification
+
+Find issues that need attention:
+
+```bash
+# Overdue (past due date, not done)
+af jira search "project = PROJ AND duedate < now() AND status != Done ORDER BY duedate ASC"
+
+# Stale (no updates in 7+ days, not done)
+af jira search "project = PROJ AND status != Done AND updated < -7d ORDER BY updated ASC"
+
+# Blocked
+af jira search "project = PROJ AND (status = Blocked OR labels = blocked)"
+
+# Scope creep (added to sprint after start)
+af jira search "project = PROJ AND sprint in openSprints() AND created >= startOfSprint()"
+
+# Under-resourced (unassigned high priority)
+af jira search "project = PROJ AND assignee IS EMPTY AND priority in (Highest, High) AND status != Done"
+```
+
+Categorize and present:
+- **Critical**: Overdue items, high-priority blockers
+- **Warning**: Stale items, scope creep indicators
+- **Attention**: Unassigned high-priority work
+
+### Backlog Grooming
+
+Help prioritize and refine backlog:
+
+```bash
+# Get backlog items
+af jira search "project = PROJ AND sprint IS EMPTY AND status = Backlog ORDER BY created ASC" --limit 50
+
+# Check for duplicates or related items
+af jira search "project = PROJ AND summary ~ 'keyword'"
+```
+
+Grooming activities:
+1. Review items for clarity and completeness
+2. Suggest priority adjustments based on:
+   - Age (older items may need re-evaluation)
+   - Dependencies (blocking other work)
+   - Business value indicators in description
+3. Identify candidates for archiving (very old, low priority)
+4. Flag items needing more detail
+
+To update priority after confirmation:
+```bash
+af jira update PROJ-123 --priority High
+```
+
+### Dependency Analysis
+
+Map dependencies for an issue:
+
+```bash
+# Get issue with links
+af jira get PROJ-123
+
+# Find related issues by summary/labels
+af jira search "project = PROJ AND (summary ~ 'related-keyword' OR labels = related-label)"
+
+# Find potential blockers (same component, earlier in pipeline)
+af jira search "project = PROJ AND component = 'Component' AND status != Done"
+```
+
+Present as:
+- **Blocks**: Issues this blocks
+- **Blocked by**: Issues blocking this
+- **Related**: Similar or dependent work
+
+## JQL Quick Reference
+
+Common queries for project management:
+
+| Purpose | JQL |
+|---------|-----|
+| My open issues | `assignee = currentUser() AND status != Done` |
+| Open sprint | `project = PROJ AND sprint in openSprints()` |
+| Blocked | `project = PROJ AND (status = Blocked OR labels = blocked)` |
+| Overdue | `project = PROJ AND duedate < now() AND status != Done` |
+| Stale (7d) | `project = PROJ AND status != Done AND updated < -7d` |
+| Unassigned | `project = PROJ AND assignee IS EMPTY` |
+| High priority | `project = PROJ AND priority in (Highest, High)` |
+| Created this week | `project = PROJ AND created >= -7d` |
+| Done this week | `project = PROJ AND status changed to Done AFTER -7d` |
+| Backlog | `project = PROJ AND sprint IS EMPTY AND status = Backlog` |
+
+## Tips
+
+- **Replace PROJ**: Substitute with actual project key in all queries
+- **Adjust time ranges**: `-7d`, `-2d`, etc. can be customized
+- **Use --json for parsing**: When you need to analyze results programmatically
+- **Combine with jira**: This skill provides workflows; jira provides operations