batch-file-creation

Batch File Scaffolding (Single-Turn Scripted Generation)

Overview

When an agent initializes a new microservice, UI component directory, or test suite, creating each file through individual write_to_file tool calls requires 10 to 20 consecutive agent turns.

Each turn re-sends the entire conversation transcript, accumulating quadratic token costs and taking 1 to 2 minutes of back-and-forth roundtrips.

The Batch File Scaffolding Protocol enables agents to create 10+ directory structures and boilerplate files in a single turn by writing and executing a local generator script or using a multi-file dictionary writer.

---

15-Turn Sequential Invocations vs. 1-Turn Batch Scaffolding

┌─────────────────────────────────────────────────────────────┐
│                 Scaffolding Turn Mechanics                  │
│                                                             │
│  Sequential Tool Calls (10 Files):                          │
│  • Turn 1: `write_to_file("Button.tsx")`                    │
│  • Turn 2: `write_to_file("Button.test.tsx")`               │
│  • Turn 3: `write_to_file("Button.module.css")`             │
│  • ... (10 turns, 10 API roundtrips, 15,000 tokens billed) │
│                                                             │
│  Single-Turn Batch Scaffolding (10 Files):                  │
│  • Turn 1: Agent writes & executes `scratch/scaffold.py`   │
│  ↳ All 10 files created on disk simultaneously in 50ms      │
│  ↳ 1 Turn, 1 API roundtrip, 650 tokens billed (95% Savings) │
└─────────────────────────────────────────────────────────────┘

---

Production Batch Scaffolding Implementations

1. Python Dictionary-Driven Multi-File Writer

Use this pattern to scaffold multiple files across directories in a single command:

# scratch/scaffold_component.py
from pathlib import Path

FILES = {
    "src/components/Modal/Modal.tsx": """import React from 'react';
import styles from './Modal.module.css';

export interface ModalProps {
  isOpen: boolean;
  onClose: () => void;
  title: string;
  children: React.ReactNode;
}

export const Modal: React.FC<ModalProps> = ({ isOpen, onClose, title, children }) => {
  if (!isOpen) return null;
  return (
    <div className={styles.overlay} onClick={onClose}>
      <div className={styles.modal} onClick={(e) => e.stopPropagation()}>
        <h2>{title}</h2>
        {children}
      </div>
    </div>
  );
};
""",
    "src/components/Modal/Modal.module.css": """.overlay { position: fixed; inset: 0; background: rgba(0,0,0,0.5); }
.modal { background: #fff; padding: 24px; border-radius: 8px; margin: 100px auto; max-width: 500px; }
""",
    "src/components/Modal/Modal.test.tsx": """import { render, screen } from '@testing-library/react';
import { Modal } from './Modal';

describe('Modal Component', () => {
  it('renders children when isOpen is true', () => {
    render(<Modal isOpen={true} onClose={() => {}} title="Test"><div>Content</div></Modal>);
    expect(screen.getByText('Content')).toBeInTheDocument();
  });
});
""",
    "src/components/Modal/index.ts": """export { Modal } from './Modal';
export type { ModalProps } from './Modal';
"""
}

for file_path, content in FILES.items():
    p = Path(file_path)
    p.parent.mkdir(parents=True, exist_ok=True)
    p.write_text(content.strip() + "\n", encoding="utf-8")
    print(f"Created: {file_path}")