@diottodev/runic 1.0.0 → 1.1.0

package/product/research-summarizer/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: "research-summarizer"
+description: "Structured research summarization agent skill for non-dev users. Handles academic papers, web articles, reports, and documentation. Extracts key findings, generates comparative analyses, and produces properly formatted citations. Use when: user wants to summarize a research paper, compare multiple sources, extract citations from documents, or create structured research briefs. Plugin for Claude Code, Codex, Gemini CLI, and OpenClaw."
+license: MIT
+metadata:
+  version: 1.0.0
+  author: Alireza Rezvani
+  category: product
+  updated: 2026-03-16
+---
+
+# Research Summarizer
+
+> Read less. Understand more. Cite correctly.
+
+Structured research summarization workflow that turns dense source material into actionable briefs. Built for product managers, analysts, founders, and anyone who reads more than they should have to.
+
+Not a generic "summarize this" — a repeatable framework that extracts what matters, compares across sources, and formats citations properly.
+
+---
+
+## Slash Commands
+
+| Command | What it does |
+|---------|-------------|
+| `/research:summarize` | Summarize a single source into a structured brief |
+| `/research:compare` | Compare 2-5 sources side-by-side with synthesis |
+| `/research:cite` | Extract and format all citations from a document |
+
+---
+
+## When This Skill Activates
+
+Recognize these patterns from the user:
+
+- "Summarize this paper / article / report"
+- "What are the key findings in this document?"
+- "Compare these sources"
+- "Extract citations from this PDF"
+- "Give me a research brief on [topic]"
+- "Break down this whitepaper"
+- Any request involving: summarize, research brief, literature review, citation, source comparison
+
+If the user has a document and wants structured understanding → this skill applies.
+
+---
+
+## Workflow
+
+### `/research:summarize` — Single Source Summary
+
+1. **Identify source type**
+   - Academic paper → use IMRAD structure (Introduction, Methods, Results, Analysis, Discussion)
+   - Web article → use claim-evidence-implication structure
+   - Technical report → use executive summary structure
+   - Documentation → use reference summary structure
+
+2. **Extract structured brief**
+   ```
+   Title: [exact title]
+   Author(s): [names]
+   Date: [publication date]
+   Source Type: [paper | article | report | documentation]
+
+   ## Key Thesis
+   [1-2 sentences: the central argument or finding]
+
+   ## Key Findings
+   1. [Finding with supporting evidence]
+   2. [Finding with supporting evidence]
+   3. [Finding with supporting evidence]
+
+   ## Methodology
+   [How they arrived at these findings — data sources, sample size, approach]
+
+   ## Limitations
+   - [What the source doesn't cover or gets wrong]
+
+   ## Actionable Takeaways
+   - [What to do with this information]
+
+   ## Notable Quotes
+   > "[Direct quote]" (p. X)
+   ```
+
+3. **Assess quality**
+   - Source credibility (peer-reviewed, reputable outlet, primary vs secondary)
+   - Evidence strength (data-backed, anecdotal, theoretical)
+   - Recency (when published, still relevant?)
+   - Bias indicators (funding source, author affiliation, methodology gaps)
+
+### `/research:compare` — Multi-Source Comparison
+
+1. **Collect sources** (2-5 documents)
+2. **Summarize each** using the single-source workflow above
+3. **Build comparison matrix**
+
+   ```
+   | Dimension        | Source A        | Source B        | Source C        |
+   |------------------|-----------------|-----------------|-----------------|
+   | Central Thesis   | ...             | ...             | ...             |
+   | Methodology      | ...             | ...             | ...             |
+   | Key Finding      | ...             | ...             | ...             |
+   | Sample/Scope     | ...             | ...             | ...             |
+   | Credibility      | High/Med/Low    | High/Med/Low    | High/Med/Low    |
+   ```
+
+4. **Synthesize**
+   - Where do sources agree? (convergent findings = stronger signal)
+   - Where do they disagree? (divergent findings = needs investigation)
+   - What gaps exist across all sources?
+   - What's the weight of evidence for each position?
+
+5. **Produce synthesis brief**
+   ```
+   ## Consensus Findings
+   [What most sources agree on]
+
+   ## Contested Points
+   [Where sources disagree, with strongest evidence for each side]
+
+   ## Gaps
+   [What none of the sources address]
+
+   ## Recommendation
+   [Based on weight of evidence, what should the reader believe/do?]
+   ```
+
+### `/research:cite` — Citation Extraction
+
+1. **Scan document** for all references, footnotes, in-text citations
+2. **Extract and format** using the requested style (APA 7 default)
+3. **Classify citations** by type:
+   - Primary sources (original research, data)
+   - Secondary sources (reviews, meta-analyses, commentary)
+   - Tertiary sources (textbooks, encyclopedias)
+4. **Output** sorted bibliography with classification tags
+
+Supported citation formats:
+- **APA 7** (default) — social sciences, business
+- **IEEE** — engineering, computer science
+- **Chicago** — humanities, history
+- **Harvard** — general academic
+- **MLA 9** — arts, humanities
+
+---
+
+## Tooling
+
+### `scripts/extract_citations.py`
+
+CLI utility for extracting and formatting citations from text.
+
+**Features:**
+- Regex-based citation detection (DOI, URL, author-year, numbered references)
+- Multiple output formats (APA, IEEE, Chicago, Harvard, MLA)
+- JSON export for integration with reference managers
+- Deduplication of repeated citations
+
+**Usage:**
+```bash
+# Extract citations from a file (APA format, default)
+python3 scripts/extract_citations.py document.txt
+
+# Specify format
+python3 scripts/extract_citations.py document.txt --format ieee
+
+# JSON output
+python3 scripts/extract_citations.py document.txt --format apa --output json
+
+# From stdin
+cat paper.txt | python3 scripts/extract_citations.py --stdin
+```
+
+### `scripts/format_summary.py`
+
+CLI utility for generating structured research summaries.
+
+**Features:**
+- Multiple summary templates (academic, article, report, executive)
+- Configurable output length (brief, standard, detailed)
+- Markdown and plain text output
+- Key findings extraction with evidence tagging
+
+**Usage:**
+```bash
+# Generate structured summary template
+python3 scripts/format_summary.py --template academic
+
+# Brief executive summary format
+python3 scripts/format_summary.py --template executive --length brief
+
+# All templates listed
+python3 scripts/format_summary.py --list-templates
+
+# JSON output
+python3 scripts/format_summary.py --template article --output json
+```
+
+---
+
+## Quality Assessment Framework
+
+Rate every source on four dimensions:
+
+| Dimension | High | Medium | Low |
+|-----------|------|--------|-----|
+| **Credibility** | Peer-reviewed, established author | Reputable outlet, known author | Blog, unknown author, no review |
+| **Evidence** | Large sample, rigorous method | Moderate data, sound approach | Anecdotal, no data, opinion |
+| **Recency** | Published within 2 years | 2-5 years old | 5+ years, may be outdated |
+| **Objectivity** | No conflicts, balanced view | Minor affiliations disclosed | Funded by interested party, one-sided |
+
+**Overall Rating:**
+- 4 Highs = Strong source — cite with confidence
+- 2+ Mediums = Adequate source — cite with caveats
+- 2+ Lows = Weak source — verify independently before citing
+
+---
+
+## Summary Templates
+
+See `references/summary-templates.md` for:
+- Academic paper summary template (IMRAD)
+- Web article summary template (claim-evidence-implication)
+- Technical report template (executive summary)
+- Comparative analysis template (matrix + synthesis)
+- Literature review template (thematic organization)
+
+See `references/citation-formats.md` for:
+- APA 7 formatting rules and examples
+- IEEE formatting rules and examples
+- Chicago, Harvard, MLA quick reference
+
+---
+
+## Proactive Triggers
+
+Flag these without being asked:
+
+- **Source has no date** → Note it. Undated sources lose credibility points.
+- **Source contradicts other sources** → Highlight the contradiction explicitly. Don't paper over disagreements.
+- **Source is behind a paywall** → Note limited access. Suggest alternatives if known.
+- **User provides only one source for a compare** → Ask for at least one more. Comparison needs 2+.
+- **Citations are incomplete** → Flag missing fields (year, author, title). Don't invent metadata.
+- **Source is 5+ years old in a fast-moving field** → Warn about potential obsolescence.
+
+---
+
+## Installation
+
+### One-liner (any tool)
+```bash
+git clone https://github.com/alirezarezvani/claude-skills.git
+cp -r claude-skills/product-team/research-summarizer ~/.claude/skills/
+```
+
+### Multi-tool install
+```bash
+./scripts/convert.sh --skill research-summarizer --tool codex|gemini|cursor|windsurf|openclaw
+```
+
+### OpenClaw
+```bash
+clawhub install cs-research-summarizer
+```
+
+---
+
+## Related Skills
+
+- **product-analytics** — Quantitative analysis. Complementary — use research-summarizer for qualitative sources, product-analytics for metrics.
+- **competitive-teardown** — Competitive research. Complementary — use research-summarizer for individual source analysis, competitive-teardown for market landscape.
+- **content-production** — Content writing. Research-summarizer feeds content-production — summarize sources first, then write.
+- **product-discovery** — Discovery frameworks. Complementary — research-summarizer for desk research, product-discovery for user research.

package/product/roadmap-communicator/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: roadmap-communicator
+description: Use when preparing roadmap narratives, release notes, changelogs, or stakeholder updates tailored for executives, engineering teams, and customers.
+---
+
+# Roadmap Communicator
+
+Create clear roadmap communication artifacts for internal and external stakeholders.
+
+## When To Use
+
+Use this skill for:
+- Building roadmap presentations in different formats
+- Writing stakeholder updates (board, engineering, customers)
+- Producing release notes (user-facing and internal)
+- Generating changelogs from git history
+- Structuring feature announcements
+
+## Roadmap Formats
+
+1. Now / Next / Later
+- Best for uncertainty and strategic flexibility.
+- Communicate direction without false precision.
+
+2. Timeline roadmap
+- Best for fixed-date commitments and launch coordination.
+- Requires active risk and dependency management.
+
+3. Theme-based roadmap
+- Best for outcome-led planning and cross-team alignment.
+- Groups initiatives by problem space or strategic objective.
+
+See `references/roadmap-templates.md` for templates.
+
+## Stakeholder Update Patterns
+
+### Board / Executive
+- Outcome and risk oriented
+- Focus on progress against strategic goals
+- Highlight trade-offs and required decisions
+
+### Engineering
+- Scope, dependencies, and sequencing clarity
+- Status, blockers, and resourcing implications
+
+### Customers
+- Value narrative and timing window
+- What is available now vs upcoming
+- Clear expectation setting
+
+See `references/communication-templates.md` for reusable templates.
+
+## Release Notes Guidance
+
+### User-Facing Release Notes
+- Lead with user value, not internal implementation details.
+- Group by workflows or user jobs.
+- Include migration/behavior changes explicitly.
+
+### Internal Release Notes
+- Include technical details, operational impact, and known issues.
+- Capture rollout plan, rollback criteria, and monitoring notes.
+
+## Changelog Generation
+
+Use:
+```bash
+python3 scripts/changelog_generator.py --from v1.0.0 --to HEAD
+```
+
+Features:
+- Reads git log range
+- Parses conventional commit prefixes
+- Groups entries by type (`feat`, `fix`, `chore`, etc.)
+- Outputs markdown or plain text
+
+## Feature Announcement Framework
+
+1. Problem context
+2. What changed
+3. Why it matters
+4. Who benefits most
+5. How to get started
+6. Call to action and feedback channel
+
+## Communication Quality Checklist
+
+- [ ] Audience-specific framing is explicit.
+- [ ] Outcomes and trade-offs are clear.
+- [ ] Terminology is consistent across artifacts.
+- [ ] Risks and dependencies are not hidden.
+- [ ] Next actions and owners are specified.

package/product/saas-scaffolder/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: "saas-scaffolder"
+description: "Generates complete, production-ready SaaS project boilerplate including authentication, database schemas, billing integration, API routes, and a working dashboard using Next.js 14+ App Router, TypeScript, Tailwind CSS, shadcn/ui, Drizzle ORM, and Stripe. Use when the user wants to create a new SaaS app, start a subscription-based web project, scaffold a Next.js application, or mentions terms like starter template, boilerplate, new project, or wiring up auth and payments."
+---
+
+# SaaS Scaffolder
+
+**Tier:** POWERFUL  
+**Category:** Product Team  
+**Domain:** Full-Stack Development / Project Bootstrapping
+
+---
+
+## Input Format
+
+```
+Product: [name]
+Description: [1-3 sentences]
+Auth: nextauth | clerk | supabase
+Database: neondb | supabase | planetscale
+Payments: stripe | lemonsqueezy | none
+Features: [comma-separated list]
+```
+
+---
+
+## File Tree Output
+
+```
+my-saas/
+├── app/
+│   ├── (auth)/
+│   │   ├── login/page.tsx
+│   │   ├── register/page.tsx
+│   │   └── layout.tsx
+│   ├── (dashboard)/
+│   │   ├── dashboard/page.tsx
+│   │   ├── settings/page.tsx
+│   │   ├── billing/page.tsx
+│   │   └── layout.tsx
+│   ├── (marketing)/
+│   │   ├── page.tsx
+│   │   ├── pricing/page.tsx
+│   │   └── layout.tsx
+│   ├── api/
+│   │   ├── auth/[...nextauth]/route.ts
+│   │   ├── webhooks/stripe/route.ts
+│   │   ├── billing/checkout/route.ts
+│   │   └── billing/portal/route.ts
+│   └── layout.tsx
+├── components/
+│   ├── ui/
+│   ├── auth/
+│   │   ├── login-form.tsx
+│   │   └── register-form.tsx
+│   ├── dashboard/
+│   │   ├── sidebar.tsx
+│   │   ├── header.tsx
+│   │   └── stats-card.tsx
+│   ├── marketing/
+│   │   ├── hero.tsx
+│   │   ├── features.tsx
+│   │   ├── pricing.tsx
+│   │   └── footer.tsx
+│   └── billing/
+│       ├── plan-card.tsx
+│       └── usage-meter.tsx
+├── lib/
+│   ├── auth.ts
+│   ├── db.ts
+│   ├── stripe.ts
+│   ├── validations.ts
+│   └── utils.ts
+├── db/
+│   ├── schema.ts
+│   └── migrations/
+├── hooks/
+│   ├── use-subscription.ts
+│   └── use-user.ts
+├── types/index.ts
+├── middleware.ts
+├── .env.example
+├── drizzle.config.ts
+└── next.config.ts
+```
+
+---
+
+## Key Component Patterns
+
+### Auth Config (NextAuth)
+
+```typescript
+// lib/auth.ts
+import { NextAuthOptions } from "next-auth"
+import GoogleProvider from "next-auth/providers/google"
+import { DrizzleAdapter } from "@auth/drizzle-adapter"
+import { db } from "./db"
+
+export const authOptions: NextAuthOptions = {
+  adapter: DrizzleAdapter(db),
+  providers: [
+    GoogleProvider({
+      clientId: process.env.GOOGLE_CLIENT_ID!,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+    }),
+  ],
+  callbacks: {
+    session: async ({ session, user }) => ({
+      ...session,
+      user: {
+        ...session.user,
+        id: user.id,
+        subscriptionStatus: user.subscriptionStatus,
+      },
+    }),
+  },
+  pages: { signIn: "/login" },
+}
+```
+
+### Database Schema (Drizzle + NeonDB)
+
+```typescript
+// db/schema.ts
+import { pgTable, text, timestamp, integer } from "drizzle-orm/pg-core"
+
+export const users = pgTable("users", {
+  id: text("id").primaryKey().$defaultFn(() => crypto.randomUUID()),
+  name: text("name"),
+  email: text("email").notNull().unique(),
+  emailVerified: timestamp("emailVerified"),
+  image: text("image"),
+  stripeCustomerId: text("stripe_customer_id").unique(),
+  stripeSubscriptionId: text("stripe_subscription_id"),
+  stripePriceId: text("stripe_price_id"),
+  stripeCurrentPeriodEnd: timestamp("stripe_current_period_end"),
+  createdAt: timestamp("created_at").defaultNow().notNull(),
+})
+
+export const accounts = pgTable("accounts", {
+  userId: text("user_id").notNull().references(() => users.id, { onDelete: "cascade" }),
+  type: text("type").notNull(),
+  provider: text("provider").notNull(),
+  providerAccountId: text("provider_account_id").notNull(),
+  refresh_token: text("refresh_token"),
+  access_token: text("access_token"),
+  expires_at: integer("expires_at"),
+})
+```
+
+### Stripe Checkout Route
+
+```typescript
+// app/api/billing/checkout/route.ts
+import { NextResponse } from "next/server"
+import { getServerSession } from "next-auth"
+import { authOptions } from "@/lib/auth"
+import { stripe } from "@/lib/stripe"
+import { db } from "@/lib/db"
+import { users } from "@/db/schema"
+import { eq } from "drizzle-orm"
+
+export async function POST(req: Request) {
+  const session = await getServerSession(authOptions)
+  if (!session?.user) return NextResponse.json({ error: "Unauthorized" }, { status: 401 })
+
+  const { priceId } = await req.json()
+  const [user] = await db.select().from(users).where(eq(users.id, session.user.id))
+
+  let customerId = user.stripeCustomerId
+  if (!customerId) {
+    const customer = await stripe.customers.create({ email: session.user.email! })
+    customerId = customer.id
+    await db.update(users).set({ stripeCustomerId: customerId }).where(eq(users.id, user.id))
+  }
+
+  const checkoutSession = await stripe.checkout.sessions.create({
+    customer: customerId,
+    mode: "subscription",
+    payment_method_types: ["card"],
+    line_items: [{ price: priceId, quantity: 1 }],
+    success_url: `${process.env.NEXT_PUBLIC_APP_URL}/dashboard?upgraded=true`,
+    cancel_url: `${process.env.NEXT_PUBLIC_APP_URL}/pricing`,
+    subscription_data: { trial_period_days: 14 },
+  })
+
+  return NextResponse.json({ url: checkoutSession.url })
+}
+```
+
+### Middleware
+
+```typescript
+// middleware.ts
+import { withAuth } from "next-auth/middleware"
+import { NextResponse } from "next/server"
+
+export default withAuth(
+  function middleware(req) {
+    const token = req.nextauth.token
+    if (req.nextUrl.pathname.startsWith("/dashboard") && !token) {
+      return NextResponse.redirect(new URL("/login", req.url))
+    }
+  },
+  { callbacks: { authorized: ({ token }) => !!token } }
+)
+
+export const config = {
+  matcher: ["/dashboard/:path*", "/settings/:path*", "/billing/:path*"],
+}
+```
+
+### Environment Variables Template
+
+```bash
+# .env.example
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+DATABASE_URL=postgresql://user:pass@ep-xxx.us-east-1.aws.neon.tech/neondb?sslmode=require
+NEXTAUTH_SECRET=generate-with-openssl-rand-base64-32
+NEXTAUTH_URL=http://localhost:3000
+GOOGLE_CLIENT_ID=
+GOOGLE_CLIENT_SECRET=
+STRIPE_SECRET_KEY=sk_test_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
+STRIPE_PRO_PRICE_ID=price_...
+```
+
+---
+
+## Scaffold Checklist
+
+The following phases must be completed in order. **Validate at the end of each phase before proceeding.**
+
+### Phase 1 — Foundation
+- [ ] 1. Next.js initialized with TypeScript and App Router
+- [ ] 2. Tailwind CSS configured with custom theme tokens
+- [ ] 3. shadcn/ui installed and configured
+- [ ] 4. ESLint + Prettier configured
+- [ ] 5. `.env.example` created with all required variables
+
+✅ **Validate:** Run `npm run build` — no TypeScript or lint errors should appear.  
+🔧 **If build fails:** Check `tsconfig.json` paths and that all shadcn/ui peer dependencies are installed.
+
+### Phase 2 — Database
+- [ ] 6. Drizzle ORM installed and configured
+- [ ] 7. Schema written (users, accounts, sessions, verification_tokens)
+- [ ] 8. Initial migration generated and applied
+- [ ] 9. DB client singleton exported from `lib/db.ts`
+- [ ] 10. DB connection tested in local environment
+
+✅ **Validate:** Run a simple `db.select().from(users)` in a test script — it should return an empty array without throwing.  
+🔧 **If DB connection fails:** Verify `DATABASE_URL` format includes `?sslmode=require` for NeonDB/Supabase. Check that the migration has been applied with `drizzle-kit push` (dev) or `drizzle-kit migrate` (prod).
+
+### Phase 3 — Authentication
+- [ ] 11. Auth provider installed (NextAuth / Clerk / Supabase)
+- [ ] 12. OAuth provider configured (Google / GitHub)
+- [ ] 13. Auth API route created
+- [ ] 14. Session callback adds user ID and subscription status
+- [ ] 15. Middleware protects dashboard routes
+- [ ] 16. Login and register pages built with error states
+
+✅ **Validate:** Sign in via OAuth, confirm session user has `id` and `subscriptionStatus`. Attempt to access `/dashboard` without a session — you should be redirected to `/login`.  
+🔧 **If sign-out loops occur in production:** Ensure `NEXTAUTH_SECRET` is set and consistent across deployments. Add `declare module "next-auth"` to extend session types if TypeScript errors appear.
+
+### Phase 4 — Payments
+- [ ] 17. Stripe client initialized with TypeScript types
+- [ ] 18. Checkout session route created
+- [ ] 19. Customer portal route created
+- [ ] 20. Stripe webhook handler with signature verification
+- [ ] 21. Webhook updates user subscription status in DB idempotently
+
+✅ **Validate:** Complete a Stripe test checkout using a `4242 4242 4242 4242` card. Confirm `stripeSubscriptionId` is written to the DB. Replay the `checkout.session.completed` webhook event and confirm idempotency (no duplicate DB writes).  
+🔧 **If webhook signature fails:** Use `stripe listen --forward-to localhost:3000/api/webhooks/stripe` locally — never hardcode the raw webhook secret. Verify `STRIPE_WEBHOOK_SECRET` matches the listener output.
+
+### Phase 5 — UI
+- [ ] 22. Landing page with hero, features, pricing sections
+- [ ] 23. Dashboard layout with sidebar and responsive header
+- [ ] 24. Billing page showing current plan and upgrade options
+- [ ] 25. Settings page with profile update form and success states
+
+✅ **Validate:** Run `npm run build` for a final production build check. Navigate all routes manually and confirm no broken layouts, missing session data, or hydration errors.
+
+---
+
+## Reference Files
+
+For additional guidance, generate the following companion reference files alongside the scaffold:
+
+- **`CUSTOMIZATION.md`** — Auth providers, database options, ORM alternatives, payment providers, UI themes, and billing models (per-seat, flat-rate, usage-based).
+- **`PITFALLS.md`** — Common failure modes: missing `NEXTAUTH_SECRET`, webhook secret mismatches, Edge runtime conflicts with Drizzle, unextended session types, and migration strategy differences between dev and prod.
+- **`BEST_PRACTICES.md`** — Stripe singleton pattern, server actions for form mutations, idempotent webhook handlers, `Suspense` boundaries for async dashboard data, server-side feature gating via `stripeCurrentPeriodEnd`, and rate limiting on auth routes with Upstash Redis + `@upstash/ratelimit`.