claudetools/AUTOCODER_INTEGRATION.md

# AutoCoder Resources Integration Guide

**Date:** 2026-01-17
**Source:** AutoCoder project (Autocode-remix fork)
**Status:** Successfully integrated

---

## Overview

This guide documents the AutoCoder resources that have been integrated into ClaudeTools, including commands, skills, templates, and an MCP server for feature management.

**What was extracted:**
- 2 Commands (create-spec, checkpoint)
- 1 Skill (frontend-design)
- 4 Templates (app spec, coding prompts, initializer)
- 1 MCP Server (feature management)

**Purpose:** Enable autonomous coding workflows with spec-driven development and feature tracking.

---

## Directory Structure

```
D:\ClaudeTools/
├── .claude/
│   ├── commands/
│   │   ├── sync.md              # EXISTING - Cross-machine sync
│   │   ├── create-spec.md       # NEW - Create app specification
│   │   └── checkpoint.md        # NEW - Create development checkpoint
│   │
│   ├── skills/
│   │   └── frontend-design/     # NEW - Frontend design skill
│   │       ├── SKILL.md
│   │       └── LICENSE.txt
│   │
│   └── templates/               # NEW directory
│       ├── app_spec.template.txt
│       ├── coding_prompt.template.md
│       ├── coding_prompt_yolo.template.md
│       └── initializer_prompt.template.md
│
└── mcp-servers/                 # NEW directory
    └── feature-management/
        ├── feature_mcp.py       # MCP server implementation
        ├── __init__.py
        ├── README.md            # Documentation
        └── config.example.json  # Configuration example
```

---

## 1. Commands

### create-spec.md

**Purpose:** Create a comprehensive application specification for autonomous coding

**How to use:**
```bash
# In Claude Code
/create-spec

# Claude will guide you through creating:
# - Project overview
# - Tech stack
# - Features list
# - Database schema
# - API endpoints
# - UI/UX requirements
```

**Output:** Creates `APP_SPEC.md` in project root with full specification

**When to use:**
- Starting a new autonomous coding project
- Documenting requirements for an agent-driven build
- Creating structured input for the feature management system

**File location:** `D:\ClaudeTools\.claude\commands\create-spec.md`

---

### checkpoint.md

**Purpose:** Create a detailed development checkpoint with commit and summary

**How to use:**
```bash
# In Claude Code
/checkpoint

# Claude will:
# 1. Analyze recent changes
# 2. Create a detailed commit message
# 3. Commit changes with co-authorship
# 4. Save session context to context recall system
```

**Output:**
- Git commit with detailed message
- Context saved to conversation_contexts table
- Decision logged in decision_logs table

**When to use:**
- After completing a feature
- Before switching to a different task
- At natural breakpoints in development

**File location:** `D:\ClaudeTools\.claude\commands\checkpoint.md`

---

## 2. Skills

### frontend-design

**Purpose:** Specialized skill for creating modern, production-ready frontend designs

**How to use:**
```bash
# In Claude Code
/frontend-design

# Claude will use the skill to:
# - Design responsive layouts
# - Create component hierarchies
# - Implement modern UI patterns
# - Follow accessibility best practices
```

**Features:**
- Modern framework patterns (React, Vue, Svelte)
- Responsive design (mobile-first)
- Accessibility (ARIA, semantic HTML)
- Performance optimization
- Component reusability

**File location:** `D:\ClaudeTools\.claude\skills\frontend-design\`

---

## 3. Templates

### app_spec.template.txt

**Purpose:** Template for creating application specifications

**Usage:** Used by `/create-spec` command to structure the output

**Contents:**
- Project metadata
- Technology stack
- Feature categories
- Database schema
- API endpoints
- Authentication/authorization
- Deployment requirements

**File location:** `D:\ClaudeTools\.claude\templates\app_spec.template.txt`

---

### coding_prompt.template.md

**Purpose:** Standard coding prompt for autonomous agents

**Usage:** Structured prompt that defines:
- Agent role and capabilities
- Development workflow
- Quality standards
- Testing requirements
- Error handling patterns

**When to use:** Starting an autonomous coding agent session

**File location:** `D:\ClaudeTools\.claude\templates\coding_prompt.template.md`

---

### coding_prompt_yolo.template.md

**Purpose:** Aggressive "move fast" coding prompt for rapid prototyping

**Usage:** Alternative prompt that prioritizes:
- Speed over perfect code
- Getting features working quickly
- Minimal testing (just basics)
- Iterative refinement

**When to use:**
- Proof of concepts
- Rapid prototyping
- MVP development
- Hackathons

**File location:** `D:\ClaudeTools\.claude\templates\coding_prompt_yolo.template.md`

---

### initializer_prompt.template.md

**Purpose:** Prompt for initializing a new project from specification

**Usage:** Sets up:
- Project structure
- Dependencies
- Configuration files
- Initial feature list
- Database setup

**When to use:** Starting a new project from an `APP_SPEC.md`

**File location:** `D:\ClaudeTools\.claude\templates\initializer_prompt.template.md`

---

## 4. MCP Server - Feature Management

### Overview

The Feature Management MCP Server provides native Claude Code integration for managing autonomous coding workflows with a priority-based feature queue.

### Setup

#### Step 1: Install Dependencies

```bash
# Activate ClaudeTools virtual environment
D:\ClaudeTools\venv\Scripts\activate

# Install required packages
pip install fastmcp sqlalchemy pydantic
```

#### Step 2: Configure Claude Desktop

Edit Claude Desktop config file:
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux:** `~/.config/claude/claude_desktop_config.json`

Add this configuration:

```json
{
  "mcpServers": {
    "features": {
      "command": "python",
      "args": ["D:\\ClaudeTools\\mcp-servers\\feature-management\\feature_mcp.py"],
      "env": {
        "PROJECT_DIR": "D:\\ClaudeTools\\projects\\your-project"
      }
    }
  }
}
```

#### Step 3: Restart Claude Desktop

Close and reopen Claude Desktop for changes to take effect.

#### Step 4: Verify Installation

In Claude Code, you should now have access to these MCP tools:
- `feature_get_stats`
- `feature_get_next`
- `feature_mark_passing`
- `feature_mark_in_progress`
- `feature_skip`
- `feature_clear_in_progress`
- `feature_get_for_regression`
- `feature_create_bulk`

---

### MCP Server Tools Reference

**Quick Reference:**

| Tool | Purpose | Usage |
|------|---------|-------|
| `feature_get_stats` | Progress overview | Start/end of session |
| `feature_get_next` | Get next feature | Start implementation |
| `feature_mark_in_progress` | Claim feature | After getting next |
| `feature_mark_passing` | Complete feature | After implementation |
| `feature_skip` | Defer feature | When blocked |
| `feature_clear_in_progress` | Reset status | When abandoning |
| `feature_get_for_regression` | Get test features | After changes |
| `feature_create_bulk` | Initialize features | Project setup |

**Full documentation:** See `D:\ClaudeTools\mcp-servers\feature-management\README.md`

---

## Typical Autonomous Coding Workflow

### Phase 1: Project Initialization

```bash
# 1. Create app specification
/create-spec
# Follow prompts to define your application

# 2. Review and save APP_SPEC.md
# Edit as needed, commit to version control

# 3. Initialize feature list
# Use MCP tool to create features from spec
feature_create_bulk(features=[...])
```

### Phase 2: Development Loop

```bash
# 1. Check progress
feature_get_stats()
# Output: 15/50 features (30%)

# 2. Get next feature
next_feature = feature_get_next()
# Feature #16: "User authentication endpoint"

# 3. Mark in-progress
feature_mark_in_progress(feature_id=16)

# 4. Implement feature
# ... write code, run tests ...

# 5. Create checkpoint
/checkpoint
# Commits changes and saves context

# 6. Mark complete
feature_mark_passing(feature_id=16)

# 7. Regression test
regression = feature_get_for_regression(limit=5)
# Test 5 random passing features
```

### Phase 3: Handling Blockers

```bash
# Get next feature
next = feature_get_next()
# Feature #20: "OAuth integration"

# Realize it depends on incomplete feature #25
feature_skip(feature_id=20)
# Moved to end of queue

# Continue with next available
next = feature_get_next()
# Feature #21: "Email validation"
```

---

## Integration with ClaudeTools API

The AutoCoder resources integrate seamlessly with the existing ClaudeTools infrastructure:

### 1. Context Recall Integration

**Save feature completion context:**
```python
POST /api/conversation-contexts
{
  "project_id": "uuid",
  "context_type": "feature_completion",
  "title": "Completed Feature #16: User authentication",
  "dense_summary": "Implemented JWT-based auth with bcrypt password hashing...",
  "relevance_score": 8.0,
  "tags": ["authentication", "feature-16", "jwt", "bcrypt"]
}
```

### 2. Decision Logging

**Log architectural decisions:**
```python
POST /api/decision-logs
{
  "project_id": "uuid",
  "decision_type": "technical",
  "decision_text": "Use JWT for stateless authentication",
  "rationale": "Scalability, no server-side session storage needed",
  "alternatives_considered": ["Session cookies", "OAuth only"],
  "impact": "high",
  "tags": ["authentication", "architecture"]
}
```

### 3. Session Tracking

**Track feature development sessions:**
```python
POST /api/sessions
{
  "project_id": "uuid",
  "machine_id": "machine-uuid",
  "started_at": "2026-01-17T10:00:00Z",
  "metadata": {"feature_id": 16, "feature_name": "User authentication"}
}
```

### 4. Problem Solutions

**Save implementation solutions:**
```python
POST /api/context-snippets
{
  "snippet_type": "solution",
  "title": "JWT token validation middleware",
  "content": "async def validate_token(request): ...",
  "language": "python",
  "tags": ["authentication", "jwt", "middleware"],
  "relevance_score": 7.5
}
```

---

## Configuration Files

### Claude Desktop Config

**Full example configuration:**

```json
{
  "mcpServers": {
    "features": {
      "command": "D:\\ClaudeTools\\venv\\Scripts\\python.exe",
      "args": ["D:\\ClaudeTools\\mcp-servers\\feature-management\\feature_mcp.py"],
      "env": {
        "PROJECT_DIR": "D:\\ClaudeTools\\projects\\my-web-app"
      }
    }
  },
  "globalShortcut": "Ctrl+Space"
}
```

### Environment Variables

**For MCP server:**
- `PROJECT_DIR` - Required. Where features.db will be stored.

**For ClaudeTools API:**
- `DATABASE_URL` - Connection string to ClaudeTools database
- `JWT_SECRET_KEY` - For API authentication
- `ENCRYPTION_KEY` - For credential encryption

---

## Testing the Integration

### 1. Test Commands

```bash
# Test create-spec
/create-spec
# Should display specification creation interface

# Test checkpoint
/checkpoint
# Should create git commit and save context
```

### 2. Test Skills

```bash
# Test frontend-design
/frontend-design
# Should activate frontend design mode
```

### 3. Test MCP Server

```python
# In Claude Code with MCP server running

# Test stats
feature_get_stats()
# Should return progress statistics

# Test get next
feature_get_next()
# Should return next feature or error if empty
```

### 4. Test Templates

Templates are used internally by commands, but you can view them:

```bash
# View templates
cat D:\ClaudeTools\.claude\templates\app_spec.template.txt
cat D:\ClaudeTools\.claude\templates\coding_prompt.template.md
```

---

## Troubleshooting

### Commands Not Available

**Problem:** `/create-spec` or `/checkpoint` not showing in command list

**Solution:**
1. Verify files exist in `.claude/commands/`
2. Restart Claude Code
3. Check file permissions (should be readable)

### Skill Not Loading

**Problem:** `/frontend-design` skill not available

**Solution:**
1. Verify `SKILL.md` exists in `.claude/skills/frontend-design/`
2. Check SKILL.md syntax (must be valid markdown)
3. Restart Claude Code

### MCP Server Not Connecting

**Problem:** Feature tools not available in Claude Code

**Solution:**
1. Verify Claude Desktop config is valid JSON
2. Check `PROJECT_DIR` environment variable is set
3. Ensure Python can be found (use full path if needed)
4. Check MCP server logs (see Claude Desktop logs)
5. Restart Claude Desktop (not just the window)

**Windows log location:**
```
%APPDATA%\Claude\logs\
```

**macOS log location:**
```
~/Library/Logs/Claude/
```

### Database Issues

**Problem:** MCP server can't create/access database

**Solution:**
1. Verify `PROJECT_DIR` exists and is writable
2. Check file permissions on `PROJECT_DIR`
3. Manually create directory if needed:
   ```bash
   mkdir -p "D:\ClaudeTools\projects\your-project"
   ```

---

## Best Practices

### 1. Spec-Driven Development

**Always start with a specification:**
1. Use `/create-spec` to document requirements
2. Review and refine the spec before coding
3. Use spec as input for `feature_create_bulk`
4. Keep spec updated as requirements evolve

### 2. Checkpoint Frequently

**Create checkpoints at natural boundaries:**
- After completing each feature
- Before starting risky refactoring
- At end of coding sessions
- When switching between tasks

### 3. Feature Management

**Maintain clean feature state:**
- Always mark features in-progress when starting
- Mark passing only when fully tested
- Skip features when blocked (don't leave them in-progress)
- Use regression testing after significant changes

### 4. Context Recall

**Integrate with ClaudeTools context system:**
- Save feature completions to conversation_contexts
- Log architectural decisions to decision_logs
- Store reusable solutions to context_snippets
- Tag everything for easy retrieval

---

## Migration Notes

### From AutoCoder to ClaudeTools

**What changed:**
- Commands moved from AutoCoder `.claude/` to ClaudeTools `.claude/`
- MCP server moved to dedicated `mcp-servers/` directory
- Templates now in `.claude/templates/` (new directory)
- Skills now in `.claude/skills/` (new directory)

**What stayed the same:**
- Command syntax and functionality
- MCP server API (same tools, same parameters)
- Template structure
- Skill format

### Backwards Compatibility

**These AutoCoder resources are compatible with:**
- Claude Code (current version)
- Claude Desktop MCP protocol
- ClaudeTools API (Phase 6, context recall)

**Not compatible with:**
- Older AutoCoder versions (pre-MCP)
- Legacy JSON-based feature tracking (auto-migrated)

---

## Next Steps

### Recommended Actions

1. **Try the commands:**
   - Run `/create-spec` on a test project
   - Create a checkpoint with `/checkpoint`

2. **Set up MCP server:**
   - Configure Claude Desktop
   - Test feature management tools
   - Create initial feature list

3. **Integrate with ClaudeTools:**
   - Connect feature completions to context recall
   - Log decisions to decision_logs
   - Track sessions with metadata

4. **Customize templates:**
   - Review templates in `.claude/templates/`
   - Adjust to match your coding style
   - Add project-specific requirements

---

## Resources

### Documentation

- **MCP Server:** `mcp-servers/feature-management/README.md`
- **Config Example:** `mcp-servers/feature-management/config.example.json`
- **ClaudeTools Docs:** `.claude/CLAUDE.md`
- **Context Recall:** `.claude/CONTEXT_RECALL_QUICK_START.md`

### Source Files

- **Commands:** `.claude/commands/`
- **Skills:** `.claude/skills/`
- **Templates:** `.claude/templates/`
- **MCP Servers:** `mcp-servers/`

### AutoCoder Project

- **Original Source:** `/c/Users/MikeSwanson/claude-projects/Autocode-remix/Autocode-fork/autocoder-master`
- **Conversation History:** `imported-conversations/auto-claude-variants/autocode-remix-fork/`

---

## Version History

| Date | Version | Changes |
|------|---------|---------|
| 2026-01-17 | 1.0 | Initial integration from AutoCoder |

---

**Last Updated:** 2026-01-17
**Integration Status:** Complete
**Tested:** Windows 11, ClaudeTools v0.95