@ulpi/cli 0.1.4 → 0.1.6

package/dist/skills/ulpi-generate-guardian/SKILL.md

@@ -1,750 +0,0 @@
----
-name: ulpi-generate-guards
-description: Use when the user asks to generate ULPI configuration for a project. Detects language, framework, package manager, and tooling to create optimized guards.yml with preconditions, permissions, postconditions, and pipelines. Invoke via /ulpi-generate-guards or when user says "generate guards", "create guards.yml", "setup ulpi", "configure guardian".
----
-
-<EXTREMELY-IMPORTANT>
-Before generating ANY guards.yml configuration, you **ABSOLUTELY MUST**:
-
-1. Verify the target directory exists
-2. Check for existing `.ulpi/guards.yml` (ask before overwriting)
-3. Detect at least one technology signal (language, framework, or package manager)
-
-**Generating without verification = wrong rules, overwritten configs, broken guards**
-
-This is not optional. Every generation requires disciplined verification.
-</EXTREMELY-IMPORTANT>
-
-# Generate ULPI Configuration
-
-## MANDATORY FIRST RESPONSE PROTOCOL
-
-Before generating ANY configuration, you **MUST** complete this checklist:
-
-1. ☐ Verify target directory exists
-2. ☐ Check for existing guards.yml
-3. ☐ Detect language (tsconfig.json, pyproject.toml, go.mod, etc.)
-4. ☐ Detect framework (next.config.*, artisan, manage.py, etc.)
-5. ☐ Detect package manager (pnpm-lock.yaml, yarn.lock, etc.)
-6. ☐ Announce: "Generating ULPI configuration for [language]/[framework]/[package_manager]"
-
-Do NOT ask "Proceed?" — the user invoked this skill explicitly. Show the detected stack as an informational summary, then generate immediately.
-
-**Generating WITHOUT completing this checklist = wrong or harmful rules.**
-
-## Purpose
-
-This skill generates configuration for **ULPI**, a tool that:
-- Auto-approves safe operations (reads, package manager commands)
-- Blocks dangerous commands (force push, database wipes, env file edits)
-- Enforces best practices (read-before-write)
-- Runs postconditions (lint, test, generate) after file changes
-
-**Output:** `.ulpi/guards.yml` configuration file
-
-**Does NOT:** Install ULPI, run the generated rules, or modify existing configurations without confirmation.
-
-## Overview
-
-Analyze a project directory, detect the technology stack, and generate a complete `guards.yml` configuration for ULPI. Creates rules that auto-approve safe operations, block dangerous commands, and enforce best practices.
-
-## When to Use
-
-- User says "generate guards", "create guards.yml", "/ulpi-generate-guards"
-- User says "setup ulpi", "configure guardian for this project"
-- $ARGUMENTS contains a path (e.g., `/ulpi-generate-guards /path/to/project`)
-
-**Never generate unprompted.** Only when explicitly requested.
-
-## Step 1: Determine Target Directory
-
-**Gate: Valid directory confirmed before proceeding to Step 2.**
-
-If $ARGUMENTS has a path, use it. Otherwise use current working directory.
-
-Verify the directory exists before proceeding. If not found, stop and inform the user.
-
-Check for existing `.ulpi/guards.yml`:
-- If found, ask user: merge, overwrite, or abort?
-- Never overwrite without explicit confirmation
-
-## Step 2: Detect Technology Stack
-
-**Gate: Stack detected before proceeding to Step 3.**
-
-Scan for indicator files in priority order:
-
-### Language Detection
-
-| Signal | Language |
-|--------|----------|
-| `tsconfig.json` | TypeScript |
-| `package.json` (no tsconfig) | JavaScript |
-| `pyproject.toml`, `requirements.txt` | Python |
-| `go.mod` | Go |
-| `Cargo.toml` | Rust |
-| `composer.json` | PHP |
-| `Gemfile` | Ruby |
-| `pom.xml`, `build.gradle` | Java |
-| `*.csproj`, `*.sln` | C# |
-| `mix.exs` | Elixir |
-
-### Framework Detection
-
-| Signal | Framework |
-|--------|-----------|
-| `next.config.*` | Next.js |
-| `nuxt.config.*` | Nuxt |
-| `angular.json` | Angular |
-| `svelte.config.*` | SvelteKit |
-| `nest-cli.json` | NestJS |
-| `artisan` | Laravel |
-| `manage.py` + django | Django |
-| `fastapi` in deps | FastAPI |
-| `actix-web` in Cargo.toml | Actix |
-| `gin` in go.mod | Gin |
-
-### Package Manager Detection
-
-| Signal | Package Manager |
-|--------|-----------------|
-| `pnpm-lock.yaml` | pnpm |
-| `yarn.lock` | yarn |
-| `package-lock.json` | npm |
-| `bun.lockb` | bun |
-| `poetry.lock` | poetry |
-| `uv.lock` | uv |
-| `Cargo.lock` | cargo |
-| `composer.lock` | composer |
-| `Gemfile.lock` | bundler |
-
-### Tooling Detection
-
-| Signal | Tool | Type |
-|--------|------|------|
-| `vitest.config.*` | Vitest | test |
-| `jest.config.*` | Jest | test |
-| `pytest.ini` | pytest | test |
-| `.eslintrc*` | ESLint | lint |
-| `.prettierrc*` | Prettier | format |
-| `biome.json` | Biome | lint+format |
-| `prisma/schema.prisma` | Prisma | ORM |
-| `drizzle.config.*` | Drizzle | ORM |
-
-### Monorepo Detection
-
-| Signal | Structure |
-|--------|-----------|
-| `turbo.json` | Turborepo |
-| `lerna.json` | Lerna |
-| `pnpm-workspace.yaml` | pnpm workspaces |
-| `"workspaces"` in package.json | Yarn/npm workspaces |
-
-**If a monorepo is detected, you MUST proceed to Step 2b (Map Monorepo Topology) before continuing.**
-
-## Step 2b: Map Monorepo Topology (Monorepos Only)
-
-**Gate: Full workspace topology mapped before proceeding to Step 3.**
-
-When a monorepo is detected, do NOT treat it as a flat project. You must:
-
-1. **Read the workspace config** — `pnpm-workspace.yaml`, `lerna.json`, or `package.json` workspaces field to find all workspace globs
-2. **List all packages** — Resolve workspace globs to actual directories (e.g., `apps/*`, `packages/*`)
-3. **Read each package's `package.json`** — Identify name, dependencies, devDependencies, scripts
-4. **Map the dependency graph** — Which packages depend on which? Identify the direction of dependency flow
-5. **Read the task runner config** — `turbo.json` task definitions, dependency chains (`^` prefix = depends on upstream)
-6. **Identify build characteristics** — Does the package have a build step? Is it consumed as source? Does it have its own tsconfig?
-
-### Topology Output Format
-
-Record the topology as a YAML comment in the header:
-
-```yaml
-# Workspace Topology:
-#   {package-a} → {package-b} (one-way dependency)
-#   {package-c} (standalone)
-#
-# Task Graph (turbo.json):
-#   build: depends on ^build
-#   type-check: depends on ^type-check
-```
-
-### What Monorepo Topology Enables
-
-- **Package boundary enforcement** — Prevent imports in the wrong direction
-- **Per-package postconditions** — Type-check only the affected package using `turbo --filter=`
-- **Turbo-first commands** — Use `turbo run` instead of direct package manager for tasks defined in turbo.json
-- **Critical file cautions** — Barrel exports, shared configs, workspace manifests
-
-See `references/framework-rules.md` → Turborepo section for complete rule templates.
-
-## Step 3: Extract Commands from Config
-
-**Gate: Commands extracted before proceeding to Step 4.**
-
-For Node.js projects, read package.json scripts to identify:
-- `test_command` (from "test" script)
-- `build_command` (from "build" script)
-- `lint_command` (from "lint" script)
-- `format_command` (from "format" script)
-
-**For monorepos:** Read BOTH the root `package.json` AND `turbo.json`:
-- If root scripts delegate to turbo (e.g., `"build": "turbo run build"`), the real commands are turbo tasks
-- Read each workspace's `package.json` scripts to understand what turbo invokes per-package
-- Postconditions and pipelines should use `turbo run <task> --filter=<package>`, NOT direct `pnpm <script>`
-
-For Python projects, check pyproject.toml for tool configurations.
-
-For Rust projects, use standard cargo commands.
-
-## Step 4: Generate guards.yml
-
-**Gate: Complete rules generated before proceeding to Step 5.**
-
-Create `.ulpi/guards.yml` with these sections:
-
-### Header
-
-```yaml
-# ULPI — Generated Configuration
-# Stack: {language} / {framework} / {package_manager}
-# Generated: {timestamp}
-
-project:
-  name: "{project_name}"
-  runtime: "{runtime}"
-  package_manager: "{package_manager}"
-```
-
-### Universal Preconditions (Always Include)
-
-```yaml
-preconditions:
-  read-before-write:
-    enabled: true
-    trigger: PreToolUse
-    matcher: "Write|Edit|MultiEdit"
-    requires_read: true
-    message: "Read {file_path} before editing it."
-    locked: true
-    priority: 10
-```
-
-### Universal Permissions (Always Include)
-
-```yaml
-permissions:
-  # --- Auto-approvals ---
-  auto-approve-reads:
-    enabled: true
-    trigger: PermissionRequest
-    matcher: "Read|LS|Glob|Grep"
-    decision: allow
-    priority: 100
-
-  auto-approve-git-readonly:
-    enabled: true
-    trigger: PermissionRequest
-    matcher: Bash
-    command_pattern: "git (status|log|diff|branch|show|stash list|remote -v|rev-parse)"
-    decision: allow
-    priority: 90
-
-  auto-approve-gh-cli:
-    enabled: true
-    trigger: PermissionRequest
-    matcher: Bash
-    command_pattern: "gh"
-    decision: allow
-    priority: 80
-
-  auto-approve-prettier:
-    enabled: true
-    trigger: PermissionRequest
-    matcher: Bash
-    command_pattern: "prettier"
-    decision: allow
-    priority: 80
-
-  auto-approve-shell-inspection:
-    enabled: true
-    trigger: PermissionRequest
-    matcher: Bash
-    command_pattern: "(ls|cat|head|tail|wc|file|which|echo|pwd|whoami)"
-    decision: allow
-    priority: 80
-
-  # --- Git destructive blocks (comprehensive) ---
-  no-force-push:
-    enabled: true
-    trigger: PreToolUse
-    matcher: Bash
-    command_pattern: "git push.*(--force|-f)"
-    decision: deny
-    message: "Force push blocked. Use --force-with-lease."
-    locked: true
-    priority: 1
-
-  no-git-checkout-dot:
-    enabled: true
-    trigger: PreToolUse
-    matcher: Bash
-    command_pattern: "git checkout \\."
-    decision: deny
-    message: "git checkout . discards all unstaged changes."
-    locked: true
-    priority: 1
-
-  no-git-restore-dot:
-    enabled: true
-    trigger: PreToolUse
-    matcher: Bash
-    command_pattern: "git restore \\."
-    decision: deny
-    message: "git restore . discards all unstaged changes."
-    locked: true
-    priority: 1
-
-  no-git-reset-hard:
-    enabled: true
-    trigger: PreToolUse
-    matcher: Bash
-    command_pattern: "git reset --hard"
-    decision: deny
-    message: "git reset --hard destroys uncommitted work."
-    locked: true
-    priority: 1
-
-  no-git-clean-force:
-    enabled: true
-    trigger: PreToolUse
-    matcher: Bash
-    command_pattern: "git clean.* -f"
-    decision: deny
-    message: "git clean -f permanently deletes untracked files."
-    locked: true
-    priority: 1
-
-  no-git-branch-delete-force:
-    enabled: true
-    trigger: PreToolUse
-    matcher: Bash
-    command_pattern: "git branch -D"
-    decision: deny
-    message: "git branch -D force-deletes branches. Use -d for safe delete."
-    locked: true
-    priority: 1
-
-  no-skip-hooks:
-    enabled: true
-    trigger: PreToolUse
-    matcher: Bash
-    command_pattern: "--no-verify"
-    decision: deny
-    message: "Do not skip git hooks."
-    locked: true
-    priority: 1
-
-  no-rm-rf:
-    enabled: true
-    trigger: PreToolUse
-    matcher: Bash
-    command_pattern: "rm -rf"
-    decision: deny
-    message: "rm -rf is destructive. Remove specific files instead."
-    locked: true
-    priority: 1
-
-  # --- File protection ---
-  block-env-files:
-    enabled: true
-    trigger: PreToolUse
-    matcher: "Write|Edit"
-    file_pattern: ".env*"
-    decision: deny
-    message: "Cannot edit .env files directly."
-    priority: 50
-
-  block-node-modules:
-    enabled: true
-    trigger: PreToolUse
-    matcher: "Write|Edit"
-    file_pattern: "node_modules/**"
-    decision: deny
-    locked: true
-    priority: 1
-
-  block-dist:
-    enabled: true
-    trigger: PreToolUse
-    matcher: "Write|Edit"
-    file_pattern: "**/dist/**"
-    decision: deny
-    locked: true
-    priority: 1
-```
-
-**Important:** `git push` is intentionally NOT auto-approved. Pushes affect shared state and should always require confirmation.
-
-### Language-Specific Rules
-
-Add based on detected language. See `references/language-rules.md`.
-
-### Framework-Specific Rules
-
-Add based on detected framework. See `references/framework-rules.md`.
-
-### Pipelines (Required Fields)
-
-Every pipeline MUST include `on_failure`. It is a **required field** — omitting it causes a validation error.
-
-```yaml
-pipelines:
-  pre-commit-checks:
-    enabled: true
-    trigger: "PreToolUse"
-    matcher: "Bash"
-    command_pattern: "git commit"
-    steps:
-      - name: "type-check"
-        run: "{type_check_command}"
-        timeout: 60000
-      - name: "lint"
-        run: "{lint_command}"
-        timeout: 60000
-    on_failure: "block"          # REQUIRED — "block" or "warn"
-    message: "Pre-commit checks failed."
-    locked: true
-    priority: 5
-```
-
-Valid `on_failure` values: `"block"` (prevent the action) or `"warn"` (show warning but allow).
-
-## Step 5: Write Configuration
-
-**Gate: File written before proceeding to Step 6.**
-
-Create the `.ulpi/` directory if it doesn't exist.
-
-Write the generated YAML to `guards.yml`.
-
-Verify the file was written successfully.
-
-## Step 6: Report Results
-
-**Gate: Results reported before marking complete.**
-
-Report to the user:
-- Stack detected
-- Rules created (counts)
-- File location
-- Suggested next steps
-
-## Pre-Generation Checklist
-
-Before generating, verify:
-- [ ] Target directory exists and is accessible
-- [ ] No existing guards.yml OR user approved overwrite
-- [ ] At least one technology detected
-
-## Error Handling
-
-| Situation | Action |
-|-----------|--------|
-| Directory not found | Stop and inform user |
-| No tech stack detected | Generate minimal universal rules only |
-| Multiple frameworks | Ask user which is primary |
-| Existing guards.yml | Ask: merge, overwrite, or abort |
-| Conflicting signals | Prefer more specific (framework > language) |
-
-## About Postconditions
-
-Postconditions are **disabled by default** because they run automatically after file changes and may:
-- Slow down workflows
-- Produce unexpected side effects
-- Conflict with user's preferred workflow
-
-**To enable:** User should manually set `enabled: true` for desired postconditions after reviewing them.
-
-## About Pipelines
-
-Pipelines define multi-step checks (e.g., pre-commit). Every pipeline **MUST** include the `on_failure` field — it is required. Valid values: `"block"` (stop the action) or `"warn"` (show warning but proceed).
-
-```yaml
-pipelines:
-  pre-commit-checks:
-    enabled: true
-    trigger: "PreToolUse"
-    matcher: "Bash"
-    command_pattern: "git commit"
-    steps:
-      - name: "type-check"
-        run: "{type_check_command}"
-        timeout: 60000
-      - name: "lint"
-        run: "{lint_command}"
-        timeout: 60000
-    on_failure: "block"    # REQUIRED — omitting this causes validation error
-    message: "Pre-commit checks."
-    locked: true
-    priority: 5
-```
-
-## Safety Rules
-
-| Rule | Reason |
-|------|--------|
-| Always include read-before-write | Prevents editing files without reading first |
-| Always block force push (--force AND -f) | Prevents history destruction |
-| Always block all git destructive ops | checkout ., restore ., reset --hard, clean -f, branch -D |
-| Always block --no-verify | Never skip git hooks |
-| Always block rm -rf | Prevents catastrophic deletions |
-| Always block .env edits | Protects secrets |
-| Always block node_modules/dist | Build artifacts should not be edited |
-| Auto-approve reads | Safe operations should not prompt |
-| Auto-approve ONLY the detected package manager | Do not auto-approve all package managers |
-| Never auto-approve git push | Pushes affect shared state, always confirm |
-| Never generate state-tracking rules | ULPI has no state; rules like "track last N" are non-functional |
-| Never generate redundant rules | If a rule duplicates another, remove the weaker one |
-| Always include `on_failure` in pipelines | Required field — omitting causes validation error |
-| Always map monorepo topology when detected | Flat treatment of monorepos produces wrong rules |
-| Never overwrite without asking | Preserves existing configuration |
-| Always verify directory exists | Prevents errors |
-
-## Quick Reference: Command Detection
-
-```
-package.json scripts:
-  "test"   → test_command
-  "build"  → build_command
-  "lint"   → lint_command
-  "format" → format_command
-  "dev"    → auto-approve permission
-
-pyproject.toml:
-  [tool.pytest]     → pytest
-  [tool.ruff]       → ruff
-  [tool.black]      → black
-
-Cargo.toml:
-  cargo test        → test_command
-  cargo build       → build_command
-  cargo clippy      → lint_command
-```
-
----
-
-## Quality Checklist (Must Score 8/10)
-
-Score yourself honestly before marking generation complete:
-
-### Detection Accuracy (0-2 points)
-- **0 points:** Guessed technology without file verification
-- **1 point:** Detected some signals but missed others
-- **2 points:** Verified all signals, detection matches reality
-
-### Stack Announcement (0-2 points)
-- **0 points:** Generated without showing detected stack
-- **1 point:** Showed partial detection
-- **2 points:** Full detection shown before generation
-
-### Rule Coverage (0-2 points)
-- **0 points:** Missing universal rules (read-before-write, block-env)
-- **1 point:** Universal rules present but missing language/framework rules
-- **2 points:** Complete coverage: universal + language + framework + tooling
-
-### Safety Rules (0-2 points)
-- **0 points:** Missing critical blocks (force-push, env files)
-- **1 point:** Some safety rules but incomplete
-- **2 points:** All dangerous operations blocked
-
-### Output Quality (0-2 points)
-- **0 points:** Invalid YAML or missing required fields
-- **1 point:** Valid but poorly organized
-- **2 points:** Clean, well-commented, properly structured YAML
-
-**Minimum passing score: 8/10**
-
----
-
-## Common Rationalizations (All Wrong)
-
-These are excuses. Don't fall for them:
-
-- **"The directory is obvious"** → STILL verify it exists
-- **"I know this is a Node.js project"** → STILL detect from config files
-- **"There's no existing guards.yml"** → STILL check before generating
-- **"The user wants it fast"** → STILL show detected stack first
-- **"These are standard rules"** → STILL customize for detected stack
-- **"Postconditions are disabled anyway"** → STILL generate them correctly
-- **"It's a monorepo but I'll just use global commands"** → Map the topology and use per-package `--filter`
-- **"git push is just like other git commands"** → Push affects shared state, NEVER auto-approve it
-- **"I'll add a rule to track recent actions"** → ULPI has no state between invocations, this won't work
-- **"All Node.js package managers should be auto-approved"** → Only approve the DETECTED one
-
----
-
-## Failure Modes
-
-### Failure Mode 1: Wrong Technology Detection
-
-**Symptom:** Generated Python rules for a TypeScript project
-**Fix:** Always verify with config files, not assumptions
-
-### Failure Mode 2: Overwritten Existing Config
-
-**Symptom:** User's custom guards.yml was replaced without warning
-**Fix:** Always check for existing file, ask before overwriting
-
-### Failure Mode 3: Missing Critical Safety Rules
-
-**Symptom:** Agent force-pushed after generation (rule wasn't blocked)
-**Fix:** Always include universal safety rules regardless of stack
-
-### Failure Mode 4: Invalid YAML Generated
-
-**Symptom:** ULPI fails to parse guards.yml
-**Fix:** Validate YAML structure before writing
-
-### Failure Mode 5: Flat Treatment of Monorepo
-
-**Symptom:** Postconditions run `tsc --noEmit` globally instead of `turbo --filter=<pkg>`, package boundaries not enforced, no topology in header
-**Fix:** Always run Step 2b when monorepo is detected. Map the full workspace dependency graph. Generate per-package postconditions with `--filter`.
-
-### Failure Mode 6: Non-Functional State-Tracking Rules
-
-**Symptom:** Rules reference "last N actions" or "track recent commands" — ULPI has no state between invocations
-**Fix:** Only generate rules that use ULPI's actual capabilities: matchers, patterns, triggers. No stateful tracking.
-
-### Failure Mode 7: Redundant Rules
-
-**Symptom:** Multiple rules block the same thing (e.g., separate `block-dist` and `block-build-output` when only one output dir exists)
-**Fix:** Audit generated rules for overlap. Each rule should block a distinct concern.
-
----
-
-## Quick Workflow Summary
-
-```
-STEP 1: DETERMINE TARGET
-├── Parse $ARGUMENTS for path
-├── Default to current directory
-├── Verify directory exists
-├── Check for existing guards.yml
-└── Gate: Valid directory confirmed
-
-STEP 2: DETECT TECHNOLOGY
-├── Scan for language signals
-├── Scan for framework signals
-├── Scan for package manager signals
-├── Scan for tooling (test, lint, ORM)
-├── Check for monorepo structure
-├── Announce detected stack (informational, no question)
-└── Gate: Stack detected
-
-STEP 2b: MAP MONOREPO TOPOLOGY (if monorepo detected)
-├── Read workspace config (pnpm-workspace.yaml, etc.)
-├── List all packages in workspace
-├── Read each package's package.json
-├── Map dependency graph (who depends on whom)
-├── Read turbo.json / lerna.json task definitions
-├── Identify build characteristics per package
-└── Gate: Full topology mapped
-
-STEP 3: EXTRACT COMMANDS
-├── Read package.json scripts (root + per-package for monorepos)
-├── Read turbo.json tasks (monorepos)
-├── Read pyproject.toml tools
-├── Identify test/build/lint commands
-├── For monorepos: note turbo --filter commands per package
-└── Gate: Commands extracted
-
-STEP 4: GENERATE RULES
-├── Start with universal rules (comprehensive git blocks, no push auto-approve)
-├── Add language-specific rules (only detected pkg manager)
-├── Add framework-specific rules
-├── Add monorepo rules (boundaries, per-pkg postconditions, prefer-turbo)
-├── Add project-specific critical file cautions
-├── Add tooling rules
-├── Audit for redundancy (no duplicate rules)
-└── Gate: Complete rules generated
-
-STEP 5: WRITE CONFIGURATION
-├── Create .ulpi/ directory
-├── Write guards.yml
-├── Verify file written
-└── Gate: File written
-
-STEP 6: REPORT RESULTS
-├── Show stack summary
-├── Show rule counts
-├── Show file location
-├── Suggest next steps
-└── Gate: Complete
-```
-
----
-
-## Completion Announcement
-
-When generation is complete, announce:
-
-```
-ULPI configuration generated.
-
-**Quality Score: X/10**
-- Detection Accuracy: X/2
-- Stack Announcement: X/2
-- Rule Coverage: X/2
-- Safety Rules: X/2
-- Output Quality: X/2
-
-**Stack Detected:**
-- Language: [language]
-- Framework: [framework]
-- Package Manager: [package_manager]
-- Test Runner: [test_runner]
-- Linter: [linter]
-
-**Rules Generated:**
-- Preconditions: [count]
-- Permissions: [count]
-- Postconditions: [count]
-
-**Output:** .ulpi/guards.yml
-
-**Next steps:**
-Run `ulpi rules validate` to verify configuration.
-```
-
----
-
-## Integration with Other Skills
-
-The `ulpi-generate-guards` skill integrates with:
-
-- **`start`** — Detects ULPI configuration needs during project setup
-- **`commit`** — Generated rules can auto-approve git operations
-- **`create-pr`** — Generated rules can auto-approve PR creation commands
-
-**Workflow Chain:**
-
-```
-New project or directory
-       │
-       ▼
-ulpi-generate-guards skill (this skill)
-       │
-       ▼
-guards.yml created
-       │
-       ▼
-ULPI uses rules during development
-```
-
----
-
-## Resources
-
-See `references/language-rules.md` for language-specific rule templates.
-See `references/framework-rules.md` for framework-specific rule templates.