claude-code-workflow 7.2.27 → 7.2.28

package/.claude/skills/security-audit/specs/owasp-checklist.md

@@ -0,0 +1,442 @@
+# OWASP Top 10 2021 Checklist
+
+Code-level detection patterns, vulnerable code examples, and remediation templates for each OWASP category.
+
+## When to Use
+
+| Phase | Usage | Section |
+|-------|-------|---------|
+| Phase 2 | Reference during OWASP code review | All categories |
+| Phase 4 | Classify findings by OWASP category | Category IDs |
+
+---
+
+## A01: Broken Access Control
+
+**CWE**: CWE-200, CWE-284, CWE-285, CWE-352, CWE-639
+
+### Detection Patterns
+
+```bash
+# Missing auth middleware on route handlers
+grep -rnE 'app\.(get|post|put|delete|patch)\s*\(\s*["\x27/]' --include='*.ts' --include='*.js' .
+# Then verify each route has auth middleware
+
+# Direct object reference without ownership check
+grep -rnE 'findById\(.*params|findOne\(.*params|\.get\(.*id' --include='*.ts' --include='*.js' --include='*.py' .
+
+# Path traversal patterns
+grep -rnE '(readFile|writeFile|createReadStream|open)\s*\(.*req\.' --include='*.ts' --include='*.js' .
+grep -rnE 'os\.path\.join\(.*request\.' --include='*.py' .
+
+# Missing CORS restrictions
+grep -rnE 'Access-Control-Allow-Origin.*\*|cors\(\s*\)' --include='*.ts' --include='*.js' .
+```
+
+### Vulnerable Code Example
+
+```javascript
+// BAD: No ownership check
+app.get('/api/documents/:id', auth, async (req, res) => {
+  const doc = await Document.findById(req.params.id);  // Any user can access any doc
+  res.json(doc);
+});
+```
+
+### Remediation
+
+```javascript
+// GOOD: Ownership check
+app.get('/api/documents/:id', auth, async (req, res) => {
+  const doc = await Document.findOne({ _id: req.params.id, owner: req.user.id });
+  if (!doc) return res.status(404).json({ error: 'Not found' });
+  res.json(doc);
+});
+```
+
+---
+
+## A02: Cryptographic Failures
+
+**CWE**: CWE-259, CWE-327, CWE-331, CWE-798
+
+### Detection Patterns
+
+```bash
+# Weak hash algorithms
+grep -rniE '(md5|sha1)\s*\(' --include='*.ts' --include='*.js' --include='*.py' --include='*.java' .
+
+# Plaintext password storage
+grep -rniE 'password\s*[:=]\s*.*\.(body|query|params)' --include='*.ts' --include='*.js' .
+
+# Hardcoded encryption keys
+grep -rniE '(encrypt|cipher|secret|key)\s*[:=]\s*["\x27][A-Za-z0-9+/=]{8,}' --include='*.ts' --include='*.js' --include='*.py' .
+
+# HTTP (not HTTPS) for sensitive operations
+grep -rniE 'http://.*\.(api|auth|login|payment)' --include='*.ts' --include='*.js' --include='*.py' .
+
+# Missing encryption at rest
+grep -rniE '(password|ssn|credit.?card|social.?security)' --include='*.sql' --include='*.prisma' --include='*.schema' .
+```
+
+### Vulnerable Code Example
+
+```python
+# BAD: MD5 for password hashing
+import hashlib
+password_hash = hashlib.md5(password.encode()).hexdigest()
+```
+
+### Remediation
+
+```python
+# GOOD: bcrypt with proper work factor
+import bcrypt
+password_hash = bcrypt.hashpw(password.encode(), bcrypt.gensalt(rounds=12))
+```
+
+---
+
+## A03: Injection
+
+**CWE**: CWE-20, CWE-74, CWE-79, CWE-89
+
+### Detection Patterns
+
+```bash
+# SQL string concatenation/interpolation
+grep -rniE "(query|execute|raw)\s*\(\s*[\`\"'].*(\+|\$\{|%s|\.format)" --include='*.ts' --include='*.js' --include='*.py' .
+grep -rniE "f[\"'].*SELECT.*\{" --include='*.py' .
+
+# NoSQL injection
+grep -rniE '\$where|\$regex.*req\.' --include='*.ts' --include='*.js' .
+grep -rniE 'find\(\s*\{.*req\.(body|query|params)' --include='*.ts' --include='*.js' .
+
+# OS command injection
+grep -rniE '(child_process|exec|execSync|spawn|system|popen|subprocess)\s*\(.*req\.' --include='*.ts' --include='*.js' --include='*.py' .
+
+# XPath/LDAP injection
+grep -rniE '(xpath|ldap).*\+.*req\.' --include='*.ts' --include='*.js' --include='*.py' .
+
+# Template injection
+grep -rniE '(render_template_string|Template\(.*req\.|eval\(.*req\.)' --include='*.py' --include='*.js' .
+```
+
+### Vulnerable Code Example
+
+```javascript
+// BAD: SQL string concatenation
+const result = await db.query(`SELECT * FROM users WHERE id = ${req.params.id}`);
+```
+
+### Remediation
+
+```javascript
+// GOOD: Parameterized query
+const result = await db.query('SELECT * FROM users WHERE id = $1', [req.params.id]);
+```
+
+---
+
+## A04: Insecure Design
+
+**CWE**: CWE-209, CWE-256, CWE-501, CWE-522
+
+### Detection Patterns
+
+```bash
+# Missing rate limiting on auth endpoints
+grep -rniE '(login|register|reset.?password|forgot.?password)' --include='*.ts' --include='*.js' --include='*.py' .
+# Then check if rate limiting middleware is applied
+
+# No account lockout mechanism
+grep -rniE 'failed.?login|login.?attempt|max.?retries' --include='*.ts' --include='*.js' --include='*.py' .
+
+# Business logic without validation
+grep -rniE '(transfer|withdraw|purchase|delete.?account)' --include='*.ts' --include='*.js' --include='*.py' .
+# Then check for confirmation/validation steps
+```
+
+### Checks
+
+- [ ] Authentication flows have rate limiting
+- [ ] Account lockout after N failed attempts
+- [ ] Multi-step operations have proper state validation
+- [ ] Business-critical operations require confirmation
+- [ ] Threat modeling has been performed (see Phase 3)
+
+### Remediation
+
+Implement defense-in-depth: rate limiting, input validation, business logic validation, and multi-step confirmation for critical operations.
+
+---
+
+## A05: Security Misconfiguration
+
+**CWE**: CWE-2, CWE-11, CWE-13, CWE-15, CWE-16, CWE-388
+
+### Detection Patterns
+
+```bash
+# Debug mode enabled
+grep -rniE '(DEBUG|NODE_ENV)\s*[:=]\s*(true|True|1|"development"|"debug")' \
+  --include='*.env' --include='*.env.*' --include='*.py' --include='*.json' --include='*.yaml' .
+
+# Default credentials
+grep -rniE '(admin|root|test|default).*[:=].*password' --include='*.env' --include='*.yaml' --include='*.json' --include='*.py' .
+
+# Verbose error responses (stack traces to client)
+grep -rniE '(stack|stackTrace|traceback).*res\.(json|send)|app\.use.*err.*stack' --include='*.ts' --include='*.js' .
+
+# Missing security headers
+grep -rniE '(helmet|X-Frame-Options|X-Content-Type-Options|Strict-Transport-Security)' --include='*.ts' --include='*.js' .
+
+# Directory listing enabled
+grep -rniE 'autoindex\s+on|directory.?listing|serveStatic.*index.*false' --include='*.conf' --include='*.ts' --include='*.js' .
+
+# Unnecessary features/services
+grep -rniE '(graphiql|playground|swagger-ui).*true' --include='*.ts' --include='*.js' --include='*.py' --include='*.yaml' .
+```
+
+### Vulnerable Code Example
+
+```javascript
+// BAD: Stack trace in error response
+app.use((err, req, res, next) => {
+  res.status(500).json({ error: err.message, stack: err.stack });
+});
+```
+
+### Remediation
+
+```javascript
+// GOOD: Generic error response in production
+app.use((err, req, res, next) => {
+  console.error(err.stack);  // Log internally
+  res.status(500).json({ error: 'Internal server error' });
+});
+```
+
+---
+
+## A06: Vulnerable and Outdated Components
+
+**CWE**: CWE-1104
+
+### Detection Patterns
+
+```bash
+# Check dependency lock files age
+ls -la package-lock.json yarn.lock requirements.txt Pipfile.lock go.sum 2>/dev/null
+
+# Run package audits (from Phase 1)
+npm audit --json 2>/dev/null
+pip-audit --format json 2>/dev/null
+
+# Check for pinned vs unpinned dependencies
+grep -E ':\s*"\^|:\s*"~|:\s*"\*|>=\s' package.json 2>/dev/null
+grep -E '^[a-zA-Z].*[^=]==[^=]' requirements.txt 2>/dev/null  # Good: pinned
+grep -E '^[a-zA-Z].*>=|^[a-zA-Z][^=]*$' requirements.txt 2>/dev/null  # Bad: unpinned
+```
+
+### Checks
+
+- [ ] All dependencies have pinned versions
+- [ ] No known CVEs in dependencies (via audit tools)
+- [ ] Dependencies are actively maintained (not abandoned)
+- [ ] Lock files are committed to version control
+
+### Remediation
+
+Run `npm audit fix` or `pip install --upgrade` for vulnerable packages. Pin all dependency versions. Set up automated dependency scanning (Dependabot, Renovate).
+
+---
+
+## A07: Identification and Authentication Failures
+
+**CWE**: CWE-255, CWE-259, CWE-287, CWE-384
+
+### Detection Patterns
+
+```bash
+# Weak password requirements
+grep -rniE 'password.*length.*[0-5]|minlength.*[0-5]|min.?length.*[0-5]' --include='*.ts' --include='*.js' --include='*.py' .
+
+# Missing password hashing
+grep -rniE 'password\s*[:=].*req\.' --include='*.ts' --include='*.js' .
+# Then check if bcrypt/argon2/scrypt is used before storage
+
+# Session fixation (no rotation after login)
+grep -rniE 'session\.regenerate|session\.id\s*=' --include='*.ts' --include='*.js' .
+
+# JWT without expiration
+grep -rniE 'jwt\.sign\(' --include='*.ts' --include='*.js' .
+# Then check for expiresIn option
+
+# Credentials in URL
+grep -rniE '(token|key|password|secret)=[^&\s]+' --include='*.ts' --include='*.js' --include='*.py' .
+```
+
+### Vulnerable Code Example
+
+```javascript
+// BAD: JWT without expiration
+const token = jwt.sign({ userId: user.id }, SECRET);
+```
+
+### Remediation
+
+```javascript
+// GOOD: JWT with expiration and proper claims
+const token = jwt.sign(
+  { userId: user.id, role: user.role },
+  SECRET,
+  { expiresIn: '1h', issuer: 'myapp', audience: 'myapp-client' }
+);
+```
+
+---
+
+## A08: Software and Data Integrity Failures
+
+**CWE**: CWE-345, CWE-353, CWE-426, CWE-494, CWE-502
+
+### Detection Patterns
+
+```bash
+# Insecure deserialization
+grep -rniE '(pickle\.load|yaml\.load\(|unserialize|JSON\.parse\(.*req\.|eval\()' --include='*.py' --include='*.ts' --include='*.js' --include='*.php' .
+
+# Missing integrity checks on downloads/updates
+grep -rniE '(download|fetch|curl|wget)' --include='*.sh' --include='*.yaml' --include='*.yml' .
+# Then check for checksum/signature verification
+
+# CI/CD pipeline without pinned action versions
+grep -rniE 'uses:\s*[^@]+$|uses:.*@(main|master|latest)' .github/workflows/*.yml 2>/dev/null
+
+# Unsafe YAML loading
+grep -rniE 'yaml\.load\(' --include='*.py' .
+# Should be yaml.safe_load()
+```
+
+### Vulnerable Code Example
+
+```python
+# BAD: Unsafe YAML loading
+import yaml
+data = yaml.load(user_input)  # Allows arbitrary code execution
+```
+
+### Remediation
+
+```python
+# GOOD: Safe YAML loading
+import yaml
+data = yaml.safe_load(user_input)
+```
+
+---
+
+## A09: Security Logging and Monitoring Failures
+
+**CWE**: CWE-223, CWE-532, CWE-778
+
+### Detection Patterns
+
+```bash
+# Check for logging of auth events
+grep -rniE '(log|logger|logging)\.' --include='*.ts' --include='*.js' --include='*.py' .
+# Then check if login/logout/failed-auth events are logged
+
+# Sensitive data in logs
+grep -rniE 'log.*(password|token|secret|credit.?card|ssn)' --include='*.ts' --include='*.js' --include='*.py' .
+
+# Empty catch blocks (swallowed errors)
+grep -rniE 'catch\s*\([^)]*\)\s*\{\s*\}' --include='*.ts' --include='*.js' .
+
+# Missing audit trail for critical operations
+grep -rniE '(delete|update|create|transfer)' --include='*.ts' --include='*.js' --include='*.py' .
+# Then check if these operations are logged with user context
+```
+
+### Checks
+
+- [ ] Failed login attempts are logged with IP and timestamp
+- [ ] Successful logins are logged
+- [ ] Access control failures are logged
+- [ ] Input validation failures are logged
+- [ ] Sensitive data is NOT logged (passwords, tokens, PII)
+- [ ] Logs include sufficient context (who, what, when, where)
+
+### Remediation
+
+Implement structured logging with: user ID, action, timestamp, IP address, result (success/failure). Exclude sensitive data. Set up log monitoring and alerting for anomalous patterns.
+
+---
+
+## A10: Server-Side Request Forgery (SSRF)
+
+**CWE**: CWE-918
+
+### Detection Patterns
+
+```bash
+# User-controlled URLs in fetch/request calls
+grep -rniE '(fetch|axios|http\.request|requests\.(get|post)|urllib)\s*\(.*req\.(body|query|params)' \
+  --include='*.ts' --include='*.js' --include='*.py' .
+
+# URL construction from user input
+grep -rniE '(url|endpoint|target|redirect)\s*[:=].*req\.(body|query|params)' --include='*.ts' --include='*.js' --include='*.py' .
+
+# Image/file fetch from URL
+grep -rniE '(download|fetchImage|getFile|loadUrl)\s*\(.*req\.' --include='*.ts' --include='*.js' --include='*.py' .
+
+# Redirect without validation
+grep -rniE 'res\.redirect\(.*req\.|redirect_to.*request\.' --include='*.ts' --include='*.js' --include='*.py' .
+```
+
+### Vulnerable Code Example
+
+```javascript
+// BAD: Unvalidated URL fetch
+app.get('/proxy', async (req, res) => {
+  const response = await fetch(req.query.url);  // Can access internal services
+  res.send(await response.text());
+});
+```
+
+### Remediation
+
+```javascript
+// GOOD: URL allowlist validation
+const ALLOWED_HOSTS = ['api.example.com', 'cdn.example.com'];
+
+app.get('/proxy', async (req, res) => {
+  const url = new URL(req.query.url);
+  if (!ALLOWED_HOSTS.includes(url.hostname)) {
+    return res.status(400).json({ error: 'Host not allowed' });
+  }
+  if (url.protocol !== 'https:') {
+    return res.status(400).json({ error: 'HTTPS required' });
+  }
+  const response = await fetch(url.toString());
+  res.send(await response.text());
+});
+```
+
+---
+
+## Quick Reference
+
+| ID | Category | Key Grep Pattern | Severity Baseline |
+|----|----------|-----------------|-------------------|
+| A01 | Broken Access Control | `findById.*params` without owner check | High |
+| A02 | Cryptographic Failures | `md5\|sha1` for passwords | High |
+| A03 | Injection | `query.*\+.*req\.\|f".*SELECT.*\{` | Critical |
+| A04 | Insecure Design | Missing rate limit on auth routes | Medium |
+| A05 | Security Misconfiguration | `DEBUG.*true\|stack.*res.json` | Medium |
+| A06 | Vulnerable Components | `npm audit` / `pip-audit` results | Varies |
+| A07 | Auth Failures | `jwt.sign` without `expiresIn` | High |
+| A08 | Integrity Failures | `pickle.load\|yaml.load` | High |
+| A09 | Logging Failures | Empty catch blocks, no auth logging | Medium |
+| A10 | SSRF | `fetch.*req.query.url` | High |

package/.claude/skills/security-audit/specs/scoring-gates.md

@@ -0,0 +1,141 @@
+# Scoring Gates
+
+Defines the 10-point scoring system, severity weights, quality gates, and trend tracking format for security audits.
+
+## When to Use
+
+| Phase | Usage | Section |
+|-------|-------|---------|
+| Phase 1 | Quick-scan scoring (daily gate) | Severity Weights, Daily Gate |
+| Phase 4 | Full audit scoring and reporting | All sections |
+
+---
+
+## 10-Point Scale
+
+All security audit scores are on a 0-10 scale where 10 = no findings and 0 = critical exposure.
+
+| Score | Rating | Description |
+|-------|--------|-------------|
+| 9.0 - 10.0 | Excellent | Minimal risk. Production-ready without reservations. |
+| 7.0 - 8.9 | Good | Low risk. Acceptable for production with minor improvements. |
+| 5.0 - 6.9 | Fair | Moderate risk. Remediation recommended before production. |
+| 3.0 - 4.9 | Poor | High risk. Remediation required. Not production-ready. |
+| 0.0 - 2.9 | Critical | Severe exposure. Immediate action required. |
+
+## Severity Weights
+
+Each finding is weighted by severity for score calculation.
+
+| Severity | Weight | Criteria | Examples |
+|----------|--------|----------|----------|
+| **Critical** | 10 | Exploitable with high impact, no user interaction needed | RCE, SQL injection with data access, leaked production credentials, auth bypass |
+| **High** | 7 | Exploitable with significant impact, may need user interaction | Broken authentication, SSRF, privilege escalation, XSS with session theft |
+| **Medium** | 4 | Limited exploitability or moderate impact | Reflected XSS, CSRF, verbose error messages, missing security headers |
+| **Low** | 1 | Informational or minimal impact | Missing best-practice headers, minor info disclosure, deprecated dependencies without known exploit |
+
+## Score Calculation
+
+```
+Input:
+  findings[]     -- array of all findings with severity
+  files_scanned  -- total source files analyzed
+
+Algorithm:
+  base_score = 10.0
+  normalization = max(10, files_scanned)
+
+  weighted_sum = 0
+  for each finding:
+    weighted_sum += severity_weight(finding.severity)
+
+  penalty = weighted_sum / normalization
+  final_score = max(0, base_score - penalty)
+  final_score = round(final_score, 1)
+
+  return final_score
+```
+
+**Example**:
+
+| Findings | Files Scanned | Weighted Sum | Penalty | Score |
+|----------|--------------|--------------|---------|-------|
+| 1 critical | 50 | 10 | 0.2 | 9.8 |
+| 2 critical, 3 high | 50 | 41 | 0.82 | 9.2 |
+| 5 critical, 10 high | 50 | 120 | 2.4 | 7.6 |
+| 10 critical, 20 high, 15 medium | 100 | 300 | 3.0 | 7.0 |
+| 20 critical | 20 | 200 | 10.0 | 0.0 |
+
+## Quality Gates
+
+### Daily Quick-Scan Gate
+
+Applies to Phase 1 (Supply Chain Scan) only.
+
+| Result | Condition | Action |
+|--------|-----------|--------|
+| **PASS** | score >= 8.0 | Continue. No blocking issues. |
+| **WARN** | 6.0 <= score < 8.0 | Log warning. Review findings before deploy. |
+| **FAIL** | score < 6.0 | Block deployment. Remediate critical/high findings. |
+
+### Comprehensive Audit Gate
+
+Applies to full audit (all 4 phases).
+
+**Initial/Baseline audit** (no previous audit exists):
+
+| Result | Condition | Action |
+|--------|-----------|--------|
+| **PASS** | score >= 2.0 | Baseline established. Plan remediation. |
+| **FAIL** | score < 2.0 | Critical exposure. Immediate triage required. |
+
+**Subsequent audits** (previous audit exists):
+
+| Result | Condition | Action |
+|--------|-----------|--------|
+| **PASS** | score >= previous_score | No regression. Continue improvement. |
+| **WARN** | score within 0.5 of previous | Marginal change. Review new findings. |
+| **FAIL** | score < previous_score - 0.5 | Regression detected. Investigate new findings. |
+
+**Production readiness target**: score >= 7.0
+
+## Trend Tracking Format
+
+Each audit report stores trend data for comparison.
+
+```json
+{
+  "trend": {
+    "current_date": "2026-03-29",
+    "current_score": 7.5,
+    "previous_date": "2026-03-22",
+    "previous_score": 6.8,
+    "score_delta": 0.7,
+    "new_findings": 2,
+    "resolved_findings": 5,
+    "direction": "improving",
+    "history": [
+      { "date": "2026-03-15", "score": 5.2, "total_findings": 45 },
+      { "date": "2026-03-22", "score": 6.8, "total_findings": 32 },
+      { "date": "2026-03-29", "score": 7.5, "total_findings": 29 }
+    ]
+  }
+}
+```
+
+**Direction values**:
+
+| Direction | Condition |
+|-----------|-----------|
+| `improving` | score_delta > 0.5 |
+| `stable` | -0.5 <= score_delta <= 0.5 |
+| `regressing` | score_delta < -0.5 |
+| `baseline` | No previous audit exists |
+
+## Finding Deduplication
+
+When the same vulnerability appears in multiple phases:
+1. Keep the highest-severity classification
+2. Merge evidence from all phases
+3. Count as a single finding for scoring
+4. Note all phases that detected it

package/.claude/skills/ship/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: ship
+description: Structured release pipeline with pre-flight checks, AI code review, version bump, changelog, and PR creation. Triggers on "ship", "release", "publish".
+allowed-tools: Read, Write, Bash, Glob, Grep
+---
+
+# Ship
+
+Structured release pipeline that guides code from working branch to pull request through 5 gated phases: pre-flight checks, automated code review, version bump, changelog generation, and PR creation.
+
+## Key Design Principles
+
+1. **Phase Gates**: Each phase must pass before the next begins — no shipping broken code
+2. **Multi-Project Support**: Detects npm (package.json), Python (pyproject.toml), and generic (VERSION) projects
+3. **AI-Powered Review**: Uses CCW CLI to run automated code review before release
+4. **Audit Trail**: Each phase produces structured output for traceability
+5. **Safe Defaults**: Warns on risky operations (direct push to main, major version bumps)
+
+## Architecture Overview
+
+```
+User: "ship" / "release" / "publish"
+         |
+         v
+┌──────────────────────────────────────────────────────────┐
+│  Phase 1: Pre-Flight Checks                              │
+│  → git clean? branch ok? tests pass? build ok?           │
+│  → Output: preflight-report.json                         │
+│  → Gate: ALL checks must pass                            │
+├──────────────────────────────────────────────────────────┤
+│  Phase 2: Code Review                                    │
+│  → detect merge base, diff against base                  │
+│  → ccw cli --tool gemini --mode analysis                 │
+│  → flag high-risk changes                                │
+│  → Output: review-summary                                │
+│  → Gate: No critical issues flagged                      │
+├──────────────────────────────────────────────────────────┤
+│  Phase 3: Version Bump                                   │
+│  → detect version file (package.json/pyproject.toml/VERSION)
+│  → determine bump type from commits or user input        │
+│  → update version file                                   │
+│  → Output: version change record                         │
+│  → Gate: Version updated successfully                    │
+├──────────────────────────────────────────────────────────┤
+│  Phase 4: Changelog & Commit                             │
+│  → generate changelog from git log since last tag        │
+│  → update CHANGELOG.md                                   │
+│  → create release commit, push to remote                 │
+│  → Output: commit SHA                                    │
+│  → Gate: Push successful                                 │
+├──────────────────────────────────────────────────────────┤
+│  Phase 5: PR Creation                                    │
+│  → gh pr create with structured body                     │
+│  → auto-link issues from commits                         │
+│  → Output: PR URL                                        │
+│  → Gate: PR created                                      │
+└──────────────────────────────────────────────────────────┘
+```
+
+## Execution Flow
+
+Execute phases sequentially. Each phase has a gate condition — if the gate fails, stop and report status.
+
+1. **Phase 1**: [Pre-Flight Checks](phases/01-preflight-checks.md) -- Validate git state, branch, tests, build
+2. **Phase 2**: [Code Review](phases/02-code-review.md) -- AI-powered diff review with risk assessment
+3. **Phase 3**: [Version Bump](phases/03-version-bump.md) -- Detect and update version across project types
+4. **Phase 4**: [Changelog & Commit](phases/04-changelog-commit.md) -- Generate changelog, create release commit, push
+5. **Phase 5**: [PR Creation](phases/05-pr-creation.md) -- Create PR with structured body and issue links
+
+## Pre-Flight Checklist (Quick Reference)
+
+| Check | Command | Pass Condition |
+|-------|---------|----------------|
+| Git clean | `git status --porcelain` | Empty output |
+| Branch | `git branch --show-current` | Not main/master |
+| Tests | `npm test` / `pytest` | Exit code 0 |
+| Build | `npm run build` / `python -m build` | Exit code 0 |
+
+## Completion Status Protocol
+
+This skill follows the Completion Status Protocol defined in [SKILL-DESIGN-SPEC.md sections 13-14](../_shared/SKILL-DESIGN-SPEC.md#13-completion-status-protocol).
+
+Every execution terminates with one of:
+
+| Status | When |
+|--------|------|
+| **DONE** | All 5 phases completed, PR created |
+| **DONE_WITH_CONCERNS** | PR created but with review warnings or non-critical issues |
+| **BLOCKED** | A gate failed (dirty git, tests fail, push rejected) |
+| **NEEDS_CONTEXT** | Cannot determine bump type, ambiguous branch target |
+
+### Escalation
+
+Follows the Three-Strike Rule (SKILL-DESIGN-SPEC section 14). On 3 consecutive failures at the same step, stop and output diagnostic dump.
+
+## Reference Documents
+
+| Document | Purpose |
+|----------|---------|
+| [phases/01-preflight-checks.md](phases/01-preflight-checks.md) | Git, branch, test, build validation |
+| [phases/02-code-review.md](phases/02-code-review.md) | AI-powered diff review |
+| [phases/03-version-bump.md](phases/03-version-bump.md) | Version detection and bump |
+| [phases/04-changelog-commit.md](phases/04-changelog-commit.md) | Changelog generation and release commit |
+| [phases/05-pr-creation.md](phases/05-pr-creation.md) | PR creation with issue linking |
+| [../_shared/SKILL-DESIGN-SPEC.md](../_shared/SKILL-DESIGN-SPEC.md) | Skill design spec (completion protocol, escalation) |