@glxmart/boss-cli 1.0.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 glxmart
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,134 @@
+# BOSS Bootstrap CLI
+
+Command-line tool for scaffolding new BOSS projects with complete configuration.
+
+## Installation
+
+```bash
+pnpm add -g @glxmart/boss-cli
+```
+
+## Usage
+
+### Interactive Mode
+
+```bash
+boss bootstrap
+```
+
+### Command Line Options
+
+```bash
+boss bootstrap --template nextjs-app-turbo --quality production --name my-project
+```
+
+### Available Commands
+
+- `boss bootstrap` - Bootstrap a new BOSS project
+- `boss doctor` - Check prerequisites and system health
+- `boss templates` - List available templates
+
+## Templates
+
+- `nextjs-app-turbo` - Next.js 15 + Turbo + Tailwind + Prisma + Vitest + shadcn/ui
+- `api-service-fastify` - Fastify + TypeScript + Prisma + Vitest
+- `blank` - Minimal TypeScript + Vitest setup
+
+## Quality Presets
+
+- `startup` - Fast iteration, minimal gates
+- `production` - Balanced quality & speed
+- `enterprise` - Maximum quality, comprehensive checks
+
+## What Gets Created
+
+- `.boss/` - BOSS orchestration configuration
+- `.specify/` - Spec-Kit structure (templates, scripts, memory)
+- `.container-use/` - Container-use environment configuration
+- `.claude/` - Claude Code/Cursor rules and commands
+- `CLAUDE.md` - Primary Claude Code configuration
+- `start-boss.sh` - Launch script with MCP restrictions
+- `.github/workflows/` - CI/CD pipelines
+- `.husky/` - Git hooks
+- `docker-compose.yml` - Local infrastructure
+- Template-specific code structure
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build
+pnpm build
+
+# Run in development
+pnpm dev
+
+# Run tests
+pnpm test
+```
+
+## Local Testing
+
+### Easiest Way: Integration Tests
+
+The easiest way to test the CLI locally is using the existing integration tests:
+
+```bash
+# Run all integration tests
+pnpm test:integration
+
+# This will automatically:
+# - Build the CLI
+# - Create test projects
+# - Verify the structure
+# - Clean up afterwards
+```
+
+### Automated Testing Script
+
+For manual testing with more control, use the `test-local.sh` script. Test projects are created in your home directory by default:
+
+```bash
+# Basic test (builds, creates test project in $HOME, verifies)
+pnpm test:local
+# or
+./test-local.sh
+
+# Test with specific template and quality
+pnpm test:local -- --template nextjs-app-turbo --quality production
+
+# Create test project in a different directory
+pnpm test:local -- --dir ~/test-projects
+
+# Link CLI globally and test
+pnpm test:local -- --link
+
+# Verify existing test project
+pnpm test:local -- --verify-only
+
+# Clean up test project
+pnpm test:local -- --cleanup-only
+```
+
+See `pnpm test:local -- --help` or `./test-local.sh --help` for all options.
+
+### Manual Testing
+
+For manual testing without the script:
+
+```bash
+# Build the CLI
+pnpm install && pnpm build
+
+# Link globally (optional)
+pnpm link --global
+
+# Create a test project
+boss bootstrap --template blank --quality startup --name test-project --non-interactive
+
+# Or use tsx directly (no build needed)
+pnpm exec tsx src/index.ts bootstrap --template blank --quality startup --name test-project --non-interactive
+```
+

package/assets/claude-folder/commands/boss-commands.md

@@ -0,0 +1,138 @@
+# BOSS Commands
+
+## Available Commands
+
+### Container-Use Commands
+
+- \`container-use log <env_id>\` - View worker logs
+- \`container-use checkout <env_id>\` - Checkout worker branch
+- \`container-use diff <env_id>\` - View code changes
+- \`container-use merge <env_id>\` - Merge worker branch
+
+### Spec-Kit Commands
+
+- \`bash .specify/scripts/speckit.plan.sh\` - Generate plan
+- \`bash .specify/scripts/speckit.tasks.sh\` - Generate tasks
+- \`bash .specify/scripts/speckit.implement.sh\` - Implement features
+
+### BOSS Commands
+
+- \`./start-boss.sh\` - Start BOSS with MCP restrictions
+
+### Initial Setup Command
+
+**Command:** `boss-initial-setup`
+
+**Purpose:** Complete the initial project setup after bootstrap.
+
+**When to Run:**
+- After bootstrap completes
+- When `initialization.stage` in `.boss/project-config.json` is `"bootstrap"` or `"remote-setup"`
+
+**What It Does:**
+1. Checks `.boss/project-config.json` for current initialization status
+2. Verifies if remote repository exists
+3. If no remote exists:
+   - Asks user:
+     - Should repository be **private** or **public**? (default: private)
+     - Should it be created in an **organization**? (if yes, which org?)
+     - Repository name (if different from project name)
+   - Creates GitHub repository using GitHub MCP
+   - Adds remote using Container-Use MCP (NOT git CLI)
+   - Pushes initial commit to remote
+   - Updates `.boss/project-config.json` with remote information
+4. Marks `initialization.stage = "ready"` in project-config.json
+5. Updates project status to indicate setup is complete
+
+**How to Execute:**
+- BOSS can run this command directly when user asks to complete setup
+- Or BOSS can spawn an initial-setup worker using Container-Use MCP
+- Worker should follow the checklist in its prompt.md
+
+**Checklist for Initial Setup:**
+- [ ] Read `.boss/project-config.json` to check current status
+- [ ] **Verify:** Main branch is EMPTY (only empty commit) - bootstrap files are NOT on main
+- [ ] **Verify:** Feature branch `feature/boss-initial-setup` exists with ALL bootstrap files (created during bootstrap)
+- [ ] Confirm you are on `feature/boss-initial-setup` branch (created during bootstrap)
+- [ ] Check if remote repository exists (read project-config.json, NOT git)
+- [ ] If no remote:
+  - [ ] Ask user for repository preferences (private/public, org)
+  - [ ] Create GitHub repository using GitHub MCP (will create under personal account)
+  - [ ] If organization was requested:
+    - [ ] Ask user: "Repository created under your personal account. Would you like me to transfer it to [org-name] now?"
+    - [ ] If user confirms:
+      - [ ] Transfer repository using GitHub API: `POST /repos/{owner}/{repo}/transfer` with `{"new_owner": "org-name"}`
+      - [ ] Wait for transfer to complete
+      - [ ] Update git remote URL to reflect new owner using Container-Use MCP
+  - [ ] **CRITICAL: Lock main branch and require PRs** - Use GitHub API to set branch protection:
+    - [ ] Make HTTP PUT request to: `https://api.github.com/repos/{owner}/{repo}/branches/main/protection`
+    - [ ] Headers: `Authorization: Bearer {GITHUB_PERSONAL_ACCESS_TOKEN}`, `Accept: application/vnd.github.v3+json` (use GITHUB_PERSONAL_ACCESS_TOKEN, not GITHUB_TOKEN, for API calls)
+    - [ ] Body (JSON):
+      ```json
+      {
+        "required_pull_request_reviews": {
+          "required": true,
+          "dismiss_stale_reviews": true,
+          "require_code_owner_reviews": false,
+          "required_approving_review_count": 1
+        },
+        "enforce_admins": true,
+        "required_status_checks": {
+          "strict": true,
+          "contexts": []
+        },
+        "restrictions": null,
+        "allow_force_pushes": false,
+        "allow_deletions": false,
+        "required_linear_history": false,
+        "allow_squash_merge": true,
+        "allow_merge_commit": true,
+        "allow_rebase_merge": true
+      }
+      ```
+    - [ ] Verify protection was set: Check response status is 200
+    - [ ] **DO NOT skip this step** - branch protection is mandatory
+  - [ ] **CRITICAL ORDER - Follow EXACTLY:**
+    1. **Add remote using HTTPS:** `git remote add origin https://github.com/<owner>/<repo>.git` (ALWAYS use HTTPS, NEVER SSH `git@github.com` format)
+    2. **If transferred, update remote:** `git remote set-url origin https://github.com/<new-owner>/<repo>.git` (use HTTPS format)
+    3. **Check current branch:** `git branch --show-current` - verify you're on the correct branch
+    4. **Handle uncommitted changes:** If on `feature/boss-initial-setup` with uncommitted changes, commit them first: `git add . && git commit -m "chore: bootstrap files"` (these should be on feature branch)
+    5. **Switch to main branch:** `git checkout main` (if uncommitted changes prevent checkout, commit them to current branch first, then switch)
+    6. **FIRST push empty main branch:** `git push -u origin main` (main is EMPTY - only empty commit, no validation needed, MUST be pushed first, git will use GITHUB_TOKEN from environment automatically, which is set to same value as GITHUB_PERSONAL_ACCESS_TOKEN)
+       - **NOTE:** The pre-push hook allows empty main push without validation checks
+       - **Main branch must be pushed first (empty) before feature branch**
+    7. **Switch back to feature branch:** `git checkout feature/boss-initial-setup` (branch should already exist from bootstrap)
+    8. **Verify validation checks pass BEFORE pushing feature branch:**
+       - **BEFORE pushing feature branch, verify all checks pass:**
+         1. **Typecheck:** Run `pnpm typecheck` (or `npm run typecheck`) - must pass
+         2. **Lint:** Run `pnpm lint` (or `npm run lint`) - must pass
+         3. **Security:** Run `bash scripts/security-check.sh` - must pass
+         4. **Tests:** Run `pnpm test:unit` (or `npm run test:unit`) - must pass
+       - **If any check fails, fix the issues before pushing**
+    9. **THEN push feature branch:** `git push -u origin feature/boss-initial-setup` (contains all bootstrap files, git will use GITHUB_TOKEN from environment automatically, which is set to same value as GITHUB_PERSONAL_ACCESS_TOKEN)
+    10. **Update project-config.json** with repository info (including final owner after transfer)
+    11. **Commit and push project-config.json:** `git add .boss/project-config.json && git commit -m "chore: update project-config.json" && git push`
+    12. **Mark `initialization.stage = "ready"`** in project-config.json
+    13. **Update `initialization.remoteCreated = true`** and `initialization.initialSetupComplete = true`
+    14. **Commit and push again:** `git add .boss/project-config.json && git commit -m "chore: mark initialization as ready" && git push`
+    15. **FINAL STEP - Create PR from feature/boss-initial-setup to main:** Use GitHub MCP `create_pull_request` with:
+        - **Title:** `"chore: BOSS initial setup - bootstrap files"`
+        - **Body:** `"This PR contains all BOSS bootstrap files and initial project structure. Ready for review and merge."`
+        - **Base branch:** `"main"`
+        - **Head branch:** `"feature/boss-initial-setup"`
+        - **DO NOT ask user** - create PR automatically
+  - [ ] **NEVER push feature branch before main branch** - empty main must be pushed first
+  - [ ] **After this, NEVER push directly to main** - main branch is protected, use PRs for future changes
+  - [ ] Report completion to user with PR link
+
+**Important Notes:**
+- BOSS uses git commands for orchestration (branches, pushes, merges) - git CLI is allowed and expected
+- Workers use Container-Use MCP for their git operations (automatic)
+- ALWAYS update `.boss/project-config.json` to reflect status changes, then commit and push immediately
+- ALWAYS ask user for repository preferences before creating
+- Default to private repositories unless user specifies otherwise
+- **CRITICAL:** Main branch MUST be protected before any pushes - require PRs for all changes
+- **NEVER push directly to main branch** - always push to feature branch and create PR
+- **ALWAYS create PRs automatically** - never ask user if they want a PR created
+- **MINIMIZE status checks** - only check worker/environment status when necessary, not repeatedly
+

package/assets/claude-folder/rules/boss-workflow.md

@@ -0,0 +1,33 @@
+# BOSS Workflow Rules
+
+## Spec-Kit Phases
+
+Follow the 8-phase Spec-Kit methodology:
+
+1. **Constitution** - Create/update constitution.md
+2. **Clarification** - Gather business requirements
+3. **Specification** - Write user stories (Given/When/Then)
+4. **Planning** - Create technical plan
+5. **Validation** - Validate against constitution
+6. **Task Breakdown** - Create tasks.md with [P] markers
+7. **Implementation** - TDD + BDD implementation
+8. **Consolidation** - Merge and create delivery artifacts
+
+## Worker Coordination
+
+- Workers execute in parallel when tasks marked with [P]
+- Each worker in isolated container-use environment
+- Workers use Spec-Kit templates from \`.specify/templates/\`
+
+## Quality Gates
+
+- All quality gates must pass before merging
+- Coverage and mutation thresholds are enforced
+- Documentation must be complete
+
+## Communication Standards
+
+- **CRITICAL:** Use plain text only when communicating with workers - NO emojis
+- All messages, instructions, prompts, and feedback to workers must be in plain text format
+- Emojis should not be used in worker prompts, Container-Use instructions, or any worker-related communication
+

package/assets/claude-folder/rules/code-style.md

@@ -0,0 +1,23 @@
+# Code Style
+
+## TypeScript
+
+- Use strict TypeScript configuration
+- Prefer explicit types over `any`
+- Use interfaces for object shapes
+- Use enums for constants
+
+## Naming Conventions
+
+- Use camelCase for variables and functions
+- Use PascalCase for classes and types
+- Use UPPER_CASE for constants
+- Use kebab-case for file names
+
+## Formatting
+
+- Use 2 spaces for indentation
+- Use semicolons
+- Use single quotes for strings
+- Trailing commas in multi-line objects/arrays
+

package/assets/claude-folder/rules/security.md

@@ -0,0 +1,22 @@
+# Security Guidelines
+
+## Secrets Management
+
+- NEVER commit secrets to git
+- Use 1Password vault "boss" for all secrets
+- Reference secrets via \`op://boss/credential/needed\` format
+- Secrets are injected at runtime via container-use
+
+## Dependencies
+
+- Keep dependencies up to date
+- Use security scanning tools
+- Review dependency changes in PRs
+
+## Code Security
+
+- Validate all user input
+- Use parameterized queries for database
+- Implement proper authentication/authorization
+- Follow OWASP guidelines
+

package/assets/claude-folder/rules/testing.md

@@ -0,0 +1,32 @@
+# Testing Requirements
+
+## Test-First (NON-NEGOTIABLE)
+
+- Write tests BEFORE implementation
+- Follow TDD cycle: red → green → refactor
+- All tests must pass before committing
+
+## BDD (Mandatory)
+
+- Use Given/When/Then format for test descriptions
+- Use BDD test frameworks (Cucumber, Gherkin, or equivalent)
+- Tests should read like specifications
+
+## Coverage
+
+- Unit tests: ≥80% coverage
+- Integration tests: Required for all API endpoints
+- Mutation testing: ≥80% score
+
+## Test Structure
+
+\`\`\`
+describe('Feature Name', () => {
+  describe('Given [context]', () => {
+    it('When [action], Then [expected result]', () => {
+      // Test implementation
+    });
+  });
+});
+\`\`\`
+

package/assets/claude-folder/settings.local.json

@@ -0,0 +1,88 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(test:*)",
+      "Bash(grep:*)",
+      "Bash(cat:*)",
+      "Bash(ls:*)",
+      "Bash(echo:*)",
+      "Bash(curl:*)",
+      "Bash(pnpm:*)",
+      "Bash(npm:*)",
+      "Bash(bash scripts/security-check.sh)",
+      "Bash(cat .boss/project-config.json)",
+      "Bash(ls .boss/)",
+      "Bash(ls -la .boss/)",
+      "Bash(git commit:*)",
+      "Bash(git merge:*)",
+      "Bash(git pull:*)",
+      "Bash(git push:*)",
+      "Bash(git add:*)",
+      "Bash(git branch:*)",
+      "Bash(git checkout:*)",
+      "Bash(git log:*)",
+      "Bash(git ls-tree:*)",
+      "Bash(git remote:*)",
+      "Bash(git show:*)",
+      "Bash(git status:*)",
+      "Bash(rm ./*)",
+      "Bash(rm -f ./*)",
+      "Bash(rm ./.*)",
+      "Bash(rm -f ./.*)",
+      "Bash(rm ./**/*)",
+      "Bash(rm -f ./**/*)",
+      "Read(*)",
+      "Read(**)",
+      "Read(.*)",
+      "Read(.*/**)",
+      "Read(.boss/**)",
+      "Read(.boss/project-config.json)",
+      "Write(*)",
+      "Write(**)",
+      "Write(.*)",
+      "Write(.*/**)",
+      "Write(.boss/**)",
+      "Write(.boss/project-config.json)",
+      "Edit(*)",
+      "Edit(**)",
+      "Edit(.*)",
+      "Edit(.*/**)",
+      "Edit(.boss/**)",
+      "Edit(.boss/project-config.json)",
+      "Delete(*)",
+      "Delete(**)"
+    ],
+    "ask": [
+      "Bash(rm -rf ./*)"
+    ],
+    "deny": [
+      "Bash(rm //etc/**)",
+      "Bash(rm //usr/**)",
+      "Bash(rm //var/**)",
+      "Bash(rm //home/**)",
+      "Bash(rm -f //etc/**)",
+      "Bash(rm -f //usr/**)",
+      "Bash(rm -f //var/**)",
+      "Bash(rm -rf //etc/**)",
+      "Bash(rm -rf //usr/**)",
+      "Bash(rm -rf //var/**)",
+      "Read(//etc/**)",
+      "Read(//usr/**)",
+      "Read(//var/**)",
+      "Read(//root/**)",
+      "Read(//tmp/**)",
+      "Write(//etc/**)",
+      "Write(//usr/**)",
+      "Write(//var/**)",
+      "Write(//root/**)",
+      "Edit(//etc/**)",
+      "Edit(//usr/**)",
+      "Edit(//var/**)",
+      "Edit(//root/**)",
+      "Delete(//etc/**)",
+      "Delete(//usr/**)",
+      "Delete(//var/**)",
+      "Delete(//root/**)"
+    ]
+  }
+}

package/assets/claude-md/docs/container-use.md

@@ -0,0 +1,140 @@
+# Container-Use MCP Operations
+
+**CRITICAL:** All file, code, and shell operations MUST use Container-Use MCP environments.
+
+## Git Hooks Enforcement
+
+**MANDATORY:** All git commits MUST respect Husky git hooks:
+- **commit-msg hook** enforces Conventional Commits format (e.g., `feat: description`, `fix: description`)
+- **pre-commit hook** runs lint-staged, typecheck, and tests
+- **pre-push hook** runs additional quality checks
+- **Container-Use environments automatically run git hooks** - hooks are active in containers
+- **Commit messages MUST follow format:** `<type>(<scope>): <description>`
+  - Valid types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`, `ci`, `build`, `revert`
+  - Examples: `feat: add user authentication`, `fix(api): handle null response`, `chore: update dependencies`
+- **Hooks are installed during bootstrap** - Husky is initialized automatically
+- **package.json includes `prepare` script** - Runs `husky install` automatically when dependencies are installed
+
+**NEVER:**
+- NOT OK Use `--no-verify` flag to skip hooks (Container-Use commits will fail if hooks fail)
+- NOT OK Bypass commit message validation
+- NOT OK Skip pre-commit checks
+- NOT OK Commit with invalid message format
+
+**ALWAYS:**
+- OK Let git hooks run automatically (Container-Use respects hooks - they cannot be bypassed)
+- OK Use proper Conventional Commits format: `<type>(<scope>): <description>`
+- OK Ensure hooks pass before committing (commits will be rejected if hooks fail)
+- OK Run `pnpm install` after bootstrap to ensure Husky is fully set up
+
+## How Container-Use Works
+
+1. **Environment Creation**
+   - Use `mcp_container-use_create_environment` to create a new environment
+   - Container-Use automatically creates a branch: `container-use/<env-id>`
+   - Each environment is an isolated container with its own git branch
+   - Branch naming convention: `container-use/<env-id>` (e.g., `container-use/env-abc123`)
+   - **Git hooks are active in Container-Use environments** - commits will be validated
+
+2. **Container Configuration (MANDATORY - BEFORE Worker Spawning)**
+   - **CRITICAL:** This is the ONLY exception where BOSS uses `environment_file_write`
+   - **Purpose:** Configure container with worker-specific context, not BOSS's orchestration context
+   - **Overwrite `.claude/CLAUDE.md` in container:**
+     - Read `.boss/workers/[worker-name]/CLAUDE.md`
+     - Use `mcp_container-use_environment_file_write` to write to `.claude/CLAUDE.md` in container
+     - Container needs worker's instructions, not BOSS's orchestration instructions
+   - **Copy worker-specific `.claude` files to container:**
+     - Check if `.boss/workers/[worker-name]/.claude/` exists
+     - If exists, copy all files maintaining directory structure:
+       - `.claude/commands/` - Worker-specific commands
+       - `.claude/skills/` - Worker-specific skills
+       - `.claude/agents/` - Worker-specific agent configs
+       - `.claude/settings*.json` - Worker-specific settings (if any)
+     - Use `mcp_container-use_environment_file_write` for each file
+   - **Why:** Container's Claude Code needs worker role context, not BOSS orchestrator context
+
+3. **Worker Spawning (MANDATORY for BOSS)**
+   - **CRITICAL:** BOSS must use `mcp_container-use_execute_in_environment` to spawn workers
+   - **BOSS must NEVER write deliverables directly** using `environment_file_write` or `environment_run_cmd`
+   - **Workers write all deliverables** (constitution.md, spec.md, plan.md, code, tests, etc.)
+   - Each worker runs in its own isolated environment/container with worker-specific `.claude` config
+   - Workers can access secrets from 1Password (configured in container-config.json)
+   - All git operations happen automatically within the environment
+   - **BOSS's role:** Orchestrate (create environment, configure container, spawn worker, review, merge)
+   - **Worker's role:** Execute (write files, run commands, create code)
+
+4. **Environment Management**
+   - `mcp_container-use_list_environments` - List all active environments
+   - `mcp_container-use_get_environment` - Get environment details
+   - `mcp_container-use_delete_environment` - Delete environment (discards work)
+   - `mcp_container-use_merge_environment` - Merge environment branch into target branch
+
+5. **Work Review**
+   - Use `container-use log <env_id>` (CLI) to view command history
+   - Use `container-use diff <env_id>` (CLI) to view code changes
+   - Use `container-use checkout <env_id>` (CLI) to test locally
+   - Inform user: `container-use log <env_id>` AND `container-use checkout <env_id>`
+
+**Key Rules:**
+- **[DO]** ALWAYS create environments for any file/code/shell operation
+- **[DO]** ALWAYS use Container-Use MCP tools (never git CLI)
+- **[DO]** ALWAYS inform user how to view work via container-use CLI
+- **[DO]** Configure container environment BEFORE spawning worker:
+  - Overwrite `.claude/CLAUDE.md` with worker's CLAUDE.md
+  - Copy worker-specific `.claude/` files to container
+  - This is the ONLY exception where BOSS uses `environment_file_write`
+- **[DO]** For large files, use shell commands (heredoc/cat) instead of `environment_file_write` with large content
+- **[DON'T]** NEVER use git CLI directly
+- **[DON'T]** NEVER modify .git directory manually
+- **[DON'T]** NEVER execute operations outside environments
+- **[DON'T]** NEVER use `environment_file_write` to create deliverables - workers write deliverables
+- **[DON'T]** NEVER use `environment_file_write` with very large content (>1000 lines) - use shell commands instead
+
+## Efficient File Operations
+
+**CRITICAL:** For large files (README.md, long documentation, large config files, constitution.md, spec.md), use shell commands with heredoc syntax instead of `environment_file_write` with large content fields. This reduces MCP payload size, improves performance, and reduces token usage.
+
+**Decision Tree:**
+- **Files >100 lines or >5KB:** Use `environment_run_cmd` with heredoc/cat
+- **Files <100 lines and <5KB:** Can use `environment_file_write` (but heredoc still preferred)
+
+**Preferred Method (Large Files - README, docs, specs):**
+```typescript
+// Use environment_run_cmd with heredoc for large files
+await mcp.containerUse.environment_run_cmd({
+  environment_id: "env-123",
+  command: `cat > README.md << 'EOF'
+# Project Title
+
+Long content here...
+Multiple lines...
+EOF`
+});
+```
+
+**Alternative for Very Large Files (Multi-step):**
+```typescript
+// For extremely large files, write in chunks or use echo with >> append
+await mcp.containerUse.environment_run_cmd({
+  environment_id: "env-123",
+  command: `cat > large-file.md << 'EOF'
+[content part 1]
+EOF
+cat >> large-file.md << 'EOF'
+[content part 2]
+EOF`
+});
+```
+
+**Small Files Only (<50 lines):**
+```typescript
+// Only use environment_file_write for very small files
+await mcp.containerUse.environment_file_write({
+  environment_id: "env-123",
+  target_file: "src/utils.ts",
+  contents: "export function helper() { return true; }"  // Small content only
+});
+```
+
+**Why:** Large content in MCP calls increases payload size, latency, and token usage. Shell commands with heredoc are more efficient for files >100 lines. Container-Use executes shell commands efficiently inside the container.
+