create-stencil-components 1.0.7 → 1.0.9

package/dist/templates/base/.opencode/skills/monitor-ci/scripts/ci-poll-decide.mjs

@@ -0,0 +1,356 @@
+#!/usr/bin/env node
+
+/**
+ * CI Poll Decision Script
+ *
+ * Deterministic decision engine for CI monitoring.
+ * Takes ci_information JSON + state args, outputs a single JSON action line.
+ *
+ * Architecture:
+ *   classify()    — pure decision tree, returns { action, code, extra? }
+ *   buildOutput() — maps classification to full output with messages, delays, counters
+ *
+ * Usage:
+ *   node ci-poll-decide.mjs '<ci_info_json>' <poll_count> <verbosity> \
+ *     [--wait-mode] [--prev-cipe-url <url>] [--expected-sha <sha>] \
+ *     [--prev-status <status>] [--timeout <seconds>] [--new-cipe-timeout <seconds>] \
+ *     [--env-rerun-count <n>] [--no-progress-count <n>] \
+ *     [--prev-cipe-status <status>] [--prev-sh-status <status>] \
+ *     [--prev-verification-status <status>] [--prev-failure-classification <status>]
+ */
+
+// --- Arg parsing ---
+
+const args = process.argv.slice(2);
+const ciInfoJson = args[0];
+const pollCount = parseInt(args[1], 10) || 0;
+const verbosity = args[2] || 'medium';
+
+function getFlag(name) {
+    return args.includes(name);
+}
+
+function getArg(name) {
+    const idx = args.indexOf(name);
+    return idx !== -1 && idx + 1 < args.length ? args[idx + 1] : null;
+}
+
+const waitMode = getFlag('--wait-mode');
+const prevCipeUrl = getArg('--prev-cipe-url');
+const expectedSha = getArg('--expected-sha');
+const prevStatus = getArg('--prev-status');
+const timeoutSeconds = parseInt(getArg('--timeout') || '0', 10);
+const newCipeTimeoutSeconds = parseInt(getArg('--new-cipe-timeout') || '0', 10);
+const envRerunCount = parseInt(getArg('--env-rerun-count') || '0', 10);
+const inputNoProgressCount = parseInt(getArg('--no-progress-count') || '0', 10);
+const prevCipeStatus = getArg('--prev-cipe-status');
+const prevShStatus = getArg('--prev-sh-status');
+const prevVerificationStatus = getArg('--prev-verification-status');
+const prevFailureClassification = getArg('--prev-failure-classification');
+
+// --- Parse CI info ---
+
+let ci;
+try {
+    ci = JSON.parse(ciInfoJson);
+} catch {
+    console.log(
+        JSON.stringify({
+            action: 'done',
+            code: 'error',
+            message: 'Failed to parse ci_information JSON',
+            noProgressCount: inputNoProgressCount + 1,
+            envRerunCount,
+        }),
+    );
+    process.exit(0);
+}
+
+const {
+    cipeStatus,
+    selfHealingStatus,
+    verificationStatus,
+    selfHealingEnabled,
+    selfHealingSkippedReason,
+    failureClassification: rawFailureClassification,
+    failedTaskIds = [],
+    verifiedTaskIds = [],
+    couldAutoApplyTasks,
+    autoApplySkipped,
+    autoApplySkipReason,
+    userAction,
+    cipeUrl,
+    commitSha,
+} = ci;
+
+const failureClassification = rawFailureClassification?.toLowerCase() ?? null;
+
+// --- Helpers ---
+
+function categorizeTasks() {
+    const verifiedSet = new Set(verifiedTaskIds);
+    const unverified = failedTaskIds.filter(t => !verifiedSet.has(t));
+    if (unverified.length === 0) return { category: 'all_verified' };
+
+    const e2e = unverified.filter(t => {
+        const parts = t.split(':');
+        return parts.length >= 2 && parts[1].includes('e2e');
+    });
+    if (e2e.length === unverified.length) return { category: 'e2e_only' };
+
+    const verifiable = unverified.filter(t => {
+        const parts = t.split(':');
+        return !(parts.length >= 2 && parts[1].includes('e2e'));
+    });
+    return { category: 'needs_local_verify', verifiableTaskIds: verifiable };
+}
+
+function backoff(count) {
+    const delays = [60, 90, 120, 180];
+    return delays[Math.min(count, delays.length - 1)];
+}
+
+function hasStateChanged() {
+    if (prevCipeStatus && cipeStatus !== prevCipeStatus) return true;
+    if (prevShStatus && selfHealingStatus !== prevShStatus) return true;
+    if (prevVerificationStatus && verificationStatus !== prevVerificationStatus) return true;
+    if (prevFailureClassification && failureClassification !== prevFailureClassification) return true;
+    return false;
+}
+
+function isTimedOut() {
+    if (timeoutSeconds <= 0) return false;
+    const avgDelay = pollCount === 0 ? 0 : backoff(Math.floor(pollCount / 2));
+    return pollCount * avgDelay >= timeoutSeconds;
+}
+
+function isWaitTimedOut() {
+    if (newCipeTimeoutSeconds <= 0) return false;
+    return pollCount * 30 >= newCipeTimeoutSeconds;
+}
+
+function isNewCipe() {
+    return (prevCipeUrl && cipeUrl && cipeUrl !== prevCipeUrl) || (expectedSha && commitSha && commitSha === expectedSha);
+}
+
+// ============================================================
+// classify() — pure decision tree
+//
+// Returns: { action: 'poll'|'wait'|'done', code: string, extra? }
+//
+// Decision priority (top wins):
+//   WAIT MODE:
+//     1. new CI Attempt detected         → poll  (new_cipe_detected)
+//     2. wait timed out                  → done  (no_new_cipe)
+//     3. still waiting                   → wait  (waiting_for_cipe)
+//   NORMAL MODE:
+//     4. polling timeout                 → done  (polling_timeout)
+//     5. circuit breaker (13 polls)      → done  (circuit_breaker)
+//     6. CI succeeded                    → done  (ci_success)
+//     7. CI canceled                     → done  (cipe_canceled)
+//     8. CI timed out                    → done  (cipe_timed_out)
+//     9. CI failed, no tasks recorded    → done  (cipe_no_tasks)
+//    10. environment failure             → done  (environment_rerun_cap | environment_issue)
+//    11. self-healing throttled          → done  (self_healing_throttled)
+//    12. CI in progress / not started    → poll  (ci_running)
+//    13. self-healing in progress        → poll  (sh_running)
+//    14. flaky task auto-rerun           → poll  (flaky_rerun)
+//    15. fix auto-applied                → poll  (fix_auto_applied)
+//    16. auto-apply: skipped             → done  (fix_auto_apply_skipped)
+//    17. auto-apply: verification pending→ poll  (verification_pending)
+//    18. auto-apply: verified            → done  (fix_auto_applying)
+//    19. fix: verification failed/none   → done  (fix_needs_review)
+//    20. fix: all/e2e verified           → done  (fix_apply_ready)
+//    21. fix: needs local verify         → done  (fix_needs_local_verify)
+//    22. self-healing failed             → done  (fix_failed)
+//    23. no fix available                → done  (no_fix)
+//    24. fallback                        → poll  (fallback)
+// ============================================================
+
+function classify() {
+    // --- Wait mode ---
+    if (waitMode) {
+        if (isNewCipe()) return { action: 'poll', code: 'new_cipe_detected' };
+        if (isWaitTimedOut()) return { action: 'done', code: 'no_new_cipe' };
+        return { action: 'wait', code: 'waiting_for_cipe' };
+    }
+
+    // --- Guards ---
+    if (isTimedOut()) return { action: 'done', code: 'polling_timeout' };
+    if (noProgressCount >= 13) return { action: 'done', code: 'circuit_breaker' };
+
+    // --- Terminal CI states ---
+    if (cipeStatus === 'SUCCEEDED') return { action: 'done', code: 'ci_success' };
+    if (cipeStatus === 'CANCELED') return { action: 'done', code: 'cipe_canceled' };
+    if (cipeStatus === 'TIMED_OUT') return { action: 'done', code: 'cipe_timed_out' };
+
+    // --- CI failed, no tasks ---
+    if (cipeStatus === 'FAILED' && failedTaskIds.length === 0 && selfHealingStatus == null) return { action: 'done', code: 'cipe_no_tasks' };
+
+    // --- Environment failure ---
+    if (failureClassification === 'environment_state') {
+        if (envRerunCount >= 2) return { action: 'done', code: 'environment_rerun_cap' };
+        return { action: 'done', code: 'environment_issue' };
+    }
+
+    // --- Throttled ---
+    if (selfHealingSkippedReason === 'THROTTLED') return { action: 'done', code: 'self_healing_throttled' };
+
+    // --- Still running: CI ---
+    if (cipeStatus === 'IN_PROGRESS' || cipeStatus === 'NOT_STARTED') return { action: 'poll', code: 'ci_running' };
+
+    // --- Still running: self-healing ---
+    if ((selfHealingStatus === 'IN_PROGRESS' || selfHealingStatus === 'NOT_STARTED') && !selfHealingSkippedReason) return { action: 'poll', code: 'sh_running' };
+
+    // --- Still running: flaky rerun ---
+    if (failureClassification === 'flaky_task') return { action: 'poll', code: 'flaky_rerun' };
+
+    // --- Fix auto-applied, waiting for new CI Attempt ---
+    if (userAction === 'APPLIED_AUTOMATICALLY') return { action: 'poll', code: 'fix_auto_applied' };
+
+    // --- Auto-apply path (couldAutoApplyTasks) ---
+    if (couldAutoApplyTasks === true) {
+        if (autoApplySkipped === true)
+            return {
+                action: 'done',
+                code: 'fix_auto_apply_skipped',
+                extra: { autoApplySkipReason },
+            };
+        if (verificationStatus === 'NOT_STARTED' || verificationStatus === 'IN_PROGRESS') return { action: 'poll', code: 'verification_pending' };
+        if (verificationStatus === 'COMPLETED') return { action: 'done', code: 'fix_auto_applying' };
+        // verification FAILED or NOT_EXECUTABLE → falls through to fix_needs_review
+    }
+
+    // --- Fix available ---
+    if (selfHealingStatus === 'COMPLETED') {
+        if (verificationStatus === 'FAILED' || verificationStatus === 'NOT_EXECUTABLE' || (couldAutoApplyTasks !== true && !verificationStatus))
+            return { action: 'done', code: 'fix_needs_review' };
+
+        const tasks = categorizeTasks();
+        if (tasks.category === 'all_verified' || tasks.category === 'e2e_only') return { action: 'done', code: 'fix_apply_ready' };
+        return {
+            action: 'done',
+            code: 'fix_needs_local_verify',
+            extra: { verifiableTaskIds: tasks.verifiableTaskIds },
+        };
+    }
+
+    // --- Fix failed ---
+    if (selfHealingStatus === 'FAILED') return { action: 'done', code: 'fix_failed' };
+
+    // --- No fix available ---
+    if (cipeStatus === 'FAILED' && (selfHealingEnabled === false || selfHealingStatus === 'NOT_EXECUTABLE')) return { action: 'done', code: 'no_fix' };
+
+    // --- Fallback ---
+    return { action: 'poll', code: 'fallback' };
+}
+
+// ============================================================
+// buildOutput() — maps classification to full JSON output
+// ============================================================
+
+// Message templates keyed by status or key
+const messages = {
+    // wait mode
+    new_cipe_detected: () => `New CI Attempt detected! CI: ${cipeStatus || 'N/A'}`,
+    no_new_cipe: () => 'New CI Attempt timeout exceeded. No new CI Attempt detected.',
+    waiting_for_cipe: () => 'Waiting for new CI Attempt...',
+
+    // guards
+    polling_timeout: () => 'Polling timeout exceeded.',
+    circuit_breaker: () => 'No progress after 13 consecutive polls. Stopping.',
+
+    // terminal
+    ci_success: () => 'CI passed successfully!',
+    cipe_canceled: () => 'CI Attempt was canceled.',
+    cipe_timed_out: () => 'CI Attempt timed out.',
+    cipe_no_tasks: () => 'CI failed but no Nx tasks were recorded.',
+
+    // environment
+    environment_rerun_cap: () => 'Environment rerun cap (2) exceeded. Bailing.',
+    environment_issue: () => 'CI: FAILED | Classification: ENVIRONMENT_STATE',
+
+    // throttled
+    self_healing_throttled: () => 'Self-healing throttled \u2014 too many unapplied fixes.',
+
+    // polling
+    ci_running: () => `CI: ${cipeStatus}`,
+    sh_running: () => `CI: ${cipeStatus} | Self-healing: ${selfHealingStatus}`,
+    flaky_rerun: () => 'CI: FAILED | Classification: FLAKY_TASK (auto-rerun in progress)',
+    fix_auto_applied: () => 'CI: FAILED | Fix auto-applied, new CI Attempt spawning',
+    verification_pending: () => `CI: FAILED | Self-healing: COMPLETED | Verification: ${verificationStatus}`,
+
+    // actionable
+    fix_auto_applying: () => 'Fix verified! Auto-applying...',
+    fix_auto_apply_skipped: extra => `Fix verified but auto-apply was skipped. ${extra?.autoApplySkipReason ? `Reason: ${extra.autoApplySkipReason}` : 'Offer to apply manually.'}`,
+    fix_needs_review: () => `Fix available but needs review. Verification: ${verificationStatus || 'N/A'}`,
+    fix_apply_ready: () => 'Fix available and verified. Ready to apply.',
+    fix_needs_local_verify: extra => `Fix available. ${extra.verifiableTaskIds.length} task(s) need local verification.`,
+    fix_failed: () => 'Self-healing failed to generate a fix.',
+    no_fix: () => 'CI failed, no fix available.',
+
+    // fallback
+    fallback: () => `CI: ${cipeStatus || 'N/A'} | Self-healing: ${selfHealingStatus || 'N/A'} | Verification: ${verificationStatus || 'N/A'}`,
+};
+
+// Codes where noProgressCount resets to 0 (genuine progress occurred)
+const resetProgressCodes = new Set(['ci_success', 'fix_auto_applying', 'fix_auto_apply_skipped', 'fix_needs_review', 'fix_apply_ready', 'fix_needs_local_verify']);
+
+function formatMessage(msg) {
+    if (verbosity === 'minimal') {
+        const currentStatus = `${cipeStatus}|${selfHealingStatus}|${verificationStatus}`;
+        if (currentStatus === (prevStatus || '')) return null;
+        return msg;
+    }
+    if (verbosity === 'verbose') {
+        return [`Poll #${pollCount + 1} | CI: ${cipeStatus || 'N/A'} | Self-healing: ${selfHealingStatus || 'N/A'} | Verification: ${verificationStatus || 'N/A'}`, msg].join('\n');
+    }
+    return `Poll #${pollCount + 1} | ${msg}`;
+}
+
+function buildOutput(decision) {
+    const { action, code, extra } = decision;
+
+    // noProgressCount is already computed before classify() was called.
+    // Here we only handle the reset for "genuine progress" done-codes.
+
+    const msgFn = messages[code];
+    const rawMsg = msgFn ? msgFn(extra) : `Unknown: ${code}`;
+    const message = formatMessage(rawMsg);
+
+    const result = {
+        action,
+        code,
+        message,
+        noProgressCount: resetProgressCodes.has(code) ? 0 : noProgressCount,
+        envRerunCount,
+    };
+
+    // Add delay
+    if (action === 'wait') {
+        result.delay = 30;
+    } else if (action === 'poll') {
+        result.delay = code === 'new_cipe_detected' ? 60 : backoff(noProgressCount);
+        result.fields = 'light';
+    }
+
+    // Add extras
+    if (code === 'new_cipe_detected') result.newCipeDetected = true;
+    if (extra?.verifiableTaskIds) result.verifiableTaskIds = extra.verifiableTaskIds;
+    if (extra?.autoApplySkipReason) result.autoApplySkipReason = extra.autoApplySkipReason;
+
+    console.log(JSON.stringify(result));
+}
+
+// --- Run ---
+
+// Compute noProgressCount from input. Single assignment, no mutation.
+// Wait mode: reset on new cipe, otherwise unchanged (wait doesn't count as no-progress).
+// Normal mode: reset on any state change, otherwise increment.
+const noProgressCount = (() => {
+    if (waitMode) return isNewCipe() ? 0 : inputNoProgressCount;
+    if (isNewCipe() || hasStateChanged()) return 0;
+    return inputNoProgressCount + 1;
+})();
+
+buildOutput(classify());

package/dist/templates/base/.opencode/skills/monitor-ci/scripts/ci-state-update.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+
+/**
+ * CI State Update Script
+ *
+ * Deterministic state management for CI monitor actions.
+ * Three commands: gate, post-action, cycle-check.
+ *
+ * Usage:
+ *   node ci-state-update.mjs gate --gate-type <local-fix|env-rerun> [counter args]
+ *   node ci-state-update.mjs post-action --action <type> [--cipe-url <url>] [--commit-sha <sha>]
+ *   node ci-state-update.mjs cycle-check --code <code> [--agent-triggered] [counter args]
+ */
+
+// --- Arg parsing ---
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+function getFlag(name) {
+    return args.includes(name);
+}
+
+function getArg(name) {
+    const idx = args.indexOf(name);
+    return idx !== -1 && idx + 1 < args.length ? args[idx + 1] : null;
+}
+
+function output(result) {
+    console.log(JSON.stringify(result));
+}
+
+// --- gate ---
+// Check if an action is allowed and return incremented counter.
+// Called before any local fix attempt or environment rerun.
+
+function gate() {
+    const gateType = getArg('--gate-type');
+
+    if (gateType === 'local-fix') {
+        const count = parseInt(getArg('--local-verify-count') || '0', 10);
+        const max = parseInt(getArg('--local-verify-attempts') || '3', 10);
+        if (count >= max) {
+            return output({
+                allowed: false,
+                localVerifyCount: count,
+                message: `Local fix budget exhausted (${count}/${max} attempts)`,
+            });
+        }
+        return output({
+            allowed: true,
+            localVerifyCount: count + 1,
+            message: null,
+        });
+    }
+
+    if (gateType === 'env-rerun') {
+        const count = parseInt(getArg('--env-rerun-count') || '0', 10);
+        if (count >= 2) {
+            return output({
+                allowed: false,
+                envRerunCount: count,
+                message: `Environment issue persists after ${count} reruns. Manual investigation needed.`,
+            });
+        }
+        return output({
+            allowed: true,
+            envRerunCount: count + 1,
+            message: null,
+        });
+    }
+
+    output({ allowed: false, message: `Unknown gate type: ${gateType}` });
+}
+
+// --- post-action ---
+// Compute next state after an action is taken.
+// Returns wait mode params and whether the action was agent-triggered.
+
+function postAction() {
+    const action = getArg('--action');
+    const cipeUrl = getArg('--cipe-url');
+    const commitSha = getArg('--commit-sha');
+
+    // MCP-triggered or auto-applied: track by cipeUrl
+    const cipeUrlActions = ['fix-auto-applying', 'apply-mcp', 'env-rerun'];
+    // Local push: track by commitSha
+    const commitShaActions = ['apply-local-push', 'reject-fix-push', 'local-fix-push', 'auto-fix-push', 'empty-commit-push'];
+
+    const trackByCipeUrl = cipeUrlActions.includes(action);
+    const trackByCommitSha = commitShaActions.includes(action);
+
+    if (!trackByCipeUrl && !trackByCommitSha) {
+        return output({ error: `Unknown action: ${action}` });
+    }
+
+    // fix-auto-applying: self-healing did it, NOT the monitor
+    const agentTriggered = action !== 'fix-auto-applying';
+
+    output({
+        waitMode: true,
+        pollCount: 0,
+        lastCipeUrl: trackByCipeUrl ? cipeUrl : null,
+        expectedCommitSha: trackByCommitSha ? commitSha : null,
+        agentTriggered,
+    });
+}
+
+// --- cycle-check ---
+// Cycle classification + counter resets when a new "done" code is received.
+// Called at the start of handling each actionable code.
+
+function cycleCheck() {
+    const status = getArg('--code');
+    const wasAgentTriggered = getFlag('--agent-triggered');
+    let cycleCount = parseInt(getArg('--cycle-count') || '0', 10);
+    const maxCycles = parseInt(getArg('--max-cycles') || '10', 10);
+    let envRerunCount = parseInt(getArg('--env-rerun-count') || '0', 10);
+
+    // Cycle classification: if previous cycle was agent-triggered, count it
+    if (wasAgentTriggered) cycleCount++;
+
+    // Reset env_rerun_count on non-environment status
+    if (status !== 'environment_issue') envRerunCount = 0;
+
+    // Approaching limit gate
+    const approachingLimit = cycleCount >= maxCycles - 2;
+
+    output({
+        cycleCount,
+        agentTriggered: false,
+        envRerunCount,
+        approachingLimit,
+        message: approachingLimit ? `Approaching cycle limit (${cycleCount}/${maxCycles})` : null,
+    });
+}
+
+// --- Dispatch ---
+
+switch (command) {
+    case 'gate':
+        gate();
+        break;
+    case 'post-action':
+        postAction();
+        break;
+    case 'cycle-check':
+        cycleCheck();
+        break;
+    default:
+        output({ error: `Unknown command: ${command}` });
+}

package/dist/templates/base/.opencode/skills/nx-generate/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: nx-generate
+description: Generate code using nx generators. INVOKE IMMEDIATELY when user mentions scaffolding, setup, structure, creating apps/libs, or setting up project structure. Trigger words - scaffold, setup, create a ... app, create a ... lib, project structure, generate, add a new project. ALWAYS use this BEFORE calling nx_docs or exploring - this skill handles discovery internally.
+---
+
+# Run Nx Generator
+
+Nx generators are powerful tools that scaffold projects, make automated code migrations or automate repetitive tasks in a monorepo. They ensure consistency across the codebase and reduce boilerplate work.
+
+This skill applies when the user wants to:
+
+- Create new projects like libraries or applications
+- Scaffold features or boilerplate code
+- Run workspace-specific or custom generators
+- Do anything else that an nx generator exists for
+
+## Key Principles
+
+1. **Always use `--no-interactive`** - Prevents prompts that would hang execution
+2. **Read the generator source code** - The schema alone is not enough; understand what the generator actually does
+3. **Match existing repo patterns** - Study similar artifacts in the repo and follow their conventions
+4. **Verify with lint/test/build/typecheck etc.** - Generated code must pass verification. The listed targets are just an example, use what's appropriate for this workspace.
+
+## Steps
+
+### 1. Discover Available Generators
+
+Use the Nx CLI to discover available generators:
+
+- List all generators for a plugin: `npx nx list @nx/react`
+- View available plugins: `npx nx list`
+
+This includes plugin generators (e.g., `@nx/react:library`) and local workspace generators.
+
+### 2. Match Generator to User Request
+
+Identify which generator(s) could fulfill the user's needs. Consider what artifact type they want, which framework is relevant, and any specific generator names mentioned.
+
+**IMPORTANT**: When both a local workspace generator and an external plugin generator could satisfy the request, **always prefer the local workspace generator**. Local generators are customized for the specific repo's patterns.
+
+If no suitable generator exists, you can stop using this skill. However, the burden of proof is high—carefully consider all available generators before deciding none apply.
+
+### 3. Get Generator Options
+
+Use the `--help` flag to understand available options:
+
+```bash
+npx nx g @nx/react:library --help
+```
+
+Pay attention to required options, defaults that might need overriding, and options relevant to the user's request.
+
+### Library Buildability
+
+**Default to non-buildable libraries** unless there's a specific reason for buildable.
+
+| Type                        | When to use                                                       | Generator flags                     |
+| --------------------------- | ----------------------------------------------------------------- | ----------------------------------- |
+| **Non-buildable** (default) | Internal monorepo libs consumed by apps                           | No `--bundler` flag                 |
+| **Buildable**               | Publishing to npm, cross-repo sharing, stable libs for cache hits | `--bundler=vite` or `--bundler=swc` |
+
+Non-buildable libs:
+
+- Export `.ts`/`.tsx` source directly
+- Consumer's bundler compiles them
+- Faster dev experience, less config
+
+Buildable libs:
+
+- Have their own build target
+- Useful for stable libs that rarely change (cache hits)
+- Required for npm publishing
+
+**If unclear, ask the user:** "Should this library be buildable (own build step, better caching) or non-buildable (source consumed directly, simpler setup)?"
+
+### 4. Read Generator Source Code
+
+**This step is critical.** The schema alone does not tell you everything. Reading the source code helps you:
+
+- Know exactly what files will be created/modified and where
+- Understand side effects (updating configs, installing deps, etc.)
+- Identify behaviors and options not obvious from the schema
+- Understand how options interact with each other
+
+To find generator source code:
+
+- For plugin generators: Use `node -e "console.log(require.resolve('@nx/<plugin>/generators.json'));"` to find the generators.json, then locate the source from there
+- If that fails, read directly from `node_modules/<plugin>/generators.json`
+- For local generators: Typically in `tools/generators/` or a local plugin directory. Search the repo for the generator name.
+
+After reading the source, reconsider: Is this the right generator? If not, go back to step 2.
+
+> **⚠️ `--directory` flag behavior can be misleading.**
+> It should specify the full path of the generated library or component, not the parent path that it will be generated in.
+>
+> ```bash
+> # ✅ Correct - directory is the full path for the library
+> nx g @nx/react:library --directory=libs/my-lib
+> # generates libs/my-lib/package.json and more
+>
+> # ❌ Wrong - this will create files at libs and libs/src/...
+> nx g @nx/react:library --name=my-lib --directory=libs
+> # generates libs/package.json and more
+> ```
+
+### 5. Examine Existing Patterns
+
+Before generating, examine the target area of the codebase:
+
+- Look at similar existing artifacts (other libraries, applications, etc.)
+- Identify naming conventions, file structures, and configuration patterns
+- Note which test runners, build tools, and linters are used
+- Configure the generator to match these patterns
+
+### 6. Dry-Run to Verify File Placement
+
+**Always run with `--dry-run` first** to verify files will be created in the correct location:
+
+```bash
+npx nx g @nx/react:library --name=my-lib --dry-run --no-interactive
+```
+
+Review the output carefully. If files would be created in the wrong location, adjust your options based on what you learned from the generator source code.
+
+Note: Some generators don't support dry-run (e.g., if they install npm packages). If dry-run fails for this reason, proceed to running the generator for real.
+
+### 7. Run the Generator
+
+Execute the generator:
+
+```bash
+nx generate <generator-name> <options> --no-interactive
+```
+
+> **Tip:** New packages often need workspace dependencies wired up (e.g., importing shared types, being consumed by apps). The `link-workspace-packages` skill can help add these correctly.
+
+### 8. Modify Generated Code (If Needed)
+
+Generators provide a starting point. Modify the output as needed to:
+
+- Add or modify functionality as requested
+- Adjust imports, exports, or configurations
+- Integrate with existing code patterns
+
+**Important:** If you replace or delete generated test files (e.g., `*.spec.ts`), either write meaningful replacement tests or remove the `test` target from the project configuration. Empty test suites will cause `nx test` to fail.
+
+### 9. Format and Verify
+
+Format all generated/modified files:
+
+```bash
+nx format --fix
+```
+
+This example is for built-in nx formatting with prettier. There might be other formatting tools for this workspace, use these when appropriate.
+
+Then verify the generated code works. Keep in mind that the changes you make with a generator or subsequent modifications might impact various projects so it's usually not enough to only run targets for the artifact you just created.
+
+```bash
+# these targets are just an example!
+nx run-many -t build,lint,test,typecheck
+```
+
+These targets are common examples used across many workspaces. You should do research into other targets available for this workspace and its projects. CI configuration is usually a good guide for what the critical targets are that have to pass.
+
+If verification fails with manageable issues (a few lint errors, minor type issues), fix them. If issues are extensive, attempt obvious fixes first, then escalate to the user with details about what was generated, what's failing, and what you've attempted.