arsenals 1.0.0

package/jira-to-code/SKILL.md

@@ -0,0 +1,446 @@
+---
+name: jira-to-code
+description: >
+  Use this skill whenever the user wants to implement a Jira ticket, story, task, or bug into actual code.
+  Triggers when a user mentions a Jira ticket ID (e.g. PROJ-123), pastes a Jira description, says "implement this ticket",
+  "work on this story", "code this task", "build this feature from Jira", or shares acceptance criteria from a ticket.
+  Also triggers for phrases like "read my Jira and implement", "analyze the ticket and write code", or
+  "implement based on the requirements". Always use this skill when the workflow involves reading a Jira ticket
+  AND producing code — even if the user doesn't explicitly say "skill".
+---
+
+# Jira-to-Code Skill
+
+A structured agentic workflow that reads a Jira ticket, deeply understands the codebase, then produces a precise, ready-to-execute implementation plan and code — all grounded in both the ticket's intent and the project's actual patterns.
+
+---
+
+## Phase Overview
+
+```
+Phase 1: INGEST         → Read & parse the Jira ticket
+         ↓ CHECKPOINT: show parse output, wait for user confirmation
+Phase 2: EXPLORE        → Scan the repository/project folder (git-aware)
+Phase 3: RECONCILE      → Cross-reference ticket intent with codebase reality
+         ↓ CHECKPOINT: show complexity score + risks, wait for user confirmation
+Phase 4: PLAN           → Produce a concrete, ordered implementation plan
+         ↓ CHECKPOINT: present plan, wait for approval before writing any code
+Phase 5: IMPLEMENT      → Write the code (or hand off the plan to the agent)
+         ↓ OUTPUT: Implementation summary + PR description
+```
+
+> **Checkpoint rule:** At each ↓ CHECKPOINT, stop, display the output, and explicitly ask:
+> *"Does this look right? Should I proceed to [next phase]?"*
+> Do not continue until the user confirms. This prevents compounding errors from a misread ticket or wrong file exploration.
+
+---
+
+## Phase 1: INGEST — Read & Parse the Jira Ticket
+
+**Goal:** Extract every meaningful signal from the ticket before touching any code.
+
+### What to extract:
+
+```
+TICKET PARSE OUTPUT
+───────────────────
+Ticket ID      : e.g. PROJ-123
+Type           : Bug | Feature | Task | Story | Spike
+Title          : One-line summary
+Priority       : Critical / High / Medium / Low
+Labels/Tags    : (if any — e.g. "backend", "auth", "v2")
+Linked tickets : blocks: [IDs] | blocked by: [IDs] | relates to: [IDs]
+
+DESCRIPTION
+  - Core problem or feature request (1–3 sentences in your own words)
+  - Stated root cause (if bug)
+  - Stakeholder / user impact
+
+ACCEPTANCE CRITERIA (AC)
+  - List each criterion explicitly, numbered
+  - Flag any AC that is vague or untestable → mark as [NEEDS CLARIFICATION]
+
+TECHNICAL NOTES (if any in ticket)
+  - Mentioned files, endpoints, methods, components
+  - Linked PRs, design docs, Confluence pages
+  - Suggested approach from the author
+
+TICKET DEPENDENCIES (if any)
+  - [TICKET-ID] → [blocks this / blocked by this / relates to this]
+  - ⚠️ Flag any dependency that may conflict with or be required before this work
+
+OUT OF SCOPE (explicit or implied)
+  - What this ticket explicitly does NOT include
+```
+
+### Ticket-type behavior:
+Adjust the workflow based on ticket type:
+
+| Type | Special behavior |
+|---|---|
+| **Bug** | Phase 3 must include root cause analysis. Test plan must include a regression test. |
+| **Feature** | Phase 3 must check API contract & backward compatibility. Plan must note any breaking changes. |
+| **Task** | Standard flow. |
+| **Story** | Break down into sub-tasks in the plan. Each sub-task gets its own Step entry. |
+| **Spike** | Do NOT produce code. Output a findings/research document instead of an implementation plan. |
+
+### Rules:
+- Do not interpret or assume intent yet — just extract faithfully.
+- If the ticket is missing AC, note it explicitly: "⚠️ No acceptance criteria found — will infer from description."
+- If ticket references external links/docs, flag them for the user to provide if needed.
+- If linked tickets are present, flag them: "⚠️ This ticket blocks/is blocked by [ID] — verify that work is complete or compatible before proceeding."
+
+### ✋ CHECKPOINT 1
+Display the full Ticket Parse Output above, then ask:
+> *"Does this capture the ticket correctly? Any corrections before I explore the codebase?"*
+Wait for confirmation before proceeding to Phase 2.
+
+---
+
+## Phase 2: EXPLORE — Scan the Repository
+
+**Goal:** Understand the project's architecture, conventions, relevant code, and current git state before writing a single line.
+
+### Step 1: Git state (run first)
+
+```bash
+# Current branch and status
+git branch --show-current
+git status --short
+
+# Recent commits for context
+git log --oneline -15
+
+# Files changed in recent commits (to detect active work areas)
+git diff --name-only HEAD~5 HEAD 2>/dev/null || echo "Not enough history"
+```
+
+Record:
+- Current branch name
+- Any uncommitted changes (warn if dirty working tree)
+- Files recently modified (flag if they overlap with ticket's likely touch points)
+- Any open work that might conflict
+
+### Step 2: Top-level scan
+
+```bash
+# Directory tree — stop at 2 levels; go deeper only into relevant modules
+find . -maxdepth 2 \
+  -not -path '*/node_modules/*' -not -path '*/.git/*' \
+  -not -path '*/__pycache__/*' -not -path '*/dist/*' \
+  -not -path '*/build/*' -not -path '*/.next/*' \
+  -not -path '*/coverage/*'
+```
+
+> **Large repo rule:** If the top-level scan reveals >200 files or a monorepo structure (multiple `package.json` / `pyproject.toml` at subdirectory level), stop and ask:
+> *"This looks like a large/mono repo. Which package or module is this ticket relevant to?"*
+> Then scope all further exploration to that subdirectory.
+
+### Step 3: Identify the stack
+
+Detect and record:
+- **Language(s)**: TypeScript, Python, Go, Java, etc.
+- **Framework(s)**: React, Next.js, FastAPI, Spring, Rails, etc.
+- **Test framework**: Jest, Pytest, RSpec, Vitest, etc.
+- **Package manager**: npm/yarn/pnpm, pip, cargo, etc.
+- **Key config files**: `tsconfig.json`, `pyproject.toml`, `.eslintrc`, `Dockerfile`, etc.
+
+### Step 4: Environment & feature flag awareness
+
+```bash
+# Check for env variable definitions
+cat .env.example 2>/dev/null || cat .env.sample 2>/dev/null || echo "No .env example found"
+
+# Check for feature flag files or config
+find . -maxdepth 3 -name "flags*" -o -name "features*" -o -name "toggles*" 2>/dev/null | head -10
+```
+
+Record:
+- Environment variables relevant to the ticket's area (e.g. if ticket touches auth, note `AUTH_*` vars)
+- Any feature flags wrapping the code being changed — the plan must account for flag state
+
+### Step 5: Targeted exploration based on ticket signals
+
+Use the parsed ticket (Phase 1) to guide what to read:
+
+| Ticket mentions | → Explore |
+|---|---|
+| An endpoint / route | Router files, controller/handler, middleware |
+| A UI component | Component file, styles, props types, parent usage |
+| A database model | Model/schema file, migration history, related queries |
+| Auth / permissions | Auth middleware, guards, role definitions |
+| A bug in feature X | The feature's files + `git log -p -- [file]` for recent changes |
+| Performance issue | The slow path — query, loop, or render + any existing profiling notes |
+| A named class/service | `grep -r "ClassName" --include="*.ts" -l` to find all usages |
+
+### Step 6: Collision detection
+
+Before naming any new files, classes, or services, verify they don't already exist:
+
+```bash
+# Example: checking if a service name is already taken
+grep -r "UserNotificationService" --include="*.ts" -l 2>/dev/null
+grep -r "UserNotificationService" --include="*.py" -l 2>/dev/null
+```
+
+Run this for every new symbol the ticket implies creating. Flag any collision.
+
+### Step 7: Document findings
+
+```
+CODEBASE SUMMARY
+────────────────
+Stack           : [language] / [framework]
+Test framework  : [framework]
+Entry point     : [file]
+Branch          : [current branch]
+Git status      : [clean | dirty — list changed files]
+Recently touched: [files changed in last 5 commits that overlap with ticket]
+
+Relevant files  :
+  - [path] → [why it matters]
+  - [path] → [why it matters]
+
+Env vars in scope:
+  - [VAR_NAME] → [what it controls, relevant to ticket]
+
+Feature flags in scope:
+  - [flag name / file] → [current state / what it gates]
+
+Patterns observed:
+  - [e.g. "Services use repository pattern with dependency injection"]
+  - [e.g. "All API responses wrapped in { data, error, meta }"]
+  - [e.g. "Components use named exports, no default exports"]
+
+Existing tests for this area:
+  - [path] → [what they cover]
+
+Collision check:
+  - [symbol name] → [Not found ✅ | Already exists at path ⚠️]
+
+Potential conflicts / risks:
+  - [e.g. "UserService is currently being refactored in branch feature/user-v2"]
+  - [e.g. "NOTIFICATION_ENABLED feature flag is currently OFF in .env.example"]
+```
+
+---
+
+## Phase 3: RECONCILE — Cross-Reference Ticket with Codebase
+
+**Goal:** Resolve the gap between what the ticket *asks for* and what the codebase *currently does*. Produce a complexity score.
+
+### AC gap analysis
+
+Go through each Acceptance Criterion from Phase 1 and answer:
+
+```
+AC #1: [criterion text]
+  Current state : [what the code does today]
+  Gap           : [what needs to change]
+  Risk          : [None / Low / Medium / High] — reason
+  Rollback note : [how to revert this change if it causes issues in prod]
+  Files touched : [list]
+
+AC #2: ...
+```
+
+### Additional checks:
+- Are there existing utilities, helpers, or abstractions this ticket should reuse?
+- Are there tests that will break and need to be updated?
+- Are there any AC that are already partially or fully implemented?
+- Are there dependencies between ACs (do some need to happen before others)?
+- For **Bug** tickets: What is the confirmed root cause? Which line/condition is the defect?
+- For **Feature** tickets: Does this change any public API, event schema, or DB schema? If yes, flag as breaking change.
+
+### Complexity Score
+
+After the AC analysis, assign a complexity estimate:
+
+```
+COMPLEXITY: [S / M / L / XL]
+─────────────────────────────
+S  = 1–2 files, 1–3 AC, no schema/API changes, low risk
+M  = 3–5 files, 3–6 AC, minor API or schema changes, medium risk
+L  = 6–10 files, many AC, API/schema changes, cross-service impact
+XL = 10+ files, breaking changes, high risk, needs team review before proceeding
+
+Score     : [S / M / L / XL]
+Reasoning : [1–2 sentences explaining the score]
+```
+
+> **XL rule:** If complexity is XL, pause and say:
+> *"This ticket is rated XL complexity. It's recommended to review the plan with your team before implementation. I'll produce the plan, but recommend not proceeding to Phase 5 without sign-off."*
+
+### ✋ CHECKPOINT 2
+Display the full Reconcile output (AC gap analysis + complexity score), then ask:
+> *"Does this analysis look accurate? Any risks I missed before I write the implementation plan?"*
+Wait for confirmation before proceeding to Phase 4.
+
+---
+
+## Phase 4: PLAN — Produce the Implementation Plan
+
+**Goal:** A precise, ordered, agent-executable plan. No ambiguity. No hand-waving.
+
+### Format:
+
+```
+IMPLEMENTATION PLAN — [TICKET-ID]: [Title]
+══════════════════════════════════════════
+Complexity : [S / M / L / XL]
+Type       : [Bug | Feature | Task | Story]
+
+SUMMARY
+  [2–3 sentence plain English summary of what will be built/changed and why]
+
+LINKED TICKET NOTES (if any)
+  - [TICKET-ID] [blocks/blocked by/relates to] → [impact on this plan]
+
+STEPS
+  Each step follows this format:
+
+  Step N — [Step Title]
+  ├── File(s)  : [exact file paths]
+  ├── Action   : [Create | Modify | Delete | Rename]
+  ├── What     : [Precise description of the change]
+  ├── Pattern  : [Reference to observed codebase pattern to follow]
+  ├── AC refs  : [Which AC(s) this step satisfies]
+  ├── Rollback : [How to revert this step if needed]
+  └── Notes    : [Edge cases, gotchas, collision checks, decisions made]
+
+TEST PLAN
+  Step T1 — [Test description]
+  ├── File     : [test file path — new or existing]
+  ├── Type     : [Unit | Integration | E2E]
+  ├── Covers   : [Which AC or step this validates]
+  └── What     : [What to assert — for Bug tickets, include a regression test]
+
+OPEN QUESTIONS (if any)
+  - [Question 1] → [Suggested default if proceeding without answer]
+  - [Question 2] → [Suggested default]
+
+DEFINITION OF DONE
+  ☐ All AC satisfied (see mapping above)
+  ☐ Tests written and passing
+  ☐ No regressions in existing tests
+  ☐ Code follows existing project patterns
+  ☐ No new dependencies introduced unless listed in plan
+  ☐ Feature flags / env vars accounted for
+  ☐ [Any ticket-specific requirement]
+```
+
+### Rules for a good plan:
+- Steps must be in dependency order (no step assumes a later step is done)
+- Every AC must map to at least one step
+- Never say "update X accordingly" — say exactly what to change
+- If a design decision is needed, state the chosen option and why
+- Keep each step small enough that it can be reviewed independently
+- Every new symbol (class, service, file) must have passed the collision check from Phase 2
+
+### ✋ CHECKPOINT 3
+Display the full implementation plan, then ask:
+> *"Does this plan look right? Approve to begin implementation, or let me know what to adjust."*
+Do not write any code until the user explicitly approves.
+
+---
+
+## Phase 5: IMPLEMENT — Write the Code
+
+After plan approval (or if the user says "just do it"), proceed to implementation following the plan exactly.
+
+### Per step:
+1. Read the target file(s) before editing
+2. Follow the exact pattern documented in Phase 2
+3. Write the code change
+4. Immediately write or update the corresponding test
+5. Verify the change satisfies its linked AC(s)
+
+### Code quality rules:
+- Match the existing code style exactly (indentation, naming, import order)
+- Do not introduce new dependencies unless the plan explicitly calls for it
+- Do not refactor unrelated code (out of scope)
+- Add inline comments only where the logic is non-obvious
+- If you find a bug outside the ticket scope, note it in the summary but do not fix it
+- Honor feature flag state — do not remove or bypass existing flags
+
+### After all steps:
+Run the test suite if a run command is available, then produce:
+
+```
+IMPLEMENTATION SUMMARY — [TICKET-ID]
+══════════════════════════════════════
+Files changed  : [list with type: created/modified/deleted]
+Tests added    : [list]
+AC coverage    : [each AC → Satisfied ✅ / Partial ⚠️ / Not addressed ❌]
+Out-of-scope bugs found : [list — not fixed, just noted]
+Notes          : [anything the reviewer should know]
+```
+
+Then produce a PR description:
+
+```
+PR DESCRIPTION — [TICKET-ID]: [Title]
+══════════════════════════════════════
+## What
+[1–2 sentences: what this PR does]
+
+## Why
+[1–2 sentences: the problem it solves, linked to ticket]
+
+## Changes
+- [file or area] — [what changed and why]
+- [file or area] — [what changed and why]
+
+## Testing
+- [ ] Unit tests added/updated: [list]
+- [ ] Integration tests added/updated: [list]
+- [ ] Manually tested: [describe scenario]
+
+## Rollback
+[How to revert if this causes issues — reference the rollback notes from the plan]
+
+## Notes for reviewer
+[Decisions made, trade-offs, anything non-obvious]
+
+Closes [TICKET-ID]
+```
+
+---
+
+## Handoff Mode (Plan-Only)
+
+If the user wants the plan fed to another agent rather than implementing directly, output only Phases 1–4 in a clean markdown block, then say:
+
+> "Plan ready. Pass this to your agent with the instruction: **Follow this implementation plan exactly, respecting all file paths, patterns, AC mappings, and rollback notes.**"
+
+---
+
+## Error Handling
+
+| Situation | Action |
+|---|---|
+| Ticket has no AC | Infer AC from description, mark as `[INFERRED]`, confirm at Checkpoint 1 |
+| Relevant file not found | State the missing file, ask user or make a best guess with `[ASSUMPTION]` tag |
+| Ticket references a Jira link/doc not accessible | Flag it, note what info is missing, proceed with what's available |
+| Ambiguous requirement | State both interpretations, pick the safer/simpler one, mark as `[DECISION]` |
+| Conflicting patterns in codebase | Pick the more recent/dominant pattern, document the choice |
+| Dirty git working tree | Warn: "⚠️ Working tree has uncommitted changes — recommend committing or stashing before proceeding" |
+| Symbol collision detected | Stop, flag it: "⚠️ [Name] already exists at [path] — plan needs to be adjusted" |
+| Ticket type is Spike | Skip Phases 4–5. Output a findings document instead. |
+| Complexity is XL | Produce plan but recommend team review before Phase 5 |
+| Linked ticket blocks this work | Flag: "⚠️ This ticket is blocked by [ID] — confirm that work is done before implementing" |
+
+---
+
+## Quick Reference Cheatsheet
+
+```
+Phase 1  →  Parse ticket → extract AC, type, dependencies
+           ✋ CHECKPOINT: confirm parse before exploring code
+Phase 2  →  Scan repo → git state, stack, env vars, feature flags, collision check
+Phase 3  →  Reconcile → AC gaps, complexity score (S/M/L/XL), rollback notes
+           ✋ CHECKPOINT: confirm analysis before planning
+Phase 4  →  Plan → ordered steps, file paths, patterns, AC refs, rollback per step
+           ✋ CHECKPOINT: approve plan before writing any code
+Phase 5  →  Implement → code + tests + implementation summary + PR description
+```

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "arsenals",
+  "version": "1.0.0",
+  "description": "Claude Code skills installer",
+  "bin": {
+    "arsenals": "bin/arsenals.js"
+  },
+  "files": [
+    "bin",
+    "cybersecurity-agent",
+    "jira-to-code",
+    "skill-seekers",
+    "ticket-writer"
+  ],
+  "keywords": [
+    "claude-code",
+    "skills",
+    "ai"
+  ],
+  "license": "MIT"
+}