@punks/cli 0.1.16 → 1.0.0

package/dist/skills/agnostic/subagents/swarm-planner/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: swarm-planner
+description: >
+  [EXPLICIT INVOCATION ONLY] Creates dependency-aware implementation plans optimized for parallel
+  multi-agent execution.
+metadata:
+  invocation: explicit-only
+---
+
+# Swarm-Ready Planner
+
+Create implementation plans with explicit task dependencies optimized for parallel agent execution. This skill can be ran inside or outside of Plan Mode. 
+
+## Core Principles
+
+1. **Explore Codebase**: Investigate architecture, patterns, existing implementations, dependencies, and frameworks in use.
+2. **Fresh Documentation First**: Use Context7 for ANY external library, framework, or API before planning tasks
+3. **Ask Questions**: Clarify ambiguities and seek clarification on scope, constraints, or priorities throughout the planning process. At any time.
+4. **Explicit Dependencies**: Every task declares what it depends on, enabling maximum parallelization
+5. **Atomic Tasks**: Each task is independently executable by a single agent
+6. **Review Before Yield**: A subagent reviews the plan for gaps before finalizing
+
+## Process
+
+### 1. Research
+
+**Codebase investigation:**
+- Architecture, patterns, existing implementations
+- Dependencies and frameworks in use
+
+### 1a. Optional: Stop to Clarification Questions
+
+- If the architecture is unclear or missing STOP AND YIELD to the user, and request user input (AskUserQuestions) before moving on. Always offer recommendations for clarification questions.
+- If architecture is present, skip 1a and move onto next step. 
+
+### 2. Documentation
+
+**Documentation retrieval (REQUIRED for external dependencies):**
+
+Use Context7 skill or MCP to fetch current docs for any libraries/frameworks or APIs that are or will be used in project. If Context7 is not available, use web search.
+
+This ensures version-accurate APIs, correct parameters, and current best practices.
+
+### 3. STOP and Request User Input
+
+When anything is unclear or could reasonably be done multiple ways:
+- Stop and ask clarifying questions immediately
+- Do not make assumptions about scope, constraints, or priorities
+- Questions should reduce risk and eliminate ambiguity
+- Always offer recommendations for clarification questions.
+- Use request_user_input or AskUserQuestion tool if available. 
+
+### 4. Create Dependency-Aware Plan
+
+Structure the plan with explicit task dependencies using this format:
+
+#### Task Dependency Format
+
+Each task MUST include:
+- **id**: Unique identifier (e.g., `T1`, `T2.1`)
+- **depends_on**: Array of task IDs that must complete first (empty `[]` for root tasks)
+- **description**: What the task accomplishes
+- **location**: File paths involved
+- **validation**: How to verify completion
+
+**Example:**
+```
+T1: [depends_on: []] Create database schema migration
+T2: [depends_on: []] Install required packages
+T3: [depends_on: [T1]] Create repository layer
+T4: [depends_on: [T1]] Create service interfaces
+T5: [depends_on: [T3, T4]] Implement business logic
+T6: [depends_on: [T2, T5]] Add API endpoints
+T7: [depends_on: [T6]] Write integration tests
+```
+
+Tasks with empty/satisfied dependencies can run in parallel (T1, T2 above).
+
+### 4. Save Plan
+
+Save to `<topic>-plan.md` in the CWD.
+
+### 5. Subagent Review
+
+After saving, spawn a subagent to review the plan:
+
+```
+Review this implementation plan for:
+1. Missing dependencies between tasks
+2. Ordering issues that would cause failures
+3. Missing error handling or edge cases
+4. Gaps, holes, gotchas.
+
+Provide specific, actionable feedback. Do not ask questions.
+
+Plan location: [file path]
+Context: [brief context about the task]
+```
+
+If the subagent provides actionable feedback, revise the plan before yielding.
+
+
+## Plan Template
+
+```markdown
+# Plan: [Task Name]
+
+**Generated**: [Date]
+
+## Overview
+[Summary of task and approach]
+
+## Prerequisites
+- [Tools, libraries, access needed]
+
+## Dependency Graph
+
+```
+[Visual representation of task dependencies]
+T1 ──┬── T3 ──┐
+     │        ├── T5 ── T6 ── T7
+T2 ──┴── T4 ──┘
+```
+
+## Tasks
+
+### T1: [Name]
+- **depends_on**: []
+- **location**: [file paths]
+- **description**: [what to do]
+- **validation**: [how to verify]
+- **status**: Not Completed
+- **log**: [leave empty, to be filled out later]
+- **files edited/created**: [leave empty, to be filled out later]
+
+### T2: [Name]
+- **depends_on**: []
+- **location**: [file paths]
+- **description**: [what to do]
+- **validation**: [how to verify]
+- **status**: Not Completed
+- **log**: [leave empty, to be filled out later]
+- **files edited/created**: [leave empty, to be filled out later]
+
+### T3: [Name]
+- **depends_on**: [T1]
+- **location**: [file paths]
+- **description**: [what to do]
+- **validation**: [how to verify]
+- **status**: Not Completed
+- **log**: [leave empty, to be filled out later]
+- **files edited/created**: [leave empty, to be filled out later]
+
+[... continue for all tasks ...]
+
+## Parallel Execution Groups
+
+| Wave | Tasks | Can Start When |
+|------|-------|----------------|
+| 1 | T1, T2 | Immediately |
+| 2 | T3, T4 | Wave 1 complete |
+| 3 | T5 | T3, T4 complete |
+| ... | ... | ... |
+
+## Testing Strategy
+- [How to test]
+- [What to verify]
+
+## Risks & Mitigations
+- [What could go wrong + how to handle]
+```
+
+## Important
+
+- Every task must have explicit `depends_on` field
+- Root tasks (no dependencies) can be executed in parallel immediately
+- Do NOT implement - only create the plan
+- Always use Context7 for external dependencies before finalizing tasks
+- Always ask questions where ambiguity exists

package/dist/skills/agnostic/write-a-skill/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: write-a-skill
+description: Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill.
+---
+
+# Writing Skills
+
+## Process
+
+1. **Gather requirements** - ask user about:
+   - What task/domain does the skill cover?
+   - What specific use cases should it handle?
+   - Does it need executable scripts or just instructions?
+   - Any reference materials to include?
+
+2. **Draft the skill** - create:
+   - SKILL.md with concise instructions
+   - Additional reference files if content exceeds 500 lines
+   - Utility scripts if deterministic operations needed
+
+3. **Review with user** - present draft and ask:
+   - Does this cover your use cases?
+   - Anything missing or unclear?
+   - Should any section be more/less detailed?
+
+## Skill Structure
+
+```
+skill-name/
+├── SKILL.md           # Main instructions (required)
+├── REFERENCE.md       # Detailed docs (if needed)
+├── EXAMPLES.md        # Usage examples (if needed)
+└── scripts/           # Utility scripts (if needed)
+    └── helper.js
+```
+
+## SKILL.md Template
+
+```md
+---
+name: skill-name
+description: Brief description of capability. Use when [specific triggers].
+---
+
+# Skill Name
+
+## Quick start
+
+[Minimal working example]
+
+## Workflows
+
+[Step-by-step processes with checklists for complex tasks]
+
+## Advanced features
+
+[Link to separate files: See [REFERENCE.md](REFERENCE.md)]
+```
+
+## Description Requirements
+
+The description is **the only thing your agent sees** when deciding which skill to load. It's surfaced in the system prompt alongside all other installed skills. Your agent reads these descriptions and picks the relevant skill based on the user's request.
+
+**Goal**: Give your agent just enough info to know:
+
+1. What capability this skill provides
+2. When/why to trigger it (specific keywords, contexts, file types)
+
+**Format**:
+
+- Max 1024 chars
+- Write in third person
+- First sentence: what it does
+- Second sentence: "Use when [specific triggers]"
+
+**Good example**:
+
+```
+Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.
+```
+
+**Bad example**:
+
+```
+Helps with documents.
+```
+
+The bad example gives your agent no way to distinguish this from other document skills.
+
+## When to Add Scripts
+
+Add utility scripts when:
+
+- Operation is deterministic (validation, formatting)
+- Same code would be generated repeatedly
+- Errors need explicit handling
+
+Scripts save tokens and improve reliability vs generated code.
+
+## When to Split Files
+
+Split into separate files when:
+
+- SKILL.md exceeds 100 lines
+- Content has distinct domains (finance vs sales schemas)
+- Advanced features are rarely needed
+
+## Review Checklist
+
+After drafting, verify:
+
+- [ ] Description includes triggers ("Use when...")
+- [ ] SKILL.md under 100 lines
+- [ ] No time-sensitive info
+- [ ] Consistent terminology
+- [ ] Concrete examples included
+- [ ] References one level deep

package/dist/skills/frameworks/better-auth/better-auth-best-practices/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: better-auth-best-practices
+description: Skill for integrating Better Auth - the comprehensive TypeScript authentication framework.
+---
+
+# Better Auth Integration Guide
+
+**Always consult [better-auth.com/docs](https://better-auth.com/docs) for code examples and latest API.**
+
+Better Auth is a TypeScript-first, framework-agnostic auth framework supporting email/password, OAuth, magic links, passkeys, and more via plugins.
+
+---
+
+## Quick Reference
+
+### Environment Variables
+- `BETTER_AUTH_SECRET` - Encryption secret (min 32 chars). Generate: `openssl rand -base64 32`
+- `BETTER_AUTH_URL` - Base URL (e.g., `https://example.com`)
+
+Only define `baseURL`/`secret` in config if env vars are NOT set.
+
+### File Location
+CLI looks for `auth.ts` in: `./`, `./lib`, `./utils`, or under `./src`. Use `--config` for custom path.
+
+### CLI Commands
+- `npx @better-auth/cli@latest migrate` - Apply schema (built-in adapter)
+- `npx @better-auth/cli@latest generate` - Generate schema for Prisma/Drizzle
+- `npx @better-auth/cli mcp --cursor` - Add MCP to AI tools
+
+**Re-run after adding/changing plugins.**
+
+---
+
+## Core Config Options
+
+| Option | Notes |
+|--------|-------|
+| `appName` | Optional display name |
+| `baseURL` | Only if `BETTER_AUTH_URL` not set |
+| `basePath` | Default `/api/auth`. Set `/` for root. |
+| `secret` | Only if `BETTER_AUTH_SECRET` not set |
+| `database` | Required for most features. See adapters docs. |
+| `secondaryStorage` | Redis/KV for sessions & rate limits |
+| `emailAndPassword` | `{ enabled: true }` to activate |
+| `socialProviders` | `{ google: { clientId, clientSecret }, ... }` |
+| `plugins` | Array of plugins |
+| `trustedOrigins` | CSRF whitelist |
+
+---
+
+## Database
+
+**Direct connections:** Pass `pg.Pool`, `mysql2` pool, `better-sqlite3`, or `bun:sqlite` instance.
+
+**ORM adapters:** Import from `better-auth/adapters/drizzle`, `better-auth/adapters/prisma`, `better-auth/adapters/mongodb`.
+
+**Critical:** Better Auth uses adapter model names, NOT underlying table names. If Prisma model is `User` mapping to table `users`, use `modelName: "user"` (Prisma reference), not `"users"`.
+
+---
+
+## Session Management
+
+**Storage priority:**
+1. If `secondaryStorage` defined → sessions go there (not DB)
+2. Set `session.storeSessionInDatabase: true` to also persist to DB
+3. No database + `cookieCache` → fully stateless mode
+
+**Cookie cache strategies:**
+- `compact` (default) - Base64url + HMAC. Smallest.
+- `jwt` - Standard JWT. Readable but signed.
+- `jwe` - Encrypted. Maximum security.
+
+**Key options:** `session.expiresIn` (default 7 days), `session.updateAge` (refresh interval), `session.cookieCache.maxAge`, `session.cookieCache.version` (change to invalidate all sessions).
+
+---
+
+## User & Account Config
+
+**User:** `user.modelName`, `user.fields` (column mapping), `user.additionalFields`, `user.changeEmail.enabled` (disabled by default), `user.deleteUser.enabled` (disabled by default).
+
+**Account:** `account.modelName`, `account.accountLinking.enabled`, `account.storeAccountCookie` (for stateless OAuth).
+
+**Required for registration:** `email` and `name` fields.
+
+---
+
+## Email Flows
+
+- `emailVerification.sendVerificationEmail` - Must be defined for verification to work
+- `emailVerification.sendOnSignUp` / `sendOnSignIn` - Auto-send triggers
+- `emailAndPassword.sendResetPassword` - Password reset email handler
+
+---
+
+## Security
+
+**In `advanced`:**
+- `useSecureCookies` - Force HTTPS cookies
+- `disableCSRFCheck` - ⚠️ Security risk
+- `disableOriginCheck` - ⚠️ Security risk  
+- `crossSubDomainCookies.enabled` - Share cookies across subdomains
+- `ipAddress.ipAddressHeaders` - Custom IP headers for proxies
+- `database.generateId` - Custom ID generation or `"serial"`/`"uuid"`/`false`
+
+**Rate limiting:** `rateLimit.enabled`, `rateLimit.window`, `rateLimit.max`, `rateLimit.storage` ("memory" | "database" | "secondary-storage").
+
+---
+
+## Hooks
+
+**Endpoint hooks:** `hooks.before` / `hooks.after` - Array of `{ matcher, handler }`. Use `createAuthMiddleware`. Access `ctx.path`, `ctx.context.returned` (after), `ctx.context.session`.
+
+**Database hooks:** `databaseHooks.user.create.before/after`, same for `session`, `account`. Useful for adding default values or post-creation actions.
+
+**Hook context (`ctx.context`):** `session`, `secret`, `authCookies`, `password.hash()`/`verify()`, `adapter`, `internalAdapter`, `generateId()`, `tables`, `baseURL`.
+
+---
+
+## Plugins
+
+**Import from dedicated paths for tree-shaking:**
+```
+import { twoFactor } from "better-auth/plugins/two-factor"
+```
+NOT `from "better-auth/plugins"`.
+
+**Popular plugins:** `twoFactor`, `organization`, `passkey`, `magicLink`, `emailOtp`, `username`, `phoneNumber`, `admin`, `apiKey`, `bearer`, `jwt`, `multiSession`, `sso`, `oauthProvider`, `oidcProvider`, `openAPI`, `genericOAuth`.
+
+Client plugins go in `createAuthClient({ plugins: [...] })`.
+
+---
+
+## Client
+
+Import from: `better-auth/client` (vanilla), `better-auth/react`, `better-auth/vue`, `better-auth/svelte`, `better-auth/solid`.
+
+Key methods: `signUp.email()`, `signIn.email()`, `signIn.social()`, `signOut()`, `useSession()`, `getSession()`, `revokeSession()`, `revokeSessions()`.
+
+---
+
+## Type Safety
+
+Infer types: `typeof auth.$Infer.Session`, `typeof auth.$Infer.Session.user`.
+
+For separate client/server projects: `createAuthClient<typeof auth>()`.
+
+---
+
+## Common Gotchas
+
+1. **Model vs table name** - Config uses ORM model name, not DB table name
+2. **Plugin schema** - Re-run CLI after adding plugins
+3. **Secondary storage** - Sessions go there by default, not DB
+4. **Cookie cache** - Custom session fields NOT cached, always re-fetched
+5. **Stateless mode** - No DB = session in cookie only, logout on cache expiry
+6. **Change email flow** - Sends to current email first, then new email
+
+---
+
+## Resources
+
+- [Docs](https://better-auth.com/docs)
+- [Options Reference](https://better-auth.com/docs/reference/options)
+- [LLMs.txt](https://better-auth.com/llms.txt)
+- [GitHub](https://github.com/better-auth/better-auth)
+- [Init Options Source](https://github.com/better-auth/better-auth/blob/main/packages/core/src/types/init-options.ts)