red64-cli 0.1.0

package/framework/stacks/generic/structure.md

@@ -0,0 +1,46 @@
+# Project Structure
+
+## Project: {{projectName}}
+
+## Organization Philosophy
+
+[Describe approach: feature-first, layered, domain-driven, etc.]
+
+## Directory Patterns
+
+### Source Code
+**Location**: `/src/`
+**Purpose**: Main application code
+**Example**: Application logic, components, services
+
+### Tests
+**Location**: `/tests/` or `/__tests__/`
+**Purpose**: Test files
+**Example**: Unit tests, integration tests
+
+### Configuration
+**Location**: `/` (root)
+**Purpose**: Project configuration
+**Example**: package.json, tsconfig.json, pyproject.toml
+
+## Naming Conventions
+
+- **Files**: [Pattern, e.g., PascalCase.tsx, kebab-case.ts]
+- **Components**: [Pattern, e.g., PascalCase]
+- **Functions**: [Pattern, e.g., camelCase]
+
+## Import Organization
+
+```
+// Example import patterns
+// 1. External packages
+// 2. Internal absolute imports
+// 3. Relative imports
+```
+
+## Code Organization Principles
+
+[Key architectural patterns and dependency rules]
+
+---
+_Document patterns, not file trees. New files following patterns shouldn't require updates_

package/framework/stacks/generic/tech.md

@@ -0,0 +1,47 @@
+# Technology Stack
+
+## Project: {{projectName}}
+
+## Architecture
+
+[High-level system design approach]
+
+## Core Technologies
+
+- **Language**: [e.g., TypeScript, Python, Go]
+- **Framework**: [e.g., React, Express, Django]
+- **Runtime**: [e.g., Node.js 20+, Python 3.11+]
+
+## Key Libraries
+
+[Only major libraries that influence development patterns]
+
+## Development Standards
+
+### Type Safety
+[e.g., TypeScript strict mode, type hints]
+
+### Code Quality
+[e.g., ESLint, Prettier, Black, Ruff]
+
+### Testing
+[e.g., Jest, Pytest, coverage requirements]
+
+## Development Environment
+
+### Required Tools
+[Key tools and version requirements]
+
+### Common Commands
+```bash
+# Dev: [command]
+# Build: [command]
+# Test: [command]
+```
+
+## Key Technical Decisions
+
+[Important architectural choices and rationale]
+
+---
+_Document standards and patterns, not every dependency_

package/framework/stacks/node/product.md

@@ -0,0 +1,27 @@
+# Product Overview
+
+## Project: {{projectName}}
+
+{{description}}
+
+## Core Capabilities
+
+[3-5 key capabilities of your Node.js application]
+
+- [API/Service capability]
+- [Data processing capability]
+- [Integration capability]
+
+## Target Use Cases
+
+[Primary scenarios this Node.js application addresses]
+
+1. [Backend service scenario]
+2. [CLI tool scenario]
+
+## Value Proposition
+
+[What makes this Node.js application unique or valuable]
+
+---
+_Focus on patterns and purpose, not exhaustive feature lists_

package/framework/stacks/node/structure.md

@@ -0,0 +1,82 @@
+# Project Structure
+
+## Project: {{projectName}}
+
+## Organization Philosophy
+
+Layered architecture with clear separation of concerns. Routes handle HTTP, controllers orchestrate, services contain business logic, and repositories handle data access.
+
+## Directory Patterns
+
+### Routes
+**Location**: `/src/routes/`
+**Purpose**: HTTP route definitions and middleware
+**Example**: users.routes.ts, auth.routes.ts
+
+### Controllers
+**Location**: `/src/controllers/`
+**Purpose**: Request handling and response formatting
+**Example**: users.controller.ts, auth.controller.ts
+
+### Services
+**Location**: `/src/services/`
+**Purpose**: Business logic and domain operations
+**Example**: user.service.ts, email.service.ts
+
+### Repositories
+**Location**: `/src/repositories/`
+**Purpose**: Data access and database queries
+**Example**: user.repository.ts
+
+### Middleware
+**Location**: `/src/middleware/`
+**Purpose**: Express/Fastify middleware
+**Example**: auth.middleware.ts, validation.middleware.ts
+
+### Types
+**Location**: `/src/types/`
+**Purpose**: TypeScript interfaces and types
+**Example**: User.ts, Request.ts
+
+### Utils
+**Location**: `/src/utils/`
+**Purpose**: Pure utility functions
+**Example**: logger.ts, crypto.ts, validators.ts
+
+## Naming Conventions
+
+- **Files**: kebab-case.ts (user-service.ts, auth-controller.ts)
+- **Classes**: PascalCase (UserService, AuthController)
+- **Functions**: camelCase (getUser, validateToken)
+- **Constants**: UPPER_SNAKE_CASE
+
+## Import Organization
+
+```typescript
+// 1. Node.js built-ins
+import { readFile } from 'node:fs/promises';
+
+// 2. External packages
+import express from 'express';
+import { z } from 'zod';
+
+// 3. Internal absolute imports
+import { UserService } from '@/services/user.service';
+import { logger } from '@/utils/logger';
+
+// 4. Relative imports
+import { validateUser } from './validators';
+```
+
+**Path Aliases**:
+- `@/`: Maps to `src/`
+
+## Code Organization Principles
+
+- **Dependency Injection**: Services receive dependencies as constructor parameters
+- **Single Responsibility**: Each file/class has one primary purpose
+- **Clean Architecture**: Dependencies point inward (routes → controllers → services → repositories)
+- **Error Boundaries**: Centralized error handling middleware
+
+---
+_Document patterns, not file trees. New files following patterns shouldn't require updates_

package/framework/stacks/node/tech.md

@@ -0,0 +1,63 @@
+# Technology Stack
+
+## Project: {{projectName}}
+
+## Architecture
+
+Service-oriented architecture with clear separation between routes, controllers, services, and data access layers.
+
+## Core Technologies
+
+- **Language**: TypeScript 5.x (strict mode)
+- **Runtime**: Node.js 20+
+- **Framework**: Express / Fastify / Hono / NestJS
+
+## Key Libraries
+
+- **Validation**: Zod / Joi / class-validator
+- **Database**: Prisma / Drizzle / TypeORM / Mongoose
+- **Authentication**: Passport / JWT
+- **Testing**: Vitest / Jest
+
+## Development Standards
+
+### Type Safety
+- TypeScript strict mode enabled
+- No `any` types
+- Zod schemas for runtime validation
+- Explicit return types for all exports
+
+### Code Quality
+- ESLint with Node.js rules
+- Prettier for formatting
+- Consistent error handling patterns
+
+### Testing
+- Unit tests for services and utilities
+- Integration tests for API endpoints
+- Minimum 80% coverage for business logic
+
+## Development Environment
+
+### Required Tools
+- Node.js 20+
+- npm / yarn / pnpm
+- Docker (for databases)
+
+### Common Commands
+```bash
+# Dev: npm run dev
+# Build: npm run build
+# Test: npm test
+# Start: npm start
+```
+
+## Key Technical Decisions
+
+- **Async/Await**: Always use async/await over callbacks
+- **Error Handling**: Custom error classes with proper HTTP status codes
+- **Environment**: Use dotenv for configuration
+- **Logging**: Structured JSON logging (pino/winston)
+
+---
+_Document standards and patterns, not every dependency_

package/framework/stacks/python/product.md

@@ -0,0 +1,27 @@
+# Product Overview
+
+## Project: {{projectName}}
+
+{{description}}
+
+## Core Capabilities
+
+[3-5 key capabilities of your Python application]
+
+- [Data processing capability]
+- [API/Service capability]
+- [Automation capability]
+
+## Target Use Cases
+
+[Primary scenarios this Python application addresses]
+
+1. [Data analysis scenario]
+2. [Web service scenario]
+
+## Value Proposition
+
+[What makes this Python application unique or valuable]
+
+---
+_Focus on patterns and purpose, not exhaustive feature lists_

package/framework/stacks/python/structure.md

@@ -0,0 +1,78 @@
+# Project Structure
+
+## Project: {{projectName}}
+
+## Organization Philosophy
+
+Package-based organization with clear module boundaries. Each package is self-contained with its own models, services, and routes.
+
+## Directory Patterns
+
+### Application Package
+**Location**: `/src/{{projectName}}/` or `/app/`
+**Purpose**: Main application code
+**Example**: __init__.py, main.py
+
+### API Routes
+**Location**: `/src/api/` or `/app/routers/`
+**Purpose**: HTTP endpoint definitions
+**Example**: users.py, auth.py
+
+### Models
+**Location**: `/src/models/`
+**Purpose**: Pydantic models and SQLAlchemy models
+**Example**: user.py, schemas.py
+
+### Services
+**Location**: `/src/services/`
+**Purpose**: Business logic
+**Example**: user_service.py, email_service.py
+
+### Repositories
+**Location**: `/src/repositories/`
+**Purpose**: Data access layer
+**Example**: user_repository.py
+
+### Core
+**Location**: `/src/core/`
+**Purpose**: Shared utilities, config, dependencies
+**Example**: config.py, dependencies.py, security.py
+
+### Tests
+**Location**: `/tests/`
+**Purpose**: Test files mirroring src structure
+**Example**: test_users.py, conftest.py
+
+## Naming Conventions
+
+- **Files**: snake_case.py (user_service.py, auth_router.py)
+- **Classes**: PascalCase (UserService, UserSchema)
+- **Functions**: snake_case (get_user, validate_token)
+- **Constants**: UPPER_SNAKE_CASE
+- **Packages**: snake_case (my_package/)
+
+## Import Organization
+
+```python
+# 1. Standard library
+from datetime import datetime
+from typing import Optional
+
+# 2. Third-party packages
+from fastapi import FastAPI, Depends
+from pydantic import BaseModel
+
+# 3. Local application imports
+from app.core.config import settings
+from app.services.user_service import UserService
+```
+
+## Code Organization Principles
+
+- **Explicit Imports**: No wildcard imports
+- **Dependency Injection**: Use FastAPI Depends or manual DI
+- **Single Responsibility**: Each module has one purpose
+- **Clean Architecture**: Dependencies flow inward
+
+---
+_Document patterns, not file trees. New files following patterns shouldn't require updates_

package/framework/stacks/python/tech.md

@@ -0,0 +1,64 @@
+# Technology Stack
+
+## Project: {{projectName}}
+
+## Architecture
+
+Modular architecture with clear separation between API layer, business logic, and data access. Uses dependency injection for testability.
+
+## Core Technologies
+
+- **Language**: Python 3.11+
+- **Framework**: FastAPI / Django / Flask
+- **Package Manager**: uv / pip / poetry
+
+## Key Libraries
+
+- **Validation**: Pydantic
+- **Database**: SQLAlchemy / asyncpg / Motor
+- **HTTP Client**: httpx / aiohttp
+- **Testing**: pytest / pytest-asyncio
+
+## Development Standards
+
+### Type Safety
+- Type hints on all function signatures
+- Pydantic models for data validation
+- mypy for static type checking
+- No `Any` types except when interfacing with untyped libraries
+
+### Code Quality
+- Ruff for linting and formatting
+- Black for code formatting
+- isort for import sorting
+
+### Testing
+- pytest for all tests
+- pytest-cov for coverage reporting
+- Minimum 80% coverage for business logic
+- Fixtures for common test setup
+
+## Development Environment
+
+### Required Tools
+- Python 3.11+
+- uv or pip
+- Docker (for databases)
+
+### Common Commands
+```bash
+# Dev: uv run uvicorn main:app --reload
+# Test: uv run pytest
+# Lint: uv run ruff check .
+# Format: uv run ruff format .
+```
+
+## Key Technical Decisions
+
+- **Async**: Use async/await for I/O operations
+- **Dependency Injection**: Use FastAPI's Depends for DI
+- **Environment**: Use pydantic-settings for configuration
+- **Logging**: Structured logging with structlog
+
+---
+_Document standards and patterns, not every dependency_

package/framework/stacks/react/product.md

@@ -0,0 +1,27 @@
+# Product Overview
+
+## Project: {{projectName}}
+
+{{description}}
+
+## Core Capabilities
+
+[3-5 key capabilities of your React application]
+
+- [User interface capability]
+- [State management capability]
+- [Data handling capability]
+
+## Target Use Cases
+
+[Primary scenarios this React application addresses]
+
+1. [User interaction scenario]
+2. [Data visualization scenario]
+
+## Value Proposition
+
+[What makes this React application unique or valuable]
+
+---
+_Focus on patterns and purpose, not exhaustive feature lists_

package/framework/stacks/react/structure.md

@@ -0,0 +1,76 @@
+# Project Structure
+
+## Project: {{projectName}}
+
+## Organization Philosophy
+
+Feature-first organization with shared components and utilities. Each feature is self-contained with its own components, hooks, and types.
+
+## Directory Patterns
+
+### Components
+**Location**: `/src/components/`
+**Purpose**: Shared, reusable UI components
+**Example**: Button, Modal, Card, Input
+
+### Features
+**Location**: `/src/features/`
+**Purpose**: Feature-specific code (components, hooks, types)
+**Example**: auth/, dashboard/, settings/
+
+### Hooks
+**Location**: `/src/hooks/`
+**Purpose**: Shared custom React hooks
+**Example**: useDebounce, useLocalStorage, useMediaQuery
+
+### Services
+**Location**: `/src/services/`
+**Purpose**: API calls and external integrations
+**Example**: api.ts, auth.service.ts
+
+### Types
+**Location**: `/src/types/`
+**Purpose**: Shared TypeScript interfaces and types
+**Example**: User.ts, ApiResponse.ts
+
+### Utils
+**Location**: `/src/utils/`
+**Purpose**: Pure utility functions
+**Example**: formatDate, validators, helpers
+
+## Naming Conventions
+
+- **Component Files**: PascalCase.tsx (Button.tsx, UserProfile.tsx)
+- **Hook Files**: use*.ts (useAuth.ts, useForm.ts)
+- **Utility Files**: camelCase.ts (formatters.ts, validators.ts)
+- **Test Files**: *.test.tsx or *.spec.tsx
+
+## Import Organization
+
+```typescript
+// 1. React and external packages
+import React, { useState, useEffect } from 'react';
+import { useNavigate } from 'react-router-dom';
+
+// 2. Internal absolute imports
+import { Button } from '@/components/Button';
+import { useAuth } from '@/hooks/useAuth';
+
+// 3. Relative imports
+import { UserCard } from './UserCard';
+import type { UserProps } from './types';
+```
+
+**Path Aliases**:
+- `@/`: Maps to `src/`
+- `@/components`: Maps to `src/components/`
+
+## Code Organization Principles
+
+- **Co-location**: Keep related code together (feature's components, hooks, types)
+- **Single Responsibility**: Each file has one primary purpose
+- **Barrel Exports**: Use index.ts for clean imports
+- **Dependency Direction**: Features depend on shared, not vice versa
+
+---
+_Document patterns, not file trees. New files following patterns shouldn't require updates_

package/framework/stacks/react/tech.md

@@ -0,0 +1,65 @@
+# Technology Stack
+
+## Project: {{projectName}}
+
+## Architecture
+
+Component-based architecture with unidirectional data flow. React components handle UI rendering while hooks manage state and side effects.
+
+## Core Technologies
+
+- **Language**: TypeScript 5.x (strict mode)
+- **Framework**: React 18+
+- **Runtime**: Node.js 20+ (development), Browser (production)
+- **Build Tool**: Vite / Create React App / Next.js
+
+## Key Libraries
+
+- **State Management**: React Context / Redux / Zustand
+- **Routing**: React Router / Next.js Router
+- **Styling**: Tailwind CSS / CSS Modules / Styled Components
+- **HTTP Client**: fetch / axios / TanStack Query
+
+## Development Standards
+
+### Type Safety
+- TypeScript strict mode enabled
+- No `any` types except for third-party library edge cases
+- Explicit return types for exported functions
+- Interface over type for object shapes
+
+### Code Quality
+- ESLint with recommended React rules
+- Prettier for formatting
+- Husky pre-commit hooks
+
+### Testing
+- Vitest / Jest for unit tests
+- React Testing Library for component tests
+- Playwright / Cypress for E2E tests
+- Minimum 80% coverage for business logic
+
+## Development Environment
+
+### Required Tools
+- Node.js 20+
+- npm / yarn / pnpm
+- VS Code with React extensions
+
+### Common Commands
+```bash
+# Dev: npm run dev
+# Build: npm run build
+# Test: npm test
+# Lint: npm run lint
+```
+
+## Key Technical Decisions
+
+- **Functional Components**: Always use functional components with hooks
+- **Custom Hooks**: Extract reusable logic into custom hooks
+- **Composition**: Prefer composition over inheritance
+- **Immutability**: Never mutate state directly
+
+---
+_Document standards and patterns, not every dependency_

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "red64-cli",
+  "version": "0.1.0",
+  "description": "Red64 Flow Orchestrator - Deterministic spec-driven development CLI",
+  "type": "module",
+  "bin": {
+    "red64": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "framework"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "build:ts": "tsc",
+    "dev": "tsx src/cli.tsx",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "type-check": "tsc --noEmit"
+  },
+  "keywords": [
+    "cli",
+    "spec-driven",
+    "workflow",
+    "orchestration"
+  ],
+  "author": "Yacin Bahi <yacin@red64.io>",
+  "license": "MIT",
+  "dependencies": {
+    "@inkjs/ui": "^2.0.0",
+    "date-fns": "^3.6.0",
+    "ink": "^5.0.1",
+    "meow": "^14.0.0",
+    "react": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "@types/react": "^18.3.18",
+    "ink-testing-library": "^4.0.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}