@agilno-tech/rivet 0.1.0-alpha.0

package/dist/mandatory/create-pr-and-commit/SKILL.md

@@ -0,0 +1,304 @@
+---
+name: rivet-create-pr-and-commit
+description: "Full workflow to commit staged changes, push the branch, open a pull request on Bitbucket,"
+---
+
+# Create PR and Commit
+
+Full workflow to commit staged changes, push the branch, open a pull request on Bitbucket,
+and move the linked Jira ticket to In Review — with correct branch naming, commit message
+format, and a generated PR title and description.
+
+## Usage
+
+```
+/create-pr-and-commit
+```
+
+---
+
+## Instructions
+
+### Step 1 — Check the current branch
+
+**Guard — verify Bitbucket remote and derive repo slug:**
+```bash
+BB_REMOTE=$(git remote get-url origin 2>/dev/null)
+if [[ "$BB_REMOTE" != *bitbucket.org* ]]; then
+  echo "This skill requires a Bitbucket remote. Detected: $BB_REMOTE"
+  exit 1
+fi
+BB_SLUG=$(echo "$BB_REMOTE" | sed 's|.*bitbucket\.org[:/]\(.*\)\.git|\1|; s|.*bitbucket\.org[:/]\(.*\)|\1|')
+```
+
+```bash
+git branch --show-current
+```
+
+- If already on a feature or fix branch (not `main`, `develop`, or `release/*`):
+  - Extract the ticket key using the pattern `[A-Z]+-\d+` (e.g. `PROJ-123`, `BC-7`)
+  - If no ticket key is found, ask the user for it
+  - Skip to Step 3
+- If on `main`, `develop`, or `release/*` — proceed to Step 2 to create a branch first
+
+---
+
+### Step 2 — Create a branch
+
+Branch naming:
+- Feature work: `feature/<JIRA-KEY>/<short-description>`
+- Bug fix: `fix/<JIRA-KEY>/<short-description>`
+- `<short-description>`: 2–5 words, lowercase, hyphen-separated, derived from the ticket title or staged changes
+
+Ask the user for the ticket key if not already known, then:
+
+```bash
+git checkout -b feature/<JIRA-KEY>/<short-description>
+```
+
+---
+
+### Step 3 — Stage and commit
+
+Check what is staged and unstaged:
+
+```bash
+git status
+git diff --stat
+```
+
+If there are unstaged changes, ask the user which files to include before staging anything.
+Never run `git add .` or `git add -A` without confirmation.
+
+Commit message format: `type(JIRA-KEY): short imperative description`
+
+- Types: `feat`, `fix`, `refactor`, `docs`, `style`, `perf`, `chore`, `ci`, `build`, `test`
+- JIRA-KEY: uppercase (e.g. `PROJ-123`)
+- Description: lowercase, imperative, under 72 chars total
+- Examples:
+  - `feat(PROJ-123): add search filter component`
+  - `fix(PROJ-123): resolve null pointer in auth middleware`
+  - `refactor(PROJ-123): extract shared hook for form validation`
+
+Do not add `Co-Authored-By` lines or EOF markers — write only the plain commit message.
+
+```bash
+git commit -m "type(JIRA-KEY): short description"
+```
+
+---
+
+### Step 4 — Push the branch
+
+```bash
+git push -u origin <current-branch>
+```
+
+If the branch is already up to date on remote, the push will be a no-op — proceed to PR creation.
+
+---
+
+### Step 5 — Get Bitbucket credentials
+
+**Credentials:**
+
+macOS:
+```bash
+security find-internet-password -s "bitbucket.org" -g
+```
+Extract the `acct` (→ `$BB_USER`) and `password` (→ `$BB_PASS`) fields.
+
+Linux / Windows or if keychain lookup fails: use `BITBUCKET_USERNAME` and `BITBUCKET_APP_PASSWORD` env vars. If neither source yields credentials, ask the user.
+
+**Write a temporary .netrc file so credentials never appear as shell arguments:**
+```bash
+printf 'machine api.bitbucket.org login %s password %s\n' "$BB_USER" "$BB_PASS" \
+  > /tmp/.bb_netrc && chmod 600 /tmp/.bb_netrc
+```
+
+**Token requirements:** the password must be an Atlassian API token **with scopes**
+(`read:account`, `read:repository`, `read:pullrequest`, `write:pullrequest` — Bitbucket app).
+Unscoped API tokens return 401 on `api.bitbucket.org`.
+
+Do **not** pre-check auth with `GET /2.0/user` — it can return 403 even with a valid scoped
+token. Just attempt the PR creation (Step 8) and handle errors there.
+
+---
+
+### Step 6 — Determine repo slug, target branch, and PR context
+
+**Repo slug** — always derive from the origin remote, never hardcode:
+
+```bash
+git remote get-url origin
+```
+
+Strip the host prefix and `.git` suffix to get `<workspace>/<repo>`:
+- `git@bitbucket.org:_agilno/biocirv-client.git` → `_agilno/biocirv-client`
+- `https://bitbucket.org/_agilno/biocirv-client.git` → `_agilno/biocirv-client`
+
+**Target branch** — the branch this feature branch was created from. Resolve in order:
+
+1. `CLAUDE.md` — a `defaultBranch` / `targetBranch` entry, if present
+2. The branch the current branch diverged from — among the repo's long-lived branches,
+   pick the one closest to HEAD (fewest commits between merge-base and branch tip):
+
+   ```bash
+   for b in dev develop main master; do
+     git show-ref --verify --quiet "refs/remotes/origin/$b" \
+       && echo "$b $(git rev-list --count "$(git merge-base HEAD "origin/$b")..origin/$b")"
+   done | sort -k2 -n | head -1
+   ```
+
+   (e.g. if the repo's default working branch is `dev`, this yields `dev`, not `main`)
+
+3. Fall back to `main`
+
+**Gather context for the PR description:**
+
+```bash
+git fetch origin <target-branch>
+git log origin/<target-branch>...HEAD --oneline
+git diff origin/<target-branch>...HEAD --name-status
+```
+
+Draft:
+- **Title**: `JIRA-KEY: Short imperative description` (under 70 chars) — derived from branch name and commits
+- **Summary**: 2–4 sentences on what changed and why
+- **Changes**: bulleted list grouped by area (backend, frontend, infra, tests)
+- **How to test**: manual or automated verification steps
+- **Screenshots**: include a placeholder section if UI was changed
+- **Risks & rollback**: anything reviewers should watch for
+
+---
+
+### Step 7 — Quality gate check
+
+If `.claude/pre-push-rules.md` exists in the project root and `/pre-push` has not been run
+yet in this session, ask before opening the PR:
+
+> "pre-push hasn't been run yet — run it now before opening the PR, or proceed anyway?"
+
+- If the user asks to run it, run `/pre-push` and report the result. If it finds Critical
+  issues, ask whether to fix them first or proceed to the PR regardless.
+- If the user says proceed anyway, continue to Step 8 without re-prompting.
+
+If `.claude/pre-push-rules.md` does not exist, or `/pre-push` already ran this session, skip
+this step silently.
+
+---
+
+### Step 8 — Create the PR via Bitbucket API
+
+Use the `<repo-slug>` and `<target-branch>` resolved in Step 6.
+
+Check if a reviewer is configured via `BITBUCKET_PR_REVIEWER` env var. If set, include it;
+if not, omit the `reviewers` field entirely.
+
+```bash
+# Without reviewer:
+curl -s --netrc-file /tmp/.bb_netrc \
+  -X POST \
+  -H "Content-Type: application/json" \
+  https://api.bitbucket.org/2.0/repositories/$BB_SLUG/pullrequests \
+  -d '{
+    "title": "<title>",
+    "description": "<description>",
+    "source": { "branch": { "name": "<current-branch>" } },
+    "destination": { "branch": { "name": "<target-branch>" } },
+    "close_source_branch": true
+  }'
+
+# With reviewer (when BITBUCKET_PR_REVIEWER is set):
+curl -s --netrc-file /tmp/.bb_netrc \
+  -X POST \
+  -H "Content-Type: application/json" \
+  https://api.bitbucket.org/2.0/repositories/$BB_SLUG/pullrequests \
+  -d '{
+    "title": "<title>",
+    "description": "<description>",
+    "source": { "branch": { "name": "<current-branch>" } },
+    "destination": { "branch": { "name": "<target-branch>" } },
+    "close_source_branch": true,
+    "reviewers": [{ "account_id": "<BITBUCKET_PR_REVIEWER>" }]
+  }'
+```
+
+Return the PR URL from the `links.html.href` field in the response.
+
+**If the API returns 401 (invalid, expired, or unscoped token):**
+
+Tell the user to create a scoped API token and update the keychain:
+
+1. Go to <https://id.atlassian.com/manage-profile/security/api-tokens>
+2. **Create API token with scopes** → app **Bitbucket** → scopes `read:account`,
+   `read:repository`, `read:pullrequest`, `write:pullrequest`
+3. Store it in the keychain:
+
+   ```bash
+   security add-internet-password -U -s "bitbucket.org" -a "<email>" -w "<token>"
+   ```
+
+   (On Linux/Windows, update the `BITBUCKET_APP_PASSWORD` env var instead.)
+
+Then retry the PR creation.
+
+---
+
+### Step 9 — Move Jira ticket to In Review
+
+If Atlassian MCP is unavailable, skip this step silently.
+
+Fetch the current ticket status:
+```
+mcp__claude_ai_Atlassian__getJiraIssue  →  fields.status.name
+```
+
+If the status is already `In Review` (or equivalent — `Code Review`, `Under Review`), skip.
+
+Otherwise fetch available transitions:
+```
+mcp__claude_ai_Atlassian__getTransitionsForJiraIssue  (issueIdOrKey: <JIRA-KEY>)
+```
+
+Find the transition whose name matches `In Review`, `Code Review`, or `Under Review`
+(case-insensitive). If found, apply it:
+```
+mcp__claude_ai_Atlassian__transitionJiraIssue  (issueIdOrKey: <JIRA-KEY>, transitionId: <id>)
+```
+
+If no matching transition is found, note it to the user:
+> "Could not find an 'In Review' transition for <JIRA-KEY> — move it manually."
+
+---
+
+### Step 10 — Clean up credentials
+
+```bash
+rm -f /tmp/.bb_netrc
+```
+
+---
+
+## Inconsistency signals — always stop and ask
+
+| Signal | What to ask |
+|---|---|
+| No ticket key found in branch name | "No ticket key found — provide the JIRA key to continue?" |
+| No staged changes and no unstaged changes | "Nothing to commit — stage the relevant files first, or abort?" |
+| Bitbucket credentials not found in keychain or env vars | "No credentials found — provide your Atlassian email and a scoped API token?" |
+| PR creation returns 401 | Walk the user through creating a scoped token (see Step 8) — do not retry with the same credentials |
+| PR already exists for this branch | "A PR already exists — show the existing PR link, or create a new one anyway?" |
+| Push fails due to non-fast-forward | "Push rejected — pull and rebase first, or force push?" |
+
+---
+
+## Notes
+
+- Step 7 is the only point that runs `/pre-push` automatically-on-prompt — don't run it
+  proactively elsewhere in this flow, and don't skip asking in Step 7 even if the user seems
+  to be in a hurry.
+- If a PR already exists for the branch, the API will return an error — inform the user and provide
+  the existing PR link if available.
+- Never force-push unless the user explicitly requests it.
+- Do **not** add any AI attribution to commit messages or PR descriptions — no "Co-Authored-By: Claude", no "Generated with Claude Code", no similar footers.

package/dist/mandatory/design/SKILL.md

@@ -0,0 +1,312 @@
+---
+name: rivet-design
+description: "Write a design document for a Jira ticket before any code is written."
+---
+
+# Design
+
+Write a design document for a Jira ticket before any code is written.
+Works for FE, BE, or full-stack tickets on any project.
+
+## Usage
+
+```
+/design <TICKET_ID>
+```
+
+Example: `/design PROJ-123`
+
+---
+
+## Instructions
+
+### Step 0 — Read project conventions
+
+Read `CLAUDE.md` at the repo root. Extract and hold in memory:
+- Naming conventions
+- TypeScript rules, component reuse rules, styling rules
+- Patterns to follow and patterns to avoid
+- Any stack-specific constraints
+- Sensitive Areas (auth, payments, PII) — needed to answer the Security & Access Control
+  questions in Step 2
+
+These will be enforced in Section 7 of the design doc.
+
+---
+
+### Step 1 — Parallel research (run all simultaneously)
+
+**1a. Fetch the primary ticket**
+
+Use `mcp__claude_ai_Atlassian__getJiraIssue` with the provided ticket ID.
+
+Extract:
+- `fields.summary` — title
+- `fields.description` — full description including any URLs
+- `fields.issuelinks` — all linked tickets
+- `fields.attachment` — attached files
+- Any URLs in the description (figma.com, confluence, notion, etc.)
+
+**1b. Fetch all linked tickets**
+
+Use `mcp__claude_ai_Atlassian__getJiraIssue` for each linked ticket ID in parallel.
+Prioritize tickets marked IMPLEMENTS, BLOCKS, RELATES TO, or CLONES.
+Extract summary, description, AC, and any further URLs from each.
+
+**1c. Explore the codebase**
+
+Spawn an Explore subagent with a prompt tailored to the ticket topic:
+
+> Search for all code relevant to [TOPIC FROM TICKET]. Find:
+> (1) existing components, screens, or modules that implement the described behaviour or would be modified,
+> (2) shared components in src/shared/ that are relevant or could be reused,
+> (3) existing types, constants, or state hooks related to this feature,
+> (4) existing tests for any of the above.
+> Return file paths, component/function names, and a one-line description of each.
+
+**1d. Explore linked design and documentation files**
+
+Collect all URLs found across the primary ticket and all linked tickets. Then for each:
+
+- **Figma URLs** (figma.com):
+  - Fetch using `mcp__claude_ai_Figma__get_design_context` (primary) and `mcp__claude_ai_Figma__get_screenshot` for visual reference. Use `mcp__claude_ai_Figma__get_metadata` for component/layer names if needed.
+  - Extract: screen names, component names, user flow annotations, any noted interactions
+  - If Figma MCP is unavailable or returns an error, note the URL and inform the user:
+    > "Figma MCP is not configured or could not access this file. Share screenshots or describe the design for full context."
+
+- **Confluence URLs**:
+  - Fetch using `mcp__claude_ai_Atlassian__getConfluencePage` or equivalent
+  - Extract any relevant specs, decisions, or background context
+
+- **Other URLs** (Notion, Google Docs, etc.):
+  - Attempt to fetch with WebFetch if publicly accessible
+  - If not accessible, note the URL and ask the user to paste the relevant content
+
+---
+
+### Step 2 — Synthesize before asking questions
+
+After Step 1, identify what is already known from tickets, code, and designs.
+Only ask questions that genuinely cannot be answered from gathered context.
+Group all unknown questions in a single message — never ask one at a time.
+
+Questions to evaluate (skip if already answered by research):
+
+**Scope & Behaviour**
+- What is the entry point / trigger for this feature?
+- Are there edge cases or failure modes the ticket doesn't mention?
+- Are there states to handle: empty, loading, error, offline?
+
+**UI & Design**
+- Are there designs not yet linked in the ticket?
+- Are there interaction details not covered in Figma (animations, transitions, gestures)?
+- Are there responsive/device-size considerations?
+
+**Data & API**
+- What API endpoints are involved? Already built or pending BE work?
+- What are the request/response shapes (if not in a linked BE ticket)?
+- Are there any data transformation or mapping requirements?
+
+**Security & Access Control**
+- Does this introduce or change any auth/authorization boundary (new role, permission
+  level, or who can access what)?
+- Does this touch PII or other data listed in `CLAUDE.md`'s Sensitive Areas section?
+- Are there rate-limiting or abuse-prevention needs (new public-facing endpoint, form
+  submission, or search)?
+
+**Navigation** *(skip for BE-only tickets)*
+- What screen/page does this flow from and to?
+- Are there deep link, back-navigation, or tab state requirements? (mobile)
+- Are there routing, redirect, or URL parameter requirements? (web)
+
+**Testing**
+- What level of testing is expected: unit only, unit + integration, or E2E?
+
+**Constraints**
+- Performance expectations (list size, pagination, image loading)?
+- Backwards compatibility with existing navigation state or persisted data?
+
+---
+
+### Step 3 — Write the design doc
+
+Using all gathered context, write the full design document.
+
+**File location:** `design_docs/<TICKET_ID>-<kebab-case-title>.md`
+
+If `design_docs/` does not exist, create it.
+
+---
+
+#### Standard template (single ticket)
+
+```markdown
+# Feature Design: [TICKET_ID] — [Feature Title]
+
+## Summary
+[1–3 sentences: what this ticket implements and why it matters to the user.]
+
+---
+
+## 1. Goal
+[2–5 sentences focused on the user/product "why", not the technical "how".]
+
+---
+
+## 2. Functional Requirements
+- **FR1:** [Observable, testable behaviour — what the user can do or see]
+- **FR2:**
+...
+
+---
+
+## 3. Non-Functional Requirements
+- **NFR1:** [Performance, accessibility, error handling, offline behaviour, security/access control, etc.]
+...
+
+---
+
+## 4. Out of Scope
+- [What this ticket explicitly does NOT include]
+...
+
+---
+
+## 5. Context & Background
+
+| Field | Details |
+|---|---|
+| Ticket(s) | |
+| Linked tickets | |
+| Related screens / modules | |
+| Design files | |
+| API / BE dependencies | |
+
+---
+
+## 6. Design & Flow
+
+### User Flow
+[Step-by-step: what the user sees and does, from entry point to exit]
+
+### Screen / Component Map
+| Screen / Component | File path | New or existing | Notes |
+|---|---|---|---|
+
+### Data Model
+| Field | Type | Source (API / local state / form) | Notes |
+|---|---|---|---|
+
+### API Calls
+| Endpoint | Method | When called | Notes |
+|---|---|---|---|
+
+---
+
+## 7. Implementation Steps
+
+### Step 1 — [What] — `path/to/file.tsx`
+[What to add/change and why. Reference specific component/function names from the Explore results.]
+[Note which CLAUDE.md conventions apply — naming, tokens, reuse, etc.]
+
+### Step 2 — [What] — `path/to/file.ts`
+...
+
+---
+
+## 8. Open Questions
+- **Q1:**
+...
+
+---
+
+## 9. Acceptance Criteria
+- [ ] ...
+- [ ] ...
+```
+
+---
+
+#### Extended template (multiple tickets)
+
+Use this when the design spans 2 or more tickets.
+
+```markdown
+# Feature Design: [UMBRELLA_ID] — [Feature Title]
+
+## Summary
+[1–3 sentences covering all tickets and their shared user-facing goal.]
+
+---
+
+## 0. Ticket Inventory
+
+| Ticket | Title | Type | Depends on |
+|---|---|---|---|
+| PROJ-XXX | ... | FE / BE / Design | — |
+| PROJ-YYY | ... | FE | PROJ-XXX |
+
+### Implementation Order
+- **Phase 1 (parallel):** PROJ-XXX, PROJ-YYY — [why they can run in parallel]
+- **Phase 2:** PROJ-ZZZ — depends on Phase 1
+
+---
+
+## 1. Goal
+...
+
+## 2. Functional Requirements
+
+### PROJ-XXX — [Short title]
+- **FR1:** ...
+
+### PROJ-YYY — [Short title]
+- **FR2:** ...
+
+## 3–5. [Same as standard template]
+
+## 6. Design & Flow
+[Unified flow showing where each ticket's changes fit]
+
+## 7. Implementation Steps
+
+### PROJ-XXX — [Short title]
+#### Step 1 — `path/to/file.tsx`
+...
+
+### PROJ-YYY — [Short title]
+#### Step 1 — `path/to/file.tsx`
+...
+
+## 8. Open Questions
+- **Q1 [PROJ-XXX]:** ...
+- **Q2 [PROJ-YYY]:** ...
+
+## 9. Acceptance Criteria
+
+### PROJ-XXX
+- [ ] ...
+
+### PROJ-YYY
+- [ ] ...
+```
+
+---
+
+### Step 4 — Ask about open questions
+
+After writing the doc, ask the user:
+1. Are any items in Section 8 blocking — need to be resolved before implementation starts?
+2. Do the Acceptance Criteria in Section 9 look complete?
+
+---
+
+## Inconsistency signals — always stop and ask
+
+| Signal | What to ask |
+|---|---|
+| Figma URL is inaccessible or MCP returns an error | "Figma MCP could not access this file — share screenshots or describe the design to continue." |
+| Linked ticket not found or returns an error | "Could not fetch [TICKET-ID] — skip it, or paste the relevant details?" |
+| Ticket has no acceptance criteria | "No AC found in the ticket — describe expected behaviour, or should I infer from the description?" |
+| Codebase search returns no results for the feature area | "No existing code found for this feature — confirm it's net-new, or is it under a different name?" |
+| Multiple tickets with unclear dependency order | "Ticket dependency order is ambiguous — which should be implemented first?" |