arsenals 1.0.0

package/skill-seekers/SKILL.md

@@ -0,0 +1,312 @@
+---
+name: skill-seekers
+description: >
+  Use this skill whenever the user wants Claude to learn, master, or absorb an unfamiliar framework, library,
+  internal tool, API, or large codebase from documentation, PDFs, or source code. Triggers when the user says
+  "learn this framework", "ingest these docs", "read this documentation", "master our internal library",
+  "study this codebase", "absorb this PDF", "understand our custom framework before implementing", or provides
+  a docs URL, a folder of PDFs, or a large repo and asks Claude to become fluent in it. Also triggers when another
+  skill or agent (e.g. Raphael / jira-to-code) needs domain knowledge it doesn't have before it can proceed.
+  The output is a distilled, reusable knowledge artifact that turns scattered source material into something
+  Claude can immediately apply.
+---
+
+# Skill Seekers
+
+Dynamically ingest documentation, PDFs, or large codebases and distill them into a reusable knowledge artifact, so Claude can immediately operate inside an unfamiliar framework, internal tool, or proprietary stack.
+
+This skill turns "I don't know your custom framework" into "I've read it, here's how it works, let's go" — in one pass.
+
+---
+
+## What this skill produces
+
+The output adapts to the source, but always lands in one of these forms (often a combination):
+
+```
+1. KNOWLEDGE PACK   (.md)  → A structured, searchable reference Claude reads to operate fluently.
+                             Default output. Lives at ./knowledge/[name]-knowledge.md
+2. CHEATSHEET       (.md)  → A condensed quick-reference for fast recall (APIs, patterns, gotchas).
+3. GENERATED SKILL  (.skill or SKILL.md) → When the material is stable and reusable across sessions,
+                             package the knowledge as its own installable skill.
+```
+
+Decision rule:
+- **One-off task** (learn it for this ticket) → Knowledge Pack + Cheatsheet
+- **Will be reused often** (your team's core internal framework) → also generate an installable Skill
+- Always ask the user at the end: "Want me to package this as a permanent skill?"
+
+---
+
+## Phase Overview
+
+```
+Phase 1: SCOPE      → Identify sources, set boundaries, estimate size
+Phase 2: INGEST     → Pull in docs / PDFs / code systematically
+Phase 3: DISTILL    → Extract concepts, APIs, patterns, conventions, gotchas
+Phase 4: STRUCTURE  → Organize into the Knowledge Pack
+Phase 5: VERIFY     → Self-test comprehension, fill gaps, flag uncertainty
+Phase 6: DELIVER    → Output artifact(s) + offer to package as a skill
+```
+
+---
+
+## Phase 1: SCOPE — Define what to ingest
+
+**Goal:** Know the boundaries before pulling anything in, so the ingest is targeted, not a firehose.
+
+### Determine sources
+
+| Source type | How to access |
+|---|---|
+| Hosted docs (URL) | Fetch the entry page, map the nav/sitemap, list the sections to read |
+| PDFs / local files | List files, get page counts / sizes, identify which are relevant |
+| Code repository | Map the directory tree, identify entry points, public API surface, and docs folders |
+
+### Set boundaries (ask if unclear)
+- What specifically does the user need to master? (the whole framework, or just the auth module?)
+- Is there a version that matters? (v2 docs vs v3)
+- Depth: API-level fluency, or deep internals?
+
+### Size estimate & strategy
+```
+INGEST PLAN
+───────────
+Sources       : [list — URLs, file paths, repo path]
+Estimated size: [page count / file count / LOC]
+Scope         : [full | scoped to: ...]
+Strategy      : [exhaustive read | breadth-first map then deep-dive relevant parts]
+Version        : [if relevant]
+```
+
+> **Large-source rule:** If the source is huge (a 500-page PDF, a 10k-file repo, an entire docs site), do NOT read everything linearly. Map the structure first, then read the high-value parts (core concepts, public API, patterns) and skim the rest. State this strategy upfront.
+
+---
+
+## Phase 2: INGEST — Pull in the material
+
+**Goal:** Get the source content into context systematically, prioritizing signal over completeness.
+
+### For hosted docs (URLs)
+1. Fetch the landing/overview page
+2. Extract the navigation structure (sitemap, sidebar, table of contents)
+3. Prioritize reading order: **Concepts → Getting Started → Core API → Guides → Advanced → Reference**
+4. Fetch pages in priority order; for reference-heavy pages, extract the API signatures and skip prose
+
+```bash
+# If in Claude Code with a local docs mirror
+find . -name "*.md" -o -name "*.mdx" | grep -i "doc" | head -50
+```
+
+### For PDFs / local files
+```bash
+# Inventory first
+ls -la *.pdf
+# Use the pdf-reading approach: get a content inventory before extracting everything
+```
+- Read the table of contents / outline first
+- Extract text section by section, prioritizing concept and API chapters
+- For scanned PDFs, note if OCR is needed
+- Pull out diagrams/tables descriptions — they often encode the architecture
+
+### For code repositories
+```bash
+# 1. Map the structure
+find . -maxdepth 3 -type d -not -path "*/node_modules/*" -not -path "*/vendor/*" \
+  -not -path "*/.git/*" 2>/dev/null
+
+# 2. Read the manifest & README first
+cat README.md package.json composer.json pyproject.toml go.mod 2>/dev/null | head -100
+
+# 3. Find the public API surface / entry points
+find . -name "index.*" -o -name "main.*" -o -name "*.d.ts" 2>/dev/null | grep -v node_modules | head -20
+
+# 4. Find the docs and examples folders
+find . -type d \( -iname "docs" -o -iname "examples" -o -iname "samples" \) 2>/dev/null | head -10
+```
+- Read entry points and public exports first — that's the contract
+- Read 3–5 representative implementations to learn the internal style
+- Read the tests — they document intended behavior better than comments
+
+### Ingest discipline
+- Track what you've read so you don't re-read or miss sections
+- If context fills up, distill-as-you-go (Phase 3) rather than holding everything raw
+- Note anything you couldn't access (paywalled, auth-required, broken link) — don't silently skip
+
+---
+
+## Phase 3: DISTILL — Extract what matters
+
+**Goal:** Convert raw material into structured knowledge. This is where ingestion becomes understanding.
+
+For everything ingested, extract:
+
+```
+CONCEPTS
+  - The mental model: what is this framework/tool, what problem does it solve, core abstractions
+  - Key terminology and what each term means in THIS framework's vocabulary
+
+PUBLIC API / INTERFACE
+  - Main entry points, classes, functions, hooks, endpoints
+  - Signatures with parameter meanings and return types
+  - The "you'll use these 20% of things 80% of the time" core set
+
+PATTERNS & CONVENTIONS
+  - The idiomatic way to do common tasks ("the framework wants you to...")
+  - Naming conventions, file organization, configuration style
+  - How errors are handled, how things are tested, how things are extended
+
+INTEGRATION POINTS
+  - How it connects to other systems (DB, auth, HTTP, events)
+  - Required setup / config / environment
+
+GOTCHAS & FOOTGUNS
+  - Common mistakes, anti-patterns, deprecated approaches
+  - Version-specific quirks
+  - Things that look like they should work but don't
+
+EXAMPLES
+  - 2–4 canonical, copy-adaptable code examples of the most common operations
+```
+
+> **Vocabulary rule:** Internal/custom frameworks often reuse common words with special meaning ("Resource", "Module", "Action" may mean something specific here). Capture the framework's own definitions, not the generic ones.
+
+---
+
+## Phase 4: STRUCTURE — Build the Knowledge Pack
+
+**Goal:** Organize the distilled knowledge into a clean, navigable artifact.
+
+### Knowledge Pack template
+```markdown
+# [Framework/Tool Name] — Knowledge Pack
+> Source: [URLs/files/repo] · Version: [x] · Ingested: [date] · Scope: [full/partial]
+
+## 1. Mental Model
+[2–4 paragraphs: what it is, what problem it solves, core abstractions]
+
+## 2. Vocabulary
+[Term → meaning in this framework]
+
+## 3. Core API (the 80/20)
+[The most-used entry points with signatures and one-line purpose each]
+
+## 4. Idiomatic Patterns
+[How the framework wants common things done, with short examples]
+
+## 5. Setup & Configuration
+[What's needed to use it — env, config, dependencies]
+
+## 6. Integration Points
+[How it talks to DB / auth / HTTP / other systems]
+
+## 7. Gotchas & Footguns
+[Mistakes to avoid, version quirks, deprecated things]
+
+## 8. Canonical Examples
+[2–4 copy-adaptable examples of the most common operations]
+
+## 9. Open Questions / Not Covered
+[What wasn't accessible or remains uncertain — be honest]
+
+## 10. Source Map
+[Where each piece of knowledge came from, for deeper lookup later]
+```
+
+Keep it dense but scannable. This file is meant to be **read by Claude (or Raphael) at the start of a task** to gain instant fluency, and by a human as a reference.
+
+### Optional Cheatsheet
+A 1-page condensed version: just the API table, the top patterns, and the top gotchas. For fast recall.
+
+---
+
+## Phase 5: VERIFY — Test comprehension & flag gaps
+
+**Goal:** Don't claim mastery you don't have. Pressure-test the knowledge.
+
+### Self-test
+Pose and answer (internally) the questions a developer would actually hit:
+- "How do I do [the most common task] in this framework?"
+- "How do I handle errors / validation / auth the way this framework expects?"
+- "What's the idiomatic way to extend or configure it?"
+- "What would break if I did it the naive/generic way?"
+
+If any answer is shaky, go back to Phase 2 and read more on that area.
+
+### Honesty about gaps
+Explicitly list:
+- Sections that weren't accessible
+- Areas where the docs were ambiguous or contradictory
+- Version uncertainty
+- Anything inferred vs directly stated
+
+> **No false confidence rule:** It's far better to say "the docs didn't cover X clearly" than to invent how X works. A flagged gap is useful; a confident hallucination is dangerous.
+
+---
+
+## Phase 6: DELIVER — Output & optionally package
+
+**Goal:** Hand over the artifact and decide whether it becomes permanent.
+
+1. Write the Knowledge Pack to `./knowledge/[name]-knowledge.md` (Claude Code) or present it inline / as a downloadable file (Claude.ai)
+2. Optionally write the Cheatsheet
+3. Give a short summary: what was ingested, what the user can now ask Claude to do with it, and what the known gaps are
+4. Offer packaging:
+   > "This knowledge is reusable. Want me to package it as a permanent installable skill so you don't have to re-ingest it next time?"
+   If yes, generate a `SKILL.md` whose description triggers on the framework's name and whose body is the Knowledge Pack.
+
+### Handoff to Raphael / other agents
+If this ingestion was requested so another agent (like Raphael) can implement against the framework, end with:
+```
+KNOWLEDGE READY → [agent]
+─────────────────────────
+Framework   : [name]
+Knowledge at: ./knowledge/[name]-knowledge.md
+Use this to : [what the agent can now do — e.g. "implement tickets using our internal Resource framework idiomatically"]
+Known gaps  : [list]
+```
+
+---
+
+## Running Modes
+
+| Mode | Behavior |
+|---|---|
+| **Full ingest** | All 6 phases. Use for a framework you'll work in repeatedly. |
+| **Quick brief** | Phases 1–3 only, output a Cheatsheet. Use when you just need fast orientation. |
+| **Just-in-time** | Triggered mid-task by another agent. Scope to exactly what's needed, produce a focused Knowledge Pack section, hand back. |
+| **Refresh** | Re-ingest only changed/new sections of a previously ingested source; update the existing Knowledge Pack. |
+
+---
+
+## Environment Notes
+
+- **Claude Code:** Can read local files/repos directly, write the Knowledge Pack to `./knowledge/`, and persist it across sessions. Preferred for large codebases and PDF folders.
+- **Claude.ai:** Fetch URLs via web tools, accept uploaded PDFs/files, output the Knowledge Pack as a downloadable artifact. For huge sources, ingest in scoped batches across messages.
+
+---
+
+## Error Handling
+
+| Situation | Action |
+|---|---|
+| Docs require login/paywall | Flag it, ask user to paste the relevant pages or provide access |
+| PDF is scanned (no text layer) | Note OCR is needed; use OCR before extracting |
+| Source is enormous (>500pg / >10k files) | Switch to breadth-first map + targeted deep-dive; state the strategy |
+| Docs contradict the code | Trust the code for behavior, note the doc discrepancy |
+| Version ambiguity | Ask which version, or ingest the one in the repo and label it |
+| Context fills mid-ingest | Distill-as-you-go; write partial Knowledge Pack, continue in next pass |
+| Conflicting info across sources | Present both, mark which source said what, flag for user |
+
+---
+
+## Quick Reference Cheatsheet
+
+```
+Phase 1  →  Scope    → sources, boundaries, size, strategy
+Phase 2  →  Ingest   → docs/PDFs/code, signal over completeness
+Phase 3  →  Distill  → concepts, API, patterns, gotchas, vocabulary
+Phase 4  →  Structure→ Knowledge Pack (mental model → examples → gaps)
+Phase 5  →  Verify   → self-test, flag gaps honestly, no false confidence
+Phase 6  →  Deliver  → output artifact + offer to package as permanent skill
+```

package/ticket-writer/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: ticket-writer
+description: >
+  Use this skill ONLY on explicit invocation via "/ticket" or "write a ticket for [X]" /
+  "draft a ticket for [X]". Given just a ticket title, scans the current repo/codebase to
+  ground the ticket in what actually exists, then produces a ready-to-paste Jira-style
+  ticket with Description, Acceptance Criteria, and Technical Implementation sections.
+  This is the inverse of the jira-to-code skill (which goes ticket → code); this one goes
+  title → ticket. Do not trigger on generic phrasing like "explain this feature" or
+  "what's the plan for X" — only on explicit ticket-writing requests.
+---
+
+# Ticket Writer Skill
+
+Takes a bare ticket title and turns it into a fully-formed ticket by reading the codebase
+for context — so the ticket reflects what's actually there, not just a guess from the title
+alone. Output is chat-only markdown, ready to paste straight into Jira. No files are created.
+
+---
+
+## Workflow
+
+```
+1. PARSE TITLE     → Infer ticket type (Bug/Feature/Task) and likely scope from the title
+2. SCAN REPO       → Find relevant files, existing patterns, current behavior
+3. DRAFT TICKET    → Description, Acceptance Criteria, Technical Implementation
+4. OUTPUT          → Clean markdown block in chat, nothing else
+```
+
+No checkpoints, no file output — this is meant to be fast. Only pause and ask the user if
+the title is genuinely too ambiguous to scope (see Error Handling).
+
+---
+
+## Step 1 — Parse the Title
+
+From the title alone, infer:
+- **Type**: Bug (title implies broken/incorrect behavior) / Feature (new capability) /
+  Task (refactor, chore, infra)
+- **Likely domain**: which part of the system this touches (auth, billing, a specific
+  admin panel/site, an integration, etc.) — use whatever domain vocabulary appears in the
+  title to guide the repo scan in Step 2
+
+If the user provides more than a title (extra context, a pasted Slack thread, a rough
+description), fold that in — treat the title as the anchor but use all provided context.
+
+---
+
+## Step 2 — Scan the Repo
+
+**Goal:** ground the ticket in what's actually in the codebase, the same way `jira-to-code`
+grounds implementation in the codebase — just run in reverse.
+
+```bash
+# Stack + structure (skip if already known from this conversation)
+find . -maxdepth 2 -not -path '*/vendor/*' -not -path '*/node_modules/*' -not -path '*/.git/*'
+
+# Search for anything matching the title's domain keywords
+grep -rn "[keyword]" --include="*.php" -l | head -20
+```
+
+Use the title's keywords to find:
+- **Existing related code**: models, Actions, DTOs, Filament resources, controllers, routes
+  already touching this area
+- **Current behavior**: if it's a bug, what does the code currently do (trace the actual
+  logic, don't guess)
+- **Existing patterns to follow**: how similar features/fixes were structured elsewhere in
+  this codebase (Actions pattern, DDD boundaries, spatie/laravel-data DTOs, Filament
+  resource conventions — match what this project already does)
+- **What's missing**: for a Feature ticket, confirm the capability genuinely doesn't exist
+  yet (avoid writing a ticket for something already built)
+
+If nothing relevant turns up, say so plainly in the draft rather than inventing context.
+
+---
+
+## Step 3 — Draft the Ticket
+
+### Description
+2–4 sentences, plain language. What is being asked for and why, written from what the
+title + repo scan actually support — not padded with generic filler. For a bug, describe
+the current (wrong) behavior found in the code. For a feature, describe the gap and the
+proposed capability.
+
+### Acceptance Criteria
+- Numbered, each one independently testable
+- Written as observable outcomes ("Given X, when Y, then Z" or plain checklist form —
+  match whichever style fits the ticket, checklist is the default)
+- Cover the happy path, at least one edge case, and any explicit non-functional requirement
+  implied by the title (e.g. performance, permissions)
+- If the repo scan revealed an existing partial implementation, one AC should cover
+  completing/fixing that specific gap rather than restating the obvious
+
+### Technical Implementation
+- Grounded in what Step 2 actually found — name real files/classes/patterns, not generic
+  advice
+- Structure as: **Affected areas** (files/modules likely touched), **Approach** (2–4
+  sentences on how this fits existing patterns — Actions/DTOs/Filament conventions as
+  relevant), **Open questions** (anything the repo scan couldn't resolve — flag rather
+  than guess)
+- This section is a starting point for whoever implements it (including `jira-to-code`
+  downstream) — not a full implementation plan. Keep it tight.
+
+---
+
+## Step 4 — Output Format
+
+Output only this block, nothing before or after except a one-line intro:
+
+```markdown
+## [Title as given]
+
+**Type**: [Bug | Feature | Task]
+
+### Description
+[2-4 sentences]
+
+### Acceptance Criteria
+- [ ] AC 1
+- [ ] AC 2
+- [ ] AC 3
+
+### Technical Implementation
+**Affected areas**
+- `[path/file]` — [why]
+- `[path/file]` — [why]
+
+**Approach**
+[2-4 sentences, grounded in repo patterns found]
+
+**Open questions**
+- [question, if any — omit section if none]
+```
+
+---
+
+## Error Handling
+
+| Situation | Action |
+|---|---|
+| Title is too vague to scope (e.g. "Fix bug") | Ask one clarifying question: *"Which part of the app — can you point me to a file, feature, or error?"* Don't guess a domain. |
+| No relevant code found for the domain | Say so in Description ("no existing code found touching X — this appears to be net-new") rather than inventing file paths |
+| Title implies something already fully implemented | Flag it before drafting: *"This looks like it may already be built — [file/path] appears to handle this. Still want a ticket, or is this about extending it?"* |
+| Repo not available / no code context in this session | Draft the ticket from the title alone, clearly note "⚠️ No repo scan — grounded in title only" at the top of the Technical Implementation section |