Develop

.claude/commands/git-workflow.md

@@ -0,0 +1,255 @@
+You are executing the provardx-cli development git workflow. Follow these steps in order. Stop and confirm with the user at each CONFIRM point before proceeding.
+
+---
+
+## Step 0 — Establish the Jira ticket (planning phase)
+
+Ask the user:
+
+> "Do you have a PDX ticket for this work?
+> A) Yes — give me the number
+> B) No — create one now as part of planning
+> C) No ticket needed (framework/chore work)"
+
+---
+
+### Option A — Existing ticket
+
+User provides the ticket number. Set `TICKET = PDX-<number>`.
+
+Fetch the ticket to confirm it exists and read its summary and status:
+
+- Call `getAccessibleAtlassianResources` to get the cloudId for your Jira instance, then use `getJiraIssue` (cloudId: `<from above>`, issueIdOrKey: `PDX-<number>`)
+- Show the user: ticket summary, current status, and URL
+- If the ticket is already Closed, warn the user before proceeding
+
+Skip to **Derive branch variables** below.
+
+---
+
+### Option B — Create ticket now (planning phase)
+
+Ask the user a single compound question to gather everything at once:
+
+> "Tell me about the work — I'll draft the ticket from your answer:
+>
+> 1. What should this change do? (one sentence — becomes the ticket summary)
+> 2. Is it a new feature, bug fix, infrastructure/CI work, research spike, or internal task?
+> 3. Why is it needed? What problem or requirement drives it?
+> 4. How will we know it's done? (acceptance criteria — list conditions)
+> 5. Anything explicitly out of scope?"
+
+From the user's answer, draft the full ticket content. Use your judgment to infer issue type if the user is vague. Do not ask follow-up questions unless a critical field (summary or acceptance criteria) is completely missing.
+
+**Issue type mapping:**
+| Work described | Issue type |
+|----------------|-----------|
+| New user-facing capability | Story |
+| Something broken | Bug |
+| CI, infra, tooling, architecture | Enabler |
+| Research / investigation / prototype | Spike |
+| Internal work, no user impact | Task |
+
+**CONFIRM**: Show the drafted ticket for review before creating:
+
+```
+Summary: <summary>
+Type: <issueTypeName>
+Label: provardx-cli
+
+Description:
+## Background
+<background>
+
+## Acceptance Criteria
+- [ ] <criterion 1>
+- [ ] <criterion 2>
+
+## Notes
+<out of scope / caveats>
+```
+
+> "Does this look right? I'll create the Jira ticket now."
+
+Once confirmed, create the ticket using the `createJiraIssue` MCP tool:
+
+- `cloudId`: `<from getAccessibleAtlassianResources>`
+- `projectKey`: `PDX`
+- `issueTypeName`: as chosen above
+- `summary`: as drafted
+- `description`: full description in markdown
+- `contentFormat`: `markdown`
+- `additional_fields`: `{ "labels": ["provardx-cli"] }`
+
+The tool returns the new ticket key (e.g. `PDX-193`). Set `TICKET = PDX-<returned-number>`.
+
+Show the user: `Ticket created: https://provartesting.atlassian.net/browse/<TICKET>`
+
+---
+
+### Option C — No ticket (PDX-0)
+
+Set `TICKET = PDX-0`. No Jira steps. Use this only for framework chores, internal tooling, or changes with no observable user or system behaviour change.
+
+---
+
+### Derive branch variables
+
+Ask: "What type of change is this? (feature / fix)" — skip if already obvious from the issue type.
+
+Ask for a short branch slug (kebab-case, ≤ 30 chars, no spaces).
+
+Derive:
+
+- `BRANCH_TYPE` = `feature` or `fix`
+- `BRANCH` = `feature/PDX-<number>-<slug>` or `fix/PDX-<number>-<slug>` (or `feature/<slug>` for PDX-0)
+
+**CONFIRM**: "I'll create branch `<BRANCH>` off `develop`. Proceed?"
+
+---
+
+## Step 1 — Create worktree and install dependencies
+
+```sh
+# From the main repo root
+git worktree add .claude/worktrees/<BRANCH> -b <BRANCH> develop
+
+# Install node_modules so husky hooks work — ALWAYS do this in a new worktree
+cd .claude/worktrees/<BRANCH> && yarn install
+```
+
+The `yarn install` step is mandatory. Without it, the pre-commit hook cannot find `wireit` and will fail with "wireit is not recognized".
+
+---
+
+## Step 2 — Implement the change
+
+Work in the worktree at `.claude/worktrees/<BRANCH>/`.
+
+Before every commit attempt, run in the worktree directory:
+
+```sh
+yarn compile
+node_modules/.bin/nyc node_modules/.bin/mocha "test/**/*.test.ts"
+node scripts/mcp-smoke.cjs 2>/dev/null
+yarn lint
+```
+
+Fix any failures before staging. Do not move to Step 3 until all four pass.
+
+---
+
+## Step 3 — Stage and commit
+
+Stage files explicitly — never `git add -A`:
+
+```sh
+git add <file1> <file2> ...
+```
+
+Commit with the required PDX format:
+
+```sh
+git commit -m "$(cat <<'EOF'
+<TICKET>: <type>(<scope>): <subject under 72 chars>
+
+RCA: <at least 40 chars — requirement or root cause>
+Fix: <at least 40 chars — what was implemented or changed>
+EOF
+)"
+```
+
+Valid `type` values: `feat`, `fix`, `test`, `docs`, `chore`, `refactor`
+Valid `scope` values: `mcp`, `prompts`, `resources`, `cli`, `test`, `docs`, `ci`
+
+If the commit-msg hook rejects the message, read the error and fix the message. **Do not use `--no-verify` unless the user explicitly approves it.**
+
+---
+
+## Step 4 — Push and open PR
+
+```sh
+git push -u origin <BRANCH>
+```
+
+The pre-push hook runs `yarn build && yarn test` (60–120 seconds). If it fails, fix the issue, commit the fix (Step 3 format), and push again.
+
+Open the PR:
+
+```sh
+gh pr create \
+  --base develop \
+  --title "<TICKET>: <short description>" \
+  --body "$(cat <<'EOF'
+## Summary
+- <bullet>
+
+## Jira
+https://provartesting.atlassian.net/browse/<TICKET>
+
+## Test plan
+- [ ] yarn compile passes
+- [ ] yarn test:only passes
+- [ ] mcp-smoke.cjs passes
+- [ ] yarn lint passes
+
+## Changes
+- <file>: <what changed>
+EOF
+)"
+```
+
+Omit the `## Jira` section for `PDX-0` work.
+
+**CONFIRM**: Show the user the PR URL and ask: "PR is open. Should I check the Copilot review now?"
+
+---
+
+## Step 5 — Address Copilot review
+
+```sh
+gh pr view <pr-number> --comments
+gh pr checks <pr-number>
+```
+
+For each Copilot comment:
+
+- **Valid concern** → fix in the worktree, commit (Step 3 format), push
+- **Not applicable** → reply explaining why: `gh pr comment <pr-number> --body "..."`
+- **Security comment** → always address; never dismiss without strong justification
+
+---
+
+## Step 6 — Merge and close ticket
+
+**CONFIRM**: "All checks pass. Should I merge the PR?"
+
+```sh
+gh pr merge <pr-number> --squash --delete-branch
+```
+
+For ticketed work (non-PDX-0): transition the Jira ticket to Closed.
+
+- Web: `https://provartesting.atlassian.net/browse/<TICKET>`
+- MCP: `transitionJiraIssue` (cloudId: `<from getAccessibleAtlassianResources>`)
+
+Clean up the worktree:
+
+```sh
+git worktree remove .claude/worktrees/<BRANCH>
+git worktree prune
+```
+
+---
+
+## Hook failures quick-reference
+
+| Hook       | Failure                    | Fix                                                            |
+| ---------- | -------------------------- | -------------------------------------------------------------- |
+| pre-commit | `wireit is not recognized` | Run `yarn install` in the worktree first                       |
+| pre-commit | ESLint violation           | Fix the violation, `git add` the file, retry                   |
+| pre-commit | Prettier                   | Run `yarn pretty-quick --staged`, restage, retry               |
+| commit-msg | Wrong format               | Read error, rewrite message with `git commit --amend -m "..."` |
+| commit-msg | Lines too short            | `RCA:` or `Req:` and `Fix:` each need ≥ 40 characters          |
+| pre-push   | Compile error              | Fix TypeScript error, commit, push again                       |
+| pre-push   | Test failure               | Fix the test, commit, push again                               |

.github/workflows/CI_Execution.yml

@@ -29,7 +29,7 @@ jobs:
       - uses: actions/checkout@v6
         with:
           persist-credentials: false
-      - uses: mrdailey99/QualityOrchestrator@v1.0.0
+      - uses: mrdailey99/QualityOrchestrator@v1
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           test-dir: 'test'

.gitignore

@@ -55,8 +55,11 @@ mochawesome-report
 .env.local
 .env.*.local
 
-# Claude
-.claude/
+# Claude — local-only directories (worktrees, per-dev agent files, gitignored routing index)
+.claude/worktrees/
+.claude/agents/
+AGENTS.md
+# .claude/commands/ is intentionally tracked — project slash commands for Claude Code
 
 # NitroX schema files — do not commit until IP/licensing confirmed with Provar team
 # See: src/mcp/tools/nitroXTools.ts and plan notes

README.md

@@ -39,26 +39,54 @@ Validation runs in two modes: **local only** (structural rules, no key required)
 
 ## Quick setup
 
-**Requires:** Provar Automation IDE installed with an activated license.
+**Requires:** Provar Automation IDE installed with an activated license. Node.js 18–24 must be on your PATH.
 
-```sh
-# 1. Install the plugin — @beta is required for MCP support
-sf plugins install @provartesting/provardx-cli@beta
+### Option A — Zero-install (recommended for Claude Desktop)
 
-# 2. (Optional) Authenticate for full 170+ rule validation
-sf provar auth login
+No prior setup needed. Paste this into your Claude Desktop config file and restart the app:
+
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "provar": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@provartesting/provardx-cli@beta",
+        "mcp",
+        "start",
+        "--allowed-paths",
+        "/path/to/your/provar/project"
+      ]
+    }
+  }
+}
 ```
 
+`npx -y` downloads the package automatically on first use — no `sf` or separate install step required.
+
 **Claude Code** — run once to register the server:
 
 ```sh
-claude mcp add provar -s user -- sf provar mcp start --allowed-paths /path/to/your/provar/project
+claude mcp add provar -s user -- npx -y @provartesting/provardx-cli@beta mcp start --allowed-paths /path/to/your/provar/project
 ```
 
-**Claude Desktop** — add to your config file and restart the app:
+### Option B — Global sf plugin install
 
-- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+Prefer a persistent global install? Install once, then use the `sf` command:
+
+```sh
+# 1. Install the plugin — @beta is required for MCP support
+sf plugins install @provartesting/provardx-cli@beta
+
+# 2. (Optional) Authenticate for full 170+ rule validation
+sf provar auth login
+```
+
+**Claude Desktop** config using the global install:
 
 ```json
 {
@@ -73,6 +101,12 @@ claude mcp add provar -s user -- sf provar mcp start --allowed-paths /path/to/yo
 
 > **Windows (Claude Desktop):** Use `sf.cmd` instead of `sf` if the server fails to start.
 
+**Claude Code** using the global install:
+
+```sh
+claude mcp add provar -s user -- sf provar mcp start --allowed-paths /path/to/your/provar/project
+```
+
 📖 **[docs/mcp.md](https://github.com/ProvarTesting/provardx-cli/blob/main/docs/mcp.md) — full setup, all 35+ tools, 7 MCP prompts, troubleshooting.**
 
 ---