@nerdev/skillset 0.2.1

package/skills/architecture/blueprint/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: blueprint
+category: architecture
+source: ECC (adapted)
+description: "Multi-PR construction plans with adversarial review. Load when planning complex features or breaking work into steps."
+
+# Blueprint
+
+**When to use:** Planning complex features, breaking work into PRs, creating implementation plans with review gates.
+
+
+## What It Does
+
+Turns a one-line objective into a multi-PR construction plan with self-contained step briefs so any agent can execute any step cold.
+
+
+## Process
+
+```
+1. Define objective (one line)
+2. Research codebase (understand current state)
+3. Break into steps (each step = one PR)
+4. Adversarial review (strongest model reviews plan)
+5. Generate step briefs (self-contained instructions)
+6. Execute with checkpoints
+```
+
+
+## Step Brief Format
+
+Each step gets a self-contained brief:
+
+```markdown
+## Step 3: Add User Authentication
+
+### Objective
+Implement JWT-based authentication with refresh tokens.
+
+### Files to Create/Modify
+- `packages/core/auth/jwt.ts` (create)
+- `packages/core/auth/middleware.ts` (create)
+- `apps/http-backend/src/routes/auth.ts` (modify)
+- `apps/http-backend/src/middleware/auth.ts` (create)
+
+### Dependencies
+- Step 1 (database schema) must be complete
+- Step 2 (user model) must be complete
+
+### Implementation Details
+1. Create JWT utilities in `packages/core/auth/jwt.ts`
+2. Add auth middleware to `apps/http-backend/src/middleware/auth.ts`
+3. Create auth routes in `apps/http-backend/src/routes/auth.ts`
+4. Protect existing routes with auth middleware
+
+### Verification
+- [ ] Unit tests for JWT utilities
+- [ ] Integration tests for auth routes
+- [ ] Protected routes return 401 without token
+- [ ] Refresh token rotation works
+
+### Rollback Plan
+- Revert auth middleware changes
+- Remove auth routes
+- Database schema unchanged (Step 1)
+```
+
+
+## Adversarial Review
+
+Before executing, have a stronger model review the plan:
+
+### Review Checklist
+- [ ] Are steps in correct order?
+- [ ] Are dependencies clear?
+- [ ] Are verification criteria specific?
+- [ ] Are rollback plans realistic?
+- [ ] Is scope appropriate per step?
+- [ ] Are there hidden complexity bombs?
+
+### Review Output
+```markdown
+## Plan Review
+
+### Issues Found
+1. Step 3 depends on Step 5 (circular dependency)
+   - Fix: Move Step 5 before Step 3
+
+2. Step 4 scope too large (300+ lines)
+   - Fix: Split into Step 4a and Step 4b
+
+### Recommendations
+- Add performance testing to Step 6
+- Consider database migration rollback in Step 1
+
+### Verdict: NEEDS REVISION
+```
+
+
+## Plan Mutation Protocol
+
+Plans change. When they do:
+
+### Split
+When a step is too large:
+```markdown
+## Step 4a: User Registration
+[original step content]
+
+## Step 4b: User Login
+[new step content]
+```
+
+### Insert
+When new work is discovered:
+```markdown
+## Step 3.5: Add Email Validation
+[inserted step with clear dependency on Step 3]
+```
+
+### Skip
+When work is no longer needed:
+```markdown
+## Step 6: ~~Add CSV Export~~ (SKIPPED)
+Reason: Feature deprioritized in favor of API access
+```
+
+### Reorder
+When dependencies change:
+```markdown
+## Step 5: ~~Add Caching~~ (MOVED to Step 3)
+Reason: Performance critical, should be implemented earlier
+```
+
+Each mutation gets an audit trail entry.
+
+
+## Branch/PR Workflow
+
+Each step becomes a PR:
+
+```bash
+# Step 1
+git checkout -b feat/user-schema
+# ... implement ...
+git commit -m "feat(db): add user schema"
+git push -u origin feat/user-schema
+gh pr create --base main --title "Step 1: User Schema"
+
+# Step 2
+git checkout -b feat/user-model
+# ... implement ...
+git commit -m "feat(core): add user model"
+git push -u origin feat/user-model
+gh pr create --base main --title "Step 2: User Model"
+```
+
+### PR Naming Convention
+```
+Step N: [Brief description]
+```
+
+Examples:
+- `Step 1: User Schema`
+- `Step 2: User Model`
+- `Step 3: JWT Authentication`
+- `Step 4a: User Registration`
+- `Step 4b: User Login`
+
+
+## Quick Commands
+
+```bash
+# Create new blueprint
+echo "## Objective: [one line description]" > blueprint.md
+
+# Review plan
+# (use strongest available model)
+
+# Create branch for step
+git checkout -b feat/step-N-description
+
+# Create PR
+gh pr create --base main --title "Step N: Description"
+```
+
+
+## Related Skills
+
+- `nerdev/nerdev-docs` - Design docs and ADRs
+- `devops/git-ci` - PR workflow and CI
+- `architecture/search-first` - Research before planning

package/skills/architecture/code-tour/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: code-tour
+category: architecture
+source: ECC (adapted)
+description: "Guided codebase walkthroughs for onboarding. Load when onboarding new team members or documenting architecture."
+
+# Code Tour
+
+**When to use:** Onboarding new team members, documenting architecture, creating guided walkthroughs, explaining complex systems.
+
+
+## What It Does
+
+Creates guided, step-by-step codebase walkthroughs with real file and line anchors. Each tour is tailored to a specific persona.
+
+
+## Personas
+
+| Persona | Focus | Depth |
+|---------|-------|-------|
+| `new-joiner` | How to get started, where things are | High-level overview |
+| `vibecoder` | Quick implementation patterns | Practical examples |
+| `architect` | System design, trade-offs | Deep analysis |
+| `pr-reviewer` | What to check, common issues | Focused checklist |
+| `rca-investigator` | Debugging, logs, failure modes | Investigation paths |
+| `security-reviewer` | Attack surfaces, auth flows | Security-focused |
+| `feature-explainer` | How a specific feature works | Feature-focused |
+| `bug-fixer` | How to debug, where to look | Problem-solving |
+
+
+## Tour Structure
+
+```markdown
+# Code Tour: [System Name]
+
+**Persona:** [target persona]
+**Last Updated:** [date]
+**Estimated Time:** [X minutes]
+
+## Orientation
+[What is this system? What does it do?]
+
+## Module Map
+[High-level diagram of components]
+
+## Core Path
+[The most important code path, step by step]
+
+## Edge Cases
+[Where things get tricky]
+
+## Next Move
+[What to explore after this tour]
+```
+
+
+## Writing Style: SMIG Rule
+
+Every section follows:
+
+- **S**ituation - What's happening?
+- **M**echanism - How does it work?
+- **I**mplication - Why does it matter?
+- **G**otcha - What to watch out for?
+
+```markdown
+## Authentication Flow
+
+**Situation:** Users need to authenticate before accessing protected routes.
+
+**Mechanism:** JWT tokens with refresh rotation. Short-lived access tokens (15min) 
+stored in memory, long-lived refresh tokens (7 days) stored in httpOnly cookies.
+
+**Implication:** No token storage in localStorage (XSS safe), but requires 
+server-side session table for revocation.
+
+**Gotcha:** Refresh token rotation means each use invalidates the previous token. 
+If a user has multiple tabs open, only the most recent tab stays authenticated.
+```
+
+
+## Tour Example: New Joiner
+
+```markdown
+# Code Tour: E-Commerce Platform
+
+**Persona:** new-joiner
+**Last Updated:** 2026-08-13
+**Estimated Time:** 20 minutes
+
+## Orientation
+
+This is a monorepo with 3 apps:
+- `apps/web` - Customer-facing storefront (Next.js)
+- `apps/admin` - Internal admin panel (React)
+- `apps/api` - Backend API (Node.js + Express)
+
+## Module Map
+
+```
+apps/
+├── web/           # Customer UI
+├── admin/         # Admin UI
+└── api/           # Backend
+packages/
+├── ui/            # Shared components
+├── db/            # Database schema
+└── common/        # Shared utilities
+```
+
+## Core Path: User Places Order
+
+1. **Cart → Checkout** (`apps/web/src/pages/checkout.tsx:45`)
+   - User clicks "Proceed to Checkout"
+   - Redirects to `/checkout` with cart items in state
+
+2. **Payment Processing** (`apps/api/src/routes/payments.ts:23`)
+   - Stripe integration for payment
+   - Creates payment intent, returns client secret
+
+3. **Order Creation** (`apps/api/src/routes/orders.ts:67`)
+   - Validates inventory
+   - Creates order in database
+   - Sends confirmation email
+
+4. **Order Confirmation** (`apps/web/src/pages/order-confirmation.tsx:12`)
+   - Shows order summary
+   - Provides tracking information
+
+## Edge Cases
+
+- **Inventory Race Condition** (`apps/api/src/services/inventory.ts:89`)
+  - Two users buy last item simultaneously
+  - Optimistic locking prevents overselling
+
+- **Payment Failure** (`apps/api/src/routes/payments.ts:156`)
+  - If payment fails after order creation
+  - Order marked as "payment_failed", inventory released
+
+## Next Move
+
+After this tour, explore:
+1. `apps/api/src/middleware/` - How requests are authenticated
+2. `packages/db/prisma/schema.prisma` - Data model
+3. `apps/web/src/hooks/` - React hooks for data fetching
+```
+
+
+## Code Annotations for Tours
+
+Mark important code with annotations:
+
+```typescript
+/**
+ * @tour [tour-name] - [step-number]: [brief description]
+ * @tour-persona new-joiner, architect
+ * @tour-gotcha Watch out for race condition here
+ */
+export async function processOrder(orderId: string): Promise<Order> {
+  // ...
+}
+```
+
+
+## Generating Tours
+
+### From Code
+```bash
+# Generate tour from code structure
+find . -name "*.ts" -o -name "*.tsx" | head -20
+
+# Identify main entry points
+grep -r "export default\|export function" --include="*.ts" --include="*.tsx"
+
+# Find important patterns
+grep -r "@tour\|@important\|@gotcha" --include="*.ts" --include="*.tsx"
+```
+
+### From Issues
+Look at past incidents and bugs - they reveal:
+- Complex code paths
+- Common failure modes
+- Areas needing documentation
+
+
+## Quick Commands
+
+```bash
+# Create new tour
+echo "# Code Tour: [System Name]" > CODE_TOUR.md
+
+# Add annotations to code
+# Add @tour comments to important functions
+
+# Update tour after changes
+# Keep file references and line numbers current
+```
+
+
+## Related Skills
+
+- `nerdev/nerdev-docs` - Documentation patterns
+- `architecture/blueprint` - Implementation planning
+- `ai-agent/agent-docs-writer` - AI agent guidance

package/skills/architecture/progress-guard/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: progress-guard
+description: "Use whenever the user does setup work while a main project (the current SHIP thread) has code work pending. Setup work includes: docs, curation, planning, skill-collecting, repo organization, and interview-script rewrites. Trigger on \"let me first update the docs\", \"just reorganizing\", \"saw this new skill/library, let me plan around it\", project-switching after an external event (interview questions, someone's comment, a new idea), or any session where the user describes feeling stuck on the main project. Detects motion vs progress. Checks whether the current activity advances the SHIP thread. Redirects to one concrete next action on the real project."
+---
+
+# Progress Guard
+
+The user's known failure mode, documented from experience: when a main
+project gets hard or scary, attention flees into "useful-looking"
+work. Docs rewrites, skill curation, planning, and scripts that
+describe the project instead of building it all count. This looks like
+progress, feels like progress, and produces none. The user shipped
+real projects with AI (modheshwari, CoDraw). The next one (playmesh)
+stalled for exactly this reason.
+
+## Current SHIP thread (recorded, dated)
+
+- **playmesh**. Direction decided by the user (2026-08-17): P2P-no-server
+  WebRTC first (never worked with WebRTC), renderer (canvas/WebGL)
+  second, original game third. The "stand out from stack" layer is the
+  new thing, not bun/ws/microservices (already proven in
+  CoDraw/modheshwari). No external audience. Intrinsic fuel. Do not
+  force an audience. Anchor sessions to this order. When the user
+  drifts to docs/curation/other projects, re-anchor here with one
+  concrete step (e.g. two-tab WebRTC hello demo).
+
+## The pattern to recognize
+
+Distinguish **motion** (activity that feels productive) from
+**progress** (activity that advances the SHIP thread):
+
+Motion:
+- Writing or rewriting docs, READMEs, architecture notes, whiteboard
+  scripts.
+- Curating skills, collecting libraries, watching or hand-picking
+  tools, planning the skill or repo.
+- Repo organization, setup refactoring, environment or tooling
+  rabbit holes.
+- Switching projects because something external poked (an interview
+  question about another project, someone praised or doubted one, a new
+  idea arrived).
+- Re-planning instead of executing: new roadmap files, fresh task lists
+  for the same old work.
+
+Progress:
+- One concrete unit of the SHIP thread's product actually built,
+  tested, or shipped.
+- Code written that the product's users will touch.
+- A decision made (with reasoning) that the code is now executing on.
+
+## The recognized external-trigger loop
+
+Specific documented loop: external event (e.g. someone says
+"modheshwari is your best project, discuss it") -> freeze (cannot
+explain under pressure) -> immediate escape into docs for that project
+("so the pain point gets resolved") -> project queue reset to whoever
+poked last. The docs are armor against a fear of explaining own work
+without notes. Fix the fear, not the docs.
+
+If the user reports a freeze moment like this, the intervention is a
+**rehearsal**, not more docs: hand the user's own script to an agent
+and have it grill them as an interviewer, escalating, no script in
+front of them, 20 minutes. Do not offer doc-writing as the resolution.
+
+## The curated-only trap (second documented failure mode)
+
+When the user imports
+every tool and design decision in the project from a
+top-tier source (best-practice skills, the "correct" architecture, the
+recommended library), the project loses the user's identity. The user
+loses the ability to explain why the architecture looks like this from
+first principles. That also blocks progress on the main project: when
+nothing is "yours", there is nothing to defend, so the project feels
+unreal.
+
+Intervention: require **one consciously-chosen divergence per project**.
+One place where the user deviates from the common answer on purpose,
+with one line of reasoning ("most projects do X; I do Y because
+<reason>"). Help name it if needed. It becomes the interview story and
+the motivation to keep building.
+
+## The delegated-thinking trap (third documented failure mode)
+
+Boundary: the user offloads the *doing* to AI freely, but never the
+*deciding*. When design decisions, architecture reasoning, or
+plan-shaping goes to the agent wholesale, the project stops being
+the user's. Nothing to defend, nothing committed, and momentum dies
+(documented: playmesh, 5 days stuck after delegating the thinking). A
+user cannot build what they did not decide to build.
+
+Hard rules for agents in any session:
+1. **Present decisions, do not make them.** Options with one-line
+   tradeoffs. The user picks. "Which?" not "I will do X."
+2. **Ask for the user's opinion first** on anything that shapes the
+   product (architecture, scope, UX, what to build next) before
+   offering a recommendation.
+3. **Surface uncertainty, do not resolve it.** If the agent notices an
+   ambiguous requirement, ask. Filling gaps silently converts the
+   user's project into the agent's project.
+4. **Design docs and plans must contain the user's stated reasons**,
+   not paraphrased AI reasoning. If a decision lacks the user's input,
+   stop and get it.
+5. **No delegated "thinking deliverables"** (AI-written architecture
+   docs, AI-chosen roadmaps) unless explicitly requested. When
+   requested, they get marked as drafts the user must amend, not final.
+
+> The user's stated anti-pattern in their own words: "don't let me
+> allocate thinking also to AI, this happened in playmesh and I was
+> stuck for 5 days." If the session shows the user deferring decisions
+> to the agent, this rule is how the agent refuses that deferral.
+
+## Protocol: when the skill fires
+
+1. **Check the "why" of the current task.** Ask (mentally or to the
+   user): does this make the SHIP thread's product more real? If the
+   user says "I'm just keeping things organized / prepping", flag it,
+   do not comply immediately.
+2. **Name the escape.** Say plainly what is happening: this is
+   docs/curation/planning, it is motion. That is the documented
+   pattern, it is fine to feel pulled, but it is not progress. Be
+   brief, non-judgmental, matter-of-fact.
+3. **Offer one concrete next code action** on the SHIP thread. Not a
+   plan. The single smallest real unit you can write, run, or
+   test in the next hour. E.g. "trade one live move in chess between
+   two browser tabs". A shipped micro-inch beats a finished roadmap.
+4. **Only after that** (or if the user insists), allow a bounded
+   doc/curation session: explicitly time-box it (e.g. 25 minutes, one
+   file) and re-anchor to the SHIP thread when it ends. Never let the
+   session end on motion.
+5. **If the user is switching projects after an external trigger**,
+   stop and ask: "did something happen, or did you choose this?" Only
+   a chosen switch counts. If it is a reaction, offer to rehearse the
+   feared moment (interview style) instead of escaping into the other
+   project.
+
+## Stack-rank reframe (when user has many threads)
+
+One money thread (SHIP), one growth thread (GROW), one maintenance
+thread (PARK-able). Everything else parked. Parked means a 3-line state
+note, then closed. The user's docs habit makes parking safe: notes are
+the archive, the thread is off the clock.
+
+## Success criteria
+
+The session ends with: one real unit of the SHIP project built, or the
+freeze moment rehearsed. Not with new docs, new curated lists, or a
+rewritten plan. And every decision that shaped the session's work was
+the user's, not the agent's.

package/skills/architecture/search-first/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: search-first
+category: architecture
+source: ECC (adapted)
+description: "Research-before-coding workflow. Load before implementing new features to find existing solutions."
+
+# Search First
+
+Load before implementing any new feature, adding dependencies, or solving a problem that might already have a solution.
+
+## Decision Matrix
+
+| Option | When to use | Effort | Risk |
+|--------|-------------|--------|------|
+| Adopt | Existing library does exactly what you need | Low | Low |
+| Extend | Existing library does 80% of what you need | Medium | Medium |
+| Compose | Multiple small libraries can be combined | Medium | Low |
+| Build | No existing solution fits, or you need full control | High | High |
+
+## Search Process
+
+### 1. Define Requirements
+
+Before searching, clarify what you need, the constraints, and the acceptance criteria.
+
+### 2. Search Existing Solutions
+
+#### npm/PyPI
+
+```bash
+npm search [keyword]
+npm info [package-name]
+npm info [package-name] | grep "weekly"
+npm info [package-name] | grep "modified"
+```
+
+#### MCP Servers
+
+Check MCP registry or community lists.
+
+#### GitHub
+
+```bash
+gh search repos [keyword] --sort stars --limit 10
+gh api repos/[owner]/[repo] | jq '.pushed_at, .stargazers_count'
+```
+
+#### Existing Skills
+
+```bash
+ls skills/ | grep [keyword]
+grep -r "description:" skills/*/SKILL.md | grep [keyword]
+```
+
+### 3. Evaluate Candidates
+
+For each candidate, check:
+
+| Criteria | How to check |
+|----------|--------------|
+| Maintenance | Last commit date, open issues, release frequency |
+| Popularity | Weekly downloads, GitHub stars, community size |
+| Quality | TypeScript support, test coverage, documentation |
+| Bundle Size | Impact on your bundle |
+| License | Compatible with your project |
+| API Fit | Does the API match your needs? |
+
+### 4. Make Decision
+
+Document the options, the decision, and the trade-offs.
+
+## Anti-Patterns
+
+| Anti-pattern | Problem | Fix |
+|--------------|---------|-----|
+| Jumping to code | Building something that already exists | Search first, build last |
+| Dependency bloat | Adding libraries for trivial things | Prefer native solutions when simple |
+| Copy-paste | Importing code without understanding | Understand before adopting |
+| NIH syndrome | "Not invented here" bias | Evaluate fairly, not emotionally |
+| Premature abstraction | Building for hypothetical future needs | Solve today's problem first |
+
+## Search Checklist
+
+Before implementing:
+
+- [ ] Searched npm/PyPI for existing libraries
+- [ ] Searched GitHub for existing implementations
+- [ ] Checked if skill already exists
+- [ ] Evaluated top 3 candidates
+- [ ] Documented decision with trade-offs
+- [ ] Considered "build" option last, not first
+
+## Related Skills
+
+- `architecture/blueprint` - Planning implementation
+- `nerdev/nerdev-docs` - Documenting decisions
+- `engineering/coding-standards` - Code quality standards