Architecture

Architecture

Component Map

┌─────────────────────────────────────────────────────────────────┐
│                         dotforge                               │
├──────────┬──────────┬──────────┬──────────┬──────────┬──────────┤
│ template │  stacks  │  skills  │  agents  │practices │  audit   │
│          │  (16)    │  (14)    │  (7)     │          │          │
├──────────┴──────────┴──────────┴──────────┴──────────┴──────────┤
│                        global/                                   │
│              (~/.claude/ management via sync.sh)                  │
├─────────────────────────────────────────────────────────────────┤
│                         mcp/                                     │
│   MCP server templates (github, postgres, supabase, redis, slack)│
├─────────────────────────────────────────────────────────────────┤
│                    integrations/                                  │
│              (cross-tool bridges: OpenClaw)                       │
├─────────────────────────────────────────────────────────────────┤
│                      registry/                                   │
│              (cross-project tracking)                             │
└─────────────────────────────────────────────────────────────────┘

Data Flow

/forge bootstrap
    │
    ├── Detect stacks (stacks/detect.md)
    ├── Apply template/ base
    ├── Layer matching stacks/
    ├── Generate .claude/ in project
    └── Create .forge-manifest.json

/forge sync
    │
    ├── Compare manifest vs current template
    ├── Merge: managed sections updated, custom preserved
    └── Update manifest + registry

/forge audit
    │
    ├── Evaluate 12-item checklist
    ├── Apply scoring formula + security cap
    └── Append to registry history[]

Session hooks (automatic)
    │
    ├── block-destructive → /tmp/counter
    ├── lint-on-save → /tmp/counter
    └── session-report → ~/.claude/metrics/{slug}/{date}.json

Key Design Decisions

• Symlinks over copies — skills/agents are symlinked from dotforge to ~/.claude/, so updates propagate instantly
• Merge, never overwrite — sync preserves everything below <!-- forge:custom --> markers
• Additive stacks — stacks compose by set union of permissions, no conflicts
• Security cap — missing security basics cap the score at 6.0, regardless of other config quality
• Counter files — hooks use md5(PWD) for deterministic per-project temp files in /tmp/