create-ax-project 1.0.0

package/README.md

@@ -0,0 +1,374 @@
+# ax-templates
+
+Multi-AI Workflow Pipeline for Software Development
+
+[![CI](https://github.com/your-org/ax-templates/actions/workflows/ci.yml/badge.svg)](https://github.com/your-org/ax-templates/actions/workflows/ci.yml)
+[![npm version](https://badge.fury.io/js/ax-templates.svg)](https://www.npmjs.com/package/ax-templates)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Overview
+
+ax-templates is a 10-stage software development workflow pipeline that orchestrates multiple AI models (Claude, Gemini, Codex) for end-to-end project development.
+
+### Key Features
+
+- **10-Stage Pipeline**: Complete development cycle from brainstorming to deployment
+- **Multi-AI Orchestration**: Intelligent collaboration between Gemini, Claude, and Codex with parallel, sequential, and debate modes
+- **Smart HANDOFF System**: Automatic context extraction, semantic compression, and AI memory integration
+- **Auto-Checkpoint & Smart Rollback**: Task-based triggers, file change detection, partial rollback support
+- **Pipeline Forking**: Branch exploration for architecture alternatives with merge capabilities
+- **Stage Personas**: Optimized AI behavior profiles per stage (Creative Explorer, Precise Builder, etc.)
+- **Output Validation**: Automated quality checks with lint, typecheck, and coverage verification
+- **Dual Distribution**: Both NPM CLI and Claude Code plugin available
+
+### Pipeline Stages
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                     ax-templates Pipeline                           │
+├─────────────────────────────────────────────────────────────────────┤
+│  01 Brainstorm  →  02 Research  →  03 Planning  →  04 UI/UX        │
+│     Gemini          Claude          Gemini          Gemini          │
+├─────────────────────────────────────────────────────────────────────┤
+│  05 Tasks  →  06 Implement  →  07 Refactor  →  08 QA  →  09 Test   │
+│    Claude       Claude           Codex         Claude     Codex     │
+├─────────────────────────────────────────────────────────────────────┤
+│                          10 Deploy                                  │
+│                            Claude                                   │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+| Stage | Name | AI Model | Mode |
+|-------|------|----------|------|
+| 01 | Brainstorming | Gemini + Claude | YOLO (Container) |
+| 02 | Research | Claude | Plan Mode |
+| 03 | Planning | Gemini | Plan Mode |
+| 04 | UI/UX Planning | Gemini | Plan Mode |
+| 05 | Task Management | Claude | Plan Mode |
+| 06 | Implementation | Claude | Plan + Sandbox |
+| 07 | Refactoring | Codex | Deep Dive |
+| 08 | QA | Claude | Plan + Sandbox |
+| 09 | Testing & E2E | Codex | Sandbox + Playwright |
+| 10 | CI/CD & Deployment | Claude | Headless |
+
+## Installation
+
+### Quick Start with npx
+
+```bash
+# Create a new project
+npx create-ax-project my-project
+cd my-project
+
+# Edit project brief
+# stages/01-brainstorm/inputs/project_brief.md
+
+# Start development with Claude Code
+/run-stage 01-brainstorm
+```
+
+### Using Claude Code
+
+In Claude Code, all slash commands are available:
+
+```
+/status              # Check pipeline status
+/run-stage 01-brainstorm
+/handoff             # Create handoff document
+/next                # Move to next stage
+```
+
+## Quick Start
+
+### Step-by-Step
+
+```bash
+# 1. Create project
+npx create-ax-project my-saas-app
+cd my-saas-app
+
+# 2. Edit your project brief
+# Open: stages/01-brainstorm/inputs/project_brief.md
+
+# 3. Start brainstorming stage
+# In Claude Code:
+/brainstorm
+
+# 4. Check status anytime
+/status
+
+# 5. Create handoff and move to next stage
+/handoff
+/next
+```
+
+### Project Brief Template
+
+Edit `stages/01-brainstorm/inputs/project_brief.md`:
+
+```markdown
+## 프로젝트 이름
+my-saas-app
+
+## 한 줄 설명
+[프로젝트를 한 줄로 설명해주세요]
+
+## 문제 정의
+[해결하려는 문제는 무엇인가요?]
+
+## 타겟 사용자
+[주요 사용자는 누구인가요?]
+
+## 핵심 기능 (초안)
+1. [기능 1]
+2. [기능 2]
+3. [기능 3]
+```
+
+## Packages
+
+This monorepo contains three packages:
+
+| Package | Description | Install |
+|---------|-------------|---------|
+| [`ax-templates`](./packages/cli) | NPM CLI | `npm install -g ax-templates` |
+| [`@ax-templates/core`](./packages/core) | Core library | `npm install @ax-templates/core` |
+| [`@ax-templates/plugin`](./packages/plugin) | Claude Code plugin | `claude plugin install @ax-templates/plugin` |
+
+## Commands
+
+### Core Commands
+
+| Command | CLI | Plugin |
+|---------|-----|--------|
+| Initialize project | `ax init` | `/init-project` |
+| Show status | `ax status` | `/status` |
+| List stages | `ax stages` | `/stages` |
+| Run stage | `ax run-stage <id>` | `/run-stage <id>` |
+| Next stage | `ax next` | `/next` |
+| Create handoff | `ax handoff` | `/handoff` |
+| Create checkpoint | `ax checkpoint` | `/checkpoint` |
+| Restore checkpoint | `ax restore` | `/restore` |
+| Check context | `ax context` | `/context` |
+
+### AI Commands
+
+| Command | CLI | Plugin |
+|---------|-----|--------|
+| Gemini prompt | `ax gemini <prompt>` | `/gemini <prompt>` |
+| Codex prompt | `ax codex <prompt>` | `/codex <prompt>` |
+
+### Multi-AI Commands
+
+| Command | CLI | Plugin | Description |
+|---------|-----|--------|-------------|
+| AI Collaboration | `ax collaborate` | `/collaborate` | Run multi-AI collaboration (parallel, sequential, debate modes) |
+| AI Benchmarking | `ax benchmark` | `/benchmark` | Compare AI model performance on tasks |
+| Pipeline Fork | `ax fork` | `/fork` | Create/manage pipeline branches for exploration |
+| Output Validation | `ax validate` | `/validate` | Validate stage outputs against quality criteria |
+
+### Stage Shortcuts
+
+| Stage | CLI | Plugin |
+|-------|-----|--------|
+| 01-brainstorm | `ax brainstorm` | `/brainstorm` |
+| 02-research | `ax research` | `/research` |
+| 03-planning | `ax planning` | `/planning` |
+| 04-ui-ux | `ax ui-ux` | `/ui-ux` |
+| 05-task-management | `ax tasks` | `/tasks` |
+| 06-implementation | `ax implement` | `/implement` |
+| 07-refactoring | `ax refactor` | `/refactor` |
+| 08-qa | `ax qa` | `/qa` |
+| 09-testing | `ax test` | `/test` |
+| 10-deployment | `ax deploy` | `/deploy` |
+
+## Configuration
+
+Project configuration is stored in `.ax-config.yaml`:
+
+```yaml
+ax_templates:
+  version: "2.0.0"
+
+paths:
+  project_root: "./my-app"
+  stages_output: "./stages"
+  state: "./state"
+  checkpoints: "./state/checkpoints"
+
+ai:
+  gemini: true
+  codex: true
+
+tmux:
+  gemini_session: "ax-gemini"
+  codex_session: "ax-codex"
+  output_timeout: 300
+
+context:
+  warning: 60
+  action: 50
+  critical: 40
+  task_save_frequency: 5
+
+git:
+  commit_language: "Korean"
+  auto_commit: true
+```
+
+## Project Structure
+
+Each project is fully self-contained with all pipeline components:
+
+```
+my-project/                        # PROJECT_ROOT
+├── .claude/                       # Claude Code configuration
+│   ├── commands/                  # Slash commands (26 commands)
+│   ├── hooks/                     # Lifecycle hooks
+│   ├── skills/                    # AI skills
+│   └── settings.json
+├── stages/                        # 10-stage pipeline
+│   ├── 01-brainstorm/
+│   │   ├── CLAUDE.md              # Stage-specific AI instructions
+│   │   ├── config.yaml
+│   │   ├── prompts/
+│   │   ├── inputs/
+│   │   │   └── project_brief.md   # Start here!
+│   │   ├── outputs/               # Generated artifacts
+│   │   └── HANDOFF.md
+│   ├── 02-research/
+│   └── ... (10 stages total)
+├── config/                        # Pipeline configuration
+│   ├── pipeline.yaml
+│   ├── context.yaml
+│   └── ... (15+ config files)
+├── state/                         # Project state
+│   ├── progress.json              # Pipeline progress
+│   ├── checkpoints/               # Recovery points
+│   └── context/                   # Context snapshots
+├── scripts/                       # Helper scripts
+├── CLAUDE.md                      # Main AI instructions
+├── src/                           # Source code (from stage 06)
+└── package.json
+```
+
+## Design Patterns
+
+1. **Sequential Workflow Architecture** - Sequential stage definition and auto-progression
+2. **Stateless Orchestration** - Stateless context transfer via HANDOFF.md
+3. **Orchestrator-Workers** - Parallel agent execution (Brainstorm stage)
+4. **Proactive State Externalization** - External state file management
+5. **State Machine Workflow** - State transition management (progress.json)
+6. **Layered Configuration** - Hierarchical configuration structure
+7. **Multi-AI Collaboration** - Parallel, sequential, and debate modes for AI coordination
+8. **Pipeline Forking** - Branch exploration with merge capabilities
+9. **Smart Context Management** - Semantic compression and AI memory integration
+
+## Documentation
+
+- [CLI Reference](./packages/cli/README.md)
+- [Plugin Reference](./packages/plugin/README.md)
+- [Migration Guide](./docs/migration-guide.md)
+
+## Development
+
+### Prerequisites
+
+- Node.js >= 18.0.0
+- pnpm >= 8.0.0
+- tmux (for AI sessions)
+
+### Setup
+
+```bash
+# Clone repository
+git clone https://github.com/your-org/ax-templates.git
+cd ax-templates
+
+# Install dependencies
+pnpm install
+
+# Build all packages
+pnpm build
+
+# Run tests
+pnpm test
+```
+
+### Local Development
+
+```bash
+# Link CLI globally
+cd packages/cli
+pnpm link --global
+
+# Test CLI
+ax --help
+
+# Link plugin to Claude Code
+claude plugin link ./packages/plugin
+```
+
+### Monorepo Structure
+
+```
+ax-templates/
+├── packages/
+│   ├── core/              # Shared business logic
+│   │   ├── src/
+│   │   │   ├── config/    # Configuration management
+│   │   │   ├── stage/     # Stage management
+│   │   │   ├── context/   # Context management
+│   │   │   └── ai/        # AI model abstraction
+│   │   └── package.json
+│   │
+│   ├── cli/               # NPM CLI package
+│   │   ├── src/
+│   │   │   ├── commands/  # CLI commands
+│   │   │   └── prompts/   # Interactive prompts
+│   │   ├── bin/ax.js
+│   │   └── package.json
+│   │
+│   └── plugin/            # Claude Code plugin
+│       ├── plugin.json
+│       ├── CLAUDE.md
+│       ├── .claude/
+│       │   ├── commands/  # Slash commands
+│       │   └── hooks/     # Lifecycle hooks
+│       ├── scripts/       # Helper scripts
+│       └── package.json
+│
+├── templates/             # Installable templates
+│   └── default/           # Default 10-stage template
+│
+├── docs/                  # Documentation
+└── package.json           # Monorepo root
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'feat: add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+### Commit Convention
+
+We use [Conventional Commits](https://www.conventionalcommits.org/):
+
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation
+- `chore`: Maintenance
+- `refactor`: Code refactoring
+- `test`: Test updates
+
+## License
+
+MIT
+
+## Related
+
+- [Claude Code](https://claude.ai/claude-code) - AI coding assistant
+- [Gemini CLI](https://github.com/google-gemini/gemini-cli) - Google's AI CLI

package/bin/create.js

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// 색상 코드
+const colors = {
+  reset: '\x1b[0m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m',
+  red: '\x1b[31m'
+};
+
+function log(message, color = 'reset') {
+  console.log(`${colors[color]}${message}${colors.reset}`);
+}
+
+function copyRecursiveSync(src, dest) {
+  const exists = fs.existsSync(src);
+  const stats = exists && fs.statSync(src);
+  const isDirectory = exists && stats.isDirectory();
+
+  if (isDirectory) {
+    if (!fs.existsSync(dest)) {
+      fs.mkdirSync(dest, { recursive: true });
+    }
+    fs.readdirSync(src).forEach(childItemName => {
+      copyRecursiveSync(
+        path.join(src, childItemName),
+        path.join(dest, childItemName)
+      );
+    });
+  } else {
+    fs.copyFileSync(src, dest);
+  }
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const projectName = args[0] || '.';
+
+  // 도움말
+  if (projectName === '--help' || projectName === '-h') {
+    console.log(`
+${colors.cyan}create-ax-project${colors.reset} - Multi-AI Workflow Pipeline 프로젝트 생성
+
+${colors.yellow}사용법:${colors.reset}
+  npx create-ax-project <project-name>
+  npx create-ax-project .  (현재 디렉토리에 생성)
+
+${colors.yellow}예시:${colors.reset}
+  npx create-ax-project my-saas-app
+  npx create-ax-project my-game
+
+${colors.yellow}생성 후:${colors.reset}
+  1. cd <project-name>
+  2. stages/01-brainstorm/inputs/project_brief.md 작성
+  3. /run-stage 01-brainstorm 실행
+`);
+    process.exit(0);
+  }
+
+  // 프로젝트 이름 검증
+  if (projectName !== '.' && !/^[a-z0-9-]+$/.test(projectName)) {
+    log('오류: 프로젝트 이름은 영문 소문자, 숫자, 하이픈만 허용됩니다.', 'red');
+    process.exit(1);
+  }
+
+  const templateDir = path.join(__dirname, '..', 'template');
+  const targetDir = path.resolve(projectName);
+  const actualProjectName = projectName === '.' ? path.basename(targetDir) : projectName;
+
+  // 템플릿 존재 확인
+  if (!fs.existsSync(templateDir)) {
+    log(`오류: 템플릿 디렉토리를 찾을 수 없습니다: ${templateDir}`, 'red');
+    process.exit(1);
+  }
+
+  // 대상 디렉토리 확인
+  if (projectName !== '.' && fs.existsSync(targetDir)) {
+    const files = fs.readdirSync(targetDir);
+    if (files.length > 0) {
+      log(`오류: 디렉토리가 비어있지 않습니다: ${targetDir}`, 'red');
+      process.exit(1);
+    }
+  }
+
+  console.log('');
+  log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━', 'cyan');
+  log(`🚀 ax-templates 프로젝트 생성: ${actualProjectName}`, 'cyan');
+  log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━', 'cyan');
+  console.log('');
+
+  // 1. 대상 디렉토리 생성
+  if (!fs.existsSync(targetDir)) {
+    fs.mkdirSync(targetDir, { recursive: true });
+  }
+  log(`✓ 프로젝트 디렉토리: ${targetDir}`, 'green');
+
+  // 2. 템플릿 복사
+  log('  템플릿 복사 중...', 'blue');
+  copyRecursiveSync(templateDir, targetDir);
+  log('✓ 템플릿 복사 완료', 'green');
+
+  // 3. progress.json 초기화
+  const progressTemplatePath = path.join(targetDir, 'state', 'progress.json.template');
+  const progressPath = path.join(targetDir, 'state', 'progress.json');
+
+  if (fs.existsSync(progressTemplatePath)) {
+    let progressContent = fs.readFileSync(progressTemplatePath, 'utf8');
+    const timestamp = new Date().toISOString();
+
+    progressContent = progressContent
+      .replace('{{PROJECT_NAME}}', actualProjectName)
+      .replace('{{STARTED_AT}}', timestamp);
+
+    fs.writeFileSync(progressPath, progressContent);
+    fs.unlinkSync(progressTemplatePath); // 템플릿 파일 삭제
+    log('✓ progress.json 초기화 완료', 'green');
+  }
+
+  // 4. project_brief.md 생성
+  const briefPath = path.join(targetDir, 'stages', '01-brainstorm', 'inputs', 'project_brief.md');
+  const briefDir = path.dirname(briefPath);
+
+  if (!fs.existsSync(briefDir)) {
+    fs.mkdirSync(briefDir, { recursive: true });
+  }
+
+  const briefContent = `# Project Brief
+
+## 프로젝트 이름
+${actualProjectName}
+
+## 한 줄 설명
+[프로젝트를 한 줄로 설명해주세요]
+
+## 문제 정의
+[해결하려는 문제는 무엇인가요?]
+
+## 타겟 사용자
+[주요 사용자는 누구인가요?]
+
+## 핵심 기능 (초안)
+1. [기능 1]
+2. [기능 2]
+3. [기능 3]
+
+## 성공 기준
+[프로젝트가 성공했다고 판단하는 기준은?]
+
+## 제약조건
+- 일정:
+- 예산:
+- 기술:
+
+## 참고 자료
+- [URL 또는 문서]
+`;
+
+  fs.writeFileSync(briefPath, briefContent);
+  log('✓ project_brief.md 생성 완료', 'green');
+
+  // 5. 완료 메시지
+  console.log('');
+  log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━', 'green');
+  log(`✓ 프로젝트 '${actualProjectName}' 생성 완료!`, 'green');
+  log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━', 'green');
+  console.log('');
+  log('다음 단계:', 'yellow');
+  if (projectName !== '.') {
+    console.log(`  1. cd ${projectName}`);
+    console.log('  2. stages/01-brainstorm/inputs/project_brief.md 작성');
+    console.log('  3. /run-stage 01-brainstorm 실행');
+  } else {
+    console.log('  1. stages/01-brainstorm/inputs/project_brief.md 작성');
+    console.log('  2. /run-stage 01-brainstorm 실행');
+  }
+  console.log('');
+  log('파이프라인 스테이지:', 'cyan');
+  console.log('  01-brainstorm → 02-research → 03-planning → 04-ui-ux');
+  console.log('  → 05-task-management → 06-implementation → 07-refactoring');
+  console.log('  → 08-qa → 09-testing → 10-deployment');
+  console.log('');
+}
+
+main();

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "create-ax-project",
+  "version": "1.0.0",
+  "description": "Multi-AI Workflow Pipeline - Create new projects with 10-stage development workflow",
+  "type": "module",
+  "bin": {
+    "create-ax-project": "./bin/create.js"
+  },
+  "files": [
+    "bin/",
+    "template/"
+  ],
+  "scripts": {
+    "create": "node bin/create.js"
+  },
+  "keywords": [
+    "ai",
+    "workflow",
+    "pipeline",
+    "claude",
+    "gemini",
+    "codex",
+    "multi-ai"
+  ],
+  "author": "znehraks@gmail.com",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/znehraks/ax-templates"
+  },
+  "bugs": {
+    "url": "https://github.com/znehraks/ax-templates/issues"
+  },
+  "homepage": "https://github.com/znehraks/ax-templates#readme"
+}

package/template/.claude/CLAUDE.md

@@ -0,0 +1,7 @@
+<claude-mem-context>
+# Recent Activity
+
+<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
+
+*No recent activity*
+</claude-mem-context>