dark-code-suite-init

name

dark-code-suite-init

description

Sets up a project to use the full dark code prevention suite in one step: creates the .claude/comprehension/ directory for comprehension artifacts, adds a ## Dark Code Prevention section to CLAUDE.md (or creates CLAUDE.md if missing), creates docs/dark-code-audit/ for audit reports, and runs an initial dark-code-audit to baseline the project's current comprehension debt. Use this skill when starting to use the dark code suite on a new project, when onboarding a codebase to dark code prevention practices, or any time you hear "set up dark code prevention", "initialize the dark code suite", "add comprehension gate to this project", or "how do I start with dark code practices here".

Dark Code Suite Init

You are setting up a project to use the full dark code prevention suite. This is a one-time initialization per project.

---

Step 1: Create required directories

Create these if they don't exist:

• .claude/comprehension/ — where comprehension-gate writes COMPREHENSION_ARTIFACT.md files
• docs/dark-code-audit/ — where dark-code-audit writes audit reports

---

Step 2: Update or create CLAUDE.md

Read the existing CLAUDE.md at the project root. If it doesn't exist, create it.

Add a ## Dark Code Prevention section. If a section with this name already exists, skip (don't duplicate it).

The section to add:

## Dark Code Prevention

This project uses the dark code prevention suite. The three skills that matter most:

- `/context-layer-generator <module-path>` — generates MODULE_MANIFEST.md,
  BEHAVIORAL_CONTRACTS.md, and DECISION_LOG.md for a module. Run this for any module
  that lacks context files before making significant changes.

- `/comprehension-gate` — runs a seven-dimension comprehension review before committing.
  Required for changes over 50 lines to modules that touch shared resources.

- `/dark-code-audit` — audits the full codebase for comprehension debt. Run quarterly
  or before major compliance/security reviews.

### Context layer files

For each significant module, the following files should exist at the module root:
- `MODULE_MANIFEST.md` — structural map: dependencies, dependents, shared resources, owner
- `BEHAVIORAL_CONTRACTS.md` — per-interface behavioral guarantees
- `DECISION_LOG.md` — architectural decisions with Warning fields

When modifying a module: check if these files exist. If they don't, run
`/context-layer-generator` before making significant changes.

### Comprehension artifact

Before committing changes over 50 lines to modules that touch shared infrastructure
(Redis, databases, queues, cross-service APIs), run `/comprehension-gate` and ensure
a COMPREHENSION_ARTIFACT.md exists in `.claude/comprehension/`.

### What this suite does NOT address

Runtime agent path monitoring, cross-tenant data exposure at runtime, and tamper-proof
regulatory audit logging require production observability tooling beyond Claude Code.

---

Step 3: Report

After setup:

Dark code suite initialized for: [project name]

Created:
  ✓ .claude/comprehension/   (comprehension artifacts go here)
  ✓ docs/dark-code-audit/    (audit reports go here)
  ✓ CLAUDE.md updated        (dark code prevention section added)

Next steps:
  1. Run /dark-code-audit to baseline this project's comprehension debt
  2. Run /context-layer-generator <highest-risk-module> to start building context layers
  3. Run /comprehension-gate before your next significant commit

The pre-commit hook in settings.json will enforce comprehension artifacts on commits
over 50 lines. Run /dark-code-audit to see which modules need context layers first.