backspace-shmackspace/claude-devkit

# /journal Workflow

## Inputs

**User provides:**
- Natural language description of what to journal (content, context, topic)
- Optional: explicit entry type (daily, meeting, project, learning, decision)
- Optional: project name, topic name, or meeting title

**Scope parameters:**
- `JOURNAL_BASE`: `~/journal/` (hardcoded, user can modify in skill file if needed)
- `TEMPLATES_DIR`: `~/journal/templates/` (on-disk templates override embedded defaults)
- Supported entry types: daily, meeting, project, learning, decision, biweekly-update

# /journal-recall Workflow

## Inputs

**User provides:**
- Natural language query describing what to find (date, keyword, topic, project, etc.)
- Optional: date range, entry type filter, project name

**Scope parameters:**
- `JOURNAL_BASE`: `~/journal/` (hardcoded, matches /journal skill)
- Entry types: daily, meetings, projects, learnings, decisions
- Search modes: date lookup, date range, keyword search, topic search, project filter, weekly review

## Step 0 — Classify Intent

# /journal-review Workflow

## Inputs

**User provides:**
- Review period: "this week", "last week", "last N days", "this sprint", a date range (YYYY-MM-DD to YYYY-MM-DD), or omitted (defaults to "this week")
- Optional: category filter (decisions, learnings, actions, themes, or all)

**Scope parameters:**
- `JOURNAL_BASE`: `~/journal/` (hardcoded, matches /journal and /journal-recall skills)
- `REVIEW_CATEGORIES`: decisions, learnings, actions, themes
- `DECISION_SIGNALS`: "decided", "chose", "went with", "opted for", "tradeoff", "picked", "selected", "decision:"
- `LEARNING_SIGNALS`: "learned", "discovered", "figured out", "TIL", "gotcha", "insight", "realization", "aha"
- `ACTION_SIGNALS`: "- [ ]", "TODO", "follow up", "need to", "action item", "next step"

# AI-Generated Code Security Review

Security review checklist and methodology for code produced by AI
coding assistants (Claude, Copilot, Cursor, Gemini, or any LLM-based
tool). AI-generated code has characteristic failure modes that differ
from human-written code and require specific review attention.

## When to Use

- Reviewing PRs or patches marked with `Assisted-by:` or
  `Generated-by:` attribution
- Auditing code known or suspected to be AI-generated
- As a supplementary checklist during any code review where AI
  assistance was used

# /architect Workflow

## Inputs
- Feature request: $ARGUMENTS
- Flags: `--fast` skips the red team review (use for low-risk changes)

## Output Rules
- **Always print full absolute paths** for all artifact references (plan files, review files, audit logs). This makes paths clickable in terminals like Warp. Use the resolved `$PLANS_DIR` value, never relative paths like `./plans/`.

## Step 0 — Pre-flight (optional)

**Resolve devkit paths (MUST be first action in Step 0):**

Tool: `Bash`

# /audit Workflow

## Inputs
- Scope: $ARGUMENTS (optional: "plan", "code", "full")
  - `plan`: Audit a plan file before implementation
  - `code`: Audit recent uncommitted changes (default)
  - `full`: Full codebase scan

## Output Rules
- **Always print full absolute paths** for all artifact references (plan files, review files, audit logs). This makes paths clickable in terminals like Warp. Use the resolved `$PLANS_DIR` value, never relative paths.

## Role
You are the **audit coordinator**. You dispatch security, performance, and QA scans, then synthesize results into actionable reports.
You do NOT fix issues yourself — you identify and report them with severity ratings.

# Build YAML Misconfiguration

Detect and prevent security misconfigurations in GitLab CI and Tekton pipeline definitions. Misconfigured build YAML is a common source of secret leakage, privilege escalation, and supply chain compromise.

## GitLab CI (.gitlab-ci.yml)

### Secret Exposure

- **Never hardcode secrets** in `.gitlab-ci.yml`, `variables:`, or `script:` blocks. Use CI/CD protected variables or an external vault.
- **Mask and protect variables**: set `masked: true` and `protected: true` on sensitive CI/CD variables. Masked variables are redacted from job logs.
- **Never echo secrets**: avoid `echo $SECRET`, `printenv`, `env`, or `set -x` in scripts that handle credentials. Debug output is stored in job logs.
- **Restrict variable scope**: use `protected: true` to limit variables to protected branches/tags only. Use environment scoping to restrict which jobs see which secrets.
- **Artifacts and caches**: never include files containing secrets (`.env`, credentials, tokens) in `artifacts:` or `cache:` paths. These are stored and downloadable.

# Client-Side Web Security

Protect browser clients against code injection, request forgery, UI redress, cross-site leaks, and unsafe third-party scripts with layered, context-aware controls.

## XSS Prevention (Context-Aware)

- **HTML context**: prefer `textContent`. If HTML is required, sanitize with a vetted library (e.g., DOMPurify) and strict allow-lists.
- **Attribute context**: always quote attributes and encode values.
- **JavaScript context**: do not build JS from untrusted strings; avoid inline event handlers; use `addEventListener`.
- **URL context**: validate protocol/domain and encode; block `javascript:` and data URLs where inappropriate.
- **Redirects/forwards**: never use user input directly for destinations; use server-side mapping (ID to URL) or validate against trusted domain allow-lists.
- **CSS context**: allow-list values; never inject raw style text from users.

Example sanitization:

# /compliance-check Workflow

## Output Rules
- **Always print full absolute paths** for all artifact references (plan files, review files, audit logs). This makes paths clickable in terminals like Warp. Use the resolved `$PLANS_DIR` value, never relative paths.

## Role

This skill is a **scan coordinator**. It orchestrates parallel compliance signal scans per requested framework, synthesizes findings, and produces a structured report with a PASS / PASS_WITH_NOTES / BLOCKED verdict. It checks **code-level signals only** — it does not verify organizational, infrastructure, or procedural controls.

This report is a development aid, not a compliance certification.

## Inputs

- Framework(s): $ARGUMENTS (required)
  - `fedramp` — Federal Risk and Authorization Management Program code-level controls

# Container Hardening

## Base Image Selection

- Use a **Universal Base Image (UBI)** from the official [Red Hat Container Registry](https://catalog.redhat.com/software/containers/search)
- Prefer **ubi-minimal** (`ubi8/ubi-minimal` or `ubi9/ubi-minimal`) to reduce attack surface
- Use the most up-to-date image available

### Image Tagging Strategy

| Source | Strategy |
|---|---|
| **Red Hat Catalog** | Omit floating tags to get the latest image; exception: Konflux project uses digest-based pinning with automated updates |
| **Non-Red Hat registries** | Pin the version or digest to ensure you use the intended image and not a tampered one |

# /dependency-audit Workflow

## Output Rules
- **Always print full absolute paths** for all artifact references (plan files, review files, audit logs). This makes paths clickable in terminals like Warp. Use the resolved `$PLANS_DIR` value, never relative paths.

## Role

This skill is a **pipeline coordinator**. It orchestrates a sequential supply chain security workflow by delegating scanner invocation and synthesis to appropriate tools. It does NOT perform LLM-based CVE lookup — it coordinates real CLI scanners that use live vulnerability databases, then synthesizes their output. The LLM's training data has a knowledge cutoff and cannot reliably detect post-cutoff CVEs.

## Inputs

- Package manifest path or scope: $ARGUMENTS (optional — auto-detected if omitted)
- Supported: `package.json`, `requirements.txt`, `pyproject.toml`, `Pipfile`, `go.mod`, `Cargo.toml`, `pom.xml`, `Gemfile`

## Step 0 — Pre-flight: detect manifest and scanner availability

# /fix Workflow

## Output Rules
- **Always print full absolute paths** for all artifact references (plan files, review files, audit logs). This makes paths clickable in terminals like Warp. Use the resolved `$PLANS_DIR` value, never relative paths.

## Role

This skill is a **pipeline coordinator**. It orchestrates a targeted fix workflow: parse a finding from a review artifact, scope the fix, dispatch a coder agent, run focused verification, and commit with traceability back to the source finding. It does NOT write code directly — it delegates implementation to a coder agent and verification to focused subagent tasks.

**Finding-driven, not plan-driven:** The finding IS the specification. No plan file required or generated.

**Supported artifacts:** Works with findings from both `/ship` artifacts (`.code-review.md`, `.secure-review.md`, `.qa-report.md`) and `/audit` artifacts (`audit-[timestamp].security.md`, `audit-[timestamp].performance.md`).

**Dry-run mode:** Supports `--dry-run` flag. Runs Steps 0-3 but skips Step 4 (commit). Changes remain in the working directory for manual review.

# Input Validation and Injection Defense

Ensure untrusted input is validated and never interpreted as code. Prevent injection across SQL, LDAP, OS commands, templating, and JavaScript runtime object graphs.

## Core Strategy

- Validate early at trust boundaries with positive (allow-list) validation and canonicalization.
- Treat all untrusted input as data, never as code. Use safe APIs that separate code from data.
- Parameterize queries/commands; escape only as last resort and context-specific.

## Validation Playbook

- **Syntactic validation**: enforce format, type, ranges, and lengths for each field.
- **Semantic validation**: enforce business rules (e.g., start <= end date, enum allow-lists).

# Code Review Reception

## Overview

Code review requires technical evaluation, not emotional performance.

## Core Principle

Verify before implementing. Ask before assuming. Technical correctness over social comfort.

## The Response Pattern

```
WHEN receiving code review feedback:

# /retro Workflow

## Inputs
- Scope: $ARGUMENTS (optional: "recent", "full", "mine", or a feature name)
  - `recent`: Last 3 archived features (default)
  - `full`: All archived features
  - `mine`: Cross-project learnings mining (skips Steps 0-5, proceeds to Step 6)
  - `<name>`: Single feature archive (e.g., "add-user-auth")

## Output Rules
- **Always print full absolute paths** for all artifact references (plan files, review files, audit logs). This makes paths clickable in terminals like Warp. Use the resolved `$PLANS_DIR` value, never relative paths.

## Role
You are the **retro coordinator**. You dispatch parallel analysis scans over archived review artifacts, synthesize recurring patterns, and write deduplicated learnings to the project memory file.
You do NOT fix code or modify agents — you extract and record patterns.

# /secrets-scan Workflow

## Output Rules
- **Always print full absolute paths** for all artifact references (plan files, review files, audit logs). This makes paths clickable in terminals like Warp. Use the resolved `$PLANS_DIR` value, never relative paths.

## Role

This skill is a **pipeline coordinator**. It orchestrates a sequential secrets detection workflow using pattern-based scanning. It delegates grep/regex scanning to Bash and synthesis to analysis tasks. It does NOT require external tools like trufflehog or gitleaks — all scanning uses built-in grep patterns, making it self-contained and deployable anywhere Claude Code runs.

**Zero tolerance policy:** Any confirmed secret detected results in a BLOCKED verdict. There is no passing threshold — secrets in code are a critical finding.

**Report redaction rule:** This skill NEVER includes actual secret values in reports. Reports show secret type, file path, and line number only. Pattern matches are redacted to show type and location: e.g., "AWS Access Key at `src/config.js:42`".

## Inputs

# /secure-review Workflow

## Output Rules
- **Always print full absolute paths** for all artifact references (plan files, review files, audit logs). This makes paths clickable in terminals like Warp. Use the resolved `$PLANS_DIR` value, never relative paths.

## Role

This skill is a **scan coordinator**. It orchestrates parallel semantic security scans across three dimensions — vulnerability patterns, data flow and PII exposure, and authentication/authorization logic — then synthesizes findings into a structured security report with a PASS / PASS_WITH_NOTES / BLOCKED verdict. It does not fix issues; it identifies and categorizes them.

This skill is a composable building block. When deployed, `/audit` can dispatch it as its security scan component for deeper analysis.

## Inputs

- Scope: $ARGUMENTS (optional)
  - `changes` — Uncommitted changes only (default)

# Semgrep Security Scan

Run a Semgrep scan with automatic language detection, parallel execution across language groups, and merged SARIF output.

## Essential Principles

1. **Always use `--metrics=off`** — Semgrep sends telemetry by default; `--config auto` also phones home. Every `semgrep` command must include `--metrics=off` to prevent data leakage during security audits.
2. **User must approve the scan plan (Step 3 is a hard gate)** — The original "scan this codebase" request is NOT approval. Present exact rulesets, target, engine, and mode; wait for explicit "yes"/"proceed" before running scanners.
3. **Third-party rulesets are required, not optional** — Trail of Bits, 0xdea, and Decurity rules catch vulnerabilities absent from the official registry. Include them whenever the detected language matches.
4. **Run all scan workers in parallel** — Parallel execution is the core performance advantage. Do not run language scans strictly one-after-another when independence allows overlap.
5. **Always check for Semgrep Pro before scanning** — Pro enables cross-file taint tracking and catches ~250% more true positives. Skipping the check means silently missing critical inter-file vulnerabilities.

## When to Use

# /ship Workflow

## Inputs
- Plan file: $ARGUMENTS   # Full path, or bare plan name (e.g. "cross-repo-plan-support")

## Output Rules
- **Always print full absolute paths** for all artifact references (plan files, review files, audit logs). This makes paths clickable in terminals like Warp. Use the resolved `$PLANS_DIR` value, never relative paths.

## Role
You are the **work coordinator**. You dispatch work to agents and check their results.
You do NOT write code, explore the codebase, or run tests yourself — agents do that.
Your job: read the plan once, dispatch each step, check verdicts, gate progression.

## Step 0 — Pre-flight checks

# /sync Workflow

## Inputs
- Scope: $ARGUMENTS (optional: "recent", "full")
  - `recent`: Last 5 commits (default)
  - `full`: Full codebase scan

## Output Rules
- **Always print full absolute paths** for all artifact references (plan files, review files, audit logs). This makes paths clickable in terminals like Warp. Use the resolved `$PLANS_DIR` value, never relative paths.

## Role
You are the **documentation coordinator**. You detect changes, delegate review to the librarian, and present diffs for user approval.
You do NOT make documentation changes yourself — you coordinate the process.

## Step 1 — Detect changes

# Threat Modeling

Structured threat identification and risk assessment for software systems
using STRIDE threat categorization and DREAD risk rating, producing both
machine-readable Open Threat Model (OTM) JSON and human-readable markdown
reports.

## Core Principles

1. **Risk-First**: Focus analysis effort on high-value assets and exposed
   trust boundaries. Not every component warrants equal analysis depth --
   prioritize by data sensitivity and exposure.

2. **Evidence-Based**: Every identified threat must be backed by specific

# Threat Model Gate

## Overview

Security cannot be added later. Features that touch user data, system boundaries, or trust relationships require threat modeling during planning — not after code is written.

## Core Principle

**Every feature that handles user data, authentication, or system boundaries requires explicit threat modeling before implementation.**

"We'll secure it in the next sprint" is a commitment that never gets honored. The cost of retrofitting security is 10x the cost of designing it in. Threat modeling during planning is the minimum viable security practice.

## When to Activate

# Verification Before Completion

## Overview

Every completion claim requires fresh evidence. No exceptions.

## The Iron Law

**NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE.**

"I believe it works" is not evidence. "The tests passed at 14:32" is evidence.

If you have not run verification commands in this session and read their output, you have not verified.