From 27a555d55ae2ee2a05144598a454867d156d1a46 Mon Sep 17 00:00:00 2001 From: Alex Holmberg Date: Tue, 31 Mar 2026 15:53:31 +0200 Subject: [PATCH] feat: updated skills --- .claude-plugin/marketplace.json | 4 +- installer/package.json | 2 +- .../.claude-plugin/plugin.json | 2 +- .../skills/syncable-analyze/SKILL.md | 98 ++----- .../skills/syncable-dependencies/SKILL.md | 90 ++---- .../skills/syncable-deploy-pipeline/SKILL.md | 145 ++++------ .../skills/syncable-iac-pipeline/SKILL.md | 71 ++--- .../skills/syncable-optimize/SKILL.md | 142 +++------- .../skills/syncable-platform/SKILL.md | 255 ++++------------- .../syncable-project-assessment/SKILL.md | 93 +++---- .../skills/syncable-security-audit/SKILL.md | 98 +++---- .../skills/syncable-security/SKILL.md | 119 +++----- .../skills/syncable-validate/SKILL.md | 119 ++------ .../skills/syncable-vulnerabilities/SKILL.md | 101 ++----- skills/commands/syncable-analyze.md | 101 ++----- skills/commands/syncable-dependencies.md | 93 ++----- skills/commands/syncable-optimize.md | 145 ++++------ skills/commands/syncable-platform.md | 258 ++++-------------- skills/commands/syncable-security.md | 122 +++------ skills/commands/syncable-validate.md | 122 +++------ skills/commands/syncable-vulnerabilities.md | 104 ++----- skills/workflows/syncable-deploy-pipeline.md | 148 ++++------ skills/workflows/syncable-iac-pipeline.md | 74 ++--- .../workflows/syncable-project-assessment.md | 96 +++---- skills/workflows/syncable-security-audit.md | 101 +++---- 25 files changed, 813 insertions(+), 1890 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 3700ce09..7bb637e4 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -6,14 +6,14 @@ }, "metadata": { "description": "Syncable CLI skills for AI coding agents — project analysis, security, vulnerabilities, dependencies, IaC validation, and cloud deployment.", - "version": "0.1.14" + "version": "0.1.15" }, "plugins": [ { "name": "syncable-cli-skills", "source": "./installer/plugins/syncable-cli-skills", "description": "Syncable CLI skills for project analysis, security scanning, vulnerability detection, dependency auditing, IaC validation, Kubernetes optimization, and cloud deployment.", - "version": "0.1.14", + "version": "0.1.15", "author": { "name": "Syncable", "email": "support@syncable.dev" diff --git a/installer/package.json b/installer/package.json index 583d40eb..82e3e9f0 100644 --- a/installer/package.json +++ b/installer/package.json @@ -1,6 +1,6 @@ { "name": "syncable-cli-skills", - "version": "0.1.14", + "version": "0.1.15", "type": "module", "description": "Install Syncable CLI skills for AI coding agents (Claude Code, Cursor, Windsurf, Codex, Gemini CLI)", "license": "GPL-3.0", diff --git a/installer/plugins/syncable-cli-skills/.claude-plugin/plugin.json b/installer/plugins/syncable-cli-skills/.claude-plugin/plugin.json index d0f1fac2..0bd8991e 100644 --- a/installer/plugins/syncable-cli-skills/.claude-plugin/plugin.json +++ b/installer/plugins/syncable-cli-skills/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "syncable-cli-skills", "description": "Syncable CLI skills for project analysis, security scanning, vulnerability detection, dependency auditing, IaC validation, Kubernetes optimization, and cloud deployment.", - "version": "0.1.14", + "version": "0.1.15", "author": { "name": "Syncable", "email": "support@syncable.dev" diff --git a/installer/plugins/syncable-cli-skills/skills/syncable-analyze/SKILL.md b/installer/plugins/syncable-cli-skills/skills/syncable-analyze/SKILL.md index e1678d11..8a616566 100644 --- a/installer/plugins/syncable-cli-skills/skills/syncable-analyze/SKILL.md +++ b/installer/plugins/syncable-cli-skills/skills/syncable-analyze/SKILL.md @@ -1,103 +1,51 @@ --- -description: "Analyze a project's tech stack including languages, frameworks, runtimes, package managers, and dependencies using the Syncable CLI sync-ctl tool" +description: "Use when the user asks to analyze a project, understand the tech stack, detect frameworks, check what languages are used, identify runtimes or package managers, or as a first step before security/vulnerability scans" --- -## Purpose +## Overview -Analyze a project directory to detect its tech stack: programming languages, frameworks, runtimes, package managers, dependencies, Docker presence, and monorepo structure. This is the foundation skill — most workflows start here to understand what they're working with. +Detect a project's tech stack — languages, frameworks, runtimes, package managers, dependencies, Docker presence, monorepo structure. Foundation command; most workflows start here. -## Prerequisites +## Quick Reference -- `sync-ctl` binary installed and on PATH -- Agent has access to the project directory +| Flag | Purpose | +|------|---------| +| `--agent` | Compressed output for agent consumption (always use) | +| `--display {matrix\|detailed\|summary}` | Human-readable format | +| `--only ` | Comma-separated: `languages`, `frameworks`, `dependencies` | -## Commands +## Steps -### Basic analysis (agent output) +### 1. Run analysis ```bash sync-ctl analyze --agent ``` -### Human-readable matrix view - -```bash -sync-ctl analyze --display matrix -``` - -### Filtered analysis (only specific aspects) - -```bash -sync-ctl analyze --agent --only languages,frameworks -sync-ctl analyze --agent --only dependencies -``` - -### Key Flags - -| Flag | Purpose | -|------|---------| -| `--agent` | Compressed output for agent consumption (always use when processing results) | -| `--detailed` | Show detailed analysis (legacy vertical format) | -| `--display {matrix\|detailed\|summary}` | Display format for human-readable output | -| `--only ` | Comma-separated: `languages`, `frameworks`, `dependencies` | - -## Output Interpretation +**Success criteria:** JSON output with `summary` and `full_data_ref` fields present. -When reporting to the user, prioritize: primary language, main framework, runtime version, and whether Docker/K8s infrastructure exists. +### 2. Report to user -## Reading Results +Prioritize: primary language, main framework, runtime version, Docker/K8s presence. -When you use `--agent`, the output is a compressed summary — not the full analysis. Act on it directly for most decisions. +### 3. Drill into details (if needed) -The output JSON includes: -- `summary` — project count, languages, frameworks detected -- `full_data_ref` — reference ID for retrieving full data -- `retrieval_hint` — exact command to get more details +Save the `full_data_ref`. Use `sync-ctl retrieve` — do NOT re-run analyze: -To drill into specifics: ```bash -# Get framework details sync-ctl retrieve --query "section:frameworks" - -# Get language breakdown sync-ctl retrieve --query "section:languages" - -# Get specific project details (monorepos) -sync-ctl retrieve --query "project:" - -# Get specific language details +sync-ctl retrieve --query "project:" # monorepos sync-ctl retrieve --query "language:Go" - -# Get specific framework details sync-ctl retrieve --query "framework:React" - -# List all stored outputs -sync-ctl retrieve --list ``` -**Available query filters:** `section:summary`, `section:frameworks`, `section:languages`, `language:`, `framework:`, `project:`, `compact:true` +**Available queries:** `section:summary`, `section:frameworks`, `section:languages`, `language:`, `framework:`, `project:`, `compact:true` ## Error Handling -| Error | Cause | Action | -|-------|-------|--------| -| `No such file or directory` | Invalid path | Ask user to verify the project path | -| Empty output | No recognizable project files | Tell user the directory may not contain a supported project. Run `sync-ctl support` to show supported technologies | -| Timeout | Very large monorepo | Try `--only languages` for a faster partial scan | - -## Examples - -**Analyze current directory:** -```bash -sync-ctl analyze . --agent -``` - -**Analyze a specific project:** -```bash -sync-ctl analyze /path/to/project --agent -``` - -**Quick language-only check:** -```bash -sync-ctl analyze . --agent --only languages -``` +| Error | Action | +|-------|--------| +| `No such file or directory` | Ask user to verify path | +| Empty output | No supported project files. Run `sync-ctl support` | +| Timeout on large monorepo | Try `--only languages` for partial scan | diff --git a/installer/plugins/syncable-cli-skills/skills/syncable-dependencies/SKILL.md b/installer/plugins/syncable-cli-skills/skills/syncable-dependencies/SKILL.md index db2aa157..289ac267 100644 --- a/installer/plugins/syncable-cli-skills/skills/syncable-dependencies/SKILL.md +++ b/installer/plugins/syncable-cli-skills/skills/syncable-dependencies/SKILL.md @@ -1,93 +1,49 @@ --- -description: "Audit project dependencies for licenses, production vs development split, and detailed package analysis using the Syncable CLI sync-ctl tool" +description: "Use when the user asks to audit dependencies, check licenses, list packages, review dependency health, check for copyleft issues, or see prod vs dev dependency split" --- -## Purpose +## Overview -Analyze project dependencies in detail: list all packages, check license types, separate production from development dependencies, and optionally flag vulnerabilities inline. Use this for license compliance and dependency inventory. +List all project dependencies with license types, prod/dev split, and ecosystem breakdown. Use for license compliance and dependency inventory. -## Prerequisites +## Flags -- `sync-ctl` binary installed and on PATH -- Agent has access to the project directory +| Flag | Purpose | +|------|---------| +| `--agent` | Compressed output (always use) | +| `--licenses` | Include license info per dependency | +| `--vulnerabilities` | Quick inline vuln check (for thorough CVE scan, use `sync-ctl vulnerabilities` instead) | +| `--prod-only` | Production dependencies only | +| `--dev-only` | Development dependencies only | -## Commands +## Steps -### Full dependency analysis with licenses +### 1. Run dependency audit ```bash sync-ctl dependencies --licenses --agent ``` -### Production dependencies only - -```bash -sync-ctl dependencies --licenses --prod-only --agent -``` - -### Key Flags - -| Flag | Purpose | -|------|---------| -| `--agent` | Compressed output for agent consumption (always use) | -| `--licenses` | Include license information for each dependency | -| `--vulnerabilities` | Quick inline vulnerability check (for thorough CVE scanning, use the standalone `sync-ctl vulnerabilities` command instead) | -| `--prod-only` | Show only production dependencies | -| `--dev-only` | Show only development dependencies | - -## Output Interpretation - -**Priority for reporting to user:** -1. License concerns (copyleft in commercial projects, unknown licenses) -2. Dependency counts (prod vs dev) -3. Specific packages only if asked +**Success criteria:** JSON output with `total`, `production`/`development` counts, and `by_license` distribution. -**When to use `--vulnerabilities` vs standalone `vulnerabilities` command:** -- Use `--vulnerabilities` here for a quick inline check alongside license info -- Use `sync-ctl vulnerabilities` for a dedicated, thorough CVE scan +### 2. Report to user -## Reading Results +Priority: license concerns (copyleft, unknown) > dependency counts (prod vs dev) > specific packages (only if asked). -When you use `--agent`, the output is a **compressed summary** with counts, license distribution, and source breakdown. Individual package details are NOT in the compressed output — use `sync-ctl retrieve` to get them. +### 3. Retrieve package details (if needed) -**What's in the compressed output:** -- `total` — total dependency count -- `production` / `development` — prod vs dev split -- `by_source` — counts per ecosystem (npm, crates.io, pypi, etc.) -- `by_license` — license distribution -- `full_data_ref` — reference ID for the full data +Compressed output has counts and distributions only. Individual packages require retrieve: -**To get individual package details, use retrieve:** ```bash -# Get the full dependency list sync-ctl retrieve - -# Search for a specific package sync-ctl retrieve --query "file:package.json" ``` -Results are paginated (default 20). Use `--limit N --offset M` for more. +Results paginated (default 20). Use `--limit N --offset M` for more. ## Error Handling -| Error | Cause | Action | -|-------|-------|--------| -| `No dependencies found` | No package manager files | Verify project path, run `sync-ctl analyze` to check for supported package managers | -| Incomplete results | Some package managers not fully parsed | Note which ecosystems were scanned and which may be missing | - -## Examples - -**Full audit with licenses:** -```bash -sync-ctl dependencies . --licenses --agent -``` - -**Production-only for license compliance:** -```bash -sync-ctl dependencies . --licenses --prod-only --agent -``` - -**Quick vulnerability check alongside deps:** -```bash -sync-ctl dependencies . --licenses --vulnerabilities --agent -``` +| Error | Action | +|-------|--------| +| `No dependencies found` | Run `sync-ctl analyze` to verify supported package managers exist | +| Incomplete results | Note which ecosystems were scanned vs missing | diff --git a/installer/plugins/syncable-cli-skills/skills/syncable-deploy-pipeline/SKILL.md b/installer/plugins/syncable-cli-skills/skills/syncable-deploy-pipeline/SKILL.md index 1b96faca..abfcce95 100644 --- a/installer/plugins/syncable-cli-skills/skills/syncable-deploy-pipeline/SKILL.md +++ b/installer/plugins/syncable-cli-skills/skills/syncable-deploy-pipeline/SKILL.md @@ -1,139 +1,106 @@ --- -description: "Deploy a project through Syncable by orchestrating authentication, project analysis, security gating, and cloud deployment using the Syncable CLI sync-ctl tool" +description: "Use when the user asks to deploy through Syncable, ship to production, push to staging, run a deploy pipeline, or deploy a service with security checks first" --- -## Purpose +## Overview -Orchestrate a full deployment pipeline through the Syncable platform: authenticate, analyze the project, run a security audit as a gate, then deploy. Ensures no deployment happens without authentication and security review. +Full deployment pipeline: authenticate → analyze → security gate → deploy. No deployment without auth and security review. -## Prerequisites +## Steps -- `sync-ctl` binary installed and on PATH -- Internet access for Syncable API -- Agent has access to the project directory - -## Workflow Steps - -### Step 1: Check authentication and platform context +### 1. Check auth and context ```bash sync-ctl auth status ``` -**Decision point:** If not authenticated: -```bash -sync-ctl auth login -``` +If not authenticated: `sync-ctl auth login` -Then verify project/environment context: ```bash sync-ctl project current ``` -**Decision point:** If no project selected: -```bash -sync-ctl org list -# Ask user which org -sync-ctl org select -sync-ctl project list -# Ask user which project -sync-ctl project select -sync-ctl env list -# Ask user which environment -sync-ctl env select -``` +If no project/env selected: guide user through `org list` → `org select` → `project list` → `project select` → `env select`. -### Step 2: Analyze the project +**Success criteria:** Authenticated with org/project/env selected. + +### 2. Analyze the project ```bash sync-ctl analyze --agent ``` -Save the `full_data_ref` from the analyze output — do not re-run analyze in later steps; use `sync-ctl retrieve` with this ref_id instead. +Save `full_data_ref`. Do NOT re-run analyze in later steps. + +**Success criteria:** JSON with summary. You know IaC types and dependencies present. + +### 3. Pre-deploy security audit -### Step 3: Pre-deploy security audit +Reuse step 2's analysis — do NOT re-run analyze. -Execute the `syncable-security-audit` workflow inline (all its steps and decision logic). **Note:** Step 2's analyze output is reused here — do not re-run analyze. +```bash +sync-ctl security --mode paranoid --agent +sync-ctl vulnerabilities --agent # skip if no deps in step 2 +sync-ctl validate --agent # skip if no IaC in step 2 +``` -1. `sync-ctl security --mode paranoid --agent` -2. `sync-ctl vulnerabilities --agent` -3. `sync-ctl validate ` (if IaC files exist per Step 2's analysis) +**CRITICAL GATE — check security `status` field:** +- `CRITICAL_ISSUES_FOUND` → present findings, warn, **require explicit confirmation** +- `HIGH_ISSUES_FOUND` → warn, allow deployment +- `CLEAN` → proceed -**CRITICAL GATE:** Check the security output's `status` field: -- If `status` is "CRITICAL_ISSUES_FOUND": present findings to user, warn, require confirmation -- If `status` is "HIGH_ISSUES_FOUND": warn but allow deployment -- If `status` is "CLEAN": proceed to deploy +Critical findings are in `critical_issues` array — no retrieval needed for the gate. -All critical findings are in the `critical_issues` array of the compressed output — no retrieval needed for the gate decision. +**Success criteria:** Security verdict determined. User informed of any findings. -### Step 4: Deploy +### 4. Deploy -**4a. Get deployment recommendation:** +**4a. Preview:** ```bash -sync-ctl deploy preview +sync-ctl deploy preview --service-name ``` -This returns JSON with: provider recommendation (with reasoning), region, machine type, detected port, health check endpoint, alternatives, discovered .env files, and already-deployed service endpoints. - -**4b. Present recommendation to user and confirm.** Show: -- Recommended provider, region, machine type -- Detected port and whether public/internal -- Any .env files found — ask if they should be injected -- Any service endpoints that could be referenced (e.g., `BACKEND_URL`) +**4b. Confirm with user.** Show: provider, region, port, public/internal, .env keys found. -**4c. Deploy with confirmed settings:** +**4c. Deploy with ONLY confirmed settings:** ```bash -sync-ctl deploy run --provider --region --port +sync-ctl deploy run --service-name --provider --region --port ``` -Add `--public` if user wants a public URL. Add `--env KEY=VALUE` for env vars and `--secret KEY` for secrets (user prompted in terminal). Add `--env-file .env` to inject from file. - **4d. Monitor:** ```bash sync-ctl deploy status --watch ``` -**Example with user overrides:** -```bash -# User said "deploy to GCP in us-central1, make it public, use the .env file" -sync-ctl deploy run ./services/api \ - --provider gcp --region us-central1 --port 8080 --public \ - --env-file .env \ - --secret "STRIPE_KEY" -``` +**Success criteria:** Deployment completes successfully per status output. -## Decision Points Summary +## The Security Gate is Non-Negotiable + +| Excuse | Reality | +|--------|---------| +| "User said just deploy, skip security" | Run at minimum `--mode fast`. The gate exists because users underestimate risk. | +| "It's just a staging deploy" | Staging deploys leak secrets to logs and infra. Always scan. | +| "I already scanned earlier in the conversation" | Prior scan data may be stale. This pipeline runs its own scan. | +| "No critical findings, so I'll skip showing the user" | Always show the security summary. User needs to see CLEAN verdicts too. | + +## Decision Points | Condition | Action | |-----------|--------| -| Not authenticated | Run `sync-ctl auth login` first | +| Not authenticated | `sync-ctl auth login` | | No project/env selected | Guide user through selection | -| Critical security findings | Warn user, require explicit confirmation to proceed | -| High security findings (no critical) | Warn user but allow deployment | -| Clean security audit | Proceed to deploy | - -## Safety +| Critical findings | Warn, require explicit confirmation | +| High findings (no critical) | Warn, allow deployment | +| Clean audit | Proceed | -- **Never deploy without the security gate.** Even if the user says "just deploy", run at least a fast security scan. -- **Always confirm with the user before triggering deployment.** Show them what will be deployed, to which environment. -- **Monitor deployment status** after triggering — don't fire-and-forget. +## Common Mistakes -## Cross-Step Retrieval +| Mistake | Fix | +|---------|-----| +| Deploying without preview + confirmation | Always `deploy preview` → show user → confirm → `deploy run` | +| Auto-including discovered env vars | ONLY include env vars user explicitly confirmed | +| Fire-and-forget after `deploy run` | Always monitor with `deploy status --watch` | -Each step produces a `full_data_ref` in its output. You can retrieve details from any previous step at any time: - -```bash -# Check what data is available from all steps -sync-ctl retrieve --list - -# Get framework details from Step 2 (analyze) -sync-ctl retrieve --query "section:frameworks" - -# Get critical security findings from Step 3 -sync-ctl retrieve --query "severity:critical" - -# Get vulnerability details from Step 3 -sync-ctl retrieve --query "severity:high" -``` +## Retrieval -Do NOT re-run a command just to get more detail — use `sync-ctl retrieve` instead. +Save each step's `full_data_ref`. Use `sync-ctl retrieve --query "..."` for drill-down. Do NOT re-run commands. diff --git a/installer/plugins/syncable-cli-skills/skills/syncable-iac-pipeline/SKILL.md b/installer/plugins/syncable-cli-skills/skills/syncable-iac-pipeline/SKILL.md index 62f250ec..7a41e6f2 100644 --- a/installer/plugins/syncable-cli-skills/skills/syncable-iac-pipeline/SKILL.md +++ b/installer/plugins/syncable-cli-skills/skills/syncable-iac-pipeline/SKILL.md @@ -1,85 +1,68 @@ --- -description: "Validate all infrastructure-as-code files by combining Dockerfile linting, Docker Compose validation, Kubernetes manifest checking, and Helm chart analysis using the Syncable CLI sync-ctl tool" +description: "Use when the user asks to validate all infrastructure files, run an IaC review, check Docker/Compose/K8s/Terraform/Helm files together, or lint infrastructure-as-code" --- -## Purpose +## Overview -Validate all infrastructure-as-code files in a project by chaining IaC linting with Kubernetes optimization and security checks. Covers Dockerfiles, Docker Compose, Terraform, K8s manifests, and Helm charts. +Chain analyze + validate + K8s optimize for a complete IaC review. Covers Dockerfiles, Compose, Terraform, K8s manifests, and Helm charts. -## Prerequisites +## Steps -- `sync-ctl` binary installed and on PATH -- Agent has access to the project directory -- Project must contain IaC files - -## Workflow Steps - -### Step 1: Analyze the project +### 1. Analyze the project ```bash sync-ctl analyze --agent ``` -Parse the output to determine: -- Which IaC types exist (Dockerfile, Compose, Terraform, K8s manifests) -- Whether K8s manifests are present — needed for step 3 +Determine: which IaC types exist, whether K8s manifests/Helm charts present (gates step 3). Save `full_data_ref`. -Save the `full_data_ref` from the analyze output — the ref_id from this step can be reused in later steps to retrieve IaC file details without re-running analyze. +**Success criteria:** You know which IaC types are present. If NO IaC files at all → abort workflow, tell user. -### Step 2: Validate IaC files +### 2. Validate IaC files ```bash -sync-ctl validate +sync-ctl validate --agent ``` -If step 1 revealed specific types, you can filter: -```bash -sync-ctl validate --types dockerfile,compose,terraform -``` +Filter if types known from step 1: `--types dockerfile,compose,terraform` + +**Success criteria:** JSON with `status` field and violations by severity. -### Step 3: Kubernetes optimization (conditional) +### 3. Kubernetes optimization (conditional) -**Decision point:** Only run if step 1 detected Kubernetes manifests or Helm charts. +**Decision:** Only run if step 1 detected K8s manifests or Helm charts. ```bash sync-ctl optimize --full --agent ``` -The `--full` flag includes kubelint security checks and helmlint validation on top of resource optimization. +`--full` includes kubelint security + helmlint validation + resource optimization. -## Decision Points Summary +**Success criteria:** JSON with recommendations, or step skipped with reason. + +## Decision Points | Condition | Action | |-----------|--------| -| No K8s manifests or Helm charts in step 1 | Skip step 3 | -| No IaC files at all in step 1 | Abort workflow, tell user no IaC files found | +| No IaC files at all | Abort, tell user | +| No K8s/Helm in step 1 | Skip step 3 | ## Report Synthesis -Produce an IaC validation report: - 1. **Dockerfile Issues** — hadolint violations by severity 2. **Docker Compose Issues** — dclint violations 3. **Terraform Issues** — validation errors -4. **Kubernetes Issues** — kubelint security findings and resource optimization recommendations (if step 3 ran) +4. **Kubernetes Issues** — kubelint findings + resource optimization (if step 3 ran) 5. **Actionable Fixes** — which issues can be auto-fixed with `--fix` -## Cross-Step Retrieval +## Retrieval -Each step produces a `full_data_ref` in its output. You can retrieve details from any previous step at any time: +Save each step's `full_data_ref`. Use `sync-ctl retrieve --query "..."` for drill-down: ```bash -# Check what data is available from all steps -sync-ctl retrieve --list - -# Get framework details from Step 1 (analyze) -sync-ctl retrieve --query "section:frameworks" - -# Get critical security findings from Step 2 -sync-ctl retrieve --query "severity:critical" - -# Get vulnerability details from Step 3 -sync-ctl retrieve --query "severity:high" +sync-ctl retrieve --query "severity:high" +sync-ctl retrieve --query "file:Dockerfile" +sync-ctl retrieve --query "container:my-app" ``` -Do NOT re-run a command just to get more detail — use `sync-ctl retrieve` instead. +Do NOT re-run commands for more detail. diff --git a/installer/plugins/syncable-cli-skills/skills/syncable-optimize/SKILL.md b/installer/plugins/syncable-cli-skills/skills/syncable-optimize/SKILL.md index 5b6aafad..106a6fbc 100644 --- a/installer/plugins/syncable-cli-skills/skills/syncable-optimize/SKILL.md +++ b/installer/plugins/syncable-cli-skills/skills/syncable-optimize/SKILL.md @@ -1,128 +1,76 @@ --- -description: "Optimize Kubernetes resource requests and limits, analyze costs, detect over-provisioned containers, and right-size pods using the Syncable CLI sync-ctl tool" +description: "Use when the user asks to optimize Kubernetes resources, right-size pods, estimate cluster costs, detect over-provisioned containers, analyze resource waste, or check K8s configuration drift" --- -## Purpose +## Overview -Analyze Kubernetes manifests and optionally live cluster metrics to recommend resource right-sizing, estimate costs, and detect configuration drift. Can also run kubelint security checks and helmlint validation with `--full` flag. +Analyze K8s manifests and optionally live cluster metrics to recommend resource right-sizing, estimate costs, and detect drift. `--full` adds kubelint + helmlint checks. -## Prerequisites +## Flags -- `sync-ctl` binary installed and on PATH -- For static analysis: K8s manifest files (YAML) in the project -- For live cluster analysis: valid kubeconfig with cluster access -- For cost estimation: `--cloud-provider` flag - -## Commands - -### Static manifest analysis +| Flag | Purpose | +|------|---------| +| `--agent` | Compressed output (always use) | +| `--cluster [CONTEXT]` | Live K8s cluster (current context if omitted) | +| `--prometheus ` | Prometheus for historical metrics | +| `--namespace ` | Target namespace (`*` for all) | +| `--period ` | Metrics period (e.g., `7d`, `30d`) | +| `--full` | Include kubelint + helmlint | +| `--cloud-provider {aws\|gcp\|azure\|onprem}` | Cost estimation | +| `--region ` | Pricing region (default: `us-east-1`) | +| `--fix` | Generate fix suggestions (does NOT modify files) | +| `--apply` | Write fixes to files. Requires `--fix`. **Never use without user confirmation.** | +| `--dry-run` | Preview `--apply` changes | +| `--severity ` | Minimum severity | +| `--threshold <0-100>` | Minimum waste percentage | + +## Steps + +### 1. Run optimization analysis ```bash sync-ctl optimize --agent ``` -### Live cluster analysis +**Success criteria:** JSON output with `summary` containing recommendation count and estimated savings. -```bash -sync-ctl optimize --cluster --agent -sync-ctl optimize --cluster my-context --namespace default --agent -``` +### 2. Report to user -### With Prometheus metrics +Priority: right-sizing recommendations with savings > critical security findings (from `--full`) > drift issues > cost breakdown. -```bash -sync-ctl optimize --cluster --prometheus http://localhost:9090 --period 30d --agent -``` +### 3. Apply fixes (if requested) -### Full analysis (includes kubelint + helmlint) +Always follow this sequence — never skip dry-run: ```bash -sync-ctl optimize --full --agent +sync-ctl optimize --fix --dry-run --agent # Preview +# Show user the changes, get explicit confirmation +sync-ctl optimize --fix --apply # Apply only after approval ``` -### Cost estimation - -```bash -sync-ctl optimize --cluster --cloud-provider aws --region us-east-1 --agent -``` +**Success criteria:** User has seen and approved the dry-run output before `--apply`. -### Key Flags +### 4. Retrieve details (if needed) -| Flag | Purpose | -|------|---------| -| `--agent` | Compressed output for agent consumption (always use) | -| `--cluster [CONTEXT]` | Connect to live K8s cluster (uses current context if no name given) | -| `--prometheus ` | Prometheus URL for historical metrics | -| `--namespace ` | Target namespace (or `*` for all) | -| `--period ` | Analysis period for metrics (e.g., `7d`, `30d`) | -| `--full` | Include kubelint security checks + helmlint validation | -| `--cloud-provider {aws\|gcp\|azure\|onprem}` | Cloud provider for cost estimation | -| `--region ` | Region for pricing (default: `us-east-1`) | -| `--fix` | Generate fix suggestions | -| `--apply` | **DANGEROUS:** Apply fixes to manifest files. Requires `--fix`. Never use without explicit user confirmation. | -| `--dry-run` | Preview changes without applying | -| `--severity ` | Minimum severity to report | -| `--threshold <0-100>` | Minimum waste percentage threshold | - -## Output Interpretation - -**Priority for reporting to user:** -1. High-confidence right-sizing recommendations with cost savings -2. Critical security findings (from `--full`) -3. Drift detection issues -4. Cost breakdown summary - -## Reading Results - -When you use `--agent`, the output is a compressed summary. High-confidence right-sizing recommendations are included in full. Cost summary and drift findings are always present when applicable. - -The output JSON includes: -- `summary` — total recommendations, estimated savings, containers analyzed -- `top_recommendations` — highest-impact right-sizing suggestions -- `costs` — cost attribution summary (if `--cloud-provider` set) -- `drift` — configuration drift issues (if `--cluster` set) -- `full_data_ref` — reference ID for retrieving full data -- `retrieval_hint` — exact command for drill-down - -To drill into specifics: ```bash -# Get high-severity findings sync-ctl retrieve --query "severity:high" - -# Get recommendations for a specific container sync-ctl retrieve --query "container:my-app" ``` -**Available query filters:** `severity:`, `container:` +**Available queries:** `severity:`, `container:` -## Safety +## Common Mistakes -- `--fix` only generates suggestions — it does NOT modify files -- `--apply` (requires `--fix`) writes changes to files — always confirm with user first -- `--dry-run` previews what `--apply` would do — use this to show the user before applying -- Recommend: always run `--fix --dry-run` first, show output, then `--fix --apply` only after user approval +| Mistake | Fix | +|---------|-----| +| Using `--apply` without showing dry-run first | Always `--fix --dry-run` first, confirm, then `--fix --apply` | +| Skipping `--cloud-provider` when user asks about costs | Cost estimation requires this flag | +| Running live cluster analysis without checking connectivity | Verify `kubectl cluster-info` first | ## Error Handling -| Error | Cause | Action | -|-------|-------|--------| -| `No Kubernetes manifests found` | No YAML with K8s resources | Run `sync-ctl analyze --agent` to check for K8s presence | -| `Cannot connect to cluster` | Invalid kubeconfig or cluster unreachable | Check `kubectl cluster-info` works, verify context name | -| `Prometheus unreachable` | Wrong URL or Prometheus not running | Verify URL, fall back to static analysis without `--prometheus` | - -## Examples - -**Quick static analysis:** -```bash -sync-ctl optimize . --agent -``` - -**Full analysis with live cluster and cost estimation:** -```bash -sync-ctl optimize . --cluster --cloud-provider aws --full --agent -``` - -**Preview fixes before applying:** -```bash -sync-ctl optimize . --fix --dry-run --agent -``` +| Error | Action | +|-------|--------| +| `No Kubernetes manifests found` | Run `sync-ctl analyze` to check for K8s presence | +| `Cannot connect to cluster` | Verify `kubectl cluster-info`, check context name | +| `Prometheus unreachable` | Verify URL, fall back to static analysis | diff --git a/installer/plugins/syncable-cli-skills/skills/syncable-platform/SKILL.md b/installer/plugins/syncable-cli-skills/skills/syncable-platform/SKILL.md index cdf8a12f..6bdcc39d 100644 --- a/installer/plugins/syncable-cli-skills/skills/syncable-platform/SKILL.md +++ b/installer/plugins/syncable-cli-skills/skills/syncable-platform/SKILL.md @@ -1,15 +1,10 @@ --- -description: "Authenticate, login, sign in to Syncable platform. Switch organizations, projects, and environments. Deploy services to cloud providers. Check current context and manage platform settings using sync-ctl" +description: "Use when the user asks to log in to Syncable, authenticate, switch projects or organizations, check current context, deploy a service, check deployment status, or manage platform settings" --- -## Purpose +## Overview -Manage Syncable platform operations: authenticate, switch organizations/projects/environments by name, check current context, and trigger deployments. This skill handles the full platform lifecycle. - -## Prerequisites - -- `sync-ctl` binary installed and on PATH -- Internet access for Syncable API +Manage Syncable platform: authenticate, switch org/project/environment, check context, deploy services. ## Auth-First Rule @@ -19,183 +14,75 @@ Manage Syncable platform operations: authenticate, switch organizations/projects sync-ctl auth status ``` -If the response says "Not logged in" or "Session expired": - -```bash -sync-ctl auth login -``` +If not authenticated: `sync-ctl auth login` (opens browser for OAuth). Tell user a browser will open. Command blocks until authorized. -This opens a browser for OAuth device flow. Tell the user: "A browser window will open for you to authorize. If it doesn't open automatically, visit the URL shown and enter the code." Then wait — the command blocks until the user authorizes. +**Success criteria:** `sync-ctl auth status` shows authenticated. -## Switching Context +## Context Switching -### Switch project by name +### By name (org/project require list → match → select) -When user says "change project to my-app" or "use project my-app": - -1. List projects to find the ID: ```bash -sync-ctl project list -``` - -2. Parse the table output to find the row where NAME matches the user's request (case-insensitive, partial match OK). - -3. Select by ID: -```bash -sync-ctl project select -``` - -**If multiple matches:** show the user the matching projects and ask which one. -**If no matches:** tell the user no project with that name was found, and show available projects. - -### Switch organization by name - -When user says "switch org to acme" or "use organization acme": - -1. List organizations: -```bash -sync-ctl org list -``` +# Organization (switching clears project + env) +sync-ctl org list → find ID → sync-ctl org select -2. Parse output to find matching org name → ID. +# Project (requires UUID) +sync-ctl project list → find ID → sync-ctl project select -3. Select: -```bash -sync-ctl org select -``` - -**Note:** Switching org clears the current project and environment selection. After switching org, you'll need to select a project too. - -### Switch environment by name - -When user says "use staging" or "switch to production": - -```bash +# Environment (accepts name directly) sync-ctl env select ``` -Environment select accepts **names directly** (not just IDs). No need to list first. - -### Combined switches - -When user says "switch to my-app on staging": - -1. Find and select the project (list → match → select) -2. Then select the environment by name: -```bash -sync-ctl env select staging -``` - -When user says "switch to acme org, project my-app, staging env": - -1. `sync-ctl org list` → find acme → `sync-ctl org select ` -2. `sync-ctl project list` → find my-app → `sync-ctl project select ` -3. `sync-ctl env select staging` +Multiple matches: show user and ask. No matches: show available options. -## Checking Current Context - -When user says "what project am I on" or "show current context": +### Check current context ```bash sync-ctl project current ``` -Shows: organization, project, environment, and last updated timestamp. - ## Commands Reference -### Authentication - ```bash -sync-ctl auth status # Check if authenticated -sync-ctl auth login # Log in (opens browser) -sync-ctl auth login --no-browser # Log in without auto-opening browser -sync-ctl auth logout # Log out and clear credentials -sync-ctl auth token --raw # Print raw access token -``` +# Auth +sync-ctl auth status | login | login --no-browser | logout | token --raw -### Organizations - -```bash -sync-ctl org list # List all organizations -sync-ctl org select # Select organization (requires UUID) -``` +# Org +sync-ctl org list | org select -### Projects +# Project +sync-ctl project list | project select | project current | project info [ID] -```bash -sync-ctl project list # List projects in current org -sync-ctl project list --org-id # List projects in specific org -sync-ctl project select # Select project (requires UUID) -sync-ctl project current # Show current context -sync-ctl project info # Show current project details -sync-ctl project info # Show specific project details +# Environment +sync-ctl env list | env select ``` -### Environments - -```bash -sync-ctl env list # List environments in current project -sync-ctl env select # Select environment (accepts name or ID) -``` +## Deploy Flow (Agents) -### Deployment (non-interactive — use these as an agent) +### 1. Preview ```bash -# Preview deployment recommendation (returns JSON) -sync-ctl deploy preview -sync-ctl deploy preview --provider hetzner --region nbg1 +sync-ctl deploy preview --service-name my-service +``` -# Deploy with settings (triggers actual deployment) -sync-ctl deploy run --provider hetzner --region nbg1 --port 8080 --public -sync-ctl deploy run --env "NODE_ENV=production" --secret "DATABASE_URL" --env-file .env +**Success criteria:** JSON with `recommendation`, `connected_providers`, `alternatives`. -# Monitor deployment -sync-ctl deploy status -sync-ctl deploy status --watch +### 2. Confirm with user -# Interactive wizard (for humans, NOT usable by agents) -sync-ctl deploy wizard +Show: service name, provider, region, port, public/internal. If .env files found, list keys and ask which to include. -# Create a new environment -sync-ctl deploy new-env -``` +**CRITICAL:** NEVER deploy without preview + user confirmation. ONLY include env vars the user explicitly confirmed. -### Deploy Flow for Agents +### 3. Deploy -**Step 1: Preview** — get a recommendation as JSON: ```bash -sync-ctl deploy preview . --service-name my-service +sync-ctl deploy run --service-name --provider --region --port ``` -The output includes: -- `recommendation` — provider, region, machine type, port, health check, with reasoning -- `connected_providers` — all available providers -- `alternatives` — other options the user could choose -- `parsed_env_files` — discovered .env files and non-secret keys -- `deployed_service_endpoints` — URLs of already-deployed services (public and private) - -**Step 2: Show user the preview and get explicit confirmation.** Present: -- Service name, provider, region, machine type -- Port and whether public or internal -- If .env files found, list the keys and ask user which ones to include -- If deployed service endpoints exist, list them and ask which to wire up - -**CRITICAL RULES:** -- NEVER deploy without showing the preview first and getting user confirmation -- ONLY include env vars the user explicitly asked for or confirmed — do NOT auto-include discovered env vars or service endpoints -- If the user says "deploy with API_BASE=..." then ONLY set API_BASE, nothing else -- If the user wants additional env vars, they need to say so explicitly -- Always use `--service-name` to set the name the user wants, not the directory name - -**Step 3: Deploy** — with ONLY the settings the user confirmed: -```bash -sync-ctl deploy run . --service-name frontend-v2 --provider hetzner --region nbg1 --port 8080 --env "API_BASE=https://..." -``` +**Success criteria:** JSON with `config_id` and `task_id`. -Returns JSON with `config_id` and `task_id`. +### 4. Monitor -**Step 4: Monitor** — watch until complete: ```bash sync-ctl deploy status --watch ``` @@ -204,67 +91,29 @@ sync-ctl deploy status --watch | Flag | Purpose | |------|---------| -| `--service-name ` | Service name (ALWAYS set this — defaults to directory name otherwise) | +| `--service-name ` | Service name (always set) | | `--provider ` | Cloud provider | -| `--region ` | Deployment region (e.g., `nbg1`, `us-central1`) | -| `--machine-type ` | Machine type (e.g., `cx22`, `e2-small`) | +| `--region ` | Deployment region | | `--port ` | Port to expose | -| `--public` | Make service publicly accessible (default: internal-only) | -| `--cpu ` | CPU allocation for GCP/Azure (e.g., `1000m`) | -| `--memory ` | Memory allocation for GCP/Azure (e.g., `512Mi`) | +| `--public` | Publicly accessible (default: internal) | | `--env ` | Non-secret env var (repeatable) | -| `--secret ` | Secret key — user prompted in terminal for value (repeatable) | -| `--env-file ` | Load env vars from .env file (secrets auto-detected by key name) | -| `--min-instances ` | Minimum replicas | -| `--max-instances ` | Maximum replicas | +| `--secret ` | Secret (user prompted for value, repeatable) | +| `--env-file ` | Load from .env file | +| `--min-instances ` / `--max-instances ` | Replica range | -## Output Format +## Common Mistakes -All platform commands output human-readable text (no `--agent` mode). Parse the table output to extract IDs and names. Table format is typically: - -``` -ID NAME DESCRIPTION -------... -abc123-def456-... my-project My project description -``` +| Mistake | Fix | +|---------|-----| +| Auto-including discovered env vars without asking | ONLY set env vars the user explicitly requested | +| Deploying without preview | Always `deploy preview` first, show user, get confirmation | +| Using directory name as service name | Always set `--service-name` explicitly | ## Error Handling -| Error | Cause | Action | -|-------|-------|--------| -| `Not authenticated` | No valid session | Run `sync-ctl auth login` | -| `Token expired` | Session timed out | Run `sync-ctl auth login` | -| `No organization selected` | Org not set | Run `sync-ctl org list` then `sync-ctl org select ` | -| `No project selected` | Project not set | Run `sync-ctl project list` then `sync-ctl project select ` | -| `No environment selected` | Env not set | Run `sync-ctl env list` then `sync-ctl env select ` | -| `Project not found` | Wrong ID | Run `sync-ctl project list` to see available projects | -| `Deployment failed` | Build or infra error | Check `sync-ctl deploy status ` for details | - -## Examples - -**User: "change project to my-app"** -```bash -sync-ctl auth status # Check auth first -sync-ctl project list # Find my-app's ID -sync-ctl project select # Select it -``` - -**User: "switch to staging"** -```bash -sync-ctl env select staging -``` - -**User: "switch to acme org and select the api-gateway project on production"** -```bash -sync-ctl auth status -sync-ctl org list # Find acme's ID -sync-ctl org select -sync-ctl project list # Find api-gateway's ID -sync-ctl project select -sync-ctl env select production -``` - -**User: "what am I connected to?"** -```bash -sync-ctl project current -``` +| Error | Action | +|-------|--------| +| `Not authenticated` / `Token expired` | `sync-ctl auth login` | +| `No organization selected` | `sync-ctl org list` then `org select ` | +| `No project selected` | `sync-ctl project list` then `project select ` | +| `Deployment failed` | `sync-ctl deploy status ` for details | diff --git a/installer/plugins/syncable-cli-skills/skills/syncable-project-assessment/SKILL.md b/installer/plugins/syncable-cli-skills/skills/syncable-project-assessment/SKILL.md index ab34e1ce..e0278c4f 100644 --- a/installer/plugins/syncable-cli-skills/skills/syncable-project-assessment/SKILL.md +++ b/installer/plugins/syncable-cli-skills/skills/syncable-project-assessment/SKILL.md @@ -1,104 +1,73 @@ --- -description: "Run a comprehensive project health check combining stack analysis, security scanning, vulnerability detection, and dependency auditing using the Syncable CLI sync-ctl tool" +description: "Use when the user asks to assess a project, run a health check, get an overview of project status, evaluate project health, or wants a comprehensive report covering stack, security, vulnerabilities, and dependencies" --- -## Purpose +## Overview -Run a comprehensive project health check by chaining multiple Syncable CLI commands. Produces a unified report covering tech stack, security posture, vulnerability status, and dependency health. +Chain analyze + security + vulnerabilities + dependencies into a unified health report. Each step informs the next via decision points. -## Prerequisites +## Steps -- `sync-ctl` binary installed and on PATH -- Agent has access to the project directory - -## Workflow Steps - -### Step 1: Analyze the project stack +### 1. Analyze the project stack ```bash sync-ctl analyze --agent ``` -Parse the output to understand: -- What languages and frameworks are present -- Whether dependencies exist (needed for steps 3 and 4) -- Whether secrets-capable files exist (affects step 2 mode) +Parse output for: languages, frameworks, whether dependencies exist (gates steps 3-4), whether secrets-capable files exist (gates step 2 mode). Save `full_data_ref`. -Save the `full_data_ref` from the analyze output — you'll use it to retrieve details without re-running analyze. +**Success criteria:** JSON with `summary` field. You know what languages, frameworks, and dependency files are present. -### Step 2: Security scan +### 2. Security scan ```bash sync-ctl security --mode balanced --agent ``` -**Decision point:** If step 1 shows no config files, secrets files, or environment files, use `--mode lightning` instead of `--mode balanced` to save time. +**Decision:** No config/secrets/env files in step 1 → use `--mode lightning` instead. + +**Success criteria:** JSON with severity counts. All critical/high findings captured. -### Step 3: Vulnerability scan +### 3. Vulnerability scan ```bash sync-ctl vulnerabilities --agent ``` -**Decision point:** If step 1 detected no dependencies (no package.json, requirements.txt, Cargo.toml, go.mod, etc.), **skip this step entirely** and note "No dependencies detected" in the report. +**Decision:** No dependencies detected in step 1 → **skip entirely**, note "No dependencies detected" in report. + +If scanner missing: `sync-ctl tools install --yes`, then retry. + +**Success criteria:** JSON with CVE counts by severity, or step skipped with documented reason. -### Step 4: Dependency audit +### 4. Dependency audit ```bash sync-ctl dependencies --licenses --agent ``` -**Decision point:** Same as step 3 — skip if no dependencies detected. +**Decision:** Same as step 3 — skip if no dependencies. -## Decision Points Summary +**Success criteria:** JSON with total count, prod/dev split, license distribution, or step skipped. + +## Decision Points | Condition | Action | |-----------|--------| -| No dependencies detected in step 1 | Skip steps 3 and 4 | +| No dependencies in step 1 | Skip steps 3 and 4 | | No secrets-capable files in step 1 | Use `--mode lightning` in step 2 | -| Vulnerability scanner missing | Run `sync-ctl tools install --yes`, then retry step 3 | +| Vulnerability scanner missing | `sync-ctl tools install --yes`, retry | ## Report Synthesis -After all steps complete, synthesize a unified report for the user: +After all steps, synthesize ONE report: 1. **Tech Stack** — primary language, frameworks, runtimes -2. **Security Score** — score from security scan, critical/high finding count -3. **Vulnerabilities** — critical/high CVE count, packages with available fixes -4. **Dependencies** — total count, license concerns (copyleft, unknown) -5. **Recommendations** — top 3-5 actionable items prioritized by severity - -## Examples - -**Assess current directory:** - -The agent runs these commands in sequence, skipping steps based on decision points: - -```bash -sync-ctl analyze . --agent -sync-ctl security . --mode balanced --agent -sync-ctl vulnerabilities . --agent -sync-ctl dependencies . --licenses --agent -``` - -Then synthesizes the results into a single report for the user. - -## Cross-Step Retrieval - -Each step produces a `full_data_ref` in its output. You can retrieve details from any previous step at any time: +2. **Security Score** — score, critical/high count +3. **Vulnerabilities** — critical/high CVE count, packages with fixes +4. **Dependencies** — total count, license concerns +5. **Recommendations** — top 3-5 actions by severity -```bash -# Check what data is available from all steps -sync-ctl retrieve --list - -# Get framework details from Step 1 (analyze) -sync-ctl retrieve --query "section:frameworks" - -# Get critical security findings from Step 2 -sync-ctl retrieve --query "severity:critical" - -# Get vulnerability details from Step 3 -sync-ctl retrieve --query "severity:high" -``` +## Retrieval -Do NOT re-run a command just to get more detail — use `sync-ctl retrieve` instead. +Save each step's `full_data_ref`. Use `sync-ctl retrieve --query "..."` for drill-down. Do NOT re-run commands for more detail. diff --git a/installer/plugins/syncable-cli-skills/skills/syncable-security-audit/SKILL.md b/installer/plugins/syncable-cli-skills/skills/syncable-security-audit/SKILL.md index ac6df1bc..e4e17785 100644 --- a/installer/plugins/syncable-cli-skills/skills/syncable-security-audit/SKILL.md +++ b/installer/plugins/syncable-cli-skills/skills/syncable-security-audit/SKILL.md @@ -1,100 +1,86 @@ --- -description: "Perform a thorough pre-deployment or compliance security review combining deep security scan, CVE checks, and IaC validation using the Syncable CLI sync-ctl tool" +description: "Use when the user asks for a security audit, pre-deployment security review, compliance check, thorough security assessment before shipping, or deep security scan for production readiness" --- -## Purpose +## Overview -Perform a deep, multi-layered security review suitable for pre-deployment gates or compliance audits. Goes deeper than the project assessment by using thorough/paranoid scan modes and including IaC validation. +Deep multi-layered security review for pre-deployment gates or compliance. Uses thorough/paranoid scan modes and includes IaC validation. Stricter than project-assessment. -## Prerequisites +## Steps -- `sync-ctl` binary installed and on PATH -- Agent has access to the project directory - -## Workflow Steps - -### Step 1: Analyze the project +### 1. Analyze the project ```bash sync-ctl analyze --agent ``` -Parse the output to determine: -- What IaC files exist (Dockerfiles, Compose, Terraform, K8s manifests) — needed for step 4 -- What dependencies exist — needed for step 3 +Determine: IaC files present (gates step 4), dependencies present (gates step 3). Save `full_data_ref`. -Save the `full_data_ref` from the analyze output — you'll use it to retrieve details without re-running analyze. +**Success criteria:** You know which IaC types and dependency files exist. -### Step 2: Deep security scan +### 2. Deep security scan -Choose mode based on context: - -**For PR reviews / pre-merge:** +**PR review / pre-merge:** ```bash sync-ctl security --mode thorough --agent ``` -**For production deployment / compliance:** +**Production / compliance:** ```bash sync-ctl security --mode paranoid --agent ``` -### Step 3: Vulnerability scan +**Success criteria:** JSON with severity counts. All critical/high findings captured with file locations. + +### 3. Vulnerability scan ```bash sync-ctl vulnerabilities --agent ``` -### Step 4: IaC validation +**Decision:** No dependencies in step 1 → skip, note in report. -**Decision point:** Only run if step 1 detected Docker, Compose, Terraform, or K8s files. +**Success criteria:** CVE counts by severity captured. -```bash -sync-ctl validate -``` +### 4. IaC validation -If specific types are known from step 1, filter: ```bash -sync-ctl validate --types dockerfile,compose +sync-ctl validate --agent ``` -## Decision Points Summary +**Decision:** No IaC files in step 1 → skip. -| Condition | Action | -|-----------|--------| -| PR review context | Use `--mode thorough` in step 2 | -| Pre-deploy / compliance context | Use `--mode paranoid` in step 2 | -| No IaC files detected in step 1 | Skip step 4 | -| No dependencies detected in step 1 | Skip step 3 | +Filter if types known: `--types dockerfile,compose` -## Report Synthesis +**Success criteria:** Lint violations captured with severity and file locations. -Produce a security audit report: +## Decision Points -1. **Security Findings** — all Critical and High findings with file locations and remediation -2. **Vulnerability Status** — CVEs by severity, packages needing updates -3. **IaC Compliance** — lint violations in Dockerfiles, Compose, Terraform -4. **Overall Verdict** — PASS (no critical/high findings), WARN (high findings but no critical), FAIL (critical findings present) -5. **Remediation Priority** — ordered list of actions to resolve findings - -**If critical findings exist:** Explicitly warn the user. If this audit is part of a deploy pipeline, recommend blocking deployment until critical issues are resolved. +| Condition | Action | +|-----------|--------| +| PR review context | `--mode thorough` in step 2 | +| Pre-deploy / compliance | `--mode paranoid` in step 2 | +| No IaC files in step 1 | Skip step 4 | +| No dependencies in step 1 | Skip step 3 | -## Cross-Step Retrieval +## Report: Verdict Format -Each step produces a `full_data_ref` in its output. You can retrieve details from any previous step at any time: +1. **Security Findings** — critical/high with locations and remediation +2. **Vulnerability Status** — CVEs by severity, packages needing updates +3. **IaC Compliance** — lint violations +4. **Verdict** — PASS (no critical/high) | WARN (high but no critical) | FAIL (critical present) +5. **Remediation Priority** — ordered action list -```bash -# Check what data is available from all steps -sync-ctl retrieve --list +**If critical findings exist:** Explicitly warn user. If part of deploy pipeline, recommend blocking deployment. -# Get framework details from Step 1 (analyze) -sync-ctl retrieve --query "section:frameworks" +## Common Mistakes -# Get critical security findings from Step 2 -sync-ctl retrieve --query "severity:critical" +| Mistake | Reality | +|---------|---------| +| "Project looks simple, lightning mode is fine" | Security audits require thorough or paranoid. That's what distinguishes this from project-assessment. | +| Skipping IaC validation because "it's just Dockerfiles" | Dockerfile misconfigurations are a top attack vector. Always validate if IaC exists. | +| Reporting verdict without running all applicable steps | Every applicable step must complete before issuing a PASS/WARN/FAIL verdict. | -# Get vulnerability details from Step 3 -sync-ctl retrieve --query "severity:high" -``` +## Retrieval -Do NOT re-run a command just to get more detail — use `sync-ctl retrieve` instead. +Save each step's `full_data_ref`. Use `sync-ctl retrieve --query "..."` for drill-down. Do NOT re-run commands. diff --git a/installer/plugins/syncable-cli-skills/skills/syncable-security/SKILL.md b/installer/plugins/syncable-cli-skills/skills/syncable-security/SKILL.md index e67a79e7..02b6720e 100644 --- a/installer/plugins/syncable-cli-skills/skills/syncable-security/SKILL.md +++ b/installer/plugins/syncable-cli-skills/skills/syncable-security/SKILL.md @@ -1,110 +1,67 @@ --- -description: "Scan code for leaked secrets, credentials, API keys, hardcoded passwords, and insecure code patterns using the Syncable CLI sync-ctl security scanner" +description: "Use when the user asks to scan for secrets, find leaked credentials, check for API keys in code, detect hardcoded passwords, review code security, or run a secrets scan" --- -## Purpose +## Overview -Perform security analysis on a codebase: detect leaked secrets (API keys, tokens, passwords, private keys), identify insecure code patterns, and analyze configuration security. Returns findings with severity levels, file locations, and remediation guidance. +Scan a codebase for leaked secrets (API keys, tokens, passwords, private keys), insecure code patterns, and configuration issues. Returns findings with severity, file locations, and remediation. -## Prerequisites +## Mode Selection -- `sync-ctl` binary installed and on PATH -- Agent has access to the project directory +Always pass `--mode` explicitly: -## Commands +| Mode | When to use | +|------|------------| +| `lightning` | Quick check, critical files only (.env, configs) | +| `fast` | Smart sampling, large repos during development | +| `balanced` | **Default.** Good coverage with optimizations | +| `thorough` | Pre-deployment, PR security reviews | +| `paranoid` | Compliance audits, production reviews | -### Standard security scan - -```bash -sync-ctl security --mode balanced --agent -``` - -### Mode Selection Guide - -Always pass `--mode` explicitly. Choose based on context: - -| Mode | When to use | Speed | -|------|------------|-------| -| `lightning` | Quick check, only critical files (.env, configs) | Fastest | -| `fast` | Smart sampling, good for large repos during development | Fast | -| `balanced` | **Default choice.** Good coverage with optimizations | Medium | -| `thorough` | Pre-deployment reviews, PR security checks | Slow | -| `paranoid` | Compliance audits, production security reviews | Slowest | - -### Key Flags +## Flags | Flag | Purpose | |------|---------| -| `--mode {lightning\|fast\|balanced\|thorough\|paranoid}` | Scan depth (always specify) | -| `--agent` | Compressed output for agent consumption (always use when processing results) | -| `--include-low` | Include low-severity findings (off by default) | -| `--no-secrets` | Skip secrets detection (only code patterns) | -| `--no-code-patterns` | Skip code pattern analysis (only secrets) | -| `--fail-on-findings` | Exit with error code if findings exist (for CI) | +| `--mode ` | Scan depth (always specify) | +| `--agent` | Compressed output (always use) | +| `--include-low` | Include low-severity findings | +| `--no-secrets` | Skip secrets detection (code patterns only) | +| `--no-code-patterns` | Skip code patterns (secrets only) | +| `--fail-on-findings` | Exit with error code if findings exist (CI) | | `--output ` | Write report to file | -## Output Interpretation +## Steps -**Priority for reporting to user:** -1. Critical findings first (leaked secrets, hardcoded credentials) -2. High findings (insecure patterns) -3. Summary with score -4. Remediation steps for top findings +### 1. Run scan -## Reading Results +```bash +sync-ctl security --mode balanced --agent +``` -When you use `--agent`, the output is a **compressed summary** — NOT the full data. Only critical and high findings are inline. To get medium/low details, you MUST use `sync-ctl retrieve`. +**Success criteria:** JSON output with `summary` containing severity counts. -**What's in the compressed output:** -- `summary` — counts by severity -- `critical_issues` — full details for every critical finding -- `high_issues` — first 10 high-severity findings -- `patterns` — deduplicated medium/low findings as counts only (NO individual details) -- `full_data_ref` — reference ID for the full stored data +### 2. Report to user -**IMPORTANT: Do NOT try to extract medium/low details from the compressed output. Use retrieve instead.** +Priority order: critical findings (leaked secrets) > high (insecure patterns) > summary score > remediation steps. + +### 3. Retrieve details (if needed) + +Compressed output only includes critical + first 10 high findings. Medium/low are counts only. Use retrieve for details: ```bash -# Get medium-severity findings sync-ctl retrieve --query "severity:medium" - -# Get findings for a specific file sync-ctl retrieve --query "file:src/auth.rs" - -# Get findings by rule code sync-ctl retrieve --query "code:hardcoded-secret" ``` -Results are paginated (default 20). Use `--limit N --offset M` for more. +Results paginated (default 20). Use `--limit N --offset M` for more. -**Available query filters:** `severity:critical|high|medium|low|info`, `file:`, `code:` +**Available queries:** `severity:critical|high|medium|low|info`, `file:`, `code:` ## Error Handling -| Error | Cause | Action | -|-------|-------|--------| -| `No such file or directory` | Invalid path | Ask user to verify the project path | -| Very slow scan | Large repo with `thorough`/`paranoid` mode | Suggest trying `balanced` or `fast` mode first | -| No findings | Clean project or scan mode too light | If `lightning`/`fast`, suggest re-running with `balanced` for deeper coverage | - -## Examples - -**Quick secrets check on current directory:** -```bash -sync-ctl security . --mode balanced --agent -``` - -**Deep pre-deploy audit:** -```bash -sync-ctl security . --mode paranoid --agent -``` - -**Secrets-only scan (skip code patterns):** -```bash -sync-ctl security . --mode thorough --no-code-patterns --agent -``` - -**Save report to file:** -```bash -sync-ctl security . --mode thorough --agent --output security-report.json -``` +| Error | Action | +|-------|--------| +| `No such file or directory` | Ask user to verify path | +| Very slow scan | Suggest `balanced` or `fast` mode instead | +| No findings with `lightning`/`fast` | Re-run with `balanced` for deeper coverage | diff --git a/installer/plugins/syncable-cli-skills/skills/syncable-validate/SKILL.md b/installer/plugins/syncable-cli-skills/skills/syncable-validate/SKILL.md index 9e226e60..689a9092 100644 --- a/installer/plugins/syncable-cli-skills/skills/syncable-validate/SKILL.md +++ b/installer/plugins/syncable-cli-skills/skills/syncable-validate/SKILL.md @@ -1,119 +1,56 @@ --- -description: "Lint and validate Dockerfiles, Docker Compose files, Kubernetes manifests, Helm charts, and Terraform configs using the Syncable CLI sync-ctl tool" +description: "Use when the user asks to validate Dockerfiles, lint Docker Compose files, check Kubernetes manifests, validate Terraform configs, lint IaC files, or review infrastructure-as-code" --- -## Purpose +## Overview -Validate Infrastructure-as-Code files against best practices. Covers Dockerfiles (via native hadolint), Docker Compose files (via native dclint), and Terraform configurations. Reports violations with severity, file locations, and auto-fix suggestions. +Validate IaC files against best practices. Covers Dockerfiles (hadolint), Docker Compose (dclint), and Terraform. Reports violations with severity, locations, and auto-fix suggestions. -## Prerequisites - -- `sync-ctl` binary installed and on PATH -- Agent has access to the project directory -- Project must contain IaC files (Dockerfiles, docker-compose.yml, *.tf files) - -## Commands - -### Validate all IaC files in a directory - -```bash -sync-ctl validate --agent -``` - -### Validate specific types only - -```bash -sync-ctl validate --types dockerfile --agent -sync-ctl validate --types dockerfile,compose --agent -sync-ctl validate --types terraform --agent -``` - -### Auto-fix issues where possible - -```bash -sync-ctl validate --fix -``` - -### Key Flags +## Flags | Flag | Purpose | |------|---------| -| `--agent` | Compressed output for agent consumption (always use when processing results) | -| `--types ` | Filter to specific IaC types: `dockerfile`, `compose`, `terraform` | -| `--fix` | Automatically fix issues where possible | +| `--agent` | Compressed output (always use) | +| `--types ` | Filter: `dockerfile`, `compose`, `terraform` (comma-separated) | +| `--fix` | Auto-fix issues where possible | -**Note:** The `--agent` flag is available for structured output. When `--agent` is not used, output is terminal text with structured lint violations. +## What Gets Checked -## Output Interpretation +| Type | Linter | Examples | +|------|--------|----------| +| Dockerfile | hadolint (Rust) | Pin versions, avoid `latest`, COPY not ADD | +| Docker Compose | dclint (Rust) | Service naming, volumes, networks (15 rules) | +| Terraform | Terraform validator | Syntax, providers, resource definitions | -Output contains lint violations, each with: +## Steps -- **file** — path to the IaC file -- **line** — line number of the violation -- **rule** — rule ID (e.g., DL3006 for hadolint, DCL001 for dclint) -- **severity** — Error, Warning, Info -- **message** — description of the issue -- **fix** — suggested fix (if available) +### 1. Run validation -**What gets checked:** +```bash +sync-ctl validate --agent +``` -| Type | Linter | Example checks | -|------|--------|---------------| -| Dockerfile | hadolint (native Rust) | Pin versions, avoid `latest` tag, use COPY not ADD, multi-stage best practices | -| Docker Compose | dclint (native Rust) | Service naming, volume declarations, network configuration, 15 configurable rules | -| Terraform | Terraform validator | Syntax validation, provider configuration, resource definitions | +**Success criteria:** JSON output with `status` field (`ERRORS_FOUND`, `WARNINGS_ONLY`, or `CLEAN`). -**Priority for reporting to user:** -1. Errors first — these will cause build/deploy failures -2. Warnings — best practice violations -3. Info — suggestions for improvement +### 2. Report to user -## Reading Results +Priority: errors (build/deploy failures) > warnings (best practice violations) > info (suggestions). -When you use `--agent`, the output is a compressed summary. All **error**-severity violations are included in full detail. Warnings are deduplicated into patterns. +### 3. Retrieve details (if needed) -The output JSON includes: -- `status` — e.g., "ERRORS_FOUND", "WARNINGS_ONLY", "CLEAN" -- `summary` — counts by severity -- `errors` — full details for every error-severity finding -- `patterns` — deduplicated warning/info findings with counts -- `full_data_ref` — reference ID for retrieving full data -- `retrieval_hint` — exact command for drill-down +Compressed output includes all errors in full. Warnings are deduplicated counts: -To drill into specifics: ```bash -# Get all error-severity findings sync-ctl retrieve --query "severity:high" - -# Get findings for a specific file sync-ctl retrieve --query "file:Dockerfile" - -# Get findings by rule code sync-ctl retrieve --query "code:DL3006" ``` -**Available query filters:** `severity:`, `file:`, `code:` +**Available queries:** `severity:`, `file:`, `code:` ## Error Handling -| Error | Cause | Action | -|-------|-------|--------| -| `No IaC files found` | Directory has no Dockerfiles, Compose, or Terraform files | Run `sync-ctl analyze --agent` to verify what IaC exists | -| `Unknown type` | Invalid `--types` value | Valid types are: `dockerfile`, `compose`, `terraform` | - -## Examples - -**Lint all IaC in current directory:** -```bash -sync-ctl validate . --agent -``` - -**Lint only Dockerfiles:** -```bash -sync-ctl validate . --types dockerfile --agent -``` - -**Auto-fix Docker Compose issues:** -```bash -sync-ctl validate . --types compose --fix -``` +| Error | Action | +|-------|--------| +| `No IaC files found` | Run `sync-ctl analyze --agent` to verify what IaC exists | +| `Unknown type` | Valid types: `dockerfile`, `compose`, `terraform` | diff --git a/installer/plugins/syncable-cli-skills/skills/syncable-vulnerabilities/SKILL.md b/installer/plugins/syncable-cli-skills/skills/syncable-vulnerabilities/SKILL.md index 6d090385..add6a59f 100644 --- a/installer/plugins/syncable-cli-skills/skills/syncable-vulnerabilities/SKILL.md +++ b/installer/plugins/syncable-cli-skills/skills/syncable-vulnerabilities/SKILL.md @@ -1,106 +1,51 @@ --- -description: "Check project dependencies for known CVEs and security vulnerabilities across npm, pip, cargo, and go ecosystems using the Syncable CLI sync-ctl tool" +description: "Use when the user asks to check for CVEs, scan dependencies for vulnerabilities, find known security issues in packages, or audit npm/pip/cargo/go/java dependency security" --- -## Purpose +## Overview -Scan project dependencies for known CVEs (Common Vulnerabilities and Exposures) across npm, pip, cargo, go, and java ecosystems. Returns vulnerable packages with severity, affected versions, and available fixes. +Scan project dependencies for known CVEs across npm, pip, cargo, go, and java ecosystems. Returns vulnerable packages with severity, affected versions, and available fixes. -## Prerequisites +## Flags -- `sync-ctl` binary installed and on PATH -- Agent has access to the project directory -- Language-specific scanning tools should be installed. If a scan fails with "tool not found", run `sync-ctl tools install` to install missing scanners. +| Flag | Purpose | +|------|---------| +| `--agent` | Compressed output (always use) | +| `--severity {low\|medium\|high\|critical}` | Minimum severity threshold | +| `--output ` | Write report to file | -## Commands +## Steps -### Scan for vulnerabilities +### 1. Run vulnerability scan ```bash sync-ctl vulnerabilities --agent ``` -### Filter by severity +**Success criteria:** JSON output with `summary` containing severity counts. -```bash -sync-ctl vulnerabilities --severity high --agent -``` +### 2. Report to user -### Key Flags +Priority: critical/high CVEs with fixes (actionable) > critical/high without fixes (risk flag) > medium/low (mention count only, don't enumerate unless asked). -| Flag | Purpose | -|------|---------| -| `--agent` | Compressed output for agent consumption (always use) | -| `--severity {low\|medium\|high\|critical}` | Only show findings at or above this severity | -| `--output ` | Write report to file | +### 3. Retrieve details (if needed) -## Output Interpretation +Compressed output includes critical + first 10 high findings. Medium/low are counts only: -**Priority for reporting to user:** -1. Critical/High CVEs with available fixes — actionable immediately -2. Critical/High CVEs without fixes — flag as risk -3. Medium/Low — mention count, don't enumerate unless asked - -## Reading Results - -When you use `--agent`, the output is a **compressed summary** — NOT the full data. Only critical and high findings are inline. To get medium/low details, you MUST use `sync-ctl retrieve`. - -**What's in the compressed output:** -- `summary` — counts by severity (total, critical, high, medium, low) -- `critical_issues` — full details for every critical finding -- `high_issues` — first 10 high-severity findings (full detail) -- `patterns` — deduplicated medium/low findings as counts only (NO individual details) -- `full_data_ref` — reference ID for the full stored data -- `retrieval_hint` — exact command for drill-down - -**IMPORTANT: Do NOT try to extract medium/low details from the compressed output. They are only available via retrieve.** - -To get individual findings by severity: ```bash -# Get medium-severity findings (NOT in compressed output — must use retrieve) sync-ctl retrieve --query "severity:medium" - -# Get low-severity findings sync-ctl retrieve --query "severity:low" - -# Get high-severity findings (also in compressed output, but retrieve gives all of them) -sync-ctl retrieve --query "severity:high" - -# Get findings for a specific source directory sync-ctl retrieve --query "file:services/api" ``` -Results are paginated (default 20). Use `--limit N --offset M` for more. +Results paginated (default 20). Use `--limit N --offset M` for more. -**Available query filters:** `severity:`, `file:` +**Available queries:** `severity:`, `file:` ## Error Handling -| Error | Cause | Action | -|-------|-------|--------| -| `tool not found` or scanner missing | Language-specific audit tool not installed | Run `sync-ctl tools install` to install missing scanners, then retry | -| `No dependencies found` | No package manager files detected | Run `sync-ctl analyze --agent` first to verify the project has dependencies | -| Timeout | Very large dependency tree | Try scanning specific subdirectories in a monorepo | - -## Examples - -**Scan current project:** -```bash -sync-ctl vulnerabilities . --agent -``` - -**Only critical and high severity:** -```bash -sync-ctl vulnerabilities . --severity high --agent -``` - -**Save report:** -```bash -sync-ctl vulnerabilities . --agent --output vuln-report.json -``` - -**Install missing scanners first:** -```bash -sync-ctl tools install --yes -sync-ctl vulnerabilities . --agent -``` +| Error | Action | +|-------|--------| +| `tool not found` / scanner missing | Run `sync-ctl tools install --yes`, then retry | +| `No dependencies found` | Run `sync-ctl analyze --agent` first to verify dependencies exist | +| Timeout on large dep tree | Try scanning specific subdirectories | diff --git a/skills/commands/syncable-analyze.md b/skills/commands/syncable-analyze.md index c6954581..dc7cec3f 100644 --- a/skills/commands/syncable-analyze.md +++ b/skills/commands/syncable-analyze.md @@ -1,104 +1,55 @@ --- name: syncable-analyze -description: Analyze a project's tech stack including languages, frameworks, runtimes, package managers, and dependencies using the Syncable CLI sync-ctl tool +description: Use when the user asks to analyze a project, understand the tech stack, detect frameworks, check what languages are used, identify runtimes or package managers, or as a first step before security/vulnerability scans +allowed-tools: + - Bash +user-invocable: true --- -## Purpose +## Overview -Analyze a project directory to detect its tech stack: programming languages, frameworks, runtimes, package managers, dependencies, Docker presence, and monorepo structure. This is the foundation skill — most workflows start here to understand what they're working with. +Detect a project's tech stack — languages, frameworks, runtimes, package managers, dependencies, Docker presence, monorepo structure. Foundation command; most workflows start here. -## Prerequisites +## Quick Reference -- `sync-ctl` binary installed and on PATH -- Agent has access to the project directory +| Flag | Purpose | +|------|---------| +| `--agent` | Compressed output for agent consumption (always use) | +| `--display {matrix\|detailed\|summary}` | Human-readable format | +| `--only ` | Comma-separated: `languages`, `frameworks`, `dependencies` | -## Commands +## Steps -### Basic analysis (agent output) +### 1. Run analysis ```bash sync-ctl analyze --agent ``` -### Human-readable matrix view - -```bash -sync-ctl analyze --display matrix -``` - -### Filtered analysis (only specific aspects) - -```bash -sync-ctl analyze --agent --only languages,frameworks -sync-ctl analyze --agent --only dependencies -``` - -### Key Flags - -| Flag | Purpose | -|------|---------| -| `--agent` | Compressed output for agent consumption (always use when processing results) | -| `--detailed` | Show detailed analysis (legacy vertical format) | -| `--display {matrix\|detailed\|summary}` | Display format for human-readable output | -| `--only ` | Comma-separated: `languages`, `frameworks`, `dependencies` | - -## Output Interpretation +**Success criteria:** JSON output with `summary` and `full_data_ref` fields present. -When reporting to the user, prioritize: primary language, main framework, runtime version, and whether Docker/K8s infrastructure exists. +### 2. Report to user -## Reading Results +Prioritize: primary language, main framework, runtime version, Docker/K8s presence. -When you use `--agent`, the output is a compressed summary — not the full analysis. Act on it directly for most decisions. +### 3. Drill into details (if needed) -The output JSON includes: -- `summary` — project count, languages, frameworks detected -- `full_data_ref` — reference ID for retrieving full data -- `retrieval_hint` — exact command to get more details +Save the `full_data_ref`. Use `sync-ctl retrieve` — do NOT re-run analyze: -To drill into specifics: ```bash -# Get framework details sync-ctl retrieve --query "section:frameworks" - -# Get language breakdown sync-ctl retrieve --query "section:languages" - -# Get specific project details (monorepos) -sync-ctl retrieve --query "project:" - -# Get specific language details +sync-ctl retrieve --query "project:" # monorepos sync-ctl retrieve --query "language:Go" - -# Get specific framework details sync-ctl retrieve --query "framework:React" - -# List all stored outputs -sync-ctl retrieve --list ``` -**Available query filters:** `section:summary`, `section:frameworks`, `section:languages`, `language:`, `framework:`, `project:`, `compact:true` +**Available queries:** `section:summary`, `section:frameworks`, `section:languages`, `language:`, `framework:`, `project:`, `compact:true` ## Error Handling -| Error | Cause | Action | -|-------|-------|--------| -| `No such file or directory` | Invalid path | Ask user to verify the project path | -| Empty output | No recognizable project files | Tell user the directory may not contain a supported project. Run `sync-ctl support` to show supported technologies | -| Timeout | Very large monorepo | Try `--only languages` for a faster partial scan | - -## Examples - -**Analyze current directory:** -```bash -sync-ctl analyze . --agent -``` - -**Analyze a specific project:** -```bash -sync-ctl analyze /path/to/project --agent -``` - -**Quick language-only check:** -```bash -sync-ctl analyze . --agent --only languages -``` +| Error | Action | +|-------|--------| +| `No such file or directory` | Ask user to verify path | +| Empty output | No supported project files. Run `sync-ctl support` | +| Timeout on large monorepo | Try `--only languages` for partial scan | diff --git a/skills/commands/syncable-dependencies.md b/skills/commands/syncable-dependencies.md index 9e859bb2..18285804 100644 --- a/skills/commands/syncable-dependencies.md +++ b/skills/commands/syncable-dependencies.md @@ -1,94 +1,53 @@ --- name: syncable-dependencies -description: Audit project dependencies for licenses, production vs development split, and detailed package analysis using the Syncable CLI sync-ctl tool +description: Use when the user asks to audit dependencies, check licenses, list packages, review dependency health, check for copyleft issues, or see prod vs dev dependency split +allowed-tools: + - Bash +user-invocable: true --- -## Purpose +## Overview -Analyze project dependencies in detail: list all packages, check license types, separate production from development dependencies, and optionally flag vulnerabilities inline. Use this for license compliance and dependency inventory. +List all project dependencies with license types, prod/dev split, and ecosystem breakdown. Use for license compliance and dependency inventory. -## Prerequisites +## Flags -- `sync-ctl` binary installed and on PATH -- Agent has access to the project directory +| Flag | Purpose | +|------|---------| +| `--agent` | Compressed output (always use) | +| `--licenses` | Include license info per dependency | +| `--vulnerabilities` | Quick inline vuln check (for thorough CVE scan, use `sync-ctl vulnerabilities` instead) | +| `--prod-only` | Production dependencies only | +| `--dev-only` | Development dependencies only | -## Commands +## Steps -### Full dependency analysis with licenses +### 1. Run dependency audit ```bash sync-ctl dependencies --licenses --agent ``` -### Production dependencies only - -```bash -sync-ctl dependencies --licenses --prod-only --agent -``` - -### Key Flags - -| Flag | Purpose | -|------|---------| -| `--agent` | Compressed output for agent consumption (always use) | -| `--licenses` | Include license information for each dependency | -| `--vulnerabilities` | Quick inline vulnerability check (for thorough CVE scanning, use the standalone `sync-ctl vulnerabilities` command instead) | -| `--prod-only` | Show only production dependencies | -| `--dev-only` | Show only development dependencies | - -## Output Interpretation - -**Priority for reporting to user:** -1. License concerns (copyleft in commercial projects, unknown licenses) -2. Dependency counts (prod vs dev) -3. Specific packages only if asked +**Success criteria:** JSON output with `total`, `production`/`development` counts, and `by_license` distribution. -**When to use `--vulnerabilities` vs standalone `vulnerabilities` command:** -- Use `--vulnerabilities` here for a quick inline check alongside license info -- Use `sync-ctl vulnerabilities` for a dedicated, thorough CVE scan +### 2. Report to user -## Reading Results +Priority: license concerns (copyleft, unknown) > dependency counts (prod vs dev) > specific packages (only if asked). -When you use `--agent`, the output is a **compressed summary** with counts, license distribution, and source breakdown. Individual package details are NOT in the compressed output — use `sync-ctl retrieve` to get them. +### 3. Retrieve package details (if needed) -**What's in the compressed output:** -- `total` — total dependency count -- `production` / `development` — prod vs dev split -- `by_source` — counts per ecosystem (npm, crates.io, pypi, etc.) -- `by_license` — license distribution -- `full_data_ref` — reference ID for the full data +Compressed output has counts and distributions only. Individual packages require retrieve: -**To get individual package details, use retrieve:** ```bash -# Get the full dependency list sync-ctl retrieve - -# Search for a specific package sync-ctl retrieve --query "file:package.json" ``` -Results are paginated (default 20). Use `--limit N --offset M` for more. +Results paginated (default 20). Use `--limit N --offset M` for more. ## Error Handling -| Error | Cause | Action | -|-------|-------|--------| -| `No dependencies found` | No package manager files | Verify project path, run `sync-ctl analyze` to check for supported package managers | -| Incomplete results | Some package managers not fully parsed | Note which ecosystems were scanned and which may be missing | - -## Examples - -**Full audit with licenses:** -```bash -sync-ctl dependencies . --licenses --agent -``` - -**Production-only for license compliance:** -```bash -sync-ctl dependencies . --licenses --prod-only --agent -``` - -**Quick vulnerability check alongside deps:** -```bash -sync-ctl dependencies . --licenses --vulnerabilities --agent -``` +| Error | Action | +|-------|--------| +| `No dependencies found` | Run `sync-ctl analyze` to verify supported package managers exist | +| Incomplete results | Note which ecosystems were scanned vs missing | diff --git a/skills/commands/syncable-optimize.md b/skills/commands/syncable-optimize.md index 0bc14a53..553cafd3 100644 --- a/skills/commands/syncable-optimize.md +++ b/skills/commands/syncable-optimize.md @@ -1,129 +1,80 @@ --- name: syncable-optimize -description: Optimize Kubernetes resource requests and limits, analyze costs, detect over-provisioned containers, and right-size pods using the Syncable CLI sync-ctl tool +description: Use when the user asks to optimize Kubernetes resources, right-size pods, estimate cluster costs, detect over-provisioned containers, analyze resource waste, or check K8s configuration drift +allowed-tools: + - Bash +user-invocable: true --- -## Purpose +## Overview -Analyze Kubernetes manifests and optionally live cluster metrics to recommend resource right-sizing, estimate costs, and detect configuration drift. Can also run kubelint security checks and helmlint validation with `--full` flag. +Analyze K8s manifests and optionally live cluster metrics to recommend resource right-sizing, estimate costs, and detect drift. `--full` adds kubelint + helmlint checks. -## Prerequisites +## Flags -- `sync-ctl` binary installed and on PATH -- For static analysis: K8s manifest files (YAML) in the project -- For live cluster analysis: valid kubeconfig with cluster access -- For cost estimation: `--cloud-provider` flag - -## Commands - -### Static manifest analysis +| Flag | Purpose | +|------|---------| +| `--agent` | Compressed output (always use) | +| `--cluster [CONTEXT]` | Live K8s cluster (current context if omitted) | +| `--prometheus ` | Prometheus for historical metrics | +| `--namespace ` | Target namespace (`*` for all) | +| `--period ` | Metrics period (e.g., `7d`, `30d`) | +| `--full` | Include kubelint + helmlint | +| `--cloud-provider {aws\|gcp\|azure\|onprem}` | Cost estimation | +| `--region ` | Pricing region (default: `us-east-1`) | +| `--fix` | Generate fix suggestions (does NOT modify files) | +| `--apply` | Write fixes to files. Requires `--fix`. **Never use without user confirmation.** | +| `--dry-run` | Preview `--apply` changes | +| `--severity ` | Minimum severity | +| `--threshold <0-100>` | Minimum waste percentage | + +## Steps + +### 1. Run optimization analysis ```bash sync-ctl optimize --agent ``` -### Live cluster analysis +**Success criteria:** JSON output with `summary` containing recommendation count and estimated savings. -```bash -sync-ctl optimize --cluster --agent -sync-ctl optimize --cluster my-context --namespace default --agent -``` +### 2. Report to user -### With Prometheus metrics +Priority: right-sizing recommendations with savings > critical security findings (from `--full`) > drift issues > cost breakdown. -```bash -sync-ctl optimize --cluster --prometheus http://localhost:9090 --period 30d --agent -``` +### 3. Apply fixes (if requested) -### Full analysis (includes kubelint + helmlint) +Always follow this sequence — never skip dry-run: ```bash -sync-ctl optimize --full --agent +sync-ctl optimize --fix --dry-run --agent # Preview +# Show user the changes, get explicit confirmation +sync-ctl optimize --fix --apply # Apply only after approval ``` -### Cost estimation - -```bash -sync-ctl optimize --cluster --cloud-provider aws --region us-east-1 --agent -``` +**Success criteria:** User has seen and approved the dry-run output before `--apply`. -### Key Flags +### 4. Retrieve details (if needed) -| Flag | Purpose | -|------|---------| -| `--agent` | Compressed output for agent consumption (always use) | -| `--cluster [CONTEXT]` | Connect to live K8s cluster (uses current context if no name given) | -| `--prometheus ` | Prometheus URL for historical metrics | -| `--namespace ` | Target namespace (or `*` for all) | -| `--period ` | Analysis period for metrics (e.g., `7d`, `30d`) | -| `--full` | Include kubelint security checks + helmlint validation | -| `--cloud-provider {aws\|gcp\|azure\|onprem}` | Cloud provider for cost estimation | -| `--region ` | Region for pricing (default: `us-east-1`) | -| `--fix` | Generate fix suggestions | -| `--apply` | **DANGEROUS:** Apply fixes to manifest files. Requires `--fix`. Never use without explicit user confirmation. | -| `--dry-run` | Preview changes without applying | -| `--severity ` | Minimum severity to report | -| `--threshold <0-100>` | Minimum waste percentage threshold | - -## Output Interpretation - -**Priority for reporting to user:** -1. High-confidence right-sizing recommendations with cost savings -2. Critical security findings (from `--full`) -3. Drift detection issues -4. Cost breakdown summary - -## Reading Results - -When you use `--agent`, the output is a compressed summary. High-confidence right-sizing recommendations are included in full. Cost summary and drift findings are always present when applicable. - -The output JSON includes: -- `summary` — total recommendations, estimated savings, containers analyzed -- `top_recommendations` — highest-impact right-sizing suggestions -- `costs` — cost attribution summary (if `--cloud-provider` set) -- `drift` — configuration drift issues (if `--cluster` set) -- `full_data_ref` — reference ID for retrieving full data -- `retrieval_hint` — exact command for drill-down - -To drill into specifics: ```bash -# Get high-severity findings sync-ctl retrieve --query "severity:high" - -# Get recommendations for a specific container sync-ctl retrieve --query "container:my-app" ``` -**Available query filters:** `severity:`, `container:` +**Available queries:** `severity:`, `container:` -## Safety +## Common Mistakes -- `--fix` only generates suggestions — it does NOT modify files -- `--apply` (requires `--fix`) writes changes to files — always confirm with user first -- `--dry-run` previews what `--apply` would do — use this to show the user before applying -- Recommend: always run `--fix --dry-run` first, show output, then `--fix --apply` only after user approval +| Mistake | Fix | +|---------|-----| +| Using `--apply` without showing dry-run first | Always `--fix --dry-run` first, confirm, then `--fix --apply` | +| Skipping `--cloud-provider` when user asks about costs | Cost estimation requires this flag | +| Running live cluster analysis without checking connectivity | Verify `kubectl cluster-info` first | ## Error Handling -| Error | Cause | Action | -|-------|-------|--------| -| `No Kubernetes manifests found` | No YAML with K8s resources | Run `sync-ctl analyze --agent` to check for K8s presence | -| `Cannot connect to cluster` | Invalid kubeconfig or cluster unreachable | Check `kubectl cluster-info` works, verify context name | -| `Prometheus unreachable` | Wrong URL or Prometheus not running | Verify URL, fall back to static analysis without `--prometheus` | - -## Examples - -**Quick static analysis:** -```bash -sync-ctl optimize . --agent -``` - -**Full analysis with live cluster and cost estimation:** -```bash -sync-ctl optimize . --cluster --cloud-provider aws --full --agent -``` - -**Preview fixes before applying:** -```bash -sync-ctl optimize . --fix --dry-run --agent -``` +| Error | Action | +|-------|--------| +| `No Kubernetes manifests found` | Run `sync-ctl analyze` to check for K8s presence | +| `Cannot connect to cluster` | Verify `kubectl cluster-info`, check context name | +| `Prometheus unreachable` | Verify URL, fall back to static analysis | diff --git a/skills/commands/syncable-platform.md b/skills/commands/syncable-platform.md index 6038f5e8..05588e0b 100644 --- a/skills/commands/syncable-platform.md +++ b/skills/commands/syncable-platform.md @@ -1,16 +1,14 @@ --- name: syncable-platform -description: Authenticate, login, sign in to Syncable platform. Switch organizations, projects, and environments. Deploy services to cloud providers. Check current context and manage platform settings using sync-ctl +description: Use when the user asks to log in to Syncable, authenticate, switch projects or organizations, check current context, deploy a service, check deployment status, or manage platform settings +allowed-tools: + - Bash +user-invocable: true --- -## Purpose +## Overview -Manage Syncable platform operations: authenticate, switch organizations/projects/environments by name, check current context, and trigger deployments. This skill handles the full platform lifecycle. - -## Prerequisites - -- `sync-ctl` binary installed and on PATH -- Internet access for Syncable API +Manage Syncable platform: authenticate, switch org/project/environment, check context, deploy services. ## Auth-First Rule @@ -20,183 +18,75 @@ Manage Syncable platform operations: authenticate, switch organizations/projects sync-ctl auth status ``` -If the response says "Not logged in" or "Session expired": - -```bash -sync-ctl auth login -``` +If not authenticated: `sync-ctl auth login` (opens browser for OAuth). Tell user a browser will open. Command blocks until authorized. -This opens a browser for OAuth device flow. Tell the user: "A browser window will open for you to authorize. If it doesn't open automatically, visit the URL shown and enter the code." Then wait — the command blocks until the user authorizes. +**Success criteria:** `sync-ctl auth status` shows authenticated. -## Switching Context +## Context Switching -### Switch project by name +### By name (org/project require list → match → select) -When user says "change project to my-app" or "use project my-app": - -1. List projects to find the ID: ```bash -sync-ctl project list -``` - -2. Parse the table output to find the row where NAME matches the user's request (case-insensitive, partial match OK). - -3. Select by ID: -```bash -sync-ctl project select -``` - -**If multiple matches:** show the user the matching projects and ask which one. -**If no matches:** tell the user no project with that name was found, and show available projects. - -### Switch organization by name - -When user says "switch org to acme" or "use organization acme": - -1. List organizations: -```bash -sync-ctl org list -``` +# Organization (switching clears project + env) +sync-ctl org list → find ID → sync-ctl org select -2. Parse output to find matching org name → ID. +# Project (requires UUID) +sync-ctl project list → find ID → sync-ctl project select -3. Select: -```bash -sync-ctl org select -``` - -**Note:** Switching org clears the current project and environment selection. After switching org, you'll need to select a project too. - -### Switch environment by name - -When user says "use staging" or "switch to production": - -```bash +# Environment (accepts name directly) sync-ctl env select ``` -Environment select accepts **names directly** (not just IDs). No need to list first. - -### Combined switches - -When user says "switch to my-app on staging": - -1. Find and select the project (list → match → select) -2. Then select the environment by name: -```bash -sync-ctl env select staging -``` - -When user says "switch to acme org, project my-app, staging env": - -1. `sync-ctl org list` → find acme → `sync-ctl org select ` -2. `sync-ctl project list` → find my-app → `sync-ctl project select ` -3. `sync-ctl env select staging` +Multiple matches: show user and ask. No matches: show available options. -## Checking Current Context - -When user says "what project am I on" or "show current context": +### Check current context ```bash sync-ctl project current ``` -Shows: organization, project, environment, and last updated timestamp. - ## Commands Reference -### Authentication - ```bash -sync-ctl auth status # Check if authenticated -sync-ctl auth login # Log in (opens browser) -sync-ctl auth login --no-browser # Log in without auto-opening browser -sync-ctl auth logout # Log out and clear credentials -sync-ctl auth token --raw # Print raw access token -``` +# Auth +sync-ctl auth status | login | login --no-browser | logout | token --raw -### Organizations - -```bash -sync-ctl org list # List all organizations -sync-ctl org select # Select organization (requires UUID) -``` +# Org +sync-ctl org list | org select -### Projects +# Project +sync-ctl project list | project select | project current | project info [ID] -```bash -sync-ctl project list # List projects in current org -sync-ctl project list --org-id # List projects in specific org -sync-ctl project select # Select project (requires UUID) -sync-ctl project current # Show current context -sync-ctl project info # Show current project details -sync-ctl project info # Show specific project details +# Environment +sync-ctl env list | env select ``` -### Environments - -```bash -sync-ctl env list # List environments in current project -sync-ctl env select # Select environment (accepts name or ID) -``` +## Deploy Flow (Agents) -### Deployment (non-interactive — use these as an agent) +### 1. Preview ```bash -# Preview deployment recommendation (returns JSON) -sync-ctl deploy preview -sync-ctl deploy preview --provider hetzner --region nbg1 +sync-ctl deploy preview --service-name my-service +``` -# Deploy with settings (triggers actual deployment) -sync-ctl deploy run --provider hetzner --region nbg1 --port 8080 --public -sync-ctl deploy run --env "NODE_ENV=production" --secret "DATABASE_URL" --env-file .env +**Success criteria:** JSON with `recommendation`, `connected_providers`, `alternatives`. -# Monitor deployment -sync-ctl deploy status -sync-ctl deploy status --watch +### 2. Confirm with user -# Interactive wizard (for humans, NOT usable by agents) -sync-ctl deploy wizard +Show: service name, provider, region, port, public/internal. If .env files found, list keys and ask which to include. -# Create a new environment -sync-ctl deploy new-env -``` +**CRITICAL:** NEVER deploy without preview + user confirmation. ONLY include env vars the user explicitly confirmed. -### Deploy Flow for Agents +### 3. Deploy -**Step 1: Preview** — get a recommendation as JSON: ```bash -sync-ctl deploy preview . --service-name my-service +sync-ctl deploy run --service-name --provider --region --port ``` -The output includes: -- `recommendation` — provider, region, machine type, port, health check, with reasoning -- `connected_providers` — all available providers -- `alternatives` — other options the user could choose -- `parsed_env_files` — discovered .env files and non-secret keys -- `deployed_service_endpoints` — URLs of already-deployed services (public and private) - -**Step 2: Show user the preview and get explicit confirmation.** Present: -- Service name, provider, region, machine type -- Port and whether public or internal -- If .env files found, list the keys and ask user which ones to include -- If deployed service endpoints exist, list them and ask which to wire up - -**CRITICAL RULES:** -- NEVER deploy without showing the preview first and getting user confirmation -- ONLY include env vars the user explicitly asked for or confirmed — do NOT auto-include discovered env vars or service endpoints -- If the user says "deploy with API_BASE=..." then ONLY set API_BASE, nothing else -- If the user wants additional env vars, they need to say so explicitly -- Always use `--service-name` to set the name the user wants, not the directory name - -**Step 3: Deploy** — with ONLY the settings the user confirmed: -```bash -sync-ctl deploy run . --service-name frontend-v2 --provider hetzner --region nbg1 --port 8080 --env "API_BASE=https://..." -``` +**Success criteria:** JSON with `config_id` and `task_id`. -Returns JSON with `config_id` and `task_id`. +### 4. Monitor -**Step 4: Monitor** — watch until complete: ```bash sync-ctl deploy status --watch ``` @@ -205,67 +95,29 @@ sync-ctl deploy status --watch | Flag | Purpose | |------|---------| -| `--service-name ` | Service name (ALWAYS set this — defaults to directory name otherwise) | +| `--service-name ` | Service name (always set) | | `--provider ` | Cloud provider | -| `--region ` | Deployment region (e.g., `nbg1`, `us-central1`) | -| `--machine-type ` | Machine type (e.g., `cx22`, `e2-small`) | +| `--region ` | Deployment region | | `--port ` | Port to expose | -| `--public` | Make service publicly accessible (default: internal-only) | -| `--cpu ` | CPU allocation for GCP/Azure (e.g., `1000m`) | -| `--memory ` | Memory allocation for GCP/Azure (e.g., `512Mi`) | +| `--public` | Publicly accessible (default: internal) | | `--env ` | Non-secret env var (repeatable) | -| `--secret ` | Secret key — user prompted in terminal for value (repeatable) | -| `--env-file ` | Load env vars from .env file (secrets auto-detected by key name) | -| `--min-instances ` | Minimum replicas | -| `--max-instances ` | Maximum replicas | +| `--secret ` | Secret (user prompted for value, repeatable) | +| `--env-file ` | Load from .env file | +| `--min-instances ` / `--max-instances ` | Replica range | -## Output Format +## Common Mistakes -All platform commands output human-readable text (no `--agent` mode). Parse the table output to extract IDs and names. Table format is typically: - -``` -ID NAME DESCRIPTION -------... -abc123-def456-... my-project My project description -``` +| Mistake | Fix | +|---------|-----| +| Auto-including discovered env vars without asking | ONLY set env vars the user explicitly requested | +| Deploying without preview | Always `deploy preview` first, show user, get confirmation | +| Using directory name as service name | Always set `--service-name` explicitly | ## Error Handling -| Error | Cause | Action | -|-------|-------|--------| -| `Not authenticated` | No valid session | Run `sync-ctl auth login` | -| `Token expired` | Session timed out | Run `sync-ctl auth login` | -| `No organization selected` | Org not set | Run `sync-ctl org list` then `sync-ctl org select ` | -| `No project selected` | Project not set | Run `sync-ctl project list` then `sync-ctl project select ` | -| `No environment selected` | Env not set | Run `sync-ctl env list` then `sync-ctl env select ` | -| `Project not found` | Wrong ID | Run `sync-ctl project list` to see available projects | -| `Deployment failed` | Build or infra error | Check `sync-ctl deploy status ` for details | - -## Examples - -**User: "change project to my-app"** -```bash -sync-ctl auth status # Check auth first -sync-ctl project list # Find my-app's ID -sync-ctl project select # Select it -``` - -**User: "switch to staging"** -```bash -sync-ctl env select staging -``` - -**User: "switch to acme org and select the api-gateway project on production"** -```bash -sync-ctl auth status -sync-ctl org list # Find acme's ID -sync-ctl org select -sync-ctl project list # Find api-gateway's ID -sync-ctl project select -sync-ctl env select production -``` - -**User: "what am I connected to?"** -```bash -sync-ctl project current -``` +| Error | Action | +|-------|--------| +| `Not authenticated` / `Token expired` | `sync-ctl auth login` | +| `No organization selected` | `sync-ctl org list` then `org select ` | +| `No project selected` | `sync-ctl project list` then `project select ` | +| `Deployment failed` | `sync-ctl deploy status ` for details | diff --git a/skills/commands/syncable-security.md b/skills/commands/syncable-security.md index 63824610..77720f9c 100644 --- a/skills/commands/syncable-security.md +++ b/skills/commands/syncable-security.md @@ -1,111 +1,71 @@ --- name: syncable-security -description: Scan code for leaked secrets, credentials, API keys, hardcoded passwords, and insecure code patterns using the Syncable CLI sync-ctl security scanner +description: Use when the user asks to scan for secrets, find leaked credentials, check for API keys in code, detect hardcoded passwords, review code security, or run a secrets scan +allowed-tools: + - Bash +user-invocable: true --- -## Purpose +## Overview -Perform security analysis on a codebase: detect leaked secrets (API keys, tokens, passwords, private keys), identify insecure code patterns, and analyze configuration security. Returns findings with severity levels, file locations, and remediation guidance. +Scan a codebase for leaked secrets (API keys, tokens, passwords, private keys), insecure code patterns, and configuration issues. Returns findings with severity, file locations, and remediation. -## Prerequisites +## Mode Selection -- `sync-ctl` binary installed and on PATH -- Agent has access to the project directory +Always pass `--mode` explicitly: -## Commands +| Mode | When to use | +|------|------------| +| `lightning` | Quick check, critical files only (.env, configs) | +| `fast` | Smart sampling, large repos during development | +| `balanced` | **Default.** Good coverage with optimizations | +| `thorough` | Pre-deployment, PR security reviews | +| `paranoid` | Compliance audits, production reviews | -### Standard security scan - -```bash -sync-ctl security --mode balanced --agent -``` - -### Mode Selection Guide - -Always pass `--mode` explicitly. Choose based on context: - -| Mode | When to use | Speed | -|------|------------|-------| -| `lightning` | Quick check, only critical files (.env, configs) | Fastest | -| `fast` | Smart sampling, good for large repos during development | Fast | -| `balanced` | **Default choice.** Good coverage with optimizations | Medium | -| `thorough` | Pre-deployment reviews, PR security checks | Slow | -| `paranoid` | Compliance audits, production security reviews | Slowest | - -### Key Flags +## Flags | Flag | Purpose | |------|---------| -| `--mode {lightning\|fast\|balanced\|thorough\|paranoid}` | Scan depth (always specify) | -| `--agent` | Compressed output for agent consumption (always use when processing results) | -| `--include-low` | Include low-severity findings (off by default) | -| `--no-secrets` | Skip secrets detection (only code patterns) | -| `--no-code-patterns` | Skip code pattern analysis (only secrets) | -| `--fail-on-findings` | Exit with error code if findings exist (for CI) | +| `--mode ` | Scan depth (always specify) | +| `--agent` | Compressed output (always use) | +| `--include-low` | Include low-severity findings | +| `--no-secrets` | Skip secrets detection (code patterns only) | +| `--no-code-patterns` | Skip code patterns (secrets only) | +| `--fail-on-findings` | Exit with error code if findings exist (CI) | | `--output ` | Write report to file | -## Output Interpretation +## Steps -**Priority for reporting to user:** -1. Critical findings first (leaked secrets, hardcoded credentials) -2. High findings (insecure patterns) -3. Summary with score -4. Remediation steps for top findings +### 1. Run scan -## Reading Results +```bash +sync-ctl security --mode balanced --agent +``` -When you use `--agent`, the output is a **compressed summary** — NOT the full data. Only critical and high findings are inline. To get medium/low details, you MUST use `sync-ctl retrieve`. +**Success criteria:** JSON output with `summary` containing severity counts. -**What's in the compressed output:** -- `summary` — counts by severity -- `critical_issues` — full details for every critical finding -- `high_issues` — first 10 high-severity findings -- `patterns` — deduplicated medium/low findings as counts only (NO individual details) -- `full_data_ref` — reference ID for the full stored data +### 2. Report to user -**IMPORTANT: Do NOT try to extract medium/low details from the compressed output. Use retrieve instead.** +Priority order: critical findings (leaked secrets) > high (insecure patterns) > summary score > remediation steps. + +### 3. Retrieve details (if needed) + +Compressed output only includes critical + first 10 high findings. Medium/low are counts only. Use retrieve for details: ```bash -# Get medium-severity findings sync-ctl retrieve --query "severity:medium" - -# Get findings for a specific file sync-ctl retrieve --query "file:src/auth.rs" - -# Get findings by rule code sync-ctl retrieve --query "code:hardcoded-secret" ``` -Results are paginated (default 20). Use `--limit N --offset M` for more. +Results paginated (default 20). Use `--limit N --offset M` for more. -**Available query filters:** `severity:critical|high|medium|low|info`, `file:`, `code:` +**Available queries:** `severity:critical|high|medium|low|info`, `file:`, `code:` ## Error Handling -| Error | Cause | Action | -|-------|-------|--------| -| `No such file or directory` | Invalid path | Ask user to verify the project path | -| Very slow scan | Large repo with `thorough`/`paranoid` mode | Suggest trying `balanced` or `fast` mode first | -| No findings | Clean project or scan mode too light | If `lightning`/`fast`, suggest re-running with `balanced` for deeper coverage | - -## Examples - -**Quick secrets check on current directory:** -```bash -sync-ctl security . --mode balanced --agent -``` - -**Deep pre-deploy audit:** -```bash -sync-ctl security . --mode paranoid --agent -``` - -**Secrets-only scan (skip code patterns):** -```bash -sync-ctl security . --mode thorough --no-code-patterns --agent -``` - -**Save report to file:** -```bash -sync-ctl security . --mode thorough --agent --output security-report.json -``` +| Error | Action | +|-------|--------| +| `No such file or directory` | Ask user to verify path | +| Very slow scan | Suggest `balanced` or `fast` mode instead | +| No findings with `lightning`/`fast` | Re-run with `balanced` for deeper coverage | diff --git a/skills/commands/syncable-validate.md b/skills/commands/syncable-validate.md index f2e0fa47..3d3e9db0 100644 --- a/skills/commands/syncable-validate.md +++ b/skills/commands/syncable-validate.md @@ -1,120 +1,60 @@ --- name: syncable-validate -description: Lint and validate Dockerfiles, Docker Compose files, Kubernetes manifests, Helm charts, and Terraform configs using the Syncable CLI sync-ctl tool +description: Use when the user asks to validate Dockerfiles, lint Docker Compose files, check Kubernetes manifests, validate Terraform configs, lint IaC files, or review infrastructure-as-code +allowed-tools: + - Bash +user-invocable: true --- -## Purpose +## Overview -Validate Infrastructure-as-Code files against best practices. Covers Dockerfiles (via native hadolint), Docker Compose files (via native dclint), and Terraform configurations. Reports violations with severity, file locations, and auto-fix suggestions. +Validate IaC files against best practices. Covers Dockerfiles (hadolint), Docker Compose (dclint), and Terraform. Reports violations with severity, locations, and auto-fix suggestions. -## Prerequisites - -- `sync-ctl` binary installed and on PATH -- Agent has access to the project directory -- Project must contain IaC files (Dockerfiles, docker-compose.yml, *.tf files) - -## Commands - -### Validate all IaC files in a directory - -```bash -sync-ctl validate --agent -``` - -### Validate specific types only - -```bash -sync-ctl validate --types dockerfile --agent -sync-ctl validate --types dockerfile,compose --agent -sync-ctl validate --types terraform --agent -``` - -### Auto-fix issues where possible - -```bash -sync-ctl validate --fix -``` - -### Key Flags +## Flags | Flag | Purpose | |------|---------| -| `--agent` | Compressed output for agent consumption (always use when processing results) | -| `--types ` | Filter to specific IaC types: `dockerfile`, `compose`, `terraform` | -| `--fix` | Automatically fix issues where possible | +| `--agent` | Compressed output (always use) | +| `--types ` | Filter: `dockerfile`, `compose`, `terraform` (comma-separated) | +| `--fix` | Auto-fix issues where possible | -**Note:** The `--agent` flag is available for structured output. When `--agent` is not used, output is terminal text with structured lint violations. +## What Gets Checked -## Output Interpretation +| Type | Linter | Examples | +|------|--------|----------| +| Dockerfile | hadolint (Rust) | Pin versions, avoid `latest`, COPY not ADD | +| Docker Compose | dclint (Rust) | Service naming, volumes, networks (15 rules) | +| Terraform | Terraform validator | Syntax, providers, resource definitions | -Output contains lint violations, each with: +## Steps -- **file** — path to the IaC file -- **line** — line number of the violation -- **rule** — rule ID (e.g., DL3006 for hadolint, DCL001 for dclint) -- **severity** — Error, Warning, Info -- **message** — description of the issue -- **fix** — suggested fix (if available) +### 1. Run validation -**What gets checked:** +```bash +sync-ctl validate --agent +``` -| Type | Linter | Example checks | -|------|--------|---------------| -| Dockerfile | hadolint (native Rust) | Pin versions, avoid `latest` tag, use COPY not ADD, multi-stage best practices | -| Docker Compose | dclint (native Rust) | Service naming, volume declarations, network configuration, 15 configurable rules | -| Terraform | Terraform validator | Syntax validation, provider configuration, resource definitions | +**Success criteria:** JSON output with `status` field (`ERRORS_FOUND`, `WARNINGS_ONLY`, or `CLEAN`). -**Priority for reporting to user:** -1. Errors first — these will cause build/deploy failures -2. Warnings — best practice violations -3. Info — suggestions for improvement +### 2. Report to user -## Reading Results +Priority: errors (build/deploy failures) > warnings (best practice violations) > info (suggestions). -When you use `--agent`, the output is a compressed summary. All **error**-severity violations are included in full detail. Warnings are deduplicated into patterns. +### 3. Retrieve details (if needed) -The output JSON includes: -- `status` — e.g., "ERRORS_FOUND", "WARNINGS_ONLY", "CLEAN" -- `summary` — counts by severity -- `errors` — full details for every error-severity finding -- `patterns` — deduplicated warning/info findings with counts -- `full_data_ref` — reference ID for retrieving full data -- `retrieval_hint` — exact command for drill-down +Compressed output includes all errors in full. Warnings are deduplicated counts: -To drill into specifics: ```bash -# Get all error-severity findings sync-ctl retrieve --query "severity:high" - -# Get findings for a specific file sync-ctl retrieve --query "file:Dockerfile" - -# Get findings by rule code sync-ctl retrieve --query "code:DL3006" ``` -**Available query filters:** `severity:`, `file:`, `code:` +**Available queries:** `severity:`, `file:`, `code:` ## Error Handling -| Error | Cause | Action | -|-------|-------|--------| -| `No IaC files found` | Directory has no Dockerfiles, Compose, or Terraform files | Run `sync-ctl analyze --agent` to verify what IaC exists | -| `Unknown type` | Invalid `--types` value | Valid types are: `dockerfile`, `compose`, `terraform` | - -## Examples - -**Lint all IaC in current directory:** -```bash -sync-ctl validate . --agent -``` - -**Lint only Dockerfiles:** -```bash -sync-ctl validate . --types dockerfile --agent -``` - -**Auto-fix Docker Compose issues:** -```bash -sync-ctl validate . --types compose --fix -``` +| Error | Action | +|-------|--------| +| `No IaC files found` | Run `sync-ctl analyze --agent` to verify what IaC exists | +| `Unknown type` | Valid types: `dockerfile`, `compose`, `terraform` | diff --git a/skills/commands/syncable-vulnerabilities.md b/skills/commands/syncable-vulnerabilities.md index 1e04f4fe..fdbe1474 100644 --- a/skills/commands/syncable-vulnerabilities.md +++ b/skills/commands/syncable-vulnerabilities.md @@ -1,107 +1,55 @@ --- name: syncable-vulnerabilities -description: Check project dependencies for known CVEs and security vulnerabilities across npm, pip, cargo, and go ecosystems using the Syncable CLI sync-ctl tool +description: Use when the user asks to check for CVEs, scan dependencies for vulnerabilities, find known security issues in packages, or audit npm/pip/cargo/go/java dependency security +allowed-tools: + - Bash +user-invocable: true --- -## Purpose +## Overview -Scan project dependencies for known CVEs (Common Vulnerabilities and Exposures) across npm, pip, cargo, go, and java ecosystems. Returns vulnerable packages with severity, affected versions, and available fixes. +Scan project dependencies for known CVEs across npm, pip, cargo, go, and java ecosystems. Returns vulnerable packages with severity, affected versions, and available fixes. -## Prerequisites +## Flags -- `sync-ctl` binary installed and on PATH -- Agent has access to the project directory -- Language-specific scanning tools should be installed. If a scan fails with "tool not found", run `sync-ctl tools install` to install missing scanners. +| Flag | Purpose | +|------|---------| +| `--agent` | Compressed output (always use) | +| `--severity {low\|medium\|high\|critical}` | Minimum severity threshold | +| `--output ` | Write report to file | -## Commands +## Steps -### Scan for vulnerabilities +### 1. Run vulnerability scan ```bash sync-ctl vulnerabilities --agent ``` -### Filter by severity +**Success criteria:** JSON output with `summary` containing severity counts. -```bash -sync-ctl vulnerabilities --severity high --agent -``` +### 2. Report to user -### Key Flags +Priority: critical/high CVEs with fixes (actionable) > critical/high without fixes (risk flag) > medium/low (mention count only, don't enumerate unless asked). -| Flag | Purpose | -|------|---------| -| `--agent` | Compressed output for agent consumption (always use) | -| `--severity {low\|medium\|high\|critical}` | Only show findings at or above this severity | -| `--output ` | Write report to file | +### 3. Retrieve details (if needed) -## Output Interpretation +Compressed output includes critical + first 10 high findings. Medium/low are counts only: -**Priority for reporting to user:** -1. Critical/High CVEs with available fixes — actionable immediately -2. Critical/High CVEs without fixes — flag as risk -3. Medium/Low — mention count, don't enumerate unless asked - -## Reading Results - -When you use `--agent`, the output is a **compressed summary** — NOT the full data. Only critical and high findings are inline. To get medium/low details, you MUST use `sync-ctl retrieve`. - -**What's in the compressed output:** -- `summary` — counts by severity (total, critical, high, medium, low) -- `critical_issues` — full details for every critical finding -- `high_issues` — first 10 high-severity findings (full detail) -- `patterns` — deduplicated medium/low findings as counts only (NO individual details) -- `full_data_ref` — reference ID for the full stored data -- `retrieval_hint` — exact command for drill-down - -**IMPORTANT: Do NOT try to extract medium/low details from the compressed output. They are only available via retrieve.** - -To get individual findings by severity: ```bash -# Get medium-severity findings (NOT in compressed output — must use retrieve) sync-ctl retrieve --query "severity:medium" - -# Get low-severity findings sync-ctl retrieve --query "severity:low" - -# Get high-severity findings (also in compressed output, but retrieve gives all of them) -sync-ctl retrieve --query "severity:high" - -# Get findings for a specific source directory sync-ctl retrieve --query "file:services/api" ``` -Results are paginated (default 20). Use `--limit N --offset M` for more. +Results paginated (default 20). Use `--limit N --offset M` for more. -**Available query filters:** `severity:`, `file:` +**Available queries:** `severity:`, `file:` ## Error Handling -| Error | Cause | Action | -|-------|-------|--------| -| `tool not found` or scanner missing | Language-specific audit tool not installed | Run `sync-ctl tools install` to install missing scanners, then retry | -| `No dependencies found` | No package manager files detected | Run `sync-ctl analyze --agent` first to verify the project has dependencies | -| Timeout | Very large dependency tree | Try scanning specific subdirectories in a monorepo | - -## Examples - -**Scan current project:** -```bash -sync-ctl vulnerabilities . --agent -``` - -**Only critical and high severity:** -```bash -sync-ctl vulnerabilities . --severity high --agent -``` - -**Save report:** -```bash -sync-ctl vulnerabilities . --agent --output vuln-report.json -``` - -**Install missing scanners first:** -```bash -sync-ctl tools install --yes -sync-ctl vulnerabilities . --agent -``` +| Error | Action | +|-------|--------| +| `tool not found` / scanner missing | Run `sync-ctl tools install --yes`, then retry | +| `No dependencies found` | Run `sync-ctl analyze --agent` first to verify dependencies exist | +| Timeout on large dep tree | Try scanning specific subdirectories | diff --git a/skills/workflows/syncable-deploy-pipeline.md b/skills/workflows/syncable-deploy-pipeline.md index eeccef79..4b09e484 100644 --- a/skills/workflows/syncable-deploy-pipeline.md +++ b/skills/workflows/syncable-deploy-pipeline.md @@ -1,140 +1,110 @@ --- name: syncable-deploy-pipeline -description: Deploy a project through Syncable by orchestrating authentication, project analysis, security gating, and cloud deployment using the Syncable CLI sync-ctl tool +description: Use when the user asks to deploy through Syncable, ship to production, push to staging, run a deploy pipeline, or deploy a service with security checks first +allowed-tools: + - Bash +user-invocable: true --- -## Purpose +## Overview -Orchestrate a full deployment pipeline through the Syncable platform: authenticate, analyze the project, run a security audit as a gate, then deploy. Ensures no deployment happens without authentication and security review. +Full deployment pipeline: authenticate → analyze → security gate → deploy. No deployment without auth and security review. -## Prerequisites +## Steps -- `sync-ctl` binary installed and on PATH -- Internet access for Syncable API -- Agent has access to the project directory - -## Workflow Steps - -### Step 1: Check authentication and platform context +### 1. Check auth and context ```bash sync-ctl auth status ``` -**Decision point:** If not authenticated: -```bash -sync-ctl auth login -``` +If not authenticated: `sync-ctl auth login` -Then verify project/environment context: ```bash sync-ctl project current ``` -**Decision point:** If no project selected: -```bash -sync-ctl org list -# Ask user which org -sync-ctl org select -sync-ctl project list -# Ask user which project -sync-ctl project select -sync-ctl env list -# Ask user which environment -sync-ctl env select -``` +If no project/env selected: guide user through `org list` → `org select` → `project list` → `project select` → `env select`. -### Step 2: Analyze the project +**Success criteria:** Authenticated with org/project/env selected. + +### 2. Analyze the project ```bash sync-ctl analyze --agent ``` -Save the `full_data_ref` from the analyze output — do not re-run analyze in later steps; use `sync-ctl retrieve` with this ref_id instead. +Save `full_data_ref`. Do NOT re-run analyze in later steps. + +**Success criteria:** JSON with summary. You know IaC types and dependencies present. + +### 3. Pre-deploy security audit -### Step 3: Pre-deploy security audit +Reuse step 2's analysis — do NOT re-run analyze. -Execute the `syncable-security-audit` workflow inline (all its steps and decision logic). **Note:** Step 2's analyze output is reused here — do not re-run analyze. +```bash +sync-ctl security --mode paranoid --agent +sync-ctl vulnerabilities --agent # skip if no deps in step 2 +sync-ctl validate --agent # skip if no IaC in step 2 +``` -1. `sync-ctl security --mode paranoid --agent` -2. `sync-ctl vulnerabilities --agent` -3. `sync-ctl validate ` (if IaC files exist per Step 2's analysis) +**CRITICAL GATE — check security `status` field:** +- `CRITICAL_ISSUES_FOUND` → present findings, warn, **require explicit confirmation** +- `HIGH_ISSUES_FOUND` → warn, allow deployment +- `CLEAN` → proceed -**CRITICAL GATE:** Check the security output's `status` field: -- If `status` is "CRITICAL_ISSUES_FOUND": present findings to user, warn, require confirmation -- If `status` is "HIGH_ISSUES_FOUND": warn but allow deployment -- If `status` is "CLEAN": proceed to deploy +Critical findings are in `critical_issues` array — no retrieval needed for the gate. -All critical findings are in the `critical_issues` array of the compressed output — no retrieval needed for the gate decision. +**Success criteria:** Security verdict determined. User informed of any findings. -### Step 4: Deploy +### 4. Deploy -**4a. Get deployment recommendation:** +**4a. Preview:** ```bash -sync-ctl deploy preview +sync-ctl deploy preview --service-name ``` -This returns JSON with: provider recommendation (with reasoning), region, machine type, detected port, health check endpoint, alternatives, discovered .env files, and already-deployed service endpoints. - -**4b. Present recommendation to user and confirm.** Show: -- Recommended provider, region, machine type -- Detected port and whether public/internal -- Any .env files found — ask if they should be injected -- Any service endpoints that could be referenced (e.g., `BACKEND_URL`) +**4b. Confirm with user.** Show: provider, region, port, public/internal, .env keys found. -**4c. Deploy with confirmed settings:** +**4c. Deploy with ONLY confirmed settings:** ```bash -sync-ctl deploy run --provider --region --port +sync-ctl deploy run --service-name --provider --region --port ``` -Add `--public` if user wants a public URL. Add `--env KEY=VALUE` for env vars and `--secret KEY` for secrets (user prompted in terminal). Add `--env-file .env` to inject from file. - **4d. Monitor:** ```bash sync-ctl deploy status --watch ``` -**Example with user overrides:** -```bash -# User said "deploy to GCP in us-central1, make it public, use the .env file" -sync-ctl deploy run ./services/api \ - --provider gcp --region us-central1 --port 8080 --public \ - --env-file .env \ - --secret "STRIPE_KEY" -``` +**Success criteria:** Deployment completes successfully per status output. -## Decision Points Summary +## The Security Gate is Non-Negotiable + +| Excuse | Reality | +|--------|---------| +| "User said just deploy, skip security" | Run at minimum `--mode fast`. The gate exists because users underestimate risk. | +| "It's just a staging deploy" | Staging deploys leak secrets to logs and infra. Always scan. | +| "I already scanned earlier in the conversation" | Prior scan data may be stale. This pipeline runs its own scan. | +| "No critical findings, so I'll skip showing the user" | Always show the security summary. User needs to see CLEAN verdicts too. | + +## Decision Points | Condition | Action | |-----------|--------| -| Not authenticated | Run `sync-ctl auth login` first | +| Not authenticated | `sync-ctl auth login` | | No project/env selected | Guide user through selection | -| Critical security findings | Warn user, require explicit confirmation to proceed | -| High security findings (no critical) | Warn user but allow deployment | -| Clean security audit | Proceed to deploy | - -## Safety +| Critical findings | Warn, require explicit confirmation | +| High findings (no critical) | Warn, allow deployment | +| Clean audit | Proceed | -- **Never deploy without the security gate.** Even if the user says "just deploy", run at least a fast security scan. -- **Always confirm with the user before triggering deployment.** Show them what will be deployed, to which environment. -- **Monitor deployment status** after triggering — don't fire-and-forget. +## Common Mistakes -## Cross-Step Retrieval +| Mistake | Fix | +|---------|-----| +| Deploying without preview + confirmation | Always `deploy preview` → show user → confirm → `deploy run` | +| Auto-including discovered env vars | ONLY include env vars user explicitly confirmed | +| Fire-and-forget after `deploy run` | Always monitor with `deploy status --watch` | -Each step produces a `full_data_ref` in its output. You can retrieve details from any previous step at any time: - -```bash -# Check what data is available from all steps -sync-ctl retrieve --list - -# Get framework details from Step 2 (analyze) -sync-ctl retrieve --query "section:frameworks" - -# Get critical security findings from Step 3 -sync-ctl retrieve --query "severity:critical" - -# Get vulnerability details from Step 3 -sync-ctl retrieve --query "severity:high" -``` +## Retrieval -Do NOT re-run a command just to get more detail — use `sync-ctl retrieve` instead. +Save each step's `full_data_ref`. Use `sync-ctl retrieve --query "..."` for drill-down. Do NOT re-run commands. diff --git a/skills/workflows/syncable-iac-pipeline.md b/skills/workflows/syncable-iac-pipeline.md index a455aae8..fded5342 100644 --- a/skills/workflows/syncable-iac-pipeline.md +++ b/skills/workflows/syncable-iac-pipeline.md @@ -1,86 +1,72 @@ --- name: syncable-iac-pipeline -description: Validate all infrastructure-as-code files by combining Dockerfile linting, Docker Compose validation, Kubernetes manifest checking, and Helm chart analysis using the Syncable CLI sync-ctl tool +description: Use when the user asks to validate all infrastructure files, run an IaC review, check Docker/Compose/K8s/Terraform/Helm files together, or lint infrastructure-as-code +allowed-tools: + - Bash +user-invocable: true --- -## Purpose +## Overview -Validate all infrastructure-as-code files in a project by chaining IaC linting with Kubernetes optimization and security checks. Covers Dockerfiles, Docker Compose, Terraform, K8s manifests, and Helm charts. +Chain analyze + validate + K8s optimize for a complete IaC review. Covers Dockerfiles, Compose, Terraform, K8s manifests, and Helm charts. -## Prerequisites +## Steps -- `sync-ctl` binary installed and on PATH -- Agent has access to the project directory -- Project must contain IaC files - -## Workflow Steps - -### Step 1: Analyze the project +### 1. Analyze the project ```bash sync-ctl analyze --agent ``` -Parse the output to determine: -- Which IaC types exist (Dockerfile, Compose, Terraform, K8s manifests) -- Whether K8s manifests are present — needed for step 3 +Determine: which IaC types exist, whether K8s manifests/Helm charts present (gates step 3). Save `full_data_ref`. -Save the `full_data_ref` from the analyze output — the ref_id from this step can be reused in later steps to retrieve IaC file details without re-running analyze. +**Success criteria:** You know which IaC types are present. If NO IaC files at all → abort workflow, tell user. -### Step 2: Validate IaC files +### 2. Validate IaC files ```bash -sync-ctl validate +sync-ctl validate --agent ``` -If step 1 revealed specific types, you can filter: -```bash -sync-ctl validate --types dockerfile,compose,terraform -``` +Filter if types known from step 1: `--types dockerfile,compose,terraform` + +**Success criteria:** JSON with `status` field and violations by severity. -### Step 3: Kubernetes optimization (conditional) +### 3. Kubernetes optimization (conditional) -**Decision point:** Only run if step 1 detected Kubernetes manifests or Helm charts. +**Decision:** Only run if step 1 detected K8s manifests or Helm charts. ```bash sync-ctl optimize --full --agent ``` -The `--full` flag includes kubelint security checks and helmlint validation on top of resource optimization. +`--full` includes kubelint security + helmlint validation + resource optimization. -## Decision Points Summary +**Success criteria:** JSON with recommendations, or step skipped with reason. + +## Decision Points | Condition | Action | |-----------|--------| -| No K8s manifests or Helm charts in step 1 | Skip step 3 | -| No IaC files at all in step 1 | Abort workflow, tell user no IaC files found | +| No IaC files at all | Abort, tell user | +| No K8s/Helm in step 1 | Skip step 3 | ## Report Synthesis -Produce an IaC validation report: - 1. **Dockerfile Issues** — hadolint violations by severity 2. **Docker Compose Issues** — dclint violations 3. **Terraform Issues** — validation errors -4. **Kubernetes Issues** — kubelint security findings and resource optimization recommendations (if step 3 ran) +4. **Kubernetes Issues** — kubelint findings + resource optimization (if step 3 ran) 5. **Actionable Fixes** — which issues can be auto-fixed with `--fix` -## Cross-Step Retrieval +## Retrieval -Each step produces a `full_data_ref` in its output. You can retrieve details from any previous step at any time: +Save each step's `full_data_ref`. Use `sync-ctl retrieve --query "..."` for drill-down: ```bash -# Check what data is available from all steps -sync-ctl retrieve --list - -# Get framework details from Step 1 (analyze) -sync-ctl retrieve --query "section:frameworks" - -# Get critical security findings from Step 2 -sync-ctl retrieve --query "severity:critical" - -# Get vulnerability details from Step 3 -sync-ctl retrieve --query "severity:high" +sync-ctl retrieve --query "severity:high" +sync-ctl retrieve --query "file:Dockerfile" +sync-ctl retrieve --query "container:my-app" ``` -Do NOT re-run a command just to get more detail — use `sync-ctl retrieve` instead. +Do NOT re-run commands for more detail. diff --git a/skills/workflows/syncable-project-assessment.md b/skills/workflows/syncable-project-assessment.md index 23e0e343..a963c44f 100644 --- a/skills/workflows/syncable-project-assessment.md +++ b/skills/workflows/syncable-project-assessment.md @@ -1,105 +1,77 @@ --- name: syncable-project-assessment -description: Run a comprehensive project health check combining stack analysis, security scanning, vulnerability detection, and dependency auditing using the Syncable CLI sync-ctl tool +description: Use when the user asks to assess a project, run a health check, get an overview of project status, evaluate project health, or wants a comprehensive report covering stack, security, vulnerabilities, and dependencies +allowed-tools: + - Bash +user-invocable: true --- -## Purpose +## Overview -Run a comprehensive project health check by chaining multiple Syncable CLI commands. Produces a unified report covering tech stack, security posture, vulnerability status, and dependency health. +Chain analyze + security + vulnerabilities + dependencies into a unified health report. Each step informs the next via decision points. -## Prerequisites +## Steps -- `sync-ctl` binary installed and on PATH -- Agent has access to the project directory - -## Workflow Steps - -### Step 1: Analyze the project stack +### 1. Analyze the project stack ```bash sync-ctl analyze --agent ``` -Parse the output to understand: -- What languages and frameworks are present -- Whether dependencies exist (needed for steps 3 and 4) -- Whether secrets-capable files exist (affects step 2 mode) +Parse output for: languages, frameworks, whether dependencies exist (gates steps 3-4), whether secrets-capable files exist (gates step 2 mode). Save `full_data_ref`. -Save the `full_data_ref` from the analyze output — you'll use it to retrieve details without re-running analyze. +**Success criteria:** JSON with `summary` field. You know what languages, frameworks, and dependency files are present. -### Step 2: Security scan +### 2. Security scan ```bash sync-ctl security --mode balanced --agent ``` -**Decision point:** If step 1 shows no config files, secrets files, or environment files, use `--mode lightning` instead of `--mode balanced` to save time. +**Decision:** No config/secrets/env files in step 1 → use `--mode lightning` instead. + +**Success criteria:** JSON with severity counts. All critical/high findings captured. -### Step 3: Vulnerability scan +### 3. Vulnerability scan ```bash sync-ctl vulnerabilities --agent ``` -**Decision point:** If step 1 detected no dependencies (no package.json, requirements.txt, Cargo.toml, go.mod, etc.), **skip this step entirely** and note "No dependencies detected" in the report. +**Decision:** No dependencies detected in step 1 → **skip entirely**, note "No dependencies detected" in report. + +If scanner missing: `sync-ctl tools install --yes`, then retry. + +**Success criteria:** JSON with CVE counts by severity, or step skipped with documented reason. -### Step 4: Dependency audit +### 4. Dependency audit ```bash sync-ctl dependencies --licenses --agent ``` -**Decision point:** Same as step 3 — skip if no dependencies detected. +**Decision:** Same as step 3 — skip if no dependencies. -## Decision Points Summary +**Success criteria:** JSON with total count, prod/dev split, license distribution, or step skipped. + +## Decision Points | Condition | Action | |-----------|--------| -| No dependencies detected in step 1 | Skip steps 3 and 4 | +| No dependencies in step 1 | Skip steps 3 and 4 | | No secrets-capable files in step 1 | Use `--mode lightning` in step 2 | -| Vulnerability scanner missing | Run `sync-ctl tools install --yes`, then retry step 3 | +| Vulnerability scanner missing | `sync-ctl tools install --yes`, retry | ## Report Synthesis -After all steps complete, synthesize a unified report for the user: +After all steps, synthesize ONE report: 1. **Tech Stack** — primary language, frameworks, runtimes -2. **Security Score** — score from security scan, critical/high finding count -3. **Vulnerabilities** — critical/high CVE count, packages with available fixes -4. **Dependencies** — total count, license concerns (copyleft, unknown) -5. **Recommendations** — top 3-5 actionable items prioritized by severity - -## Examples - -**Assess current directory:** - -The agent runs these commands in sequence, skipping steps based on decision points: - -```bash -sync-ctl analyze . --agent -sync-ctl security . --mode balanced --agent -sync-ctl vulnerabilities . --agent -sync-ctl dependencies . --licenses --agent -``` - -Then synthesizes the results into a single report for the user. - -## Cross-Step Retrieval - -Each step produces a `full_data_ref` in its output. You can retrieve details from any previous step at any time: +2. **Security Score** — score, critical/high count +3. **Vulnerabilities** — critical/high CVE count, packages with fixes +4. **Dependencies** — total count, license concerns +5. **Recommendations** — top 3-5 actions by severity -```bash -# Check what data is available from all steps -sync-ctl retrieve --list - -# Get framework details from Step 1 (analyze) -sync-ctl retrieve --query "section:frameworks" - -# Get critical security findings from Step 2 -sync-ctl retrieve --query "severity:critical" - -# Get vulnerability details from Step 3 -sync-ctl retrieve --query "severity:high" -``` +## Retrieval -Do NOT re-run a command just to get more detail — use `sync-ctl retrieve` instead. +Save each step's `full_data_ref`. Use `sync-ctl retrieve --query "..."` for drill-down. Do NOT re-run commands for more detail. diff --git a/skills/workflows/syncable-security-audit.md b/skills/workflows/syncable-security-audit.md index 5a1cbfec..03ba4691 100644 --- a/skills/workflows/syncable-security-audit.md +++ b/skills/workflows/syncable-security-audit.md @@ -1,101 +1,90 @@ --- name: syncable-security-audit -description: Perform a thorough pre-deployment or compliance security review combining deep security scan, CVE checks, and IaC validation using the Syncable CLI sync-ctl tool +description: Use when the user asks for a security audit, pre-deployment security review, compliance check, thorough security assessment before shipping, or deep security scan for production readiness +allowed-tools: + - Bash +user-invocable: true --- -## Purpose +## Overview -Perform a deep, multi-layered security review suitable for pre-deployment gates or compliance audits. Goes deeper than the project assessment by using thorough/paranoid scan modes and including IaC validation. +Deep multi-layered security review for pre-deployment gates or compliance. Uses thorough/paranoid scan modes and includes IaC validation. Stricter than project-assessment. -## Prerequisites +## Steps -- `sync-ctl` binary installed and on PATH -- Agent has access to the project directory - -## Workflow Steps - -### Step 1: Analyze the project +### 1. Analyze the project ```bash sync-ctl analyze --agent ``` -Parse the output to determine: -- What IaC files exist (Dockerfiles, Compose, Terraform, K8s manifests) — needed for step 4 -- What dependencies exist — needed for step 3 +Determine: IaC files present (gates step 4), dependencies present (gates step 3). Save `full_data_ref`. -Save the `full_data_ref` from the analyze output — you'll use it to retrieve details without re-running analyze. +**Success criteria:** You know which IaC types and dependency files exist. -### Step 2: Deep security scan +### 2. Deep security scan -Choose mode based on context: - -**For PR reviews / pre-merge:** +**PR review / pre-merge:** ```bash sync-ctl security --mode thorough --agent ``` -**For production deployment / compliance:** +**Production / compliance:** ```bash sync-ctl security --mode paranoid --agent ``` -### Step 3: Vulnerability scan +**Success criteria:** JSON with severity counts. All critical/high findings captured with file locations. + +### 3. Vulnerability scan ```bash sync-ctl vulnerabilities --agent ``` -### Step 4: IaC validation +**Decision:** No dependencies in step 1 → skip, note in report. -**Decision point:** Only run if step 1 detected Docker, Compose, Terraform, or K8s files. +**Success criteria:** CVE counts by severity captured. -```bash -sync-ctl validate -``` +### 4. IaC validation -If specific types are known from step 1, filter: ```bash -sync-ctl validate --types dockerfile,compose +sync-ctl validate --agent ``` -## Decision Points Summary +**Decision:** No IaC files in step 1 → skip. -| Condition | Action | -|-----------|--------| -| PR review context | Use `--mode thorough` in step 2 | -| Pre-deploy / compliance context | Use `--mode paranoid` in step 2 | -| No IaC files detected in step 1 | Skip step 4 | -| No dependencies detected in step 1 | Skip step 3 | +Filter if types known: `--types dockerfile,compose` -## Report Synthesis +**Success criteria:** Lint violations captured with severity and file locations. -Produce a security audit report: +## Decision Points -1. **Security Findings** — all Critical and High findings with file locations and remediation -2. **Vulnerability Status** — CVEs by severity, packages needing updates -3. **IaC Compliance** — lint violations in Dockerfiles, Compose, Terraform -4. **Overall Verdict** — PASS (no critical/high findings), WARN (high findings but no critical), FAIL (critical findings present) -5. **Remediation Priority** — ordered list of actions to resolve findings - -**If critical findings exist:** Explicitly warn the user. If this audit is part of a deploy pipeline, recommend blocking deployment until critical issues are resolved. +| Condition | Action | +|-----------|--------| +| PR review context | `--mode thorough` in step 2 | +| Pre-deploy / compliance | `--mode paranoid` in step 2 | +| No IaC files in step 1 | Skip step 4 | +| No dependencies in step 1 | Skip step 3 | -## Cross-Step Retrieval +## Report: Verdict Format -Each step produces a `full_data_ref` in its output. You can retrieve details from any previous step at any time: +1. **Security Findings** — critical/high with locations and remediation +2. **Vulnerability Status** — CVEs by severity, packages needing updates +3. **IaC Compliance** — lint violations +4. **Verdict** — PASS (no critical/high) | WARN (high but no critical) | FAIL (critical present) +5. **Remediation Priority** — ordered action list -```bash -# Check what data is available from all steps -sync-ctl retrieve --list +**If critical findings exist:** Explicitly warn user. If part of deploy pipeline, recommend blocking deployment. -# Get framework details from Step 1 (analyze) -sync-ctl retrieve --query "section:frameworks" +## Common Mistakes -# Get critical security findings from Step 2 -sync-ctl retrieve --query "severity:critical" +| Mistake | Reality | +|---------|---------| +| "Project looks simple, lightning mode is fine" | Security audits require thorough or paranoid. That's what distinguishes this from project-assessment. | +| Skipping IaC validation because "it's just Dockerfiles" | Dockerfile misconfigurations are a top attack vector. Always validate if IaC exists. | +| Reporting verdict without running all applicable steps | Every applicable step must complete before issuing a PASS/WARN/FAIL verdict. | -# Get vulnerability details from Step 3 -sync-ctl retrieve --query "severity:high" -``` +## Retrieval -Do NOT re-run a command just to get more detail — use `sync-ctl retrieve` instead. +Save each step's `full_data_ref`. Use `sync-ctl retrieve --query "..."` for drill-down. Do NOT re-run commands.