Project Setup

When to Use

• •Joining existing project without CLAUDE.md
• •Project has outdated/incomplete CLAUDE.md
• •Taking over maintenance of unfamiliar codebase
• •Claude repeatedly asks the same questions

Onboarding Workflow

Phase 1: Discovery

1. Repository structure scan (Glob)
2. Package/dependency analysis (package.json, go.mod, requirements.txt)
3. Configuration files (tsconfig, .eslintrc, Makefile)
4. Existing documentation (README, docs/, CONTRIBUTING)
5. CI/CD configuration (.github/workflows)

Phase 2: Pattern Extraction

Phase 3: CLAUDE.md Generation

Generate with this structure:

```markdown

CLAUDE.md - [Project Name]

Status: Active Development | Maintenance | Legacy Last Updated: YYYY-MM-DD

Critical Rules

ALWAYS [most important constraints] NEVER [dangerous actions to avoid]

Architecture

``` src/ ├── components/ # [purpose] ├── lib/ # [purpose] └── utils/ # [purpose] ```

Tech Stack

Commands

Known Pitfalls

CLAUDE.md Best Practices

ALWAYS:

• •Start with Status and Last Updated
• •Put Critical Rules (NEVER/ALWAYS) at top
• •Use specific versions, paths, exact commands
• •Include code examples for key patterns

NEVER:

• •Write vague descriptions ("modern tech stack")
• •Skip examples for important concepts
• •List commands without context

File Hierarchy

All locations load automatically. Most specific wins.

Modularization with @imports

For large projects, split documentation:

```markdown

CLAUDE.md

@docs/architecture.md @docs/api-conventions.md @docs/testing-strategy.md ```

Keep main CLAUDE.md clean. Only core rules inline.

Policies (Strict Guidelines)

Policies are STRICT constraints that MUST be followed:

```json { "project_id": "global", "title": "POLICY: test-before-fix", "content": "RULE: Always run tests before claiming a fix is complete.\nCATEGORY: verification\nSEVERITY: high", "outcome": "success", "tags": ["type:policy", "category:verification", "severity:high"] } ```

Categories: verification, process, security, quality, communication

Severity: critical, high, medium

After Setup

```

Re-index repository with new documentation

repository_index(path: ".")

Record the setup as a memory

memory_record( project_id: "<project>", title: "Project onboarded with CLAUDE.md", content: "Created CLAUDE.md with architecture, commands, pitfalls...", outcome: "success", tags: ["onboarding", "claude-md"] ) ```

Common Mistakes

Quick Reference

Tech Stack Database Patterns

Automatic Stack Detection

Setup auto-detects and records tech stack metadata:

Stack-Specific Memories

Setup creates foundation memories per stack:

```json { "project_id": "contextd", "title": "STACK: Go 1.22 with embedded vectorstore", "content": "Tech: Go 1.22\nDeps: chromem-go, chi router\nPatterns: Registry DI, table-driven tests\nLinting: golangci-lint", "tags": ["type:pattern", "stack:go", "auto-generated"] } ```

Database Pattern Recognition

Policy Enforcement Metadata

Policy Structure

Policies are STRICT constraints with enforcement metadata:

```json { "project_id": "global", "title": "POLICY: test-before-fix", "content": "RULE: Always run tests before claiming a fix is complete.", "outcome": "success", "tags": ["type:policy", "category:verification", "severity:high"], "enforcement": { "mode": "strict", "check_hook": "PreToolUse", "check_tool": "Bash", "violation_action": "block" } } ```

Enforcement Modes

Policy Categories

Setup Checksums

Integrity Verification

Setup generates checksums to detect drift:

```json { "setup_checksum": { "claude_md_hash": "sha256:abc123...", "stack_snapshot": "sha256:def456...", "policy_version": "v1.2.0", "generated_at": "2026-01-28T10:00:00Z" } } ```

Drift Detection

On session start, compare checksums:

```

1. •Hash current CLAUDE.md
2. •Compare to stored setup_checksum.claude_md_hash
3. •If mismatch:
   • •Warn: "CLAUDE.md has changed since setup"
   • •Suggest: "Run /init --update to sync" ```

Checksum Commands

Hierarchical Namespace Guidance

Project ID Structure

``` <org>/<team>/<project>/<module>

Examples: fyrsmithlabs/platform/contextd/api fyrsmithlabs/platform/contextd/vectorstore fyrsmithlabs/marketplace/fs-dev/skills ```

ID Format Requirements (contextd v1.5+)

IMPORTANT: `tenant_id` and `project_id` must be lowercase alphanumeric with underscores:

• •Valid: `my_project`, `contextd`, `org123`, `fyrsmithlabs_marketplace`
• •Invalid: `My-Project`, `org/repo`, `project..name`
• •Length: 1-64 characters

When deriving IDs from git remotes:

• •Replace hyphens with underscores: `my-project` → `my_project`
• •Remove invalid characters (slashes, dots)
• •Convert to lowercase

Setup Namespace Detection

Setup auto-detects namespace from:

1. •Git remote URL: `github.com/fyrsmithlabs/contextd` -> `fyrsmithlabs/contextd`
2. •Directory structure: Monorepo detection
3. •Existing CLAUDE.md: Parse namespace declarations

Namespace Inheritance

```markdown

In root CLAUDE.md

@namespace fyrsmithlabs/platform

In packages/api/CLAUDE.md (inherits)

@namespace ../api # Resolves to fyrsmithlabs/platform/api ```

Audit Fields

Setup records create audit metadata:

Claude Code 2.1 Patterns

Background Indexing

Use background tasks for large repos:

``` Task( subagent_type: "general-purpose", prompt: "Index all source files in /path/to/repo", run_in_background: true, description: "Repository indexing" )

// Continue with other setup tasks... TaskOutput(task_id, block: false) // Check progress ```

Setup Task Dependencies

Chain setup phases:

``` phase1 = Task(prompt: "Scan repository structure") phase2 = Task(prompt: "Detect tech stack", addBlockedBy: [phase1.id]) phase3 = Task(prompt: "Generate CLAUDE.md", addBlockedBy: [phase2.id]) phase4 = Task(prompt: "Index repository", addBlockedBy: [phase3.id]) ```

PreToolUse Hook for Setup Verification

Auto-verify setup before operations:

```json { "hook_type": "PreToolUse", "tool_name": "Read", "condition": "file_path.endsWith('CLAUDE.md')", "prompt": "Check setup checksum for drift before reading CLAUDE.md." } ```

Event-Driven State Sharing

Setup emits events for other skills:

```json { "event": "setup_complete", "payload": { "project_id": "fyrsmithlabs/contextd", "stack": "go", "policies_loaded": 5, "checksum": "sha256:..." }, "notify": ["workflow", "consensus-review"] } ```

Subscribe to setup events:

• •`setup_started` - Setup initiated
• •`setup_complete` - Setup finished successfully
• •`setup_drift_detected` - Checksum mismatch found
• •`policy_loaded` - New policy activated