Automatasaurus Development Guide

Automatasaurus Development Guide

Automatasaurus is a workflow orchestration framework for Claude Code that enables multi-agent autonomous development through GitHub issues and PRs.

Project Structure

automatasaurus/
├── bin/cli.js              # CLI entry point (init, update, status)
├── src/
│   ├── commands/           # CLI command implementations
│   │   ├── init.js         # Initialize framework in target project
│   │   ├── update.js       # Update framework to latest version
│   │   └── status.js       # Show installation status
│   └── lib/                # Shared utilities
│       ├── paths.js        # Path utilities (template dir, project dir)
│       ├── manifest.js     # Track installation state (.automatasaurus/.manifest.json)
│       ├── symlinks.js     # Create .claude -> .automatasaurus symlinks
│       ├── block-merge.js  # Merge content into marked blocks in files
│       └── json-merge.js   # Deep merge JSON settings
├── template/               # Files installed into target projects
│   ├── CLAUDE.block.md     # Core framework docs (block-merged)
│   ├── commands.block.md   # Framework commands (block-merged)
│   ├── settings.json       # Claude Code settings with hooks
│   ├── mcp.json            # MCP server config (Playwright)
│   ├── commands/           # Slash command definitions
│   ├── agents/             # Specialized personas (PM, Developer, Architect, etc.)
│   ├── skills/             # Reusable knowledge modules
│   └── hooks/              # Shell scripts (notify, on-stop, request-attention)
└── .claude/                # Symlinked to template/ for dogfooding

Commands

npm test                    # Run tests (node --test src/**/*.test.js)
npx automatasaurus init     # Test installer on a project
npx automatasaurus update   # Test update mechanism
npx automatasaurus status   # Test status display

Key Concepts

Block Merging

Files with `.block.md` extension use marked blocks that get merged into target files:

Framework content here (replaced on update)

Content outside blocks is preserved during updates.

Symlink Architecture

The installer creates `.automatasaurus/` with copied files, then symlinks `.claude/` subdirectories to it. This allows:

• Framework updates without losing project customizations
• Dogfooding (this repo's .claude/ symlinks to template/)

Manifest Tracking

`.automatasaurus/.manifest.json` tracks:

• Installation version
• Installed files and their hashes
• Symlink mappings

Layered Settings Configuration

Settings use a layered approach to preserve user customizations across updates:

.claude/
├── settings.json        # Final merged output (Claude Code reads this)
└── settings.local.json  # User overrides (never touched by framework)

**Merge flow:**

1. Framework writes defaults to settings.json
2. User overrides from settings.local.json are merged on top
3. User va