stamp init Command

Initialize LogicStamp in your project by setting up .gitignore patterns and other project configuration.

Usage

Arguments

• [path] - Target directory to initialize (default: current directory)

Options

• --skip-gitignore - Skip .gitignore setup
• --yes, -y - Skip all prompts (non-interactive mode)
• --no-secure - Skip security scan (security scan runs by default in v0.3.0+)
• -h, --help - Show help

What It Does

stamp init sets up LogicStamp in your project by:

1. Creating or updating .gitignore with LogicStamp-specific patterns:

   The following patterns are added to prevent generated files and sensitive reports from being committed:

   • context.json - Per-folder context bundles generated by stamp context. These are large JSON files containing component contracts and dependency graphs. They're regenerated on each run and don't need to be versioned.

   • context_*.json - Main index file (context_main.json) and other context variants. The main index provides a directory overview of all context files. Like context.json, these are regenerated and can be large.

   • context.toon and context_*.toon - TOON format context bundles generated when using --format toon. These are alternative output format files (similar to JSON but in TOON format) that are regenerated on each run and don't need to be versioned.

   • *.uif.json - UIF (User Interface Format) contract files. These are generated contract sidecars that may be created by other LogicStamp tools. They're build artifacts and don't need to be committed.

   • logicstamp.manifest.json - Dependency manifest files that track project dependencies. These are generated metadata files that can be regenerated.

   • .logicstamp/ - Configuration directory containing user preferences (config.json) and potentially cache files. This directory stores local settings and shouldn't be committed.

   • stamp_security_report.json - 🔒 SECURITY CRITICAL: Security scan report file generated by stamp security scan. This file only contains sensitive information if secrets are actually detected (file locations, line numbers, code snippets). If no secrets are found, the report will have secretsFound: 0 and an empty matches: [] array. Note: Secrets should not normally be present in TypeScript, JavaScript, or JSON source files—they should be stored in .env files or environment variables. The security scan checks for secrets that may have been accidentally committed to source files. This file should never be committed to prevent exposing security findings. Important: Even if you don't run stamp init, stamp security scan automatically ensures this file is in .gitignore to protect sensitive findings.

   Why these patterns? LogicStamp generates files that are:

   • Large (context bundles can be hundreds of KB)
   • Regenerable (can be recreated from source code)
   • Potentially sensitive (security reports contain secret locations)
   • User-specific (configuration preferences vary by developer)

   These files are meant for local use and sharing with AI assistants, not for version control.

   🔒 Security Note: The stamp_security_report.json pattern is critical for security. This file only contains sensitive information if secrets are actually detected (file paths, line numbers, code snippets). If no secrets are found during the scan, the report will have secretsFound: 0 and an empty matches: [] array. Note: Secrets should not normally be present in TypeScript (.ts, .tsx), JavaScript (.js, .jsx), or JSON (.json) source files—they should be stored in .env files or environment variables. The security scan checks for secrets that may have been accidentally committed to source files. Even if you don't run stamp init, stamp security scan automatically ensures this file is in .gitignore to protect sensitive findings. Never commit security reports to version control.

2. Generating LLM_context.md in the project root (if it doesn't already exist) - A guide that helps AI assistants understand your project structure and how to work with LogicStamp context files

3. Creating .logicstamp/config.json to save your preferences so stamp context won't prompt again

Examples

Basic initialization

Initializes LogicStamp in the current directory. Creates or updates .gitignore with the necessary patterns and runs a security scan by default. This is non-interactive by default - informational messages are shown, but no prompts appear and all operations are performed automatically.

Initialize a specific directory

Initializes LogicStamp in the specified directory.

Skip .gitignore setup

Initializes LogicStamp but skips modifying .gitignore. Useful if you want to manage .gitignore manually.

Non-interactive mode

Initializes LogicStamp without any prompts. All operations are performed automatically. Note: This is redundant since stamp init is already non-interactive by default (security scan runs automatically). The --yes flag is provided for explicit clarity in CI/CD pipelines.

Skip security scan (enables interactive mode)

Initializes LogicStamp without running the security scan. This will:

1. Set up .gitignore patterns (with interactive prompts if in TTY)
2. Generate LLM_context.md (with interactive prompts if in TTY)

Note: By default, stamp init runs a security scan automatically, which makes it non-interactive. Use --no-secure to skip the security scan and enable interactive prompts (when running in a TTY environment).

Behavior

When .gitignore doesn't exist

Creates a new .gitignore file with LogicStamp patterns:

When .gitignore exists but doesn't have LogicStamp patterns

Adds LogicStamp patterns to the existing .gitignore:

When .gitignore already has LogicStamp patterns

If all patterns are present, no changes are made:

If some patterns exist but others are missing (idempotent patch mode), only missing patterns are added:

✅ Updated existing LogicStamp section in .gitignore

LLM_context.md Generation

stamp init also generates LLM_context.md in your project root:

✅ Created LLM_context.md

If LLM_context.md already exists:

ℹ️ LLM_context.md already exists

This file provides guidance for AI assistants on how to understand and work with your LogicStamp context files. It's automatically generated from the package template and includes information about:

• Project structure and context file organization
• How to load and use context files
• Understanding bundle structure and metadata
• Interpreting missing dependencies

Interactive Prompts

By default, stamp init is non-interactive because the security scan runs automatically. However, if you use --no-secure, stamp init will prompt you interactively (in TTY mode) for both .gitignore and LLM_context.md setup:

.gitignore Setup Prompt

When .gitignore doesn't already have LogicStamp patterns, you'll see:

If you choose "Y" (or just press Enter):

• Patterns are added to .gitignore
• Preference saved as "added" in .logicstamp/config.json
• stamp context will automatically maintain patterns in future runs

If you choose "n":

• .gitignore is not modified
• Preference saved as "skipped" in .logicstamp/config.json
• stamp context will never touch .gitignore
• ⚠️ Security Warning: If you skip this, you must manually ensure stamp_security_report.json is in .gitignore before running stamp security scan, or the security report will be automatically added by the scan command itself.

LLM_context.md Generation Prompt

When LLM_context.md doesn't exist, you'll see:

If you choose "Y" (or just press Enter):

• LLM_context.md is created in the project root
• Preference saved as "added" in .logicstamp/config.json
• stamp context will automatically maintain the file in future runs

If you choose "n":

• LLM_context.md is not created
• Preference saved as "skipped" in .logicstamp/config.json
• stamp context will never create this file

Default Behavior (Non-Interactive)

By default, stamp init is non-interactive because the security scan runs automatically:

• Informational messages are shown (e.g., "The following patterns will be added to .gitignore:")
• No prompts are shown - operations proceed automatically
• All operations are performed automatically without user input
• Preferences are saved to config

To enable interactive mode: Use --no-secure to skip the security scan, which will enable interactive prompts (when running in a TTY environment). In interactive mode, you'll see the same informational messages plus prompts asking for confirmation.

Behavior in stamp context

The stamp context command never prompts—it respects the preferences you set via stamp init:

• If config has "added" preference: Automatically performs the operation
• If config has "skipped" preference: Skips the operation
• If no config exists: Defaults to skipping (safe, CI-friendly behavior)

You can override per-run with the --skip-gitignore flag:

Safety

stamp init is:

• Idempotent - Safe to run multiple times without duplicating patterns
• Non-destructive - Preserves existing .gitignore content
• Safe by default - Only adds patterns, never removes anything

Security Considerations

🔒 Important Security Notes:

1. Security Report Protection: The stamp_security_report.json pattern is critical for security. This file only contains sensitive information if secrets are actually detected (file paths, line numbers, code snippets). If no secrets are found, the report will have secretsFound: 0 and an empty matches: [] array. Note: Secrets should not normally be present in TypeScript (.ts, .tsx), JavaScript (.js, .jsx), or JSON (.json) source files—they should be stored in .env files or environment variables. The security scan checks for secrets that may have been accidentally committed to source files. Even if you skip .gitignore setup during stamp init, stamp security scan will automatically add this pattern when it runs. Never commit security reports to version control.

2. If You Skip .gitignore Setup: If you choose to skip adding patterns to .gitignore:

   • You must manually ensure stamp_security_report.json is in .gitignore before running stamp security scan
   • Or rely on stamp security scan to automatically add it (which it will do)
   • Other patterns (context.json, etc.) are optional but recommended to avoid committing large generated files

3. Automatic Protection: stamp security scan always ensures the security report file is in .gitignore, regardless of your stamp init preferences. This cannot be disabled because security reports must never be committed.

When to Use

Use stamp init when:

• Setting up LogicStamp in a new project
• You want explicit control over initialization
• You want to set up .gitignore before generating context files

You don't need stamp init if:

• Your .gitignore already has the necessary patterns
• You prefer to manually manage .gitignore and LLM_context.md
• You're running stamp context in CI (it defaults to skipping both operations)

Related Commands

• stamp context - Generate context files (includes smart detection)
• stamp context validate - Validate generated context files
• stamp context compare - Detect drift in context files
• stamp security scan - Scan for secrets and generate security report