@harness-engineering/cli 1.14.0 → 1.16.0

package/dist/agents/commands/cursor/harness/harness-security-scan.mdc

@@ -0,0 +1,162 @@
+---
+description: Lightweight mechanical security scan for health checks
+alwaysApply: false
+---
+
+<!-- Generated by harness generate-slash-commands. Do not edit. -->
+
+# Harness Security Scan
+
+> Lightweight mechanical security scan. Fast triage, not deep review.
+
+## When to Use
+
+- As part of the codebase-health-analyst sweep
+- For quick security triage on a project or changed files
+- On scheduled cron runs for continuous security coverage
+- NOT for deep security review (use harness-security-review)
+- NOT for threat modeling (use harness-security-review --deep)
+
+## Process
+
+### Phase 1: SCAN — Run Mechanical Scanner
+
+1. **Resolve project root.** Use provided path or cwd.
+
+2. **Load security config.** Read `harness.config.json` and extract `security`
+   section. Fall back to defaults if absent.
+
+3. **Determine file scope.**
+   - If `--changed-only` or triggered by PR: run `git diff --name-only HEAD~1`
+     to get changed files. Filter to source files only (exclude node_modules,
+     dist, test files per config).
+   - Otherwise: scan all source files in the project.
+
+4. **Run SecurityScanner.** Call `SecurityScanner.scanFiles()` from
+   `@harness-engineering/core`.
+
+5. **Filter by severity threshold.** Remove findings below the configured
+   threshold:
+   - `error`: only errors
+   - `warning`: errors and warnings (default)
+   - `info`: all findings
+
+6. **Output report.** Present findings grouped by severity:
+
+   ```
+   Security Scan: [PASS/FAIL]
+   Scanned: N files, M rules applied
+   Errors: N | Warnings: N | Info: N
+
+   [List findings with rule ID, file:line, severity, message, remediation]
+   ```
+
+## Gates
+
+- **Error-severity findings are blocking.** Report is FAIL if any error-severity
+  finding exists after filtering.
+- **No AI review.** This skill is mechanical only. Do not perform OWASP analysis
+  or threat modeling.
+
+## Harness Integration
+
+- **`harness check-security`** — CLI command that invokes this skill's scanner.
+- **`SecurityScanner`** — Core class from `@harness-engineering/core` that executes the rule engine.
+- **`harness.config.json`** — Security section configures severity threshold and file exclusions.
+- **codebase-health-analyst persona** — Invokes this skill as part of its sweep.
+
+## 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
+
+- **"This finding is in test code, so it's not a real issue"** — Stop. Test code can leak secrets, establish bad patterns, and be copy-pasted to production.
+- **"This dependency is widely used, so it's safe"** — Stop. Popularity is not a security guarantee. Check CVE databases and advisory feeds.
+- **"This is a low-severity finding, skipping"** — Stop. Low-severity findings compound. Document why you are deprioritizing, do not silently skip.
+- **"The scanner didn't flag it, so it's clean"** — Stop. Scanners have false negatives. A clean scan is not proof of security — it is absence of evidence.
+
+## 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
+
+- **"No attacker would find this"** — Security by obscurity. If the code is wrong, flag it regardless of discoverability.
+- **"We're behind a firewall"** — Network boundaries change. Code should be secure at every layer regardless of deployment topology.
+- **"The framework handles this for us"** — Verify the framework's actual behavior. Misuse of a secure framework is still insecure.
+
+## Escalation
+
+- **When error-severity findings are disputed:** The scanner is mechanical — it may flag false positives. If a finding is a false positive, add a `// harness-ignore SEC-XXX` comment on the line and document the rationale. Do not suppress without explanation.
+- **When the scanner misses a known vulnerability:** This skill runs pattern-based rules only. For semantic analysis (taint tracking, control flow), use `/harness:security-review` instead.
+- **When scan is too slow on large codebases:** Use `--changed-only` to scope to recently changed files. Full scans can run on a scheduled cron instead.
+
+## Success Criteria
+
+- Scanner ran and produced findings (or confirmed clean)
+- Findings are filtered by the configured severity threshold
+- Report follows the structured format
+- Exit code reflects pass/fail status
+
+## Examples
+
+### Example: Clean Scan
+
+```
+Security Scan: PASS
+Scanned: 42 files, 12 rules applied
+Errors: 0 | Warnings: 0 | Info: 0
+```
+
+### Example: Findings Detected
+
+```
+Security Scan: FAIL
+Scanned: 42 files, 12 rules applied
+Errors: 1 | Warnings: 2 | Info: 0
+
+[SEC-SECRET-001] src/config.ts:15 (error)
+  Hardcoded API key detected: `const API_KEY = "sk-..."`
+  Remediation: Move to environment variable, use dotenv or secrets manager.
+
+[SEC-NET-001] src/cors.ts:5 (warning)
+  CORS wildcard origin: `origin: "*"`
+  Remediation: Restrict to specific allowed origins.
+
+[SEC-CRYPTO-001] src/auth.ts:22 (warning)
+  Weak hash algorithm: `crypto.createHash("md5")`
+  Remediation: Use SHA-256 or stronger.
+```
+

package/dist/agents/commands/cursor/harness/harness-skill-authoring.mdc

@@ -0,0 +1,300 @@
+---
+description: Create and maintain harness skills following the rich skill format
+alwaysApply: false
+---
+
+<!-- Generated by harness generate-slash-commands. Do not edit. -->
+
+# Harness Skill Authoring
+
+> Create and extend harness skills following the rich skill format. Define purpose, choose type, write skill.yaml and SKILL.md with all required sections, validate, and test.
+
+## When to Use
+
+- Creating a new skill for a team's recurring workflow
+- Extending an existing skill with new phases, gates, or examples
+- Converting an informal process ("how we do code reviews") into a formal harness skill
+- When a team notices they repeat the same multi-step process and wants to codify it
+- NOT when running an existing skill (use the skill directly)
+- NOT when listing or discovering skills (use `harness skill list`)
+- NOT when the process is a one-off task that will not recur
+
+## Process
+
+### Phase 1: DEFINE — Establish the Skill's Purpose
+
+1. **Identify the recurring process.** What does the team do repeatedly? Name it. Describe it in one sentence. This becomes the skill's `description` in `skill.yaml` and the blockquote summary in `SKILL.md`.
+
+2. **Define the scope boundary.** A good skill does one thing well. If the process has distinct phases that could be done independently, consider whether it should be multiple skills. Signs of a skill that is too broad: more than 6 phases, multiple unrelated triggers, trying to serve two different audiences.
+
+3. **Identify the trigger conditions.** When should this skill activate?
+   - `manual` — Only when explicitly invoked
+   - `on_new_feature` — When starting a new feature
+   - `on_bug_fix` — When fixing a bug
+   - `on_pr_review` — When reviewing a pull request
+   - `on_project_init` — When initializing or entering a project
+   - Multiple triggers are fine if the skill genuinely applies to all of them
+
+4. **Determine required tools.** What tools does the skill need? Common sets:
+   - Read-only analysis: `Read`, `Glob`, `Grep`
+   - Code modification: `Read`, `Write`, `Edit`, `Glob`, `Grep`, `Bash`
+   - Full workflow: all of the above plus specialized tools
+
+### Phase 2: CHOOSE TYPE — Rigid or Flexible
+
+1. **Choose rigid when:**
+   - The process has strict ordering that must not be violated
+   - Skipping steps causes real damage (data loss, security holes, broken deployments)
+   - Compliance or policy requires auditability of each step
+   - The process includes mandatory checkpoints where human approval is needed
+   - Examples: TDD cycle, deployment pipeline, security audit, database migration
+
+2. **Choose flexible when:**
+   - The process has recommended steps but the order can adapt to context
+   - The agent should use judgment about which steps to emphasize
+   - Different situations call for different subsets of the process
+   - The process is more about guidelines than rigid procedure
+   - Examples: code review, onboarding, brainstorming, project initialization
+
+3. **Key difference in SKILL.md:** Rigid skills require `## Gates` and `## Escalation` sections. Flexible skills may omit them (though they can include them if useful).
+
+### Phase 3: WRITE SKILL.YAML — Define Metadata
+
+1. **Create the skill directory** under `agents/skills/<platform>/<skill-name>/`.
+
+2. **Write `skill.yaml`** with all required fields:
+
+```yaml
+name: <skill-name> # Kebab-case, matches directory name
+version: '1.0.0' # Semver
+description: <one-line summary> # What this skill does
+triggers:
+  - <trigger-1>
+  - <trigger-2>
+platforms:
+  - claude-code # Which agent platforms support this skill
+tools:
+  - <tool-1> # Tools the skill requires
+  - <tool-2>
+cli:
+  command: harness skill run <skill-name>
+  args:
+    - name: <arg-name>
+      description: <arg-description>
+      required: <true|false>
+mcp:
+  tool: run_skill
+  input:
+    skill: <skill-name>
+type: <rigid|flexible>
+state:
+  persistent: <true|false> # Does this skill maintain state across sessions?
+  files:
+    - <state-file-path> # List state files if persistent
+depends_on:
+  - <prerequisite-skill> # Skills that must be available (not necessarily run first)
+```
+
+3. **Validate the YAML.** Ensure proper indentation, correct field names, and valid values. The `name` field must match the directory name exactly.
+
+### Phase 4: WRITE SKILL.MD — Author the Skill Content
+
+1. **Start with the heading and summary:**
+
+```markdown
+# <Skill Name>
+
+> <One-sentence description of what the skill does and why.>
+```
+
+2. **Write `## When to Use`.** Include both positive (when TO use) and negative (when NOT to use) conditions. Be specific. Negative conditions prevent misapplication and point to the correct alternative skill.
+
+3. **Write `## Process`.** This is the core of the skill. Guidelines for writing good process sections:
+   - **Use phases to organize.** Group related steps into named phases (e.g., ASSESS, IMPLEMENT, VERIFY). Each phase should have a clear purpose and completion criteria.
+   - **Number every step.** Steps within a phase are numbered. This makes them referenceable ("go back to Phase 2, step 3").
+   - **Be prescriptive about actions.** Say "Run `harness validate`" not "consider validating." Say "Read the file" not "you might want to read the file."
+   - **Include decision points.** When the process branches, state the conditions clearly: "If X, do A. If Y, do B."
+   - **State what NOT to do.** Prohibitions prevent common mistakes: "Do not proceed to Phase 3 if validation fails."
+   - **For rigid skills:** Add an Iron Law at the top — the one inviolable principle. Then define phases with mandatory ordering and explicit gates between them.
+   - **For flexible skills:** Describe the recommended flow but acknowledge that adaptation is expected. Focus on outcomes rather than exact commands.
+
+4. **Write `## Harness Integration`.** List every harness CLI command the skill uses, with a brief description of when to use it. This section connects the skill to the harness toolchain.
+
+5. **Write `## Success Criteria`.** Define how to know the skill was executed well. Each criterion should be observable and verifiable — not subjective.
+
+6. **Write `## Examples`.** At least one concrete example showing the full process from start to finish. Use realistic project names, file paths, and commands. Show both the commands and their expected outputs.
+
+7. **For rigid skills, write `## Gates`.** Gates are hard stops — conditions that must be true to proceed. Each gate should state what happens if violated. Format: "**<condition> = <consequence>.**"
+
+8. **For rigid skills, write `## Escalation`.** Define when to stop and ask for help. Each escalation condition should describe the symptom, the likely cause, and what to report.
+
+### Phase 5: VALIDATE — Verify the Skill
+
+1. **Run `harness skill validate`** to check:
+   - `skill.yaml` has all required fields and valid values
+   - `SKILL.md` has all required sections (`## When to Use`, `## Process`, `## Harness Integration`, `## Success Criteria`, `## Examples`)
+   - Rigid skills have `## Gates` and `## Escalation` sections
+   - The `name` in `skill.yaml` matches the directory name
+   - Referenced tools exist
+   - Referenced dependencies exist
+
+2. **Fix any validation errors.** Common issues:
+   - Missing required section in `SKILL.md`
+   - `name` field does not match directory name
+   - Invalid trigger name
+   - Missing `type` field in `skill.yaml`
+
+3. **Test by running the skill:** `harness skill run <name>`. Verify it loads correctly and the process instructions make sense in context.
+
+### Skill Quality Checklist
+
+Evaluate every skill along two dimensions:
+
+|                             | **Clear activation**                | **Ambiguous activation**                | **Missing activation** |
+| --------------------------- | ----------------------------------- | --------------------------------------- | ---------------------- |
+| **Specific implementation** | Good skill                          | Wasted — good instructions nobody finds | Broken                 |
+| **Vague implementation**    | Trap — agents activate but flounder | Bad skill                               | Empty shell            |
+| **Missing implementation**  | Stub                                | Stub                                    | Does not exist         |
+
+- **Good skill** = clear activation + specific implementation. The agent knows when to use it and exactly what to do.
+- **Clear activation + vague implementation** = trap. The skill fires correctly but the agent has no concrete instructions, leading to inconsistent results.
+- **Ambiguous activation + specific implementation** = wasted. Great instructions that never get used because the agent does not know when to activate the skill.
+
+Use this checklist as a final quality gate before declaring a skill complete.
+
+## Harness Integration
+
+- **`harness skill validate`** — Validate a skill's `skill.yaml` and `SKILL.md` against the schema and structure requirements.
+- **`harness skill run <name>`** — Execute a skill to test it in context.
+- **`harness skill list`** — List all available skills, useful for checking that a new skill appears after creation.
+- **`harness add skill <name> --type <type>`** — Scaffold a new skill directory with template files (alternative to manual creation).
+
+## Success Criteria
+
+- `skill.yaml` exists with all required fields and passes schema validation
+- `SKILL.md` exists with all required sections filled with substantive content (not placeholders)
+- The skill name in `skill.yaml` matches the directory name
+- `harness skill validate` passes with zero errors
+- The process section has clear, numbered, actionable steps organized into phases
+- When to Use includes both positive and negative conditions
+- At least one concrete example demonstrates the full process
+- Rigid skills include Gates and Escalation sections with specific conditions and consequences
+- The skill can be loaded and run with `harness skill run <name>`
+
+## Examples
+
+### Example: Creating a Flexible Skill for Database Migration Review
+
+**DEFINE:**
+
+```
+Process: The team reviews database migrations before applying them.
+Scope: Review only — not creating or applying migrations.
+Triggers: manual (invoked when a migration PR is opened).
+Tools: Read, Glob, Grep, Bash.
+```
+
+**CHOOSE TYPE:** Flexible — the review steps can vary based on migration complexity. Some migrations need data impact analysis, others do not.
+
+**WRITE skill.yaml:**
+
+```yaml
+name: review-db-migration
+version: '1.0.0'
+description: Review database migration files for safety and correctness
+triggers:
+  - manual
+platforms:
+  - claude-code
+tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+cli:
+  command: harness skill run review-db-migration
+  args:
+    - name: migration-file
+      description: Path to the migration file to review
+      required: true
+mcp:
+  tool: run_skill
+  input:
+    skill: review-db-migration
+type: flexible
+state:
+  persistent: false
+  files: []
+depends_on: []
+```
+
+**WRITE SKILL.md:**
+
+```markdown
+# Review Database Migration
+
+> Review database migration files for safety, correctness, and
+> reversibility before they are applied to any environment.
+
+## When to Use
+
+- When a new migration file has been created and needs review
+- When a migration PR is opened
+- NOT when writing migrations (write first, then review)
+- NOT when applying migrations to environments (that is a deployment concern)
+
+## Process
+
+### Phase 1: ANALYZE — Understand the Migration
+
+1. Read the migration file completely...
+   [... full process content ...]
+
+## Harness Integration
+
+- `harness validate` — Verify project health after migration review
+  [... etc ...]
+```
+
+**VALIDATE:**
+
+```bash
+harness skill validate review-db-migration  # Pass
+harness skill run review-db-migration       # Loads correctly
+```
+
+### Example: Creating a Rigid Skill for Release Deployment
+
+**DEFINE:**
+
+```
+Process: Deploy a release to production. Strict ordering — cannot skip steps.
+Triggers: manual.
+Tools: Bash, Read, Glob.
+```
+
+**CHOOSE TYPE:** Rigid — skipping the smoke test or rollback verification step could cause production outages. Mandatory checkpoints for human approval before each environment promotion.
+
+**WRITE SKILL.md (key rigid sections):**
+
+```markdown
+## Gates
+
+- **Tests must pass before build.** If the test suite fails, do not
+  proceed to build. Fix the tests first.
+- **Staging must be verified before production.** If staging smoke tests
+  fail, do not promote to production. Roll back staging and investigate.
+- **Human approval required at each promotion.** Use [checkpoint:human-verify]
+  before promoting from staging to production. No auto-promotion.
+
+## Escalation
+
+- **When staging smoke tests fail on a test that passed locally:**
+  Report: "Smoke test [name] fails in staging but passes locally.
+  Likely cause: environment-specific configuration or data difference.
+  Need to investigate before proceeding."
+- **When rollback verification fails:** This is critical. Report immediately:
+  "Rollback to version [X] failed. Current state: [description].
+  Manual intervention required."
+```
+