# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

MetaCraft is an AI-powered meta-development tool that transforms software development into a series of composable, executable prompts, scripts, and documents. The project itself is developed using this toolchain, creating a bootstrapping loop that validates and optimizes the development workflow.

## Common Commands

### Development Workflow
```bash
# Run the bootstrap loop (self-development cycle)
npm start

# Execute a specific prompt file
npm run prompt -- prompts/example.md
# or directly:
node scripts/run-prompt.js prompts/example.md

# Plan the next development step
npm run plan
# or directly:
node scripts/plan-next.js

# Check if Claude Code CLI is installed
claude --version

# View current todo tasks
cat meta/todo.md
```

### Testing
```bash
# Run tests (currently just a placeholder)
npm test
```

### Installation
```bash
# Install dependencies (Node.js 18+ required)
npm install
```

## Code Architecture

### Core Components

**1. Prompt Engine (`scripts/run-prompt.js`)**
- Loads and parses Markdown-based prompt files
- Extracts metadata (target, priority, etc.)
- Injects dynamic context (project structure, git status)
- Calls Claude Code CLI to execute prompts
- Parses AI responses into actionable operations

**2. Bootstrap Loop (`scripts/bootstrap.js`)**
- Reads todo list from `meta/todo.md`
- Prompts user to select a pending task
- Finds corresponding prompt file
- Executes the prompt via `run-prompt.js`
- Updates task status after verification

**3. Plan Next Step (`scripts/plan-next.js`)**
- Analyzes current project state (completed vs pending tasks)
- Recommends next task based on priority and category
- Generates prompt files for recommended tasks
- Creates detailed next-step planning documents

**4. Context Manager (conceptual)**
- Maintains project state and structure
- Provides relevant context to AI during prompt execution
- Tracks dependencies, recent changes, and task history

### Directory Structure
```
MetaCraft/
├── prompts/          # Prompt library for tasks
│   └── example.md   # Example: creates welcome.js
├── scripts/          # Core automation scripts
│   ├── run-prompt.js # Executes prompts via Claude Code
│   └── bootstrap.js  # Self-development cycle
├── docs/             # Project documentation
│   ├── ARCHITECTURE.md    # Detailed architecture
│   ├── GETTING_STARTED.md # Quick start guide
│   └── next-steps/    # Auto-generated next step plans
├── meta/             # Tool metadata
│   └── todo.md      # Pending development tasks
├── config/           # Configuration (currently empty)
├── templates/        # File templates (currently empty)
├── package.json
└── README.md
```

## Key Files

### Task Management
- **`meta/todo.md`**: Markdown task list tracking all pending work
  - Categorized by: Core功能开发, 基础设施, 文档, 测试与质量, 未来功能
  - Tasks are checked off as they're completed
  - Bootstrap loop automatically updates this file

### Prompt Format
Prompts use Markdown with special metadata blocks:
```markdown
<!-- target: task-name -->
<!-- priority: high|medium|low -->

## 描述
Task description in detail.

## 上下文
Auto-injected project context

## 输出要求
Expected deliverables
```

### Scripts
- **`run-prompt.js`**: Accepts a prompt file path, validates Claude Code CLI, executes prompt, displays AI response
- **`bootstrap.js`**: Interactive loop for self-development - shows pending tasks, executes selected prompt, updates todo.md
- **`plan-next.js`**: Analyzes project state, recommends next task, generates prompt files and planning documents

## Development Workflow

### Bootstrapping Process
1. View pending tasks: `cat meta/todo.md`
2. Run bootstrap loop: `npm start`
3. Select a task number
4. Tool finds corresponding prompt file in `prompts/`
5. Executes prompt via Claude Code CLI
6. Review AI-generated output
7. Mark task as complete (updates `meta/todo.md`)

### Adding New Tasks
1. Edit `meta/todo.md` and add a new unchecked task: `- [ ] Task description`
2. Create corresponding prompt file in `prompts/` (optional)
   - Filename should relate to task (e.g., `implement-prompt-engine.md`)
3. Run bootstrap loop to execute

### Planning Next Steps
1. Run `npm run plan` to analyze project state and get task recommendations
2. Choose an action: generate prompt file, planning document, or both
3. Review generated files and adjust as needed
4. Execute the task using `npm start` or directly via `run-prompt.js`

### Example: Running the Example Prompt
```bash
# Execute the example prompt
node scripts/run-prompt.js prompts/example.md

# This creates welcome.js with a timestamped welcome message
node welcome.js  # Run the generated script
```

## Dependencies

### Runtime Dependencies
- **commander**: CLI argument parsing
- **fs-extra**: Enhanced file system operations
- **marked**: Markdown parsing
- **simple-git**: Git operations

### Requirements
- Node.js 18+
- Claude Code CLI installed and configured
- Git

## Important Notes

### Current Implementation Status
- Core infrastructure exists with bootstrap loop, prompt execution, and planning functionality
- Core components (prompt-engine, script-runner, context-manager) are not yet implemented
- Bootstrap loop, prompt execution, and plan-next are functional prototypes
- Project is in early development phase (v0.0.1)

### Prompt Execution
- Requires Claude Code CLI to be installed and in PATH
- If Claude Code is unavailable, the script outputs the prompt content for manual execution
- Prompts are written to `.temp/` directory during execution

### File Generation
- Prompts can generate files (like `welcome.js` from the example)
- Generated files are gitignored (see `.gitignore`)

### Self-Development
This project uses itself to develop itself. The bootstrap loop:
1. Reads tasks from `meta/todo.md`
2. Executes corresponding prompts
3. Lets AI generate or modify code
4. Updates task status

This creates a closed loop where the tool improves its own capabilities.

## Documentation

Key documentation files provide different perspectives:
- **README.md**: Vision, core concepts, quick overview
- **docs/ARCHITECTURE.md**: Detailed technical architecture, component design
- **docs/GETTING_STARTED.md**: Step-by-step setup and usage guide
- **meta/todo.md**: Current development priorities and status