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 adopts a **documentation-only architecture** - containing only documents, designs, and AI tool scripts, with no execution environment or runtime services. External AI tools execute the logic described in these scripts.

## Common Commands

### Development Workflow (AI Tool Reference)
These commands describe how an external AI tool should execute development workflows. The scripts in this project are **tool descriptions** for AI reference, not executable code.

```bash
# How to execute the bootstrap loop logic (self-development cycle)
# Reference: scripts/bootstrap.js for detailed steps
# External AI tool should implement: read todo.md, show tasks, execute prompts

# How to execute a specific prompt file
# Reference: scripts/run-prompt.js for detailed steps
# External AI tool should implement: read prompt file, extract metadata, call Claude Code

# How to plan the next development step
# Reference: scripts/plan-next.js for detailed steps
# External AI tool should implement: analyze project state, recommend tasks, generate files

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

### Testing (Design Concept)
```bash
# Testing framework design - to be implemented by external AI tools
# Reference: docs/ARCHITECTURE.md for testing strategy design
```

### Installation (Project Setup)
```bash
# This project requires no installation - it's a documentation and design repository
# Clone the repository and explore the documentation
git clone <repository-url>
cd MetaCraft
```

## Code Architecture

### Core Components (Design Concepts)

**1. Prompt Engine Design** (`scripts/run-prompt.js`)
- Describes how to parse Markdown-based prompt files
- Explains metadata extraction (target, priority, etc.)
- Outlines context injection (project structure, git status)
- Provides guidance on calling external AI tools
- Documents response parsing into actionable operations

**2. Bootstrap Loop Design** (`scripts/bootstrap.js`)
- Describes reading todo list from `meta/todo.md`
- Explains user interaction for task selection
- Documents prompt file lookup logic
- Outlines prompt execution steps via external tools
- Provides task status update procedures

**3. Plan Next Step Design** (`scripts/plan-next.js`)
- Describes project state analysis (completed vs pending tasks)
- Documents task recommendation algorithms based on priority and category
- Explains prompt file generation logic
- Outlines next-step planning document creation

**4. Context Manager Design** (conceptual)
- Describes project state maintenance strategies
- Documents context provision techniques for AI during prompt execution
- Explains dependency tracking and change history management

Note: These are design documents for AI reference, not executable code.

### Directory Structure
```
MetaCraft/
├── prompts/          # Prompt library for tasks
│   └── example.md   # Example: creates welcome.js
├── scripts/          # AI tool scripts (design documents, not executable)
│   ├── run-prompt.js   # Prompt execution logic description
│   ├── bootstrap.js    # Bootstrap loop design document
│   └── plan-next.js    # Next-step planning design document
├── docs/             # Project documentation
│   ├── ARCHITECTURE.md    # Detailed architecture design
│   ├── 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      # Project metadata (dependencies are design references)
└── README.md         # Project overview and architecture
```

## 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 (AI Tool Descriptions)
- **`run-prompt.js`**: Describes how to execute a prompt file - file validation, metadata extraction, external AI tool invocation
- **`bootstrap.js`**: Documents the self-development loop logic - task listing, user interaction, prompt execution, status updates
- **`plan-next.js`**: Outlines project state analysis and next-step planning - task recommendation algorithms, file generation procedures

## Development Workflow

### Bootstrapping Process (Design Logic)
1. View pending tasks: Read `meta/todo.md`
2. Bootstrap loop logic: Reference `scripts/bootstrap.js` for implementation steps
3. Select a task number: User interaction design
4. Find corresponding prompt file: File lookup algorithm in `prompts/` directory
5. Execute prompt: Call external AI tool (e.g., Claude Code) following `scripts/run-prompt.js` guidelines
6. Review AI-generated output: Result processing and validation
7. Mark task as complete: Update `meta/todo.md` status

### Adding New Tasks (Design Logic)
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. Execute via bootstrap loop logic: Reference `scripts/bootstrap.js` for implementation

### Planning Next Steps (Design Logic)
1. Analyze project state: Reference `scripts/plan-next.js` for recommendation algorithms
2. Choose an action: generate prompt file, planning document, or both
3. Review generated files and adjust as needed
4. Execute the task: Use external AI tools following the described logic

### Example: Running the Example Prompt (Design Logic)
```bash
# How to execute the example prompt:
# 1. Reference scripts/run-prompt.js for execution logic
# 2. Read prompts/example.md for prompt content
# 3. Call external AI tool to execute the prompt

# Expected outcome:
# - AI generates welcome.js with timestamped welcome message
# - External tool can then execute welcome.js
```

## Dependencies (Design References)

### Design Dependency Descriptions
- **commander**: CLI argument parsing design pattern reference
- **fs-extra**: Enhanced file system operation design patterns
- **marked**: Markdown parsing design approach
- **simple-git**: Git operation design patterns

### Implementation Requirements
- **External AI Tool**: For actual execution (e.g., Claude Code, other AI assistants)
- **File System Access**: Required by external tools to read project files
- **Git**: For version control of the design documents

Note: This project contains no runtime dependencies or execution environment. The dependencies listed are **design references** describing how external tools should implement similar functionality.

## Important Notes

### Architecture Philosophy
MetaCraft follows a **documentation-only architecture**:
- **No execution environment**: Scripts are design documents, not executable code
- **External tool execution**: All logic is implemented by external AI tools (e.g., Claude Code)
- **Portable knowledge**: Designs can be referenced by any AI system
- **Self-development concept**: The toolchain describes how to develop itself

### Current Implementation Status
- **Design documents complete**: Bootstrap loop, prompt execution, and planning logic are fully documented
- **No runtime components**: Core components (prompt-engine, script-runner, context-manager) exist only as design concepts
- **Pure documentation**: All scripts are descriptive, not functional
- **Version**: Design phase v0.0.1

### Prompt Execution (Design Concept)
- **External tool requirement**: Execution requires external AI tools, not built-in runtime
- **Logic description**: `scripts/run-prompt.js` describes how to validate, extract metadata, and invoke AI tools
- **Temporary files**: Design includes `.temp/` directory concept for intermediate files

### File Generation (Design Concept)
- **AI-generated artifacts**: Prompts can describe file generation (e.g., `welcome.js` from example)
- **Git integration**: Generated files would be gitignored in actual implementations

### Self-Development (Design Concept)
This project describes a self-development methodology. The bootstrap loop design:
1. Describes reading tasks from `meta/todo.md`
2. Documents executing corresponding prompts via external tools
3. Outlines AI code generation and modification processes
4. Provides status update procedures

This creates a **design for a closed loop** where tools could theoretically improve themselves.

## Documentation

This project consists entirely of design documentation and AI tool descriptions:

### Core Design Documents
- **README.md**: Project vision, architecture philosophy, and overview
- **docs/ARCHITECTURE.md**: Detailed technical architecture design and component specifications
- **docs/GETTING_STARTED.md**: Design implementation guide and conceptual setup

### Development Planning
- **meta/todo.md**: Design task tracking and development priorities
- **docs/next-steps/**: Auto-generated next-step planning documents (design concepts)

### AI Tool Scripts (Design References)
- **scripts/run-prompt.js**: Prompt execution logic description
- **scripts/bootstrap.js**: Bootstrap loop design document
- **scripts/plan-next.js**: Next-step planning design document

All content is **design documentation** meant to be referenced by external AI tools for implementation guidance.