Init

---
description: Bootstrap or update a repo for hashb compliance -- Project Profile, rules, business scaffolds. Idempotent.
---

# Init

Bootstrap or update a consumer repo for hashb compliance. Interactive --
asks about fields it can't auto-detect.

**Idempotent.** Running `/init` twice produces the same result. Never duplicates content.

**Input:** Consumer repo (current working directory), optionally an `/audit` report.
**Output:** Updated repo structure with hashb compliance scaffolding.

---

## When to Use

| Situation | Skill |
|-----------|-------|
| New repo adopting hashb | **`/init`** |
| Existing repo, check compliance first | `/audit` then `/init` |
| Scaffold a new module | `/module` (after `/init` sets up the repo) |
| Review code | `/review` |

`/init` is the entry point for new hashb consumers. Run it once to set up,
run it again to update or fix drift.

---

## Execution Flow (MANDATORY)

> **This is the ONLY valid sequence. Never skip or reorder phases.**
> Each gate marked **STOP** requires completion before proceeding.

```
┌─────────────────────────────────────────────────┐
│ Phase 0: Assess Current State                   │
└────────────────────┬────────────────────────────┘
                     │
              ■ STOP │ User approves action plan
                     │
┌────────────────────┴────────────────────────────┐
│ Phase 0.25: Stray Doc Consolidation (if found)  │
└────────────────────┬────────────────────────────┘
                     │
              ■ STOP │ User approves per-doc action
                     │
┌────────────────────┴────────────────────────────┐
│ Phase 0.5: CLAUDE.md Refactor (if bloated)      │
└────────────────────┬────────────────────────────┘
                     │
              ■ STOP │ User approves extraction plan
                     │
┌────────────────────┴────────────────────────────┐
│ Phase 1: Project Profile (interactive)          │
└────────────────────┬────────────────────────────┘
                     │
              ■ STOP │ User confirms all fields
                     │
┌────────────────────┴────────────────────────────┐
│ Phase 2: Rules Setup                            │
└────────────────────┬────────────────────────────┘
                     │
              ■ STOP │ User approves rule scaffolds
                     │
┌────────────────────┴────────────────────────────┐
│ Phase 3: Rule Overrides                         │
└────────────────────┬────────────────────────────┘
                     │
              ■ STOP │ User approves each override
                     │
┌────────────────────┴────────────────────────────┐
│ Phase 4: Supporting Files                       │
└────────────────────┬────────────────────────────┘
                     │
┌────────────────────┴────────────────────────────┐
│ Phase 5: Verify                                 │
└─────────────────────────────────────────────────┘
```

---

## Presentation Rules

1. **Wizard flow** — present one phase at a time. Never dump everything at once.
2. **Discussion chunking** — when a follow-up response would be too dense to digest in one shot, present a numbered big-picture overview first, then discuss each point one at a time, waiting for user input between points. Use judgment: chunk whenever the response feels like a wall of text, not at a fixed threshold.
3. **Gate placement** — gates emit at the BOTTOM of each phase's output, after receipts/plan, not above. The reader has context to decide without scrolling back up. No top-of-page gate prompt + bottom reminder duplication.
4. **Progress indicator** — every output starts with the block below; **re-emit the full block at the start of any phase that contains a gate** (Phases 0, 0.25, 0.5, 1, 2, 3):

```
/init ═══════════════════════════════════════════════════════════

  ▸ Phase 0      Assess Current State
  ○ Phase 0.25   Stray Doc Consolidation    (if needed)
  ○ Phase 0.5    CLAUDE.md Refactor         (if needed)
  ○ Phase 1    Project Profile
  ○ Phase 2    Rules Setup
  ○ Phase 3    Rule Overrides
  ○ Phase 4    Supporting Files
  ○ Phase 5    Verify

═════════════════════════════════════════════════════════════════
```

Update `▸` (current), `✓` (done), `○` (pending) as phases progress.
Completed phases show a status note on the right (e.g., `✓ 6/6 fields`, `✓ 3 rules`).

Also follow the shared formatting rules in `skills/shared/formatting.md`.

---

## Phase 0: Assess Current State

Detect what already exists. If `/audit` was run previously in the conversation,
consume its report to prioritize actions. If `/understand` was run, consume
`.understand/architecture-map.md` to pre-populate Profile fields and domain boundaries.

```bash
# What exists?
ls CLAUDE.md README.md CHANGELOG.md TODOS.md .gitignore .claudeignore 2>/dev/null
ls -d rules/ rules/business/ 2>/dev/null

# Detect stack
ls package.json requirements.txt Pipfile pyproject.toml go.mod Cargo.toml \
   *.csproj *.sln composer.json Gemfile 2>/dev/null

# Read existing CLAUDE.md if present
cat CLAUDE.md 2>/dev/null | head -100

# Architecture map from /understand (if run previously)
ls .understand/architecture-map.md 2>/dev/null

# Count source directories for complexity check
ls -d src/*/ app/*/ lib/*/ modules/*/ services/*/ packages/*/ 2>/dev/null | wc -l
```

### Complexity Check

If the repo has 5+ top-level source directories and no `.understand/architecture-map.md`
exists, suggest running `/understand` first:

> "This looks like a complex codebase with {N} source directories. Consider running
> `/understand` first to map the architecture — the findings will pre-populate
> Architecture, domain boundaries, and other Profile fields here."

This is a suggestion, not a gate. If the user wants to proceed, continue normally.

Present assessment in table format:

```
INIT ASSESSMENT ─────────────────────────────────────────────────
```

| Area | Check | Status | Action |
|------|-------|--------|--------|
| CLAUDE.md | File exists | {yes / missing} | {skip / create} |
| CLAUDE.md | Project Profile present | {complete / partial / missing} | {skip / add fields / create} |
| CLAUDE.md | Under 200 lines | {yes / no ({N} lines)} | {skip / refactor: extract to rules/} |
| CLAUDE.md | No inlined rule/skill content | {yes / no} | {skip / extract to files, replace with paths} |
| Rules | `rules/` directory exists | {yes / missing} | {skip / create} |
| Rules | `rules/business/` exists | {yes / empty / missing} | {skip / scaffold} |
| Rules | All rules have `paths:` frontmatter | {yes / {N} missing} | {skip / add frontmatter} |
| Rules | Overrides present | {N found} | {skip / suggest} |
| Stray docs | Documents overlapping with hashb structure | {none / {N} found} | {skip / consolidate} |
| Routing | Skill Routing section present | {yes / missing} | {skip / add} |
| Context | `@` imports in CLAUDE.md | {N} | {ok ≤ 5 / refactor} |
| Context | Skills referenced by name only | {yes / inlined} | {skip / extract} |
| Support | CHANGELOG.md | {exists / missing} | {skip / create} |
| Support | .gitignore (hashb entries) | {present / missing} | {skip / add entries} |
| Support | .claudeignore | {exists / missing / incomplete} | {skip / create / add entries} |
| Support | .env.example | {exists / missing / n/a} | {skip / create from .env} |
| Support | Testing config detected | {vitest / jest / pytest / etc. / none} | — |
| Docs | README.md sections complete | {yes / {N} missing} | {skip / scaffold missing} |
| Docs | LICENSE file | {exists / missing} | {skip / suggest} |
| Docs | KORE.md (getting started) | {exists / missing} | {skip / generate} |

```
  PLAN
  ─────────────────────────────────────────────────
  1.  {action — e.g., "Create CLAUDE.md with Project Profile"}
  2.  {action — e.g., "Extract inlined rules to rules/ with paths: frontmatter"}
  3.  {action — e.g., "Add paths: to 3 rule files missing it"}

  SKIP (already compliant)
  ─────────────────────────────────────────────────
  -  {item — e.g., "CHANGELOG.md exists and follows format"}

─────────────────────────────────────────────────────────────────
```

> **STOP.** User approves the action plan before any changes.

---

### Branch Guard

Before making any file changes, ensure you're on a feature branch:

```bash
BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
  echo "⚠ ON PROTECTED BRANCH — creating chore branch"
  git checkout -b "chore/hashb-init"
fi
```

> **Never modify repo structure directly on main/master.**

---

## Phase 0.25: Stray Document Consolidation

**Skip if:** No stray documents detected in Phase 0 assessment.

**Trigger if:** Phase 0 found documents outside hashb's expected locations that
overlap with content hashb manages (rules, CLAUDE.md sections, supporting files).

### Why This Comes Before CLAUDE.md Refactor

Stray documents may contain content that should be merged into CLAUDE.md, rule
files, or other hashb-managed locations. Consolidating them first prevents
duplication — Phase 0.5 (CLAUDE.md Refactor) then works with the complete picture.

> **Full walkthrough:** See `references.md` for discovery commands,
> classification rules, per-document approval format, and execution steps.

---

## Phase 0.5: CLAUDE.md Refactor

**Skip if:** CLAUDE.md doesn't exist, or is under 200 lines with no inlined content.

**Trigger if:** CLAUDE.md is over 200 lines, OR contains inlined rule/skill content,
OR has large instruction blocks that belong in scoped rule files.

### Why This Comes First

A bloated CLAUDE.md degrades Claude's instruction adherence and wastes tokens on
every message. Fixing this before adding Profile, Routing, and rules prevents
the file from growing further. Extract first, then build on a lean foundation.

> **Full walkthrough:** See `references.md` for section classification
> rules, extraction plan format, and execution steps.

---

## Phase 1: Project Profile (Interactive)

If CLAUDE.md is missing or has no Project Profile, walk through each field.

> **Per-field walkthrough:** See `references.md` for auto-detection
> commands, per-field prompts (Stack through MCP Servers), and the
> Skill Routing template.

### Architecture Map Integration

If `.understand/architecture-map.md` exists, read it and use findings to
pre-populate suggestions for fields that normally require asking:

| Field | How architecture map helps |
|-------|--------------------------|
| Architecture | Use Module Boundaries + Data Flow to suggest (e.g., "modular monolith with 5 domains") |
| Tenancy | Check Conventions Detected for tenant scoping patterns |
| MCP Servers | If graphify was used in the map, recommend adding it as MCP server |

Present these as evidence-backed suggestions, not assumptions. User still confirms.


### Graphify MCP Recommendation

During the MCP Servers walkthrough, check if graphify is installed:

```bash
python -c "import graphify; print('installed')" 2>/dev/null || echo "not installed"
```

If installed but not in MCP Servers: recommend adding it. Provide the config snippet:

```json
{
  "mcpServers": {
    "graphify": {
      "command": "python",
      "args": ["-m", "graphify.serve", "/absolute/path/to/graphify-out/graph.json"]
    }
  }
}
```

> "Graphify is installed. Adding it as an MCP server enables graph-accelerated
> analysis in `/understand`, `/explore`, `/review`, and `/audit`."

### Graphify CLAUDE.md Section

If graphify is installed AND `graphify-out/` exists (graph already built),
scaffold a `## graphify` section in the consumer's CLAUDE.md:

```markdown
## graphify

Graph available at `graphify-out/`. For structural questions (architecture,
schemas, dependencies, connections), query graph MCP tools before exploring
raw files. See skill docs for tool reference.
```

This section establishes the query-first behavioral rule. Keep it short —
CLAUDE.md survives compaction (rule E5), so every token is loaded every session.
MCP tool reference tables belong in the skills, not here.

If `graphify-out/` does not exist, skip this section — only recommend adding
graphify to MCP Servers (see above).

> **STOP.** User confirms the Profile looks correct.

---

## Phase 2: Rules Setup

Based on the declared Profile, set up the rules directory structure.

### Determine What's Needed

| Profile Signal | Rules Action |
|----------------|-------------|
| Architecture mentions "modular" or domain boundaries | Create `rules/business/<domain>/` scaffolds |
| Architecture mentions "microservices" | Create per-service business rule scaffolds |
| Stack includes specific frameworks | Verify matching frontend/backend rules apply |
| No business rules exist | Suggest domain areas based on directory scan |

### Detect Domain Boundaries

```bash
# Scan for domain-like directories
ls -d src/*/  app/*/  lib/*/  modules/*/  services/*/ 2>/dev/null
```

### Create Business Rule Scaffolds

For each identified domain area, create a starter rule file:

```yaml
---
id: business-{domain}
description: "TODO: Business rules for {domain} -- add domain-specific constraints"
paths:
  - "src/{domain}/**/*"
---

# {Domain} Business Rules

> TODO: Add domain-specific rules for this bounded context.
> These rules activate when Claude reads files matching the paths above.

## Constraints

> TODO: What invariants must this domain preserve?
> Examples:
> - "Orders must always have a valid customer reference"
> - "Prices are stored in cents, never floating point"

## Patterns

> TODO: What patterns should code in this domain follow?
> Examples:
> - "All mutations go through domain services, never direct DB access"
> - "Events published for every state transition"
```

Present the scaffolds:

```
RULES SCAFFOLDS:
  1. rules/business/{domain-a}/{domain-a}.md
     Paths: src/{domain-a}/**/*
     Status: NEW (TODO template)

  2. rules/business/{domain-b}/{domain-b}.md
     Paths: src/{domain-b}/**/*
     Status: NEW (TODO template)
```

> **STOP.** User approves rule scaffolds. They can add, remove, or rename domains.

---

## Phase 3: Rule Overrides

Based on the declared stack and codebase structure, suggest rule overrides
where the consumer's repo legitimately needs different behavior.

### Override Detection

| Signal | Suggested Override | Reason |
|--------|-------------------|--------|
| `**/test-utils/**`, `**/fixtures/**` | Override `testing` | Test helpers don't need full test discipline |
| Generated code (Prisma client, protobuf, etc.) | Override `security` | Auto-generated, not human-written |
| Internal admin tools (`**/admin/**`) | Override `security` | Internal-only, behind VPN |
| Migration files (`**/migrations/**`) | Override `git` | Different commit conventions for migrations |
| Scripts/tooling (`**/scripts/**`) | Override `security` | Dev tooling, not production code |

### Per-Override Approval

For each suggested override, present:

```
SUGGESTED OVERRIDE:
  Paths:     src/admin/**/*.ts
  Overrides: security
  Reason:    Admin tools are internal-only, behind VPN

  Relaxations:
  - CSRF tokens not required (internal tool)
  - Rate limiting relaxed (low traffic, trusted users)

  All other security rules still apply.

  Create this override? [y/n]
```

> **STOP.** User approves each override individually.

---

## Phase 4: Supporting Files

Check and update supporting files. These are done without individual approval
unless the change is significant.

### .gitignore

Add hashb-relevant entries if missing:

```
# hashb audit/qa artifacts
.audit/
.qa-reports/
.retro/
```

### .claudeignore, .env.example, CHANGELOG.md, TODOS.md, README.md, KORE.md

> **File templates:** See `references.md` for .claudeignore template,
> .env.example format, README section scaffolds, and KORE.md template.

---

## Phase 5: Verify

Run a quick check to confirm the setup is correct.

### Verification Checklist

| Area | Check | Status |
|------|-------|--------|
| Profile | CLAUDE.md exists with Project Profile | {pass / fail} |
| Profile | All Profile fields populated | {N}/6 |
| Profile | Context7 listed in MCP Servers | {pass / fail} |
| Routing | Skill Routing section present | {pass / fail} |
| Stray docs | No overlapping documents outside hashb structure | {pass / fail ({N} remaining)} |
| Context | CLAUDE.md under 200 lines | {pass / fail ({N} lines)} |
| Context | No inlined rule/skill content | {pass / fail} |
| Context | Skills referenced by name only | {pass / fail} |
| Rules | Directory structure valid | {pass / fail} |
| Rules | All rules have `paths:` frontmatter | {pass / fail ({N}/{total})} |
| Rules | Business rule frontmatter valid | {pass / fail / n/a} |
| Rules | Override targets resolve | {pass / fail / n/a} |
| Support | .gitignore has hashb entries | {pass / fail} |
| Support | .claudeignore exists with recommended entries | {pass / fail} |
| Support | .env.example exists (if .env detected) | {pass / fail / n/a} |
| Support | CHANGELOG.md exists | {pass / fail} |
| Docs | README.md has required sections | {pass / fail ({N}/5)} |
| Docs | LICENSE file exists | {pass / fail} |
| Docs | KORE.md getting started guide | {pass / fail} |

### Summary

```
✓ INIT COMPLETE ─────────────────────────────────────────────────

  CREATED
  ─────────────────────────────────────────────────
  -  {list of new files}

  UPDATED
  ─────────────────────────────────────────────────
  -  {list of modified files}

  SKIPPED (already compliant)
  ─────────────────────────────────────────────────
  -  {list}

  VERIFIED
  ─────────────────────────────────────────────────
  Profile fields           {N}/6 populated
  Rules structure          valid
  Business rule frontmatter valid
  Rule overrides           {N} created

  Next: /hashb:audit (recommended — verify compliance){· /hashb:eng (if ready to start feature work) — only when flagged · /hashb:spec (if requirements work comes first) — only when flagged}

─────────────────────────────────────────────────────────────────
```

### Next: line resolution

The recommendation is `/hashb:audit` in nearly every case — `/init` produces structural changes and `/audit` is the verification pass that confirms them. Alternatives are signal-gated:

| Condition detected | Append on `Next:` line | Phrase |
|---|---|---|
| User explicitly stated readiness to build a feature next | `/hashb:eng` | `if ready to start feature work` |
| User explicitly stated requirements work comes first | `/hashb:spec` | `if requirements work comes first` |

If neither signal fired, emit only the recommendation. Examples (canonical form):

```
Next: /hashb:audit (recommended — verify compliance)
Next: /hashb:audit (recommended — verify compliance)  ·  /hashb:eng (if ready to start feature work)
```

**Autonomous mode:** If running inside a recipe chain (e.g., Onboarding):
- After initial setup → auto-proceed to `/hashb:audit`
- After fixing audit findings → auto-re-run `/hashb:audit` for verification

---

## Idempotency Rules

Every action checks before modifying:

| Action | Before creating | If exists |
|--------|-----------------|-----------|
| Stray documents | Scan for overlapping docs | Skip -- already consolidated |
| CLAUDE.md | Check if file exists | Update Profile and Routing sections only, preserve rest |
| Business rule scaffold | Check if rule file exists | Skip -- don't overwrite user's rules |
| Rule override | Check if override exists | Skip -- don't duplicate |
| .gitignore entries | Check if entries present | Add only missing entries |
| .claudeignore | Check if file exists and has entries | Add only missing entries |
| .env.example | Check if file exists | Skip -- don't overwrite |
| CHANGELOG.md | Check if file exists | Skip -- don't overwrite |
| TODOS.md | Check if file exists | Skip -- don't overwrite |
| README.md sections | Check which sections exist | Add only missing sections, preserve existing |
| KORE.md | Check if file exists | Skip -- don't overwrite |

**Running `/init` after `/init` should produce:**
```
Already compliant. {N} items verified, 0 changes needed.
```

---

## Rules

- **Idempotent.** Running twice produces the same result. Never duplicate content.
- **Interactive.** Never assume -- ask about fields that can't be auto-detected.
  The user knows their stack better than dependency file analysis.
- **Preserve existing content.** When updating CLAUDE.md, preserve all non-Profile
  sections. Never delete user content.
- **Scaffolds are templates, not opinions.** Business rule scaffolds contain TODO
  markers, not opinionated content the consumer didn't write.
- **Consume /audit output.** If an audit report exists in conversation context,
  use its findings to prioritize actions and skip already-compliant items.
- **Minimal changes.** Only create what's needed for hashb compliance. Don't
  refactor the consumer's project structure.
- **Explain every file.** Before creating or modifying any file, state what it
  does and why it's needed.
- **Respect the consumer's choices.** If they decline an override or rule scaffold,
  accept it. Don't re-suggest in the same session.