skillfullstack 1.0.1 → 1.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -54,6 +54,7 @@ SkillFullStack/
54
54
  │ └── foundation/
55
55
  │ └── promptEvalTesting/ # Promptfoo & DeepEval CI/CD regression suites
56
56
  └── scripts/
57
+ ├── validateSkills.py # Strict production quality & consistency validator (100/100 score)
57
58
  ├── scaffoldSkill.py # Automated spec-compliant skill generator
58
59
  └── installSkill.sh # One-liner skill installer via raw GitHub URL
59
60
  ```
@@ -82,6 +83,26 @@ https://raw.githubusercontent.com/prasangaramanpokharel/skills/main/<path>/SKILL
82
83
 
83
84
  ---
84
85
 
86
+ ### 🚀 Method 0: Official NPM Package (`npx skillfullstack`)
87
+ Install any skill directly into your project in one command (auto-detects Claude Code, Cursor, Antigravity, Windsurf, or Copilot):
88
+ ```bash
89
+ # 1. Install specific skills (auto-configures for your agent)
90
+ npx skillfullstack add nextjs
91
+ npx skillfullstack add astro cloudflare
92
+ npx skillfullstack add databaseArchitecture --agent=cursor
93
+
94
+ # 2. Inspect project and auto-recommend skills for your tech stack
95
+ npx skillfullstack init
96
+
97
+ # 3. List all 25+ verified skills across all domains
98
+ npx skillfullstack list
99
+
100
+ # 4. Search by keyword or framework
101
+ npx skillfullstack search graphql
102
+ ```
103
+
104
+ ---
105
+
85
106
  ### Method 1: Direct Raw URL (Zero Clone / Single Skill)
86
107
  Every skill's primary definition is located at its raw GitHub URL:
87
108
  ```text
package/bin/index.js CHANGED
@@ -12,7 +12,6 @@ import fs from 'fs';
12
12
  import { promises as fsp } from 'fs';
13
13
  import path from 'path';
14
14
  import { fileURLToPath } from 'url';
15
- import readline from 'readline';
16
15
 
17
16
  const __filename = fileURLToPath(import.meta.url);
18
17
  const __dirname = path.dirname(__filename);
@@ -46,18 +45,6 @@ function loadCatalog() {
46
45
  return { skills: [] };
47
46
  }
48
47
 
49
- async function fetchRemoteCatalog() {
50
- try {
51
- const res = await fetch(`${REPO_RAW}/.skillsRegistry/catalog.json`);
52
- if (res.ok) {
53
- return await res.json();
54
- }
55
- } catch (err) {
56
- // Ignore
57
- }
58
- return loadCatalog();
59
- }
60
-
61
48
  // Auto-detect project environment
62
49
  function detectAgents() {
63
50
  const detected = [];
@@ -97,8 +84,10 @@ function resolveInstallTarget(skillName, agent, customDir = null) {
97
84
  };
98
85
  case 'cursor':
99
86
  return {
100
- targetDir: path.join(cwd, '.cursor/rules'),
101
- targetFile: path.join(cwd, '.cursor/rules', `${skillName}.mdc`),
87
+ targetDir: path.join(cwd, '.cursor/skills', skillName),
88
+ targetFile: path.join(cwd, '.cursor/skills', skillName, 'SKILL.md'),
89
+ ruleDir: path.join(cwd, '.cursor/rules'),
90
+ ruleFile: path.join(cwd, '.cursor/rules', `${skillName}.mdc`),
102
91
  agent: 'cursor',
103
92
  };
104
93
  case 'windsurf':
@@ -123,20 +112,6 @@ function resolveInstallTarget(skillName, agent, customDir = null) {
123
112
  }
124
113
  }
125
114
 
126
- async function copyDirRecursive(src, dest) {
127
- await fsp.mkdir(dest, { recursive: true });
128
- const entries = await fsp.readdir(src, { withFileTypes: true });
129
- for (const entry of entries) {
130
- const srcPath = path.join(src, entry.name);
131
- const destPath = path.join(dest, entry.name);
132
- if (entry.isDirectory()) {
133
- await copyDirRecursive(srcPath, destPath);
134
- } else {
135
- await fsp.copyFile(srcPath, destPath);
136
- }
137
- }
138
- }
139
-
140
115
  // -------------------------------------------------------------
141
116
  // Commands
142
117
  // -------------------------------------------------------------
@@ -222,7 +197,6 @@ async function cmdInfo(skillName, catalog) {
222
197
  console.log(` ${c.bold}Official Docs:${c.reset} ${skill.docs || 'N/A'}`);
223
198
  console.log(`\n ${c.bold}Description:${c.reset}\n ${skill.description}\n`);
224
199
 
225
- // Check if offline assets exist
226
200
  const localAssetDir = path.join(PKG_ROOT, skill.path, 'assets');
227
201
  const hasAssets = fs.existsSync(localAssetDir);
228
202
  console.log(` ${c.bold}Offline Assets:${c.reset} ${hasAssets ? c.green + '✓ Bundled (High-Accuracy)' : c.gray + 'Remote only'}${c.reset}`);
@@ -249,59 +223,62 @@ async function installSingleSkill(skillName, catalog, options = {}) {
249
223
  }
250
224
  }
251
225
 
252
- // 1. Get content (local or remote)
253
- let content = null;
254
- const localFile = path.join(PKG_ROOT, skill.path, 'SKILL.md');
255
- if (fs.existsSync(localFile)) {
256
- content = await fsp.readFile(localFile, 'utf8');
257
- } else {
258
- const remoteUrl = `${REPO_RAW}/${skill.path}/SKILL.md`;
259
- const res = await fetch(remoteUrl);
260
- if (!res.ok) throw new Error(`Failed to fetch ${remoteUrl} (HTTP ${res.status})`);
261
- content = await res.text();
262
- }
226
+ const localSkillDir = path.join(PKG_ROOT, skill.path);
227
+ const hasLocalDir = fs.existsSync(localSkillDir);
263
228
 
264
- // 2. Install to targets
265
229
  for (const agent of agentsToInstall) {
266
230
  const target = resolveInstallTarget(skill.name, agent, options.dir);
267
231
  await fsp.mkdir(target.targetDir, { recursive: true });
268
- await fsp.writeFile(target.targetFile, content, 'utf8');
269
232
 
270
- // Special handling for Claude Code slash command
233
+ if (hasLocalDir) {
234
+ // 1. Copy the ENTIRE skill folder (SKILL.md, references/, assets/, scripts/, evals/, policies/, templates/)
235
+ await fsp.cp(localSkillDir, target.targetDir, { recursive: true });
236
+ } else {
237
+ // Remote fallback: Fetch SKILL.md
238
+ const remoteUrl = `${REPO_RAW}/${skill.path}/SKILL.md`;
239
+ const res = await fetch(remoteUrl);
240
+ if (!res.ok) throw new Error(`Failed to fetch ${remoteUrl} (HTTP ${res.status})`);
241
+ const content = await res.text();
242
+ await fsp.writeFile(target.targetFile, content, 'utf8');
243
+ }
244
+
245
+ // 2. Special handling for Claude Code: also register slash command
271
246
  if (target.cmdFile && target.cmdDir) {
272
247
  await fsp.mkdir(target.cmdDir, { recursive: true });
273
- await fsp.writeFile(target.cmdFile, content, 'utf8');
248
+ const skillMdContent = await fsp.readFile(path.join(target.targetDir, 'SKILL.md'), 'utf8');
249
+ await fsp.writeFile(target.cmdFile, skillMdContent, 'utf8');
274
250
  }
275
251
 
276
- // Special handling for Cursor: Add header if .mdc
277
- if (target.targetFile.endsWith('.mdc')) {
252
+ // 3. Special handling for Cursor: also create .mdc rule file
253
+ if (target.ruleFile && target.ruleDir) {
254
+ await fsp.mkdir(target.ruleDir, { recursive: true });
255
+ const skillMdContent = await fsp.readFile(path.join(target.targetDir, 'SKILL.md'), 'utf8');
278
256
  const cursorContent = `---
279
257
  description: ${skill.description}
280
258
  globs: *
281
259
  alwaysApply: false
282
260
  ---
283
261
 
284
- ${content}`;
285
- await fsp.writeFile(target.targetFile, cursorContent, 'utf8');
262
+ ${skillMdContent}`;
263
+ await fsp.writeFile(target.ruleFile, cursorContent, 'utf8');
286
264
  }
287
265
 
288
- // Handle --with-assets
289
- if (options.withAssets) {
290
- const localAssets = path.join(PKG_ROOT, skill.path, 'assets');
291
- const localRefs = path.join(PKG_ROOT, skill.path, 'references');
292
- if (fs.existsSync(localAssets)) {
293
- await copyDirRecursive(localAssets, path.join(target.targetDir, 'assets'));
294
- }
295
- if (fs.existsSync(localRefs)) {
296
- await copyDirRecursive(localRefs, path.join(target.targetDir, 'references'));
297
- }
298
- }
266
+ // List installed subdirectories for transparency
267
+ const installedItems = ['SKILL.md'];
268
+ if (fs.existsSync(path.join(target.targetDir, 'references'))) installedItems.push('references/');
269
+ if (fs.existsSync(path.join(target.targetDir, 'assets'))) installedItems.push('assets/');
270
+ if (fs.existsSync(path.join(target.targetDir, 'scripts'))) installedItems.push('scripts/');
271
+ if (fs.existsSync(path.join(target.targetDir, 'evals'))) installedItems.push('evals/');
272
+ if (fs.existsSync(path.join(target.targetDir, 'policies'))) installedItems.push('policies/');
299
273
 
300
274
  console.log(` ${c.green}✓${c.reset} Installed ${c.bold}${skill.name}${c.reset} for ${c.cyan}${agent}${c.reset}`);
301
- console.log(` ${c.gray}→ ${path.relative(process.cwd(), target.targetFile)}${c.reset}`);
275
+ console.log(` ${c.gray}→ ${path.relative(process.cwd(), target.targetDir)}/ [${installedItems.join(', ')}]${c.reset}`);
302
276
  if (target.cmdFile) {
303
277
  console.log(` ${c.gray}→ Slash command: ${path.relative(process.cwd(), target.cmdFile)} (/${skill.name})${c.reset}`);
304
278
  }
279
+ if (target.ruleFile) {
280
+ console.log(` ${c.gray}→ Cursor rule: ${path.relative(process.cwd(), target.ruleFile)}${c.reset}`);
281
+ }
305
282
  }
306
283
  }
307
284
 
@@ -395,7 +372,7 @@ ${c.bold}USAGE${c.reset}
395
372
  $ ${c.cyan}sfs${c.reset} <command> [options]
396
373
 
397
374
  ${c.bold}COMMANDS${c.reset}
398
- ${c.green}add, install${c.reset} <skill...> Install one or more skills into your project
375
+ ${c.green}add, install${c.reset} <skill...> Install one or more skills (copies SKILL.md, references, assets, etc.)
399
376
  ${c.green}list, ls${c.reset} List all 25+ verified skills across all domains
400
377
  ${c.green}search${c.reset} <query> Search skills by keyword, framework, or capability
401
378
  ${c.green}info${c.reset} <skill> Show detailed documentation, slash commands, & metadata
@@ -404,7 +381,6 @@ ${c.bold}COMMANDS${c.reset}
404
381
  ${c.bold}OPTIONS${c.reset}
405
382
  ${c.yellow}-a, --agent <name>${c.reset} Target agent: ${c.dim}claude, cursor, antigravity, windsurf, copilot, agent, all${c.reset}
406
383
  ${c.yellow}-d, --dir <path>${c.reset} Custom destination folder
407
- ${c.yellow}--with-assets${c.reset} Download complete offline documentation assets
408
384
  ${c.yellow}-t, --taxonomy <name>${c.reset} Filter list by category (frontend, backend, github, etc.)
409
385
  ${c.yellow}--json${c.reset} Output catalog as JSON
410
386
  ${c.yellow}-h, --help${c.reset} Display help guide
@@ -414,7 +390,6 @@ ${c.bold}EXAMPLES${c.reset}
414
390
  $ ${c.cyan}npx skillfullstack add nextjs${c.reset}
415
391
  $ ${c.cyan}npx skillfullstack add astro cloudflare --agent=cursor${c.reset}
416
392
  $ ${c.cyan}npx skillfullstack add databaseArchitecture --agent=claude${c.reset}
417
- $ ${c.cyan}npx skillfullstack add nextjs --with-assets${c.reset}
418
393
  $ ${c.cyan}npx skillfullstack list --taxonomy frontend${c.reset}
419
394
  $ ${c.cyan}npx skillfullstack search graphql${c.reset}
420
395
  $ ${c.cyan}npx skillfullstack init${c.reset}
@@ -442,11 +417,9 @@ async function main() {
442
417
 
443
418
  const catalog = loadCatalog();
444
419
 
445
- // Parse simple flags
446
420
  const options = {
447
421
  agent: null,
448
422
  dir: null,
449
- withAssets: false,
450
423
  taxonomy: null,
451
424
  json: false,
452
425
  };
@@ -462,9 +435,7 @@ async function main() {
462
435
  options.dir = arg.split('=')[1];
463
436
  } else if (arg === '-d' || arg === '--dir') {
464
437
  options.dir = rawArgs[++i];
465
- } else if (arg === '--with-assets') {
466
- options.withAssets = true;
467
- } else if (arg.startsWith('--taxonomy=')|| arg.startsWith('-t=')) {
438
+ } else if (arg.startsWith('--taxonomy=') || arg.startsWith('-t=')) {
468
439
  options.taxonomy = arg.split('=')[1];
469
440
  } else if (arg === '-t' || arg === '--taxonomy') {
470
441
  options.taxonomy = rawArgs[++i];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "skillfullstack",
3
- "version": "1.0.1",
3
+ "version": "1.0.3",
4
4
  "description": "Production AI Agent Skills CLI & library for Claude Code, Cursor, Antigravity, Windsurf, and GitHub Copilot.",
5
5
  "main": "bin/index.js",
6
6
  "type": "module",
@@ -18,10 +18,11 @@
18
18
  "AGENTS.md"
19
19
  ],
20
20
  "scripts": {
21
- "test": "node bin/index.js --help",
21
+ "test": "python3 scripts/validateSkills.py --strict && node bin/index.js --help",
22
+ "validate": "python3 scripts/validateSkills.py --strict",
22
23
  "list": "node bin/index.js list",
23
24
  "init": "node bin/index.js init",
24
- "prepublishOnly": "node bin/index.js list"
25
+ "prepublishOnly": "python3 scripts/validateSkills.py --strict && node bin/index.js list"
25
26
  },
26
27
  "keywords": [
27
28
  "ai",
@@ -67,7 +67,7 @@ flowchart LR
67
67
  - Design request/response DTOs:
68
68
  - Success Envelope: `{ "data": T, "meta": Meta }`
69
69
  - Error Envelope: RFC 9457 `application/problem+json`
70
- - Select pagination model (see [references/paginationVersioning.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/backend/apiEngineering/references/paginationVersioning.md)).
70
+ - Select pagination model (see [references/paginationVersioning.md](references/paginationVersioning.md)).
71
71
  - Conduct OWASP API Security Top 10 threat modeling.
72
72
 
73
73
  ### Stage 4: Execute
@@ -96,7 +96,15 @@ Produce the final API delivery summary:
96
96
 
97
97
  | Architectural Layer | Location & Purpose |
98
98
  | :--- | :--- |
99
- | **Policies** | [policies/mandatory.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/backend/apiEngineering/policies/mandatory.md), [policies/security.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/backend/apiEngineering/policies/security.md), [policies/performance.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/backend/apiEngineering/policies/performance.md), [policies/compatibility.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/backend/apiEngineering/policies/compatibility.md) — Enforceable rulebooks. |
100
- | **Methods & References** | [references/responseStandards.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/backend/apiEngineering/references/responseStandards.md), [references/openApi32Standards.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/backend/apiEngineering/references/openApi32Standards.md), [references/apiSecurityOwasp.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/backend/apiEngineering/references/apiSecurityOwasp.md), [references/paginationVersioning.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/backend/apiEngineering/references/paginationVersioning.md), [references/databaseTransactions.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/backend/apiEngineering/references/databaseTransactions.md), [references/distributedReliability.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/backend/apiEngineering/references/distributedReliability.md), [references/contractCompatibility.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/backend/apiEngineering/references/contractCompatibility.md), [references/multiTenancy.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/backend/apiEngineering/references/multiTenancy.md), [references/apiObservability.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/backend/apiEngineering/references/apiObservability.md) — Implementation guides. |
99
+ | **Policies** | [policies/mandatory.md](policies/mandatory.md), [policies/security.md](policies/security.md), [policies/performance.md](policies/performance.md), [policies/compatibility.md](policies/compatibility.md) — Enforceable rulebooks. |
100
+ | **Methods & References** | [references/responseStandards.md](references/responseStandards.md), [references/openApi32Standards.md](references/openApi32Standards.md), [references/apiSecurityOwasp.md](references/apiSecurityOwasp.md), [references/paginationVersioning.md](references/paginationVersioning.md), [references/databaseTransactions.md](references/databaseTransactions.md), [references/distributedReliability.md](references/distributedReliability.md), [references/contractCompatibility.md](references/contractCompatibility.md), [references/multiTenancy.md](references/multiTenancy.md), [references/apiObservability.md](references/apiObservability.md) — Implementation guides. |
101
101
  | **Automation Tooling** | `scripts/auditApiContract.py`, `scripts/generateResponseEnvelope.py`, `scripts/checkBreakingChanges.py` — Deterministic CLI tools. |
102
102
  | **Templates** | `templates/openapi.yaml`, `templates/problemDetails.json`, `templates/apiChecklist.md` — Starter blueprints. |
103
+
104
+ ## 4. Anti-Patterns & Common Traps
105
+ | Anti-Pattern | Why It Fails | Production Remediation |
106
+ | :--- | :--- | :--- |
107
+ | Ad-hoc error objects (`{ "error": "msg" }`) | Breaks client parsing consistency | Enforce RFC 9457 `application/problem+json` envelopes |
108
+ | Offset-based pagination on large datasets | Degrades to $O(N)$ scans at high offsets | Use Keyset / Cursor-based pagination (`starting_after`) |
109
+ | Unbounded payload responses | Memory exhaustion and network timeouts | Enforce strict `max_page_size` and partial projection |
110
+ | Mutating endpoints without idempotency | Duplicate charges and double records on retries | Implement IETF `Idempotency-Key` draft-08 header checks |
@@ -83,16 +83,16 @@ flowchart LR
83
83
  - Analyze slow query logs, N+1 query patterns, and connection pool saturation metrics.
84
84
 
85
85
  ### Stage 3: Plan
86
- - Generate Architecture Decision Record ([templates/adrTemplate.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/backend/databaseArchitecture/templates/adrTemplate.md)).
86
+ - Generate Architecture Decision Record ([templates/adrTemplate.md](templates/adrTemplate.md)).
87
87
  - Create conceptual $\rightarrow$ logical $\rightarrow$ physical data models.
88
- - Apply relational normalization (1NF through BCNF) or query-driven NoSQL design ([references/normalizationTheory.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/backend/databaseArchitecture/references/normalizationTheory.md)).
89
- - Complete the mandatory **Pre-Creation Table & Security Gate** ([policies/tableCreationChecklist.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/backend/databaseArchitecture/policies/tableCreationChecklist.md)): Verify entity justification, enforce `snake_case` plural naming, verify YAGNI lean columns, and complete security threat review.
90
- - Design indexing and partitioning strategy ([references/indexingOptimization.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/backend/databaseArchitecture/references/indexingOptimization.md)).
88
+ - Apply relational normalization (1NF through BCNF) or query-driven NoSQL design ([references/normalizationTheory.md](references/normalizationTheory.md)).
89
+ - Complete the mandatory **Pre-Creation Table & Security Gate** ([policies/tableCreationChecklist.md](policies/tableCreationChecklist.md)): Verify entity justification, enforce `snake_case` plural naming, verify YAGNI lean columns, and complete security threat review.
90
+ - Design indexing and partitioning strategy ([references/indexingOptimization.md](references/indexingOptimization.md)).
91
91
 
92
92
  ### Stage 4: Execute
93
- - Author DDL schemas strictly adhering to [policies/tableCreationChecklist.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/backend/databaseArchitecture/policies/tableCreationChecklist.md), [policies/integrity.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/backend/databaseArchitecture/policies/integrity.md), and [policies/security.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/backend/databaseArchitecture/policies/security.md).
94
- - Create zero-downtime migration scripts following the expand-and-contract protocol ([templates/migrationPlan.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/backend/databaseArchitecture/templates/migrationPlan.md)).
95
- - Configure connection pools and transaction boundaries ([references/transactionConcurrency.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/backend/databaseArchitecture/references/transactionConcurrency.md)).
93
+ - Author DDL schemas strictly adhering to [policies/tableCreationChecklist.md](policies/tableCreationChecklist.md), [policies/integrity.md](policies/integrity.md), and [policies/security.md](policies/security.md).
94
+ - Create zero-downtime migration scripts following the expand-and-contract protocol ([templates/migrationPlan.md](templates/migrationPlan.md)).
95
+ - Configure connection pools and transaction boundaries ([references/transactionConcurrency.md](references/transactionConcurrency.md)).
96
96
 
97
97
  ### Stage 5: Validate
98
98
  1. Run schema and constraint linter: `python3 scripts/auditDatabaseSchema.py --schema=schema.sql --strict`.
@@ -112,7 +112,7 @@ Produce the comprehensive database architecture report:
112
112
 
113
113
  | Architectural Layer | Location & Purpose |
114
114
  | :--- | :--- |
115
- | **Policies** | [policies/mandatory.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/backend/databaseArchitecture/policies/mandatory.md), [policies/tableCreationChecklist.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/backend/databaseArchitecture/policies/tableCreationChecklist.md), [policies/integrity.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/backend/databaseArchitecture/policies/integrity.md), [policies/normalization.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/backend/databaseArchitecture/policies/normalization.md), [policies/security.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/backend/databaseArchitecture/policies/security.md), [policies/performance.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/backend/databaseArchitecture/policies/performance.md), [policies/migration.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/backend/databaseArchitecture/policies/migration.md), [policies/recovery.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/backend/databaseArchitecture/policies/recovery.md) — Enforceable rulebooks. |
116
- | **Methods & References** | [references/normalizationTheory.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/backend/databaseArchitecture/references/normalizationTheory.md), [references/databaseTaxonomy.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/backend/databaseArchitecture/references/databaseTaxonomy.md), [references/dataModelingLifecycle.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/backend/databaseArchitecture/references/dataModelingLifecycle.md), [references/scalabilitySharding.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/backend/databaseArchitecture/references/scalabilitySharding.md), [references/indexingOptimization.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/backend/databaseArchitecture/references/indexingOptimization.md), [references/transactionConcurrency.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/backend/databaseArchitecture/references/transactionConcurrency.md), [references/analyticsWarehousing.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/backend/databaseArchitecture/references/analyticsWarehousing.md), [references/backupDisasterRecovery.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/backend/databaseArchitecture/references/backupDisasterRecovery.md) — Deep theory & guides. |
115
+ | **Policies** | [policies/mandatory.md](policies/mandatory.md), [policies/tableCreationChecklist.md](policies/tableCreationChecklist.md), [policies/integrity.md](policies/integrity.md), [policies/normalization.md](policies/normalization.md), [policies/security.md](policies/security.md), [policies/performance.md](policies/performance.md), [policies/migration.md](policies/migration.md), [policies/recovery.md](policies/recovery.md) — Enforceable rulebooks. |
116
+ | **Methods & References** | [references/normalizationTheory.md](references/normalizationTheory.md), [references/databaseTaxonomy.md](references/databaseTaxonomy.md), [references/dataModelingLifecycle.md](references/dataModelingLifecycle.md), [references/scalabilitySharding.md](references/scalabilitySharding.md), [references/indexingOptimization.md](references/indexingOptimization.md), [references/transactionConcurrency.md](references/transactionConcurrency.md), [references/analyticsWarehousing.md](references/analyticsWarehousing.md), [references/backupDisasterRecovery.md](references/backupDisasterRecovery.md) — Deep theory & guides. |
117
117
  | **Automation Tooling** | `scripts/auditDatabaseSchema.py`, `scripts/analyzeMigration.py`, `scripts/inspectDatabaseIndexes.py` — Deterministic CLI analysis tools. |
118
118
  | **Templates** | `templates/adrTemplate.md`, `templates/migrationPlan.md`, `templates/databaseChecklist.md` — Enterprise blueprints. |
@@ -4,6 +4,17 @@ description: Durable background execution, long-running agent workflows, and zer
4
4
  version: 3.x
5
5
  last-verified: 2026-11-15
6
6
  compatibility: Next.js, Node.js 18+, Python 3.10+, Inngest SDK, Trigger.dev v3
7
+ slash-commands:
8
+ - command: /jobs-workflow
9
+ description: Design durable multi-step workflows with Inngest or Trigger.dev
10
+ argument-hint: "[--engine=inngest|triggerdev]"
11
+ - command: /jobs-step
12
+ description: Implement zero-timeout step function with automatic retries
13
+ argument-hint: "[--step=Name]"
14
+ - command: /jobs-cron
15
+ description: Configure scheduled background cron jobs with jitter
16
+ argument-hint: "[--schedule='*/5 * * * *']"
17
+
7
18
  ---
8
19
 
9
20
  # Durable Background Jobs & Workflows Engineering Guide
@@ -4,6 +4,17 @@ description: Production-grade Go engineering standards. Implements log/slog stru
4
4
  version: 1.23+
5
5
  last-verified: 2026-11-16
6
6
  compatibility: Go 1.22+, Go 1.23+, Go 1.24+
7
+ slash-commands:
8
+ - command: /go-standard
9
+ description: Enforce production Go architecture, clean domain layout, and error wrapping
10
+ argument-hint: "[--domain=order|user]"
11
+ - command: /go-slog
12
+ description: Configure structured logging with log/slog and context propagation
13
+ argument-hint: "[--format=json|text]"
14
+ - command: /go-concurrency
15
+ description: Design structured concurrency with errgroup and context cancellation
16
+ argument-hint: "[--workers=10]"
17
+
7
18
  ---
8
19
 
9
20
  # Production Go Engineering Guide
@@ -4,6 +4,17 @@ description: Modern production Python engineering standards with Astral uv toolc
4
4
  version: 3.12+
5
5
  last-verified: 2026-11-16
6
6
  compatibility: Python 3.11, Python 3.12, Python 3.13, uv, ruff, pydantic 2.x
7
+ slash-commands:
8
+ - command: /python-standard
9
+ description: Enforce modern Python standards with uv, Ruff, and Pydantic v2
10
+ argument-hint: "[--strict=true]"
11
+ - command: /python-uv
12
+ description: Manage virtual environments and dependency locking with Astral uv
13
+ argument-hint: "[--add=package]"
14
+ - command: /python-typing
15
+ description: Apply strict PEP 585/604 type hints and TaskGroup concurrency
16
+ argument-hint: "[--async=true]"
17
+
7
18
  ---
8
19
 
9
20
  # Modern Production Python Engineering Guide
@@ -4,6 +4,17 @@ description: Production serverless Redis, Vector, QStash messaging, durable Work
4
4
  version: 2026.x
5
5
  last-verified: 2026-11-15
6
6
  compatibility: Node.js 18+, Vercel Edge / Serverless, Cloudflare Workers, Next.js, Python 3.10+
7
+ slash-commands:
8
+ - command: /upstash-redis
9
+ description: Configure low-latency serverless Redis operations and pipelines
10
+ argument-hint: "[--pipeline=true]"
11
+ - command: /upstash-ratelimit
12
+ description: Implement dynamic sliding window rate limiting
13
+ argument-hint: "[--limit=10] [--window=10s]"
14
+ - command: /upstash-workflow
15
+ description: Design serverless QStash durable workflows
16
+ argument-hint: "[--step=Name]"
17
+
7
18
  ---
8
19
 
9
20
  # Upstash Serverless Engineering Guide
@@ -145,4 +145,12 @@ Summarize pipeline stage durations, image layer sizes, and DORA telemetry projec
145
145
  ## 4. Helper Scripts & Deep References
146
146
 
147
147
  - Dockerfile Security Linter: `python3 scripts/auditDockerfileSecurity.py`
148
- - Reference: [references/cicdDeploymentPatterns.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/cicdDevops/cicdPipeline/references/cicdDeploymentPatterns.md)
148
+ - Reference: [references/cicdDeploymentPatterns.md](references/cicdDeploymentPatterns.md)
149
+
150
+ ## 5. Anti-Patterns & Common Traps
151
+ | Anti-Pattern | Why It Fails | Production Remediation |
152
+ | :--- | :--- | :--- |
153
+ | Running container as root (`USER root`) | Container breakout privilege escalation | Always enforce `USER nonroot` or dedicated UID/GID |
154
+ | Using `:latest` tags for base images | Unpredictable non-deterministic builds | Pin immutable digest (`node:22-alpine@sha256:...`) |
155
+ | Storing secrets in Docker image layers | Secrets leaked in public registry pulls | Use build secrets (`--mount=type=secret`) |
156
+ | Monolithic serial CI pipelines | Long feedback cycles (> 30 minutes) | Implement matrix parallelization and dependency caching |
@@ -4,6 +4,17 @@ description: Build Model Context Protocol (MCP) servers exposing tools, resource
4
4
  version: 1.x
5
5
  last-verified: 2026-11-15
6
6
  compatibility: Node.js 18+, Python 3.10+, uv, TypeScript 5+
7
+ slash-commands:
8
+ - command: /mcp-server
9
+ description: Scaffold production Model Context Protocol server in FastMCP Python or TypeScript
10
+ argument-hint: "[--lang=ts|py]"
11
+ - command: /mcp-tool
12
+ description: Define type-safe MCP tools with Zod or Pydantic validation
13
+ argument-hint: "[--tool=Name]"
14
+ - command: /mcp-resource
15
+ description: Expose dynamic and static MCP context resources
16
+ argument-hint: "[--uri=schema://resource]"
17
+
7
18
  ---
8
19
 
9
20
  # MCP Server Development Engineering Guide
@@ -4,6 +4,17 @@ description: Production-grade RAG pipeline implementing BM25 and dense vector hy
4
4
  version: 2.x
5
5
  last-verified: 2026-11-15
6
6
  compatibility: Python 3.10+, LangChain, LlamaIndex, Qdrant/pgvector, Cohere API
7
+ slash-commands:
8
+ - command: /rag-pipeline
9
+ description: Design production hybrid RAG search architecture
10
+ argument-hint: "[--vector-db=pinecone|vectorize|qdrant]"
11
+ - command: /rag-hybrid
12
+ description: Implement BM25 lexical + dense vector retrieval with RRF fusion
13
+ argument-hint: "[--k=60]"
14
+ - command: /rag-rerank
15
+ description: Apply cross-encoder and Cohere rerankers for top-k precision
16
+ argument-hint: "[--model=cohere|bge]"
17
+
7
18
  ---
8
19
 
9
20
  # Production RAG Pipeline Engineering Guide
@@ -4,6 +4,14 @@ description: CI/CD prompt regression testing, evaluation harnesses, and LLM-as-a
4
4
  version: latest
5
5
  last-verified: 2026-11-15
6
6
  compatibility: Node.js 18+, Python 3.10+, pytest, GitHub Actions, GitLab CI
7
+ slash-commands:
8
+ - command: /prompt-eval
9
+ description: Design CI/CD regression evaluation harness with Promptfoo and DeepEval
10
+ argument-hint: "[--tool=promptfoo|deepeval]"
11
+ - command: /prompt-judge
12
+ description: Configure LLM-as-a-judge scoring metrics and assert criteria
13
+ argument-hint: "[--metric=semantic-similarity|g-eval]"
14
+
7
15
  ---
8
16
 
9
17
  # Prompt Evaluation & Regression Testing Engineering Guide
@@ -4,6 +4,14 @@ description: Stream interactive React components from LLMs using Vercel AI SDK,
4
4
  version: v4
5
5
  last-verified: 2026-11-15
6
6
  compatibility: Next.js 14/15, React 18/19, Vercel AI SDK v4+
7
+ slash-commands:
8
+ - command: /genui-stream
9
+ description: Stream interactive React components from LLMs via Vercel AI SDK
10
+ argument-hint: "[--transport=createDataStreamResponse]"
11
+ - command: /genui-tool
12
+ description: Map generative AI tool executions to interactive client components
13
+ argument-hint: "[--component=Name]"
14
+
7
15
  ---
8
16
 
9
17
  # Generative UI Engineering Guide
@@ -4,6 +4,14 @@ description: Modern TypeScript and React 19 production engineering standards. Im
4
4
  version: React 19 / TS 5+
5
5
  last-verified: 2026-11-16
6
6
  compatibility: React 19, TypeScript 5.0+, Next.js 15, Vite
7
+ slash-commands:
8
+ - command: /react-standard
9
+ description: Enforce strict React 19 standards, ref props, and clean hooks
10
+ argument-hint: "[--strict=true]"
11
+ - command: /react-action
12
+ description: Implement type-safe Server Actions with useActionState
13
+ argument-hint: "[--action=Name]"
14
+
7
15
  ---
8
16
 
9
17
  # Modern TypeScript & React 19 Engineering Guide
@@ -124,5 +124,13 @@ git rebase --continue # or git merge --continue
124
124
  - **Official Git & GitHub CLI Offline Assets**: [assets/](assets/) — Official specifications for Git remotes, DAG concepts, credential caching, and full GitHub CLI (`gh`) reference manual.
125
125
  - Graph Diagnostics: `python3 scripts/diagnoseGitGraph.py`
126
126
  - Conflict Resolver Helper: `python3 scripts/resolveConflictHeuristics.py`
127
- - Reference: [references/branchingModels.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/gitVersionControl/gitWorkflow/references/branchingModels.md)
128
- - Reference: [references/gitInternalsDag.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/gitVersionControl/gitWorkflow/references/gitInternalsDag.md)
127
+ - Reference: [references/branchingModels.md](references/branchingModels.md)
128
+ - Reference: [references/gitInternalsDag.md](references/gitInternalsDag.md)
129
+
130
+ ## 5. Anti-Patterns & Common Traps
131
+ | Anti-Pattern | Why It Fails | Production Remediation |
132
+ | :--- | :--- | :--- |
133
+ | Force pushing to shared branches (`git push -f`) | Overwrites colleagues' work permanently | Use `--force-with-lease` or enforce branch protection |
134
+ | Giant mega-PRs (> 800 lines) | High defect rate, review fatigue | Slice into small, self-contained, reviewable units |
135
+ | Committing secrets or build artifacts | Leaked credentials in immutable DAG | Enforce `.gitignore` and pre-commit secret scanning |
136
+ | Orphaned WIP branches without reflog | Lost commits during accidental reset | Use `git reflog` and named backup branches |
@@ -0,0 +1,75 @@
1
+ # Git Directed Acyclic Graph (DAG) & Object Model Internals
2
+
3
+ Git is fundamentally a content-addressable storage filesystem structured as a **Directed Acyclic Graph (DAG)** of immutable objects.
4
+
5
+ ---
6
+
7
+ ## 1. The Four Core Git Object Types
8
+
9
+ Every object in Git is identified by the SHA-1 or SHA-256 hash of its header and compressed payload:
10
+
11
+ | Object Type | Role | Content |
12
+ | :--- | :--- | :--- |
13
+ | **Blob** | Raw file contents | File payload (no metadata, no filename, no permissions) |
14
+ | **Tree** | Directory structure | Array of SHA hashes, file modes, and filenames pointing to blobs or subtrees |
15
+ | **Commit** | Point-in-time snapshot | Tree SHA, parent commit SHA(s), author/committer timestamps, commit message |
16
+ | **Annotated Tag** | Immutable release marker | Object SHA, tagger, date, GPG signature, tag message |
17
+
18
+ ```
19
+ Commit Object (SHA: 8f3a1...)
20
+ ├── tree: 4c2b9... (Root Directory)
21
+ │ ├── 100644 blob e69de... README.md
22
+ │ └── 040000 tree 9a1d3... src/
23
+ │ └── 100644 blob 3b184... index.ts
24
+ ├── parent: 1e5f8... (Previous Commit)
25
+ ├── author: Dev <dev@example.com> 1731750000 +0000
26
+ └── message: "feat: add user authentication"
27
+ ```
28
+
29
+ ---
30
+
31
+ ## 2. DAG Mechanics & Branch Pointers
32
+
33
+ 1. **Branches are just mutable pointers**: A branch in Git (e.g., `main`, `feature/auth`) is simply a 41-byte text file located in `.git/refs/heads/<branch>` containing the 40-character commit hash it currently points to.
34
+ 2. **HEAD**: A reference pointer (`.git/HEAD`) pointing to the currently active branch or a detached commit.
35
+ 3. **Immutability of History**: When you rebase or amend, Git **does not mutate** existing commit objects; it creates new commit objects with different parent pointers. The old commits remain in the DAG until garbage collected (`git gc`).
36
+ 4. **Reflog (`git reflog`)**: A local audit ledger of every update to `HEAD` and branch tips over the past 30-90 days, enabling recovery of orphaned commits after destructive operations (`git reset --hard`).
37
+
38
+ ---
39
+
40
+ ## 3. Fast-Forward vs Three-Way Merge DAGs
41
+
42
+ ### Fast-Forward (`git merge --ff`)
43
+ Moves the branch pointer forward along the direct linear ancestor chain. Zero new commit objects created.
44
+ ```
45
+ main: A ─── B
46
+ \
47
+ feature: C ─── D
48
+
49
+ Result: A ─── B ─── C ─── D (main, feature)
50
+ ```
51
+
52
+ ### Three-Way Merge (`git merge --no-ff`)
53
+ Creates a new merge commit object with **two parent pointers** (`parent1` = main tip, `parent2` = feature tip).
54
+ ```
55
+ main: A ─── B ───────── M (Merge Commit: parents B, D)
56
+ \ /
57
+ feature: C ─── D /
58
+ ```
59
+
60
+ ---
61
+
62
+ ## 4. Rebase Internals (`git rebase`)
63
+
64
+ Rebase unplugs a branch's commits from their original fork point and replays each commit as a brand new patch onto the target upstream tip:
65
+ ```
66
+ Original:
67
+ A ─── B ─── C (main)
68
+ \
69
+ D ─── E (feature)
70
+
71
+ After `git rebase main`:
72
+ A ─── B ─── C (main)
73
+ \
74
+ D' ─── E' (feature: new commit hashes!)
75
+ ```
@@ -4,6 +4,14 @@ description: Defend and red-team LLM applications against OWASP Top 10 vulnerabi
4
4
  version: 2026.x
5
5
  last-verified: 2026-11-15
6
6
  compatibility: All LLM runtimes, LangChain, LlamaIndex, OpenAI, Anthropic, Gemini
7
+ slash-commands:
8
+ - command: /llm-redteam
9
+ description: Audit and defend LLM prompts against OWASP Top 10 for LLMs
10
+ argument-hint: "[--threat=injection|extraction]"
11
+ - command: /llm-jailbreak
12
+ description: Run automated jailbreak and indirect prompt injection simulations
13
+ argument-hint: "[--model=Name]"
14
+
7
15
  ---
8
16
 
9
17
  # LLM Security & Red Teaming Engineering Guide
@@ -107,4 +107,12 @@ Produce a finalized requirements package ready for engineering sprint planning.
107
107
  ## 3. Helper Scripts & Deep References
108
108
 
109
109
  - Story Quality Linter: `python3 scripts/validateUserStories.py`
110
- - Reference: [references/requirementsAnalysisModels.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/softwareDevelopment/requirementsEngineering/references/requirementsAnalysisModels.md)
110
+ - Reference: [references/requirementsAnalysisModels.md](references/requirementsAnalysisModels.md)
111
+
112
+ ## 4. Anti-Patterns & Common Traps
113
+ | Anti-Pattern | Why It Fails | Production Remediation |
114
+ | :--- | :--- | :--- |
115
+ | Subjective acceptance criteria ("Make it fast") | Non-testable, leads to scope disputes | Quantify metrics ("p95 latency < 200ms at 1000 RPS") |
116
+ | Skipping negative/edge scenarios | System crashes on unexpected input | Author explicit Given/When/Then negative test cases |
117
+ | Treating MoSCoW "Could-haves" as commitments | Sprint deadline blowouts | Ruthlessly scope down to Must-Haves for initial MVP |
118
+ | Functional requirements without threat modeling | Security vulnerabilities discovered post-release | Generate STRIDE / Attack Trees during story refinement |
@@ -119,4 +119,12 @@ Generate test summary including assertion count, execution time, and coverage de
119
119
  ## 4. Helper Scripts & Deep References
120
120
 
121
121
  - Test Pyramid Auditor: `python3 scripts/auditTestPyramid.py`
122
- - Reference: [references/testPyramidDoubles.md](file:///Users/prasangaramanpokharel/projects/SkillFullStack/skills/testing/testDrivenDevelopment/references/testPyramidDoubles.md)
122
+ - Reference: [references/testPyramidDoubles.md](references/testPyramidDoubles.md)
123
+
124
+ ## 5. Anti-Patterns & Common Traps
125
+ | Anti-Pattern | Why It Fails | Production Remediation |
126
+ | :--- | :--- | :--- |
127
+ | Testing implementation details instead of behavior | Tests break on refactor despite working behavior | Assert public inputs/outputs, avoid mocking private state |
128
+ | Inverted Test Pyramid (Ice cream cone) | Slow, brittle, flaky end-to-end test suites | 70% Unit tests, 20% Integration tests, 10% E2E tests |
129
+ | Tests sharing mutable global state | Random failures dependent on test execution order | Isolate tests with fresh fixtures and in-memory databases |
130
+ | Mocking everything blindly | Tests pass but production integration fails | Use Fakes for storage/DB, reserve Mocks for RPC boundaries |