Bootstrap Project

Initialize a complete

.claude/

in the current project using the dotforge template.

Step 0: Determine profile

Check if $ARGUMENTS contains

--profile minimal

,

--profile standard

, or

--profile full

. If not specified, use

standard

as default.

Profiles control what gets installed:

Component	minimal	standard	full
CLAUDE.md	yes	yes	yes
settings.json	yes	yes	yes
block-destructive hook	yes	yes	yes
lint-on-save hook	no	yes	yes
session-report hook	no	yes	yes
warn-missing-test hook	no	no	yes (strict profile)
rules/ (_common + stack)	yes	yes	yes
commands/	no	yes	yes
agents/ + orchestration	no	yes	yes
agent-memory/	no	no	yes
CLAUDE_ERRORS.md	no	yes	yes (pre-populated)
memory.md rule	no	yes	yes

Save the profile in

.claude/settings.local.json

under

env.FORGE_BOOTSTRAP_PROFILE

.

Step 1: Detect stack

Use detection rules from

$DOTFORGE_DIR/stacks/detect.md

.

Step 2: Confirm with user

Show:

Profile: {{profile}}
Detected stack: {{stacks}}
Will create:
- CLAUDE.md (base template + stack rules)
- .claude/settings.json (base permissions + stack)
- .claude/rules/ (common rules + stack)
- .claude/hooks/ (block-destructive + lint + session-report)  [minimal: block-destructive only]
- .claude/commands/ (audit, health)                    [minimal: skipped]
- .claude/agents/ + orchestration                      [minimal: skipped]
- CLAUDE_ERRORS.md (empty, for error logging)          [minimal: skipped]

Proceed? (yes/no)

Adapt the list shown based on the profile (hide components that won't be installed).

Step 3: Generate CLAUDE.md

Use

$DOTFORGE_DIR/template/CLAUDE.md.tmpl

as the base. Replace markers:

• {{PROJECT_NAME}}

  → name of the current directory

• <!-- forge:stack -->

  → detected technologies

• <!-- forge:commands -->

  → detected build/test commands (package.json scripts, Makefile targets, etc.)

Step 4: Generate settings.json

1. Load

   $DOTFORGE_DIR/template/settings.json.tmpl

   as the base
2. For each detected stack, read

   $DOTFORGE_DIR/stacks/{stack}/settings.json.partial

3. Merge: combine the

   allow

   arrays from all partials with the base (union of sets, no duplicates)
4. Merge: combine the

   deny

   arrays the same way
5. Write to

   .claude/settings.json

Multi-stack: If multiple stacks are detected (e.g.: python-fastapi + react-vite-ts + docker-deploy), merge ALL partials. Order does not matter — it is a union of sets.

Step 4b: Validate JSON

Before writing

settings.json

, validate that the generated JSON is valid:

python3 -c 'import json; json.load(open(".claude/settings.json"))' 2>&1

Or if not yet written, validate the content in memory/string:

echo '<json_content>' | python3 -c 'import json,sys; json.load(sys.stdin)'

If validation fails, show the exact error and DO NOT write the file. Fix the JSON before continuing.

Step 5: Copy hooks

1. Copy

   $DOTFORGE_DIR/template/hooks/block-destructive.sh

   →

   .claude/hooks/

   (ALL profiles)
2. If profile is

   standard

   or

   full

   : copy

   $DOTFORGE_DIR/template/hooks/lint-on-save.sh

3. If profile is

   standard

   or

   full

   : copy

   $DOTFORGE_DIR/template/hooks/session-report.sh

4. If profile is

   standard

   or

   full

   : copy

   $DOTFORGE_DIR/template/hooks/detect-stack-drift.sh

5. If profile is

   full

   : copy

   $DOTFORGE_DIR/template/hooks/warn-missing-test.sh

6. chmod +x

   all copied hooks
7. For each detected stack, if

   $DOTFORGE_DIR/stacks/{stack}/hooks/

   exists:
   • Copy the entire hooks directory to

     .claude/hooks/{stack}/

   • If a

     core/

     directory exists alongside hooks, copy it too (e.g., hookify needs core/ + hooks/)
   • Ensure Python scripts are executable

Step 6: Copy rules

1. Copy

   $DOTFORGE_DIR/template/rules/_common.md

   →

   .claude/rules/

2. For each detected stack, copy rules from

   $DOTFORGE_DIR/stacks/{stack}/rules/

   →

   .claude/rules/

Step 6b: Domain knowledge scaffolding

Only if domain info was provided (via

/forge init

Q4 or user explicitly requests it during bootstrap).

If any detected stack has a

domain:

field in its rules (e.g.,

stacks/trading/rules/trading.md

):

1. Create

   .claude/rules/domain/

   directory
2. Copy domain-tagged rules from the stack into

   .claude/rules/domain/

   instead of

   .claude/rules/

3. Show: "Domain stack detected: {{domain}}. Domain rules copied to .claude/rules/domain/"

If the user provided domain description (from init Q4 context):

1. Create

   .claude/rules/domain/

   directory if not exists
2. Generate 1-3 seed domain rule files based on the described concepts:
   • Each file: frontmatter with

     globs:

     (domain-specific patterns),

     domain:

     tag,

     last_verified:

     (today)
   • Content: key facts, constraints, business rules — concise, imperative, <40 lines each
   • File names: kebab-case matching the domain area (e.g.,

     jira-api.md

     ,

     agile-metrics.md

     )
3. Show generated files to user for confirmation before writing

If neither condition is met, skip this step entirely — no noise for projects without domain context.

Important: Domain rules in

.claude/rules/domain/

are project-owned. They are NOT tracked in the forge manifest and are NOT updated by

/forge sync

.

Step 7: Copy commands

Skip if profile is

minimal

.

Copy

$DOTFORGE_DIR/template/commands/

→

.claude/commands/

Step 8: Copy agents and orchestration rule

Skip if profile is

minimal

.

1. Copy

   $DOTFORGE_DIR/agents/*.md

   →

   .claude/agents/

2. Copy

   $DOTFORGE_DIR/template/rules/agents.md

   →

   .claude/rules/agents.md

This gives the project access to the 6 specialized subagents (researcher, architect, implementer, code-reviewer, security-auditor, test-runner) and the orchestration rule that defines when to delegate.

Step 9: Create CLAUDE_ERRORS.md

Skip if profile is

minimal

.

For

full

profile: pre-populate with the Type column format and example entry. For

standard

profile: create empty template.

# Known errors — {{PROJECT_NAME}}

Evolving log of errors and lessons learned. Consult BEFORE working in areas with prior errors.

Truth hierarchy: source code > CLAUDE.md > CLAUDE_ERRORS.md > auto-memory

## Format
| Date | Area | Type | Error | Root cause | Fix | Derived rule |
|------|------|------|-------|------------|-----|--------------|

Valid types: `syntax`, `logic`, `integration`, `config`, `security`

Step 9b: Create agent-memory/

Only for

full

profile. Standard creates the directory but not the seed files.

Create

.claude/agent-memory/

directory for agents with

memory: project

to persist learnings:

mkdir -p .claude/agent-memory

Create a seed file for each memory-enabled agent so the directory structure is ready:

for agent in implementer architect code-reviewer security-auditor; do
  touch ".claude/agent-memory/${agent}.md"
done

This enables implementer, architect, code-reviewer, and security-auditor to accumulate project-specific knowledge across sessions.

Step 10: Suggest global hook

If the user does not have

detect-claude-changes.sh

installed in

~/.claude/settings.json

, show:

Tip: For automatic practice capture, install the global hook:
Copy hooks/detect-claude-changes.sh to ~/.claude/hooks/
Add in ~/.claude/settings.json under hooks → Stop
See docs for details.

Step 11: Generate manifest

Create

.claude/.forge-manifest.json

with the SHA256 hash of each file created during bootstrap:

shasum -a 256 <file> | cut -d' ' -f1

Format:

{
  "dotforge_version": "<version from $DOTFORGE_DIR/VERSION>",
  "synced_at": "<current date YYYY-MM-DD>",
  "stacks": ["<detected-stack-1>", "<detected-stack-2>"],
  "files": {
    ".claude/settings.json": {"hash": "sha256:<hash>", "source": "template+stacks"},
    ".claude/rules/_common.md": {"hash": "sha256:<hash>", "source": "template"},
    ".claude/hooks/block-destructive.sh": {"hash": "sha256:<hash>", "source": "template"},
    ".claude/hooks/lint-on-save.sh": {"hash": "sha256:<hash>", "source": "template"}
  }
}

• source

  indicates where the file came from:

  "template"

  ,

  "template+stacks"

  (if merged from base + stacks), or

  "stacks/<name>"

  .
• Include ALL files created in

  .claude/

  (rules, hooks, commands, agents).
• Do NOT include CLAUDE.md or CLAUDE_ERRORS.md (they are in the root, not in

  .claude/

  ).

Step 12: Report

Show a summary of created files and suggest running

/audit-project

to verify.