@harness-engineering/cli 1.14.0 → 1.16.0

package/dist/agents/skills/cursor/harness-deployment/SKILL.md

@@ -0,0 +1,307 @@
+# Harness Deployment
+
+> CI/CD pipeline analysis, deployment strategy design, and environment management. From commit to production with confidence.
+
+## When to Use
+
+- When setting up or reviewing CI/CD pipelines for a new or existing project
+- When evaluating deployment strategies (blue-green, canary, rolling) for a service
+- When auditing environment separation and promotion workflows
+- NOT for container image building or registry management (use harness-containerization)
+- NOT for infrastructure provisioning (use harness-infrastructure-as-code)
+- NOT for application performance under load (use harness-perf)
+
+## Process
+
+### Phase 1: DETECT -- Identify Pipeline and Environment Configuration
+
+1. **Scan for CI/CD configuration files.** Search the project root for pipeline definitions:
+   - `.github/workflows/*.yml` -- GitHub Actions
+   - `.gitlab-ci.yml` -- GitLab CI
+   - `Jenkinsfile` -- Jenkins
+   - `.circleci/config.yml` -- CircleCI
+   - `bitbucket-pipelines.yml` -- Bitbucket Pipelines
+   - `azure-pipelines.yml` -- Azure DevOps
+   - `deploy/`, `scripts/deploy*` -- custom deployment scripts
+
+2. **Identify deployment targets.** Parse pipeline files for deployment steps and extract:
+   - Target environments (dev, staging, production)
+   - Deployment mechanisms (kubectl apply, aws ecs update-service, serverless deploy, rsync)
+   - Cloud provider and region information
+   - Container registry references
+
+3. **Detect environment configuration.** Look for environment-specific config:
+   - `.env.production`, `.env.staging` files
+   - Environment variable injection in pipeline definitions
+   - Secret references (GitHub Secrets, GitLab CI variables, Vault paths)
+   - Feature flag provider configuration per environment
+
+4. **Map the deployment topology.** Build a summary of what gets deployed where:
+   - Service name, pipeline file, target environment, deployment mechanism
+   - Dependencies between services (deploy order constraints)
+   - Manual approval gates vs. automatic promotion
+
+5. **Present detection summary.** Output the discovered topology before proceeding:
+
+   ```
+   Deployment Topology:
+     Platform: GitHub Actions
+     Pipelines: 3 workflow files
+     Environments: dev, staging, production
+     Strategy: Rolling (detected from kubectl rolling-update)
+     Approval gates: production (manual)
+   ```
+
+---
+
+### Phase 2: ANALYZE -- Evaluate Pipeline Quality and Gaps
+
+1. **Check pipeline stage completeness.** A mature pipeline includes these stages. Flag any that are missing:
+   - Build and compile
+   - Unit tests
+   - Integration tests
+   - Security scan (SAST/DAST)
+   - Artifact packaging
+   - Deploy to staging
+   - Smoke tests post-deploy
+   - Deploy to production
+   - Post-deploy verification
+
+2. **Evaluate environment isolation.** Verify that environments are properly separated:
+   - Staging and production use different credentials
+   - Environment-specific variables are not shared across environments
+   - Database connections point to the correct environment
+   - No hardcoded production URLs in non-production configs
+
+3. **Check deployment safety mechanisms.** Verify the pipeline includes:
+   - Rollback procedures (automatic or documented manual)
+   - Health checks after deployment
+   - Timeout configuration on deployment steps
+   - Concurrency controls (prevent parallel deploys to the same environment)
+   - Branch protection rules that gate production deploys
+
+4. **Analyze pipeline performance.** Identify bottlenecks:
+   - Steps that could run in parallel but are sequential
+   - Missing caching (dependencies, build artifacts, Docker layers)
+   - Redundant steps across workflows
+   - Total pipeline duration from commit to production
+
+5. **Check secret hygiene in pipelines.** Verify:
+   - No secrets hardcoded in pipeline files
+   - Secrets are scoped to the minimum required environment
+   - Secret rotation is possible without pipeline changes
+   - OIDC or workload identity is used where available instead of long-lived credentials
+
+---
+
+### Phase 3: DESIGN -- Recommend Strategy Improvements
+
+1. **Recommend deployment strategy.** Based on the service characteristics:
+   - **Rolling** -- suitable for stateless services with backward-compatible changes
+   - **Blue-green** -- suitable when zero-downtime cutover is required and rollback must be instant
+   - **Canary** -- suitable for high-traffic services where gradual validation reduces blast radius
+   - **Recreate** -- suitable only for development environments or when downtime is acceptable
+
+2. **Design missing pipeline stages.** For each gap identified in Phase 2, provide:
+   - The stage definition in the project's CI/CD platform syntax
+   - Where it fits in the pipeline order
+   - What tools or services it requires
+   - Example configuration snippet
+
+3. **Recommend environment promotion workflow.** Design the path from commit to production:
+   - Automatic promotion from dev to staging after tests pass
+   - Manual approval gate before production (with notification to the team channel)
+   - Smoke test suite that runs post-deploy in each environment
+   - Rollback trigger conditions (error rate spike, health check failure)
+
+4. **Design rollback procedure.** Every deployment must have a documented rollback:
+   - For container deployments: revert to previous image tag
+   - For serverless: revert to previous function version
+   - For database migrations: backward-compatible migration strategy
+   - Maximum rollback time target (e.g., under 5 minutes)
+
+5. **Recommend monitoring integration.** Connect deployment events to observability:
+   - Deploy markers in APM tools (Datadog, New Relic, Grafana)
+   - Automated alerts on error rate increase after deploy
+   - Deployment frequency and lead time tracking
+
+---
+
+### Phase 4: VALIDATE -- Verify Pipeline Correctness
+
+1. **Lint pipeline configuration.** Run syntax validation:
+   - GitHub Actions: `actionlint` or YAML schema validation
+   - GitLab CI: `gitlab-ci-lint` API endpoint
+   - Jenkinsfile: Groovy syntax check
+   - General: YAML structure validation for all config files
+
+2. **Verify environment variable completeness.** For each environment:
+   - All required variables are defined
+   - No placeholder values remain (TODO, CHANGEME, xxx)
+   - Variables referenced in code exist in the pipeline configuration
+
+3. **Verify branch protection alignment.** Confirm that:
+   - Production deploy pipelines only trigger from protected branches
+   - Required status checks match the pipeline stages
+   - Force-push is disabled on deployment branches
+
+4. **Generate deployment readiness report.** Summarize findings:
+
+   ```
+   Deployment Readiness: [PASS/WARN/FAIL]
+
+   Pipeline stages: 7/9 present (missing: security scan, smoke tests)
+   Environment isolation: PASS
+   Rollback procedure: WARN (documented but not automated)
+   Secret hygiene: PASS
+   Pipeline performance: 12m avg (recommend parallelizing test stages)
+
+   Recommendations:
+     1. Add SAST scan stage between build and deploy
+     2. Add post-deploy smoke test stage
+     3. Automate rollback on health check failure
+   ```
+
+5. **Present results.** Use `emit_interaction` to deliver the report and ask whether to proceed with implementing recommendations.
+
+---
+
+## Harness Integration
+
+- **`harness skill run harness-deployment`** -- Primary invocation for deployment analysis.
+- **`harness validate`** -- Run after any pipeline configuration changes to verify project health.
+- **`harness check-deps`** -- Verify deployment script dependencies are available.
+- **`emit_interaction`** -- Present deployment readiness report and gather decisions on strategy.
+
+## Success Criteria
+
+- All CI/CD configuration files in the project are identified and cataloged
+- Pipeline stage completeness is assessed against the standard checklist
+- Environment isolation is verified with no cross-environment credential leakage
+- A deployment strategy recommendation is provided with rationale
+- Rollback procedures are documented or flagged as missing
+- Pipeline lint passes without errors
+
+## Examples
+
+### Example: Node.js API with GitHub Actions
+
+```
+Phase 1: DETECT
+  Found: .github/workflows/ci.yml, .github/workflows/deploy.yml
+  Environments: staging (auto), production (manual dispatch)
+  Strategy: Rolling (kubectl set image)
+  Registry: ghcr.io/org/api-server
+
+Phase 2: ANALYZE
+  Missing stages: security scan, post-deploy smoke tests
+  Environment isolation: PASS
+  Secret hygiene: WARN -- AWS_ACCESS_KEY_ID used instead of OIDC
+  Pipeline duration: 18m (test and lint run sequentially)
+
+Phase 3: DESIGN
+  Recommendation: Add trivy scan after Docker build
+  Recommendation: Switch to AWS OIDC for keyless authentication
+  Recommendation: Parallelize lint and test jobs (saves ~4m)
+  Recommendation: Add smoke test job after deploy-staging
+
+Phase 4: VALIDATE
+  actionlint: PASS
+  Environment variables: PASS
+  Branch protection: WARN -- main branch allows force-push
+  Result: WARN -- 3 recommendations, 1 security improvement needed
+```
+
+### Example: Python Service with GitLab CI and Canary Deploy
+
+```
+Phase 1: DETECT
+  Found: .gitlab-ci.yml with 5 stages
+  Environments: dev, staging, production
+  Strategy: Canary (Istio VirtualService weight shifting)
+  Registry: registry.gitlab.com/org/service
+
+Phase 2: ANALYZE
+  All 9 standard stages present
+  Environment isolation: PASS
+  Canary configuration: 5% -> 25% -> 75% -> 100% over 30 minutes
+  Rollback: Automatic on 5xx rate > 1%
+
+Phase 3: DESIGN
+  Current strategy is well-configured. Minor recommendations:
+  - Add canary duration metrics to Grafana dashboard
+  - Add deployment event annotation to Prometheus
+  - Consider adding a manual gate between 75% and 100%
+
+Phase 4: VALIDATE
+  GitLab CI lint: PASS
+  Environment variables: PASS
+  Branch protection: PASS
+  Result: PASS -- pipeline is production-ready
+```
+
+## Gates
+
+- **No production deploy without staging validation.** If the pipeline allows direct-to-production deployment without a prior staging step, flag as a blocking issue.
+- **No long-lived credentials in pipelines.** Hardcoded secrets or long-lived access keys in pipeline files are blocking findings. OIDC or short-lived tokens must be used.
+- **No deploy without rollback.** Every deployment target must have a documented or automated rollback mechanism. Missing rollback is a blocking warning.
+- **No skipping pipeline lint.** Pipeline configuration must pass syntax validation before recommendations are made.
+
+## Evidence Requirements
+
+When this skill makes claims about existing code, architecture, or behavior,
+it MUST cite evidence using one of:
+
+1. **File reference:** `file:line` format (e.g., `src/auth.ts:42`)
+2. **Code pattern reference:** `file` with description (e.g., `src/utils/hash.ts` —
+   "existing bcrypt wrapper")
+3. **Test/command output:** Inline or referenced output from a test run or CLI command
+4. **Session evidence:** Write to the `evidence` session section via `manage_state`
+
+**Uncited claims:** Technical assertions without citations MUST be prefixed with
+`[UNVERIFIED]`. Example: `[UNVERIFIED] The auth middleware supports refresh tokens`.
+
+## Red Flags
+
+### Universal
+
+These apply to ALL skills. If you catch yourself doing any of these, STOP.
+
+- **"I believe the codebase does X"** — Stop. Read the code and cite a file:line
+  reference. Belief is not evidence.
+- **"Let me recommend [pattern] for this"** without checking existing patterns — Stop.
+  Search the codebase first. The project may already have a convention.
+- **"While we're here, we should also [unrelated improvement]"** — Stop. Flag the idea
+  but do not expand scope beyond the stated task.
+
+### Domain-Specific
+
+- **"Deploying without a health check endpoint"** — Stop. Without health checks, the orchestrator cannot detect failed deployments. Add health checks before deploying.
+- **"Skipping canary deployment, it's a small change"** — Stop. Small changes cause outages too. Follow the deployment policy regardless of change size.
+- **"Rolling back manually if something goes wrong"** — Stop. Manual rollback under incident pressure fails. Automate rollback before deploying.
+- **"We can update the runbook after the deploy"** — Stop. If the deployment changes operational behavior, update the runbook first. Stale runbooks during incidents cause escalations.
+
+## Rationalizations to Reject
+
+### Universal
+
+These reasoning patterns sound plausible but lead to bad outcomes. Reject them.
+
+- **"It's probably fine"** — "Probably" is not evidence. Verify before asserting.
+- **"This is best practice"** — Best practice in what context? Cite the source and
+  confirm it applies to this codebase.
+- **"We can fix it later"** — If it is worth flagging, it is worth documenting now
+  with a concrete follow-up plan.
+
+### Domain-Specific
+
+- **"It's just a config change, not a code change"** — Config changes cause outages at the same rate as code changes. Deploy them with the same rigor and rollback strategy.
+- **"We tested this in staging"** — Staging is not production. Traffic patterns, data volume, and edge cases differ. Staging success does not guarantee production safety.
+- **"Downtime will be brief"** — Brief is not zero. Quantify the expected impact and communicate it to stakeholders before deploying.
+
+## Escalation
+
+- **When the CI/CD platform is unsupported:** Report which platform was detected and that analysis is limited to general best practices. Recommend the user provide platform-specific documentation for deeper analysis.
+- **When secrets are found hardcoded in pipeline files:** Immediately flag as a critical finding. Do not proceed with strategy recommendations until secrets are remediated. Recommend rotating the exposed credentials.
+- **When multiple deployment strategies are mixed across environments:** This is valid (e.g., rolling for staging, canary for production). Analyze each independently and verify the promotion workflow handles the strategy transition.
+- **When pipeline configuration is generated by a tool (Terraform, Pulumi):** Analyze the generated output but note that fixes must be applied to the generator configuration, not the output files.

package/dist/agents/skills/cursor/harness-deployment/skill.yaml

@@ -0,0 +1,77 @@
+name: harness-deployment
+version: "1.0.0"
+description: CI/CD pipelines, blue-green, canary, and environment management
+cognitive_mode: advisory-guide
+tier: 3
+internal: false
+keywords:
+  - deployment
+  - CI/CD
+  - pipeline
+  - GitHub Actions
+  - GitLab CI
+  - Jenkins
+  - blue-green
+  - canary
+  - rolling
+  - environment
+  - staging
+  - production
+  - CD
+stack_signals:
+  - ".github/workflows/"
+  - ".gitlab-ci.yml"
+  - "Jenkinsfile"
+  - "deploy/"
+  - "infrastructure/"
+  - ".circleci/"
+  - "bitbucket-pipelines.yml"
+triggers:
+  - manual
+  - on_new_feature
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - emit_interaction
+cli:
+  command: harness skill run harness-deployment
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: strategy
+      description: Deployment strategy to evaluate (blue-green, canary, rolling)
+      required: false
+    - name: platform
+      description: Target CI/CD platform (github-actions, gitlab-ci, jenkins)
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-deployment
+    path: string
+type: rigid
+phases:
+  - name: detect
+    description: Identify existing CI/CD configuration and deployment targets
+    required: true
+  - name: analyze
+    description: Evaluate pipeline structure, stages, and environment separation
+    required: true
+  - name: design
+    description: Recommend deployment strategy improvements and missing stages
+    required: true
+  - name: validate
+    description: Verify pipeline correctness and environment isolation
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/harness-design/SKILL.md

@@ -0,0 +1,265 @@
+# Harness Design
+
+> Aesthetic direction workflow. Capture design intent, generate DESIGN.md with anti-patterns and platform notes, review components against aesthetic guidelines, and enforce design constraints at configurable strictness levels.
+
+## When to Use
+
+- Establishing aesthetic direction for a new or existing project (style, tone, differentiator)
+- When `on_new_feature` triggers fire and the feature has design scope requiring aesthetic guidance
+- Reviewing existing components against declared design intent and anti-patterns
+- Enforcing design constraints via the knowledge graph with configurable strictness
+- Generating or updating `design-system/DESIGN.md` with aesthetic direction, anti-patterns, and platform notes
+- NOT for design token generation or palette selection (use harness-design-system)
+- NOT for accessibility auditing or WCAG compliance (use harness-accessibility)
+- NOT for platform-specific token implementation into CSS/Tailwind/etc. (use harness-design-web/mobile, Phase 5)
+
+## Process
+
+### Phase 1: INTENT -- Capture Aesthetic Intent
+
+1. **Read existing design artifacts.** Search for:
+   - `design-system/DESIGN.md` -- existing aesthetic direction documentation (from harness-design-system output)
+   - `design-system/tokens.json` -- existing W3C DTCG tokens (palette, typography, spacing defined by harness-design-system)
+   - `harness.config.json` -- project configuration for design settings
+
+2. **Check harness configuration.** Read `harness.config.json` for:
+   - `design.strictness` -- enforcement level (`strict`, `standard`, `permissive`). If not set, default to `standard`.
+   - `design.platforms` -- which platforms are enabled (web, mobile)
+   - `design.aestheticIntent` -- path to design intent doc (default: `design-system/DESIGN.md`)
+
+3. **Load industry profile.** If an industry is specified (via CLI `--industry` arg or config), read the industry profile from `agents/skills/shared/design-knowledge/industries/{industry}.yaml`. Available industries include: `saas`, `fintech`, `healthcare`, `ecommerce`, `creative`, `emerging-tech`, `lifestyle`, `services`. The profile provides sector-specific guidance on:
+   - Recommended visual style and tone
+   - Industry conventions and user expectations
+   - Regulatory or cultural considerations
+   - Common anti-patterns for the sector
+
+4. **Capture user intent.** Ask the user to define:
+   - **Style:** minimal, expressive, corporate, playful, editorial, or custom
+   - **Tone:** warm, cool, neutral, bold, muted, or custom
+   - **Key differentiator:** what makes this product's visual identity unique
+   - **Anti-patterns:** specific design choices to explicitly avoid (e.g., "no gradients on data elements," "no decorative borders on cards")
+
+5. **Load shared design knowledge.** Read anti-pattern awareness from `agents/skills/shared/design-knowledge/`:
+   - `palettes/curated.yaml` -- curated palettes to understand which aesthetic families are available
+   - `typography/pairings.yaml` -- typography pairings to understand which font combinations are recommended
+   - Industry-specific anti-pattern guidance from the loaded industry profile
+
+6. **Confirm intent before proceeding.** Present a summary of the captured aesthetic intent to the user. This is a hard gate -- no DESIGN.md generation without the user confirming their aesthetic intent.
+
+### Phase 2: DIRECTION -- Generate DESIGN.md
+
+1. **Generate or update `design-system/DESIGN.md`.** The document must contain the following sections:
+
+   **Aesthetic Direction:**
+   - Style declaration (the chosen style and what it means for this project)
+   - Tone description (how the tone manifests in color usage, typography weight, spacing density)
+   - Key differentiator (the unique visual identity aspect and how it is expressed)
+
+   **Anti-Patterns:**
+   - Project-specific anti-patterns (from user input in Phase 1)
+   - Industry-informed anti-patterns (from the loaded industry profile)
+   - Each anti-pattern includes: name, description, example of what NOT to do, and why it conflicts with the declared intent
+
+   **Platform Notes:**
+   - Web-specific guidance (CSS strategy, responsive behavior, animation preferences)
+   - Mobile-specific guidance (touch targets, native component usage, platform conventions)
+   - Cross-platform consistency rules (which elements must be identical vs. platform-adapted)
+
+   **Strictness Override:**
+   - Current `designStrictness` level and what it means
+   - Instructions for changing strictness in `harness.config.json`
+   - Behavior differences per level:
+     - `permissive` -- all design violations reported as `info` (nothing blocks)
+     - `standard` -- anti-pattern and accessibility violations are `warn`, critical violations are `error` (default)
+     - `strict` -- accessibility violations are `error` (blocks CI/PR merge), anti-pattern violations are `warn`
+
+2. **Populate the knowledge graph.** If a graph exists at `.harness/graph/`:
+   - Create an `AestheticIntent` node with properties: style, tone, differentiator, strictness level. Use `DesignIngestor` from `packages/graph/src/ingest/DesignIngestor.ts` for graph ingestion.
+   - Create a `DECLARES_INTENT` edge from the project node to the `AestheticIntent` node.
+   - This enables downstream skills (harness-accessibility, harness-impact-analysis) to query the declared design intent.
+
+3. **Run harness validate.** After generating DESIGN.md, verify the project still passes all constraints. The new file must not break existing validations.
+
+### Phase 3: REVIEW -- Review Components Against Design Intent
+
+1. **Scan for anti-pattern violations.** Use Grep to search the codebase for patterns that match declared anti-patterns:
+   - Hardcoded color values not present in `design-system/tokens.json` (suggests off-brand color usage)
+   - Font families flagged as anti-patterns in the design intent (e.g., decorative fonts in a minimal project)
+   - Layout patterns on the forbidden list (e.g., excessive drop shadows in a flat design, gradients on data elements)
+   - CSS properties or values that contradict the declared style (e.g., rounded corners in a sharp-edge design)
+
+2. **Load detection rules from shared design knowledge.** Read from `agents/skills/shared/design-knowledge/`:
+   - `anti-patterns/typography.yaml` — font combinations, size, weight, and line-height issues that clash with the declared style
+   - `anti-patterns/color.yaml` — hardcoded colors, insufficient contrast, color-only indicators that undermine the declared tone
+   - `anti-patterns/layout.yaml` — spacing inconsistencies, missing touch targets, fixed-width containers
+   - `anti-patterns/motion.yaml` — missing prefers-reduced-motion, long animations, scroll-jacking
+   - `industries/{industry}.yaml` — industry-specific rules from the loaded industry profile
+
+3. **Cross-reference with graph constraints.** If a graph exists at `.harness/graph/`:
+   - Query for existing `VIOLATES_DESIGN` edges using `DesignConstraintAdapter` from `packages/graph/src/constraints/DesignConstraintAdapter.ts`
+   - Compare current findings against previously recorded violations
+   - Identify new violations and resolved violations
+
+4. **Assign severity based on `designStrictness`:**
+   - `permissive` -- all findings are `info` severity
+   - `standard` -- anti-pattern violations and accessibility-related findings are `warn`, critical design constraint violations are `error`
+   - `strict` -- accessibility violations are `error` (blocks), anti-pattern violations are `warn`
+
+5. **Report findings.** Present each finding with:
+   - File path and line number
+   - Violation description and which anti-pattern or design constraint it violates
+   - Severity level (based on current strictness)
+   - Suggested remediation
+
+### Phase 4: ENFORCE -- Surface and Record Violations
+
+1. **Create constraint nodes in the graph.** For each violated design rule, if a graph exists at `.harness/graph/`:
+   - Create a `DesignConstraint` node for the rule being violated (if one does not already exist)
+   - Create a `VIOLATES_DESIGN` edge from the violating component to the `DesignConstraint` node
+   - Use `DesignConstraintAdapter` from `packages/graph/src/constraints/DesignConstraintAdapter.ts` to manage constraint creation and violation recording
+
+2. **Format violation output.** Each violation follows a numbered format:
+
+   ```
+   DESIGN-001 [warn] Anti-pattern: gradient used on data visualization element
+     File:       src/components/Chart.tsx
+     Line:       42
+     Constraint: No gradients on data elements
+     Intent:     Style "minimal" prohibits decorative effects on informational components
+     Fix:        Replace linear-gradient with solid color from token "neutral.100"
+
+   DESIGN-002 [error] Off-brand color: hardcoded #ff6b35 not in token set
+     File:       src/components/Alert.tsx
+     Line:       18
+     Constraint: All colors must reference design tokens
+     Intent:     Tone "cool" conflicts with warm orange accent
+     Fix:        Use token "semantic.warning" (#f59e0b) or add color to tokens.json via harness-design-system
+
+   DESIGN-003 [info] Typography: decorative font "Playfair Display" used in component
+     File:       src/components/Hero.tsx
+     Line:       8
+     Constraint: Heading font must match declared typography pairing
+     Intent:     Style "minimal" uses Inter for all headings
+     Fix:        Replace with token "typography.heading.fontFamily"
+   ```
+
+3. **Control severity by `designStrictness`:**
+   - `permissive` -- all violations output as `info` (DESIGN-001 [info], DESIGN-002 [info], etc.)
+   - `standard` -- anti-patterns and a11y = `warn`, off-brand tokens = `error` (default)
+   - `strict` -- a11y violations = `error` (blocks CI), anti-patterns = `warn`, off-brand tokens = `error`
+
+4. **Run harness validate.** After recording violations in the graph, run validation to ensure the enforcement pass is consistent with the project state.
+
+## Harness Integration
+
+- **`harness validate`** -- Run after generating DESIGN.md and after enforcement passes. Design violations surface as constraint violations at the configured strictness level.
+- **`harness scan`** -- Run after changes to refresh the knowledge graph. Updated graph enables accurate violation detection and impact analysis.
+- **`DesignIngestor`** (`packages/graph/src/ingest/DesignIngestor.ts`) -- Parses `tokens.json` and `DESIGN.md` to create graph nodes representing the design system. Creates `AestheticIntent` nodes and `DECLARES_INTENT` edges during the DIRECTION phase.
+- **`DesignConstraintAdapter`** (`packages/graph/src/constraints/DesignConstraintAdapter.ts`) -- Manages `DesignConstraint` nodes and `VIOLATES_DESIGN` edges in the graph. Reads `design.strictness` to control violation severity. Used during REVIEW and ENFORCE phases.
+
+**Graph naming convention:** This skill uses PascalCase for node types (`AestheticIntent`, `DesignToken`, `DesignConstraint`) and UPPER_SNAKE for edge types (`DECLARES_INTENT`, `VIOLATES_DESIGN`, `USES_TOKEN`, `PLATFORM_BINDING`) as conceptual labels. The graph schema registers these as snake_case identifiers (`aesthetic_intent`, `design_token`, `design_constraint`, `declares_intent`, `violates_design`, `uses_token`, `platform_binding`). The adapter classes (`DesignIngestor`, `DesignConstraintAdapter`) handle the mapping — always use the adapters rather than constructing graph queries with raw type names.
+
+- **`harness-design-system`** -- Dependency. This skill reads tokens and design intent generated by harness-design-system. Token-level issues (palette changes, new colors) are resolved by running harness-design-system, not this skill.
+- **`harness-impact-analysis`** -- When design tokens change, impact analysis traces which components consume affected tokens. Use this to determine which components need re-review after token updates.
+
+## Success Criteria
+
+- `design-system/DESIGN.md` exists with all required sections: Aesthetic Direction, Anti-Patterns, Platform Notes, Strictness Override
+- Anti-patterns are detected in the codebase and reported with file paths, line numbers, and severity
+- `designStrictness` configuration is read from `harness.config.json` and respected in all severity assignments
+- `AestheticIntent` node created in the knowledge graph with style, tone, differentiator, and strictness properties
+- `DECLARES_INTENT` edge connects the project to the aesthetic intent node
+- `DesignConstraint` nodes created for each violated design rule
+- `VIOLATES_DESIGN` edges connect violating components to their constraint nodes
+- Violations output in numbered format (DESIGN-001, DESIGN-002, etc.) with severity matching strictness level
+- `harness validate` passes after DESIGN.md generation and enforcement
+- User confirmed aesthetic intent before DESIGN.md generation (hard gate)
+
+## Examples
+
+### Example: SaaS Analytics Dashboard Aesthetic Direction
+
+**Context:** A SaaS analytics dashboard project. Industry: `saas`. Design tokens already generated by harness-design-system. No existing DESIGN.md aesthetic direction.
+
+**INTENT capture:**
+
+```
+Industry profile:     Loaded (saas) -- recommends professional, data-focused aesthetic
+Style:                Minimal
+Tone:                 Cool, professional
+Differentiator:       Dense information display with generous whitespace between sections
+Anti-patterns:        No gradients on data elements, no decorative borders on cards,
+                      no more than 2 font weights per component
+Strictness:           standard (from harness.config.json)
+```
+
+**DIRECTION output (DESIGN.md excerpt):**
+
+```markdown
+## Aesthetic Direction
+
+**Style:** Minimal -- clean lines, flat surfaces, no decorative elements that do not serve
+an informational purpose. Every visual element must earn its place by conveying data or
+guiding the user's eye.
+
+**Tone:** Cool, professional -- slate and blue palette dominates. Warm colors reserved
+exclusively for semantic states (warning, error). No warm accents in neutral UI.
+
+**Differentiator:** Dense information display with generous whitespace between sections.
+Components are compact internally but breathe externally. Card padding is tight (12px),
+but gaps between cards are generous (24px+).
+
+## Anti-Patterns
+
+| Pattern                    | Description                                  | Why It Conflicts                           |
+| -------------------------- | -------------------------------------------- | ------------------------------------------ |
+| Gradients on data elements | linear-gradient on charts, tables, cards     | Minimal style: flat surfaces only          |
+| Decorative card borders    | border with color on .card elements          | Minimal style: borders are structural only |
+| Excess font weights        | More than 2 font-weight values per component | Minimal style: typographic restraint       |
+
+## Strictness Override
+
+Current level: **standard**
+
+To change, update `harness.config.json`:
+"design": { "strictness": "strict" | "standard" | "permissive" }
+```
+
+**REVIEW findings:**
+
+```
+Found 3 anti-pattern violations in 2 files:
+
+DESIGN-001 [warn] Gradient on data element
+  File:       src/components/RevenueChart.tsx:42
+  Constraint: No gradients on data elements
+  Fix:        Replace linear-gradient(#3b82f6, #1d4ed8) with solid token "primary.500"
+
+DESIGN-002 [warn] Decorative border on card
+  File:       src/components/MetricCard.tsx:15
+  Constraint: No decorative borders on cards
+  Fix:        Remove border-color: #3b82f6, use border-color: transparent or remove border
+
+DESIGN-003 [info] Three font weights in one component
+  File:       src/components/MetricCard.tsx:8
+  Constraint: Max 2 font weights per component
+  Fix:        Consolidate font-weight values to 400 (body) and 600 (heading) only
+```
+
+## Gates
+
+These are hard stops. Violating any gate means the process has broken down.
+
+- **No DESIGN.md generated without the user confirming aesthetic intent.** The INTENT phase must end with explicit user confirmation of style, tone, differentiator, and anti-patterns. Do not generate based on assumptions.
+- **No enforcement without reading tokens from harness-design-system.** The REVIEW and ENFORCE phases require `design-system/tokens.json` to exist. If tokens have not been generated, instruct the user to run harness-design-system first.
+- **Strictness must be read from configuration, not assumed.** Read `design.strictness` from `harness.config.json`. If the key does not exist, default to `standard` and report the default to the user. Never hardcode a strictness level.
+- **No anti-pattern detection without a declared intent.** The REVIEW phase requires an existing DESIGN.md with declared anti-patterns. If no intent has been captured, run the INTENT and DIRECTION phases first.
+- **No graph mutations without validating node types.** When creating `AestheticIntent`, `DesignConstraint`, or `VIOLATES_DESIGN` edges, verify the node and edge types are registered in the graph schema before writing.
+
+## Escalation
+
+- **When the user cannot articulate a style or tone:** Suggest industry-based defaults from the loaded industry profile. Present 2-3 options with examples: "Based on the saas industry profile, common styles are: (1) Minimal -- clean, data-focused, (2) Corporate -- structured, trustworthy, (3) Expressive -- colorful, engaging. Which resonates most?"
+- **When declared anti-patterns conflict with existing code:** Present a migration path rather than flagging every instance as a violation. Report: "Found 47 instances of gradients on data elements. Recommend a phased migration: (1) Update new components immediately, (2) Schedule legacy component updates over 3 sprints. Set strictness to 'permissive' during migration to avoid blocking CI."
+- **When tokens do not exist yet:** Do not attempt to infer a token set. Instruct the user: "Design tokens have not been generated. Run harness-design-system first to create `design-system/tokens.json`, then re-run harness-design for aesthetic direction."
+- **When strictness level conflicts with team velocity:** Explain the tradeoffs: "Strict mode blocks PRs on any design violation. If this is slowing the team, consider 'standard' mode which blocks only on critical violations (off-brand colors, accessibility) and warns on anti-patterns."
+- **When the knowledge graph is unavailable:** Skip graph operations in DIRECTION and ENFORCE phases. Log: "Graph not available at `.harness/graph/` -- skipping AestheticIntent node creation and violation recording. Run `harness scan` later to populate." Continue with file-based operations.