MetaCraft/CLAUDE.md

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

# 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

# Run tests (currently just a placeholder)
npm test

Installation

# 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:

<!-- 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

# 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