# Implementation Plan: gemma-deployment-security

**Branch**: `feat/gemma-airflow-security` | **Date**: 2026-04-15 | **Spec**: `plugins/gemma-deployment-security/docs/spec.md`
**Input**: Design spec + constitution at `specs/constitution.md`

## Summary

Create a 7-skill Claude Code plugin for auditing self-hosted Docker Compose data tool deployments. Each skill reads repo files (or SSH configs) and produces prioritized findings using a reference-checklist pattern. A report generator orchestrates all skills into a unified Markdown audit report.

## Technical Context

**Language/Version**: Markdown (SKILL.md) — no application code, pure Claude Code skill definitions
**Primary Dependencies**: Claude Code plugin system, `${CLAUDE_SKILL_DIR}` runtime variable
**Storage**: N/A — output is a Markdown file
**Testing**: Manual execution against known-insecure reference repos
**Target Platform**: Claude Code CLI (Anthropic API or Bedrock)
**Project Type**: Claude Code plugin (skills + reference docs)
**Constraints**: SKILL.md < 500 lines each, follow `gemma-agentic-toolkit/CLAUDE.md` conventions

## Constitution Check

| Principle | Status | Notes |
|---|---|---|
| I. Read-Only Auditing | PASS | All skills read files, write only to report output |
| II. Reference-Checklist Architecture | PASS | Each skill has `references/checklist.md` |
| III. Prioritized, Actionable Findings | PASS | Every check has severity + remediation snippet |
| IV. Graceful Degradation | PASS | Server audit falls back to guided checklist |
| V. Checklist Provenance | PASS | All checks trace to security report or real findings |

## Project Structure

```text
plugins/gemma-deployment-security/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   ├── audit-docker-compose/
│   │   ├── SKILL.md
│   │   └── references/
│   │       └── checklist.md
│   ├── audit-dockerfile/
│   │   ├── SKILL.md
│   │   └── references/
│   │       └── checklist.md
│   ├── audit-cicd-workflows/
│   │   ├── SKILL.md
│   │   └── references/
│   │       └── checklist.md
│   ├── audit-server-config/
│   │   ├── SKILL.md
│   │   └── references/
│   │       ├── checklist.md
│   │       └── guided-checklist.md
│   ├── audit-infrastructure-as-code/
│   │   ├── SKILL.md
│   │   └── references/
│   │       └── checklist.md
│   ├── audit-airflow-config/
│   │   ├── SKILL.md
│   │   └── references/
│   │       └── checklist.md
│   └── generate-security-report/
│       ├── SKILL.md
│       └── assets/
│           └── report-template.md
├── CHANGELOG.md
```

## Implementation Strategy

### Build Order

Skills are independent — no skill depends on another for its logic. The report generator depends on all other skills being defined (it references them by name). Therefore:

1. **Phase 1 (Setup)**: Plugin scaffold + registration
2. **Phase 2 (Core skills)**: Build all 6 audit skills in parallel (independent files, no dependencies)
3. **Phase 3 (Orchestrator)**: Build the report generator (references all skills)
4. **Phase 4 (Validation)**: Test against reference repos, plugin validation

### Parallel Opportunities

All 6 audit skills can be built in parallel by subagents — they share no files and have no cross-dependencies. Each skill = 1 SKILL.md + 1 checklist.md (+ optional extras for server audit).

### Source Material for Checklists

| Skill | Primary Source | Secondary Source |
|---|---|---|
| audit-docker-compose | Security report §05 (Docker Compose Security) | `airflow3-demo/docker-compose.yaml` findings |
| audit-dockerfile | Security report §05 + real findings | `gemma-airflow/Dockerfile` (bad), `airflow3-demo` branch `feat/production-learnings` Dockerfile (good) |
| audit-cicd-workflows | Security report §07 (CI/CD Deployment) | GitHub Actions best practices |
| audit-server-config | Security report §03 (Network), §04 (SSH), §08 (Hardening) | `saxonia-data-infrastructure/server/opentofu/main.tf` cloud-init |
| audit-infrastructure-as-code | Real patterns from saxonia setup | OpenTofu/Ansible security best practices |
| audit-airflow-config | Security report + Airflow docs | `gemma-airflow/Dockerfile` (secrets), `airflow3-demo/docker-compose.yaml` (defaults) |

### How to Use skill-creator

For each skill, invoke `skill-creator:skill-creator` with:
1. The skill name and description
2. The checklist content (derived from security report)
3. The SKILL.md instructions (how to apply the checklist to target files)
4. Request validation that the skill follows plugin conventions

## Verification

1. **Plugin validation**: Run `plugin-dev:plugin-validator` against the complete plugin
2. **Skill trigger test**: Verify each skill's description triggers correctly (use skill-creator eval)
3. **Functional test - Docker Compose**: Run `audit-docker-compose` against `airflow3-demo/docker-compose.yaml` — expect findings for: port binding (8080 not on 127.0.0.1), no internal network, no cap_drop, no resource limits, Docker socket mount
4. **Functional test - Dockerfile**: Run `audit-dockerfile` against `gemma-airflow/Dockerfile` — expect findings for: secrets in ENV, hardcoded credentials, no USER directive, image not SHA-pinned
5. **Functional test - Report**: Run `generate-security-report` against `airflow3-demo/` — expect a complete report with executive summary, findings, and passed checks
6. **Constitution compliance**: Verify all skills are read-only, use reference-checklists, produce actionable findings, and degrade gracefully