@esoteric-logic/praxis-harness 1.1.0

package/kits/infrastructure/rules/infrastructure.md

@@ -0,0 +1,82 @@
+# Infrastructure — Kit Rules
+# Scope: Active when /kit:infrastructure is loaded
+# Generalized from azure.md and terraform.md for cross-cloud applicability
+
+## Invariants — BLOCK on violation
+
+### No hardcoded subscription or account IDs
+- Never hardcode cloud subscription IDs, account IDs, tenant IDs, or project IDs in Terraform or scripts.
+- Use variables, data sources, or environment-based lookups.
+
+### Plan before apply — always
+- `terraform plan` (or equivalent) must be reviewed before ANY `terraform apply`.
+- No blind applies. No `-auto-approve` without explicit user approval.
+- Flag destructive changes (destroy, replace) prominently in plan output.
+
+### Remote state only
+- No local state files committed to git.
+- State backend must be configured before first apply.
+- State files never contain secrets — verify backend config before committing.
+
+### Least privilege RBAC
+- No Owner or Contributor at subscription/account scope as permanent assignments.
+- Propose least-privilege alternatives with specific scope.
+- RBAC changes to production must be documented in vault `specs/` before implementation.
+
+### Private endpoints by default
+- PaaS data services (storage, databases, key vaults, analytics) use private endpoints.
+- Public endpoint exposure requires explicit justification written to vault `specs/`.
+
+### No any-any network rules
+- Never create firewall/NSG rules with `source: Any` and `destination: Any`.
+- Flag existing any-any rules as HIGH risk.
+- Every allow rule must have a documented business reason.
+
+### Mandatory tagging
+- Every resource must include tags required by the engagement.
+- Check `_index.md` for engagement-specific tag requirements.
+- Missing mandatory tags = BLOCK. Add them before proceeding.
+
+---
+
+## Conventions — WARN on violation
+
+### Drift detection
+- Run `terraform plan -detailed-exitcode` periodically to detect drift.
+- Exit code 2 = drift detected. Document in vault and remediate or accept.
+
+### Module hygiene
+- Pin module versions. No floating `source` references without version constraints.
+- Prefer registry modules over git references for stability.
+
+### Cost awareness
+- Flag resource changes estimated to increase monthly cost by >5%.
+- Note SKU changes, reserved instance candidates, and scale-out implications.
+
+### Compliance mapping
+- Federal/government engagements: reference NIST CSF function or 800-53 control family
+  for security-relevant changes.
+- Compliance framework requirements documented in engagement `_index.md`.
+
+---
+
+## Verification Commands
+
+```bash
+# Check for hardcoded subscription/account IDs in Terraform
+rg '(subscription_id|account_id|tenant_id)\s*=\s*"[a-f0-9-]{36}"' --glob '*.tf'
+
+# Find any-any security rules
+rg '(source_address_prefix|source)\s*=\s*"\*"' --glob '*.tf'
+
+# Check for local state files
+find . -name 'terraform.tfstate' -o -name '*.tfstate.backup' 2>/dev/null
+
+# Verify remote backend configured
+rg 'backend\s+"(azurerm|s3|gcs|consul)"' --glob '*.tf'
+```
+
+---
+
+## Removal Condition
+Remove when `/kit:infrastructure` is deactivated. Rules are kit-scoped, not universal.

package/kits/infrastructure/teardown.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+set -euo pipefail
+
+echo "=== Praxis: Removing infrastructure kit ==="
+echo ""
+echo "This kit has no npm skills or MCP servers to remove."
+echo "CLI tools (az, terraform, tflint) are system-level and not managed by this kit."
+echo ""
+echo "To fully remove:"
+echo "  1. Remove /kit:infrastructure from any project CLAUDE.md '## Active kit' sections"
+echo "  2. Delete this directory: rm -rf ~/.claude/kits/infrastructure"
+echo ""
+echo "=== infrastructure kit removed ==="
+echo ""

package/kits/web-designer/KIT.md

@@ -0,0 +1,76 @@
+---
+name: web-designer
+version: 1.0.0
+description: Full-stack website design — design systems, components, audit
+activation: /kit:web-designer
+deactivation: /kit:off
+skills_chain:
+  - phase: design-system-init
+    skills: [ui-ux-pro-max, design-system-patterns]
+  - phase: component-build
+    skills: [frontend-design, shadcn-ui, 21st-dev-mcp]
+  - phase: audit
+    skills: [web-accessibility, ui-skills-baseline, ui-skills-motion]
+  - phase: final-lint
+    skills: [web-design-guidelines]
+mcp_servers:
+  - name: 21st-magic
+    command: npx -y @21st-dev/magic@latest
+rules:
+  - web-design.md
+removal_condition: >
+  Remove when design system is mature and component library covers 90%+
+  of recurring patterns — kit becomes overhead, not leverage.
+---
+
+# Web Designer Kit
+
+## Purpose
+Chain design skills into a phased workflow for building production websites.
+From design system initialization through component construction to
+accessibility audit and final lint.
+
+## Skills Chain
+
+| # | Phase | Skills | What It Provides |
+|---|-------|--------|-----------------|
+| 1 | Design System Init | UI/UX Pro Max, Design System Patterns | Style direction, palette, typography, 3-tier token hierarchy |
+| 2 | Component Build | frontend-design, shadcn-ui, 21st.dev MCP | Responsive grid, component primitives, production marketplace |
+| 3 | Audit | web-accessibility, UI Skills (baseline + motion) | WCAG compliance, ARIA, visual polish, animation performance |
+| 4 | Final Lint | web-design-guidelines | Production design standards audit |
+
+## Workflow Integration
+
+This kit operates WITHIN the universal base workflow:
+- **GSD** structures the work (discuss → plan → execute → verify)
+- **Superpowers** enforces TDD and code review during execution
+- **This kit** adds domain-specific design rules and skill chain
+
+The skills chain is a SEQUENCE, not a replacement for GSD phases.
+Use GSD to plan which phase to work on, then execute within that phase
+using the kit's skills.
+
+## Ralph Integration
+
+To persist this kit across Ralph iterations, add to project `CLAUDE.md`:
+
+```markdown
+## Active kit
+On session start, activate: /kit:web-designer
+```
+
+Each Ralph iteration reads project CLAUDE.md and activates the kit automatically.
+The `/kit` command is idempotent — double-activation is a no-op.
+
+## Prerequisites
+
+Run `install.sh` in this directory to install all required npm skills and MCP servers.
+Verify with `/kit:web-designer` after install.
+
+## MCP Servers
+
+| Server | Purpose | Registration |
+|--------|---------|-------------|
+| 21st-magic | Production component marketplace | `claude mcp add 21st-magic npx -- -y @21st-dev/magic@latest` |
+
+MCP servers persist globally once registered. Kit deactivation does not unregister them.

package/kits/web-designer/commands/web-audit.md

@@ -0,0 +1,67 @@
+---
+description: Run accessibility and design system compliance audit. Use to verify components meet WCAG standards and follow design token conventions. Optionally scope to a specific directory.
+---
+
+You are auditing design system compliance and accessibility.
+
+**Step 1 — Determine scope**
+If argument provided (e.g., `/web:audit src/components/Button`): audit that path only.
+If no argument: audit all component directories.
+
+**Step 2 — Token compliance**
+```bash
+# Find hardcoded colors in components
+grep -rn "color:" src/components/ | grep -v "var(--" | grep -v "token" | grep -v "tailwind"
+
+# Find hardcoded spacing
+grep -rn "margin:\|padding:" src/components/ | grep -rn "[0-9]px" | grep -v "var(--"
+```
+
+**Step 3 — Semantic HTML**
+```bash
+# Div click handlers
+grep -rn 'onClick.*<div' src/components/
+
+# Images without alt
+grep -rn '<img' src/components/ | grep -v 'alt='
+
+# Inputs without labels
+grep -rn '<input' src/components/ | grep -v 'aria-label' | grep -v 'id=.*label'
+```
+
+**Step 4 — Accessibility (if tools available)**
+```bash
+# axe-core (if installed)
+npx axe-core src/ --exit 2>/dev/null || echo "axe-core not installed — manual review needed"
+```
+
+**Step 5 — Motion and performance**
+```bash
+# Animations without reduced-motion check
+grep -rn '@keyframes\|animation:' src/components/ | head -20
+grep -rn 'prefers-reduced-motion' src/components/ | head -20
+# Compare counts — every animation file should have a motion query
+
+# Images without dimensions (CLS risk)
+grep -rn '<img' src/components/ | grep -v 'width' | grep -v 'height'
+```
+
+**Step 6 — Report**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  WEB AUDIT — {scope}  ({today_date})
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Token compliance:    {pass/fail count}
+  Semantic HTML:       {pass/fail count}
+  Accessibility:       {pass/fail count}
+  Motion/performance:  {pass/fail count}
+
+  BLOCKING ({n})
+  ✗ {finding}
+
+  WARNINGS ({n})
+  ⚠ {finding}
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```

package/kits/web-designer/commands/web-component.md

@@ -0,0 +1,54 @@
+---
+description: Full component lifecycle — scaffold, build, test, audit. Use when creating a new UI component. Follows the web-designer kit skills chain.
+---
+
+You are building a component using the web-designer skills chain.
+
+**Step 1 — Component spec**
+Ask in a single message:
+- Component name (PascalCase)
+- Purpose (one sentence)
+- Variants needed (e.g., primary/secondary/ghost)
+- Interactive? (hover, click, keyboard)
+- Where does it live? (shared `ui/` or page-specific)
+
+**Step 2 — Scaffold**
+Create component directory:
+```
+src/components/{location}/{ComponentName}/
+  index.tsx          ← Main component
+  {ComponentName}.test.tsx  ← Tests
+  {ComponentName}.stories.tsx  ← Storybook (if project uses it)
+```
+
+**Step 3 — Build (skills chain phase 2)**
+Implement following these rules:
+- Use design tokens from `design-system/tokens/` — no hardcoded values
+- Use semantic HTML elements — no div click handlers
+- Include keyboard handling for all interactive elements
+- Include `aria-label` or associated `<label>` for form elements
+- Use existing component primitives (shadcn/ui) where applicable
+- Check 21st.dev MCP for production-ready implementations before building from scratch
+
+**Step 4 — Test**
+Write tests covering:
+- Renders without errors
+- Each variant renders correctly
+- Interactive states work (click, keyboard)
+- Accessibility: semantic structure, aria attributes
+
+**Step 5 — Audit (skills chain phase 3)**
+Run accessibility and design compliance checks:
+- Token compliance: no hardcoded colors
+- Semantic HTML: no div handlers
+- WCAG: color contrast, keyboard nav
+- Motion: respects prefers-reduced-motion
+
+**Step 6 — Report**
+```
+✓ Component: {ComponentName}
+  Files:    {list created files}
+  Variants: {list}
+  Tests:    {pass/fail count}
+  Audit:    {pass/fail with details}
+```

package/kits/web-designer/commands/web-init.md

@@ -0,0 +1,42 @@
+---
+description: Bootstrap a design system for the current project. Creates token files, theme config, and base component structure. Use at the start of any new web project.
+---
+
+You are bootstrapping a design system for the current project.
+
+**Step 1 — Assess current state**
+- Check if `design-system/` or equivalent already exists
+- Check if Tailwind config exists (`tailwind.config.*`)
+- Check if any CSS variables or tokens are already defined
+- If design system exists: report what's there and ask what to update
+
+**Step 2 — Gather design direction**
+Ask in a single message:
+- Brand colors (primary, secondary, accent) — or "suggest based on project type"
+- Typography preference (serif, sans-serif, mono, or specific fonts)
+- Design aesthetic (minimal, bold, editorial, playful, corporate)
+- Dark mode support needed? [Y/n]
+
+**Step 3 — Create token hierarchy**
+Create 3-tier token structure:
+1. **Primitive tokens** — raw values (`--color-blue-500: #3B82F6`)
+2. **Semantic tokens** — meaning (`--color-primary: var(--color-blue-500)`)
+3. **Component tokens** — usage (`--button-bg: var(--color-primary)`)
+
+Write to `design-system/tokens/` (or project-appropriate location).
+
+**Step 4 — Create base components**
+Scaffold these if they don't exist:
+- Button (primary, secondary, ghost variants)
+- Input (text, with label and error state)
+- Card (with header, body, footer slots)
+- Typography (h1-h6, body, caption)
+
+**Step 5 — Report**
+```
+✓ Design system initialized
+  Tokens:     {path}/tokens/
+  Components: {path}/components/
+  Theme:      {tailwind.config or css vars file}
+  Dark mode:  {enabled/disabled}
+```

package/kits/web-designer/commands/web-tokens-sync.md

@@ -0,0 +1,49 @@
+---
+description: Validate the token pipeline — ensure design tokens flow correctly from definition through to component usage. Catches orphan tokens, missing references, and broken chains.
+---
+
+You are validating the design token pipeline.
+
+**Step 1 — Locate token definitions**
+Find token files:
+```bash
+find . -path "*/tokens/*" -o -path "*/design-system/*" | grep -E "\.(css|ts|js|json)$"
+```
+Also check: `tailwind.config.*` for theme extensions.
+
+**Step 2 — Extract defined tokens**
+Parse all token files. Build a list of defined token names:
+- CSS custom properties (`--token-name`)
+- Tailwind theme keys
+- JS/TS token exports
+
+**Step 3 — Find token usage in components**
+```bash
+# CSS var references
+grep -rn "var(--" src/components/ | sed 's/.*var(--/--/' | sed 's/).*//' | sort -u
+
+# Tailwind class usage (approximate — look for theme-derived classes)
+grep -rn "className" src/components/ | grep -oE "[a-z]+-[a-z]+-[0-9]+" | sort -u
+```
+
+**Step 4 — Cross-reference**
+- **Orphan tokens**: Defined but never used in any component → WARN
+- **Missing tokens**: Referenced in components but not defined → BLOCK
+- **Broken chain**: Semantic token references a primitive that doesn't exist → BLOCK
+- **Shadow values**: Component uses a raw value that has a token equivalent → WARN
+
+**Step 5 — Report**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  TOKEN SYNC — {today_date}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Defined tokens:   {count}
+  Used tokens:      {count}
+  Orphan tokens:    {count}  (defined, never used)
+  Missing tokens:   {count}  (used, never defined) — BLOCKING
+  Shadow values:    {count}  (raw value has token equivalent)
+
+  {details for each finding}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```

package/kits/web-designer/install.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+set -euo pipefail
+
+echo "=== Praxis: Installing web-designer kit ==="
+echo ""
+
+# Skills
+echo "Installing npm skills..."
+
+SKILLS=(
+  "nextlevelbuilder/ui-ux-pro-max-skill@ui-ux-pro-max"
+  "shadcn-ui/ui@skills"
+  "web-accessibility"
+  "ibelick/ui-skills"
+  "vercel/web-design-guidelines"
+)
+
+for skill in "${SKILLS[@]}"; do
+  echo "  Installing $skill..."
+  if npx skills add "$skill" -g -y 2>/dev/null; then
+    echo "  ✓ $skill"
+  else
+    echo "  ⚠ $skill failed — install manually: npx skills add $skill -g -y"
+  fi
+done
+
+echo ""
+
+# MCP Servers
+echo "Registering MCP servers..."
+if claude mcp add 21st-magic npx -- -y @21st-dev/magic@latest 2>/dev/null; then
+  echo "  ✓ 21st-magic MCP server registered"
+else
+  echo "  ⚠ 21st-magic registration failed — run manually:"
+  echo "    claude mcp add 21st-magic npx -- -y @21st-dev/magic@latest"
+fi
+
+echo ""
+echo "=== web-designer kit installed ==="
+echo "Activate with: /kit:web-designer"
+echo ""

package/kits/web-designer/rules/web-design.md

@@ -0,0 +1,79 @@
+---
+paths:
+  - "*.tsx"
+  - "*.jsx"
+  - "*.vue"
+  - "*.css"
+  - "*.scss"
+  - "src/components/**"
+  - "design-system/**"
+  - "styles/**"
+---
+# Web Design — Rules
+# Scope: Frontend component and design system files
+# Part of: web-designer AI-Kit
+
+## Invariants (BLOCK on violation)
+
+### Design Tokens
+- No inline styles in component files — use design tokens or Tailwind utilities.
+- No hardcoded color values (`#fff`, `rgb(...)`) — must reference token variables
+  (`var(--color-primary)`, Tailwind classes, or theme values).
+- Check: `grep -rn "color:" src/components/ | grep -v "var(--" | grep -v "tailwind"`
+
+### Semantic HTML
+- No `<div>` click handlers — use `<button>` for actions, `<a>` for navigation.
+- Check: `grep -rn 'onClick.*<div' src/components/`
+- Every interactive element must have explicit keyboard handling (`onKeyDown` or
+  native keyboard support via semantic elements).
+
+### Accessibility
+- Every `<img>` must have an `alt` attribute (empty `alt=""` for decorative images).
+- Form inputs must have associated `<label>` elements or `aria-label`.
+- Color contrast must meet WCAG AA minimum (4.5:1 for text, 3:1 for large text).
+
+## Conventions (WARN on violation)
+
+### Component Structure
+- Component files follow `ComponentName/index.tsx` + `ComponentName.module.css`
+  (or `ComponentName.tsx` with Tailwind — pick one pattern per project, don't mix).
+- Design tokens live in `design-system/tokens/` or equivalent.
+- Shared components live in `src/components/ui/` — page-specific components
+  live in `src/components/[page-name]/`.
+
+### Animation and Motion
+- Animation durations use token values, not magic numbers.
+- Respect `prefers-reduced-motion` — wrap animations in media query.
+- CSS transitions preferred over JS animation libraries for simple effects.
+
+### Performance
+- Images have explicit `width` and `height` to prevent CLS (Cumulative Layout Shift).
+- Lazy-load images below the fold (`loading="lazy"`).
+- No layout-triggering CSS in animation loops (`top`, `left`, `width`, `height` — use `transform` and `opacity`).
+
+### Design System Hygiene
+- New components must use existing tokens before creating new ones.
+- If a new token is needed: add to the token file, not inline.
+- Component variants use a consistent API pattern (props, not className overrides).
+
+## Verification Commands
+```bash
+# Token compliance — find hardcoded colors
+grep -rn "color:" src/components/ | grep -v "var(--" | grep -v "token" | grep -v "tailwind"
+
+# Semantic HTML — find div click handlers
+grep -rn 'onClick.*<div' src/components/
+
+# Accessibility — find images without alt
+grep -rn '<img' src/components/ | grep -v 'alt='
+
+# CLS prevention — find images without dimensions
+grep -rn '<img' src/components/ | grep -v 'width' | grep -v 'height'
+
+# Accessibility audit (if axe-core installed)
+npx axe-core src/ --exit
+```
+
+## Removal Condition
+Remove when the project's design system is mature with >90% component coverage
+and design review is handled by a dedicated design tool or CI pipeline.

package/kits/web-designer/teardown.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+set -euo pipefail
+
+echo "=== Praxis: Removing web-designer kit dependencies ==="
+echo ""
+echo "Note: This removes npm skills. MCP servers persist globally"
+echo "and must be removed manually via: claude mcp remove 21st-magic"
+echo ""
+
+SKILLS=(
+  "nextlevelbuilder/ui-ux-pro-max-skill@ui-ux-pro-max"
+  "shadcn-ui/ui@skills"
+  "web-accessibility"
+  "ibelick/ui-skills"
+  "vercel/web-design-guidelines"
+)
+
+for skill in "${SKILLS[@]}"; do
+  echo "  Removing $skill..."
+  npx skills remove "$skill" -g 2>/dev/null || echo "  ⚠ $skill not found or already removed"
+done
+
+echo ""
+echo "=== web-designer kit dependencies removed ==="
+echo "To also remove MCP server: claude mcp remove 21st-magic"
+echo ""

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@esoteric-logic/praxis-harness",
+  "version": "1.1.0",
+  "description": "Layered Claude Code harness — workflow discipline, AI-Kits, persistent vault integration",
+  "bin": {
+    "praxis-harness": "./bin/praxis.js"
+  },
+  "files": [
+    "bin/",
+    "base/",
+    "kits/",
+    "templates/",
+    "scripts/"
+  ],
+  "scripts": {
+    "test": "node --check bin/praxis.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/arcanesme/praxis.git"
+  },
+  "keywords": ["claude-code", "ai-harness", "vault", "obsidian", "logseq", "workflow", "gsd"],
+  "author": "arcanesme",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}