chati-dev 1.4.0 → 2.0.2

package/framework/tasks/greenfield-wu-analyze-empty.md

@@ -0,0 +1,169 @@
+---
+id: greenfield-wu-analyze-empty
+agent: greenfield-wu
+trigger: orchestrator
+phase: clarity
+requires_input: false
+parallelizable: false
+outputs: [wu-analysis.yaml]
+handoff_to: greenfield-wu-scaffold-detection
+autonomous_gate: true
+criteria:
+  - Runtime environment detected (node, python, etc.)
+  - Existing configuration files catalogued
+  - Git state analyzed (initialized, remote, branches)
+  - Project root structure documented
+---
+# Analyze Empty Project
+
+## Purpose
+Perform initial analysis of an empty or minimal project directory to establish baseline environment and detect any existing configuration.
+
+## Prerequisites
+- Project directory exists
+- User has read permissions
+- Path to project root is known
+
+## Steps
+
+### 1. Detect Runtime Environment
+- Check for runtime indicators:
+  - Node.js: `package.json`, `.nvmrc`, `node_modules/`
+  - Python: `requirements.txt`, `pyproject.toml`, `setup.py`, `venv/`, `.python-version`
+  - Ruby: `Gemfile`, `.ruby-version`
+  - PHP: `composer.json`
+  - Go: `go.mod`
+  - Rust: `Cargo.toml`
+  - Java: `pom.xml`, `build.gradle`
+- Record detected runtimes and versions if specified
+- Flag multi-runtime projects
+
+### 2. Scan Configuration Files
+- Search for common config files:
+  - Editor configs: `.editorconfig`, `.vscode/`, `.idea/`
+  - Linters: `.eslintrc*`, `.prettierrc*`, `pylint.rc`, `rubocop.yml`
+  - Type checkers: `tsconfig.json`, `mypy.ini`
+  - Build tools: `webpack.config.js`, `vite.config.ts`, `rollup.config.js`
+  - CI/CD: `.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`
+  - Docker: `Dockerfile`, `docker-compose.yml`
+  - Environment: `.env.example`, `.env.template`
+- Catalog all found configurations with paths
+
+### 3. Analyze Git State
+- Check if git repository is initialized (`git rev-parse --git-dir`)
+- If initialized:
+  - Get current branch (`git branch --show-current`)
+  - List all branches (`git branch -a`)
+  - Check for remote (`git remote -v`)
+  - Count commits (`git rev-list --count HEAD`)
+  - Check for uncommitted changes (`git status --porcelain`)
+- If not initialized:
+  - Flag as new repository
+  - Recommend initialization
+
+### 4. Document Directory Structure
+- List top-level directories and files
+- Identify standard patterns:
+  - `src/`, `lib/`, `app/` = source code
+  - `test/`, `tests/`, `__tests__/` = test files
+  - `docs/`, `documentation/` = documentation
+  - `public/`, `static/` = static assets
+  - `scripts/`, `bin/` = utility scripts
+  - `config/`, `configs/` = configuration
+- Calculate total file count and directory depth
+
+### 5. Detect Existing Frameworks
+- Look for framework indicators:
+  - React: `react` in dependencies, `src/App.jsx`
+  - Next.js: `next.config.js`, `pages/` or `app/`
+  - Vue: `vue` in dependencies, `*.vue` files
+  - Angular: `angular.json`
+  - Express: `express` in dependencies
+  - Django: `manage.py`, `settings.py`
+  - Rails: `Rakefile`, `config/routes.rb`
+- Record framework names and versions
+
+### 6. Assess Project Maturity
+- Calculate maturity score based on:
+  - Presence of tests (0-25 points)
+  - CI/CD configuration (0-25 points)
+  - Documentation (0-25 points)
+  - Linting/formatting setup (0-25 points)
+- Classify as: empty (0-10), minimal (11-40), basic (41-70), mature (71-100)
+
+### 7. Identify Missing Essentials
+- Check for critical files:
+  - `README.md` - project documentation
+  - `LICENSE` - licensing information
+  - `.gitignore` - git exclusions
+  - `CONTRIBUTING.md` - contribution guidelines (for open source)
+- Flag missing files as recommendations
+
+### 8. Compile Analysis Report
+- Aggregate all findings into structured YAML
+- Include confidence scores for each detection
+- Add recommendations for next steps
+
+## Decision Points
+- **Multi-Runtime Detected**: Ask user which runtime is primary
+- **No Runtime Detected**: Ask user to specify intended runtime
+- **Git Remote Mismatch**: If remote exists but doesn't match user's organization, flag for review
+
+## Error Handling
+- **Permission Denied**: Request user to check directory permissions or run with appropriate access
+- **Invalid Project Path**: Verify path exists and retry, or ask user to provide correct path
+- **Git Not Installed**: Flag git operations as skipped, continue with other analysis
+- **Corrupted Config Files**: Note files that cannot be parsed, continue analysis
+
+## Output Format
+```yaml
+# wu-analysis.yaml
+project_path: /absolute/path/to/project
+analysis_timestamp: 2026-02-13T10:30:00Z
+runtime:
+  detected: [node, python]
+  primary: node
+  versions:
+    node: "22.22.0"
+    npm: "10.5.0"
+configuration_files:
+  - path: package.json
+    type: npm_manifest
+    valid: true
+  - path: tsconfig.json
+    type: typescript_config
+    valid: true
+git:
+  initialized: true
+  branch: main
+  remote: origin
+  remote_url: https://github.com/user/repo.git
+  commit_count: 3
+  uncommitted_changes: false
+structure:
+  directories: [src, tests, docs]
+  file_count: 12
+  max_depth: 3
+frameworks:
+  - name: react
+    version: "18.2.0"
+  - name: vite
+    version: "5.0.0"
+maturity:
+  score: 35
+  classification: minimal
+  breakdown:
+    tests: 10
+    ci_cd: 0
+    docs: 15
+    linting: 10
+missing_essentials:
+  - README.md
+  - LICENSE
+  - .gitignore
+recommendations:
+  - Add README.md with project description
+  - Initialize .gitignore for Node.js
+  - Set up basic testing framework
+confidence: 95
+```

package/framework/tasks/greenfield-wu-report.md

@@ -0,0 +1,266 @@
+---
+id: greenfield-wu-report
+agent: greenfield-wu
+trigger: greenfield-wu-tech-stack-assess
+phase: clarity
+requires_input: false
+parallelizable: false
+outputs: [wu-report.yaml]
+handoff_to: brief
+autonomous_gate: true
+criteria:
+  - All analysis artifacts consolidated
+  - Clear recommendations provided
+  - Risk assessment included
+  - Next steps documented
+---
+# Compile Greenfield WU Report
+
+## Purpose
+Consolidate all greenfield analysis findings into a comprehensive Work Understanding report that provides clear recommendations and next steps.
+
+## Prerequisites
+- `wu-analysis.yaml` exists
+- `scaffold-report.yaml` exists
+- `tech-stack.yaml` exists
+
+## Steps
+
+### 1. Load All Analysis Artifacts
+- Read `wu-analysis.yaml` for environment and maturity assessment
+- Read `scaffold-report.yaml` for scaffolding recommendations
+- Read `tech-stack.yaml` for complete stack recommendations
+- Verify all files are valid YAML and contain expected keys
+
+### 2. Create Executive Summary
+Write a 3-5 sentence summary covering:
+- Current project state (empty, minimal, or basic)
+- Detected runtime and existing setup (if any)
+- Recommended scaffolding tool
+- Recommended tech stack highlights
+- Estimated time to initial scaffold
+
+### 3. Consolidate Environment Analysis
+Summarize from `wu-analysis.yaml`:
+- **Project Path**: Absolute path to project
+- **Current State**: Empty, minimal, or basic with maturity score
+- **Runtime Environment**: Detected runtimes and versions
+- **Git Status**: Initialized, branch, remote status
+- **Existing Configuration**: List of found config files
+- **Missing Essentials**: Critical files not present
+
+### 4. Consolidate Scaffolding Recommendations
+Summarize from `scaffold-report.yaml`:
+- **Recommended Tool**: Top choice with score
+- **Command to Run**: Exact scaffolding command
+- **Alternatives**: Brief mention of alternatives considered
+- **Justification**: Why this tool was chosen
+
+### 5. Consolidate Tech Stack
+Summarize from `tech-stack.yaml`:
+- **Frontend**: Framework, UI library, build tool
+- **Backend**: Runtime, framework, API style
+- **Database**: Primary database and cache
+- **Infrastructure**: Hosting and CI/CD
+- **Key Justifications**: Major reasoning for choices
+
+### 6. Aggregate Risk Assessment
+Compile all risks mentioned across artifacts:
+- Runtime/version compatibility risks
+- Tool maintenance risks
+- Team expertise gaps
+- Vendor lock-in concerns
+- Performance bottlenecks
+- Security considerations
+For each risk:
+- Severity: Low, Medium, High, Critical
+- Likelihood: Low, Medium, High
+- Impact: What happens if risk materializes
+- Mitigation: How to address or reduce risk
+
+### 7. Calculate Confidence Score
+Determine overall confidence (0-100) based on:
+- Environment detection confidence (from wu-analysis.yaml)
+- Availability of clear requirements (if ambiguous, reduce confidence)
+- Maturity of recommended tools (bleeding edge = lower confidence)
+- Team expertise match (unknown team = lower confidence)
+- Compatibility verification (verified = higher confidence)
+
+### 8. Define Next Steps
+Provide ordered list of immediate actions:
+1. **Review and Approve**: User reviews this report and tech stack
+2. **Run Scaffold Command**: Execute recommended scaffolding
+3. **Install Dependencies**: Any additional packages needed
+4. **Configure Tooling**: Set up linters, formatters, type checkers
+5. **Initialize Git** (if not already): Commit initial scaffold
+6. **Create Brief**: Move to requirements gathering phase
+
+### 9. Add Recommendations
+Include actionable recommendations:
+- **Immediate**: Actions to take before writing code
+- **Short-term**: Set up during first sprint (CI/CD, testing)
+- **Medium-term**: Add as project matures (monitoring, documentation site)
+- **Long-term**: Consider for scale (microservices, caching layers)
+
+### 10. Generate Final Report
+Combine all sections into structured YAML with clear hierarchy and human-readable formatting.
+
+## Decision Points
+- **Low Confidence (<70%)**: Flag the report for user review and ask if additional analysis is needed before proceeding
+- **High Risk Identified**: If any critical risks found, highlight prominently and recommend risk mitigation tasks before development
+- **Conflicting Data**: If analysis artifacts have conflicting information (e.g., scaffold-report suggests different runtime than wu-analysis), flag conflict and ask for clarification
+
+## Error Handling
+- **Missing Artifact**: If any prerequisite YAML file is missing, halt and request that previous task be completed
+- **Invalid YAML**: If any artifact cannot be parsed, log error with file path and line number, attempt to continue with partial data
+- **Empty Recommendations**: If tech-stack.yaml has no recommendations, flag as error and request tech-stack-assess be re-run
+- **Circular Dependencies**: If next_steps reference tasks that reference back, flag as planning error
+
+## Output Format
+```yaml
+# wu-report.yaml
+report_type: greenfield
+timestamp: 2026-02-13T10:45:00Z
+executive_summary: |
+  Empty Node.js project detected with no existing framework. Recommended scaffolding
+  with Vite for React + TypeScript. Full-stack architecture recommended with
+  Fastify backend, PostgreSQL database, and deployment on Vercel + Railway.
+  Estimated 30 minutes to initial scaffold, 2-4 hours to complete tooling setup.
+
+environment:
+  project_path: /Users/user/projects/my-app
+  current_state: empty
+  maturity_score: 0
+  runtime:
+    primary: node
+    version: "22.22.0"
+  git:
+    initialized: false
+    recommendation: Initialize after scaffold
+  existing_config: []
+  missing_essentials:
+    - README.md
+    - .gitignore
+    - LICENSE
+
+scaffolding:
+  recommended_tool: vite
+  command: npm create vite@latest my-app -- --template react-ts
+  justification: |
+    Fast build times, modern architecture, excellent TypeScript support.
+    Minimal but extensible starting point for React applications.
+  alternatives:
+    - create-next-app: Full-stack needs
+    - create-react-app: Traditional setup (slower builds)
+  estimated_time: 5 minutes
+
+tech_stack:
+  frontend:
+    framework: React 18.2
+    ui_library: shadcn/ui
+    build_tool: Vite
+    state: TanStack Query
+  backend:
+    runtime: Node.js 22.x
+    framework: Fastify
+    orm: Prisma
+  database:
+    primary: PostgreSQL 16
+    cache: Redis 7
+  infrastructure:
+    hosting_frontend: Vercel
+    hosting_backend: Railway
+    ci_cd: GitHub Actions
+  justification_summary: |
+    Modern React stack prioritizing developer experience and type safety.
+    Node.js backend for shared language. PostgreSQL for data integrity.
+    Vercel + Railway for simple deployment with good free tiers.
+
+risks:
+  - id: R1
+    description: Team unfamiliarity with Fastify
+    severity: medium
+    likelihood: medium
+    impact: Slower initial backend development
+    mitigation: Provide Fastify learning resources, leverage strong documentation
+  - id: R2
+    description: Node.js single-threaded performance limits
+    severity: low
+    likelihood: low
+    impact: May need to refactor under extreme load
+    mitigation: Use clustering, profile early, consider Go microservices for hot paths
+  - id: R3
+    description: Rapid JavaScript ecosystem churn
+    severity: medium
+    likelihood: high
+    impact: Frequent breaking changes requiring updates
+    mitigation: Pin versions carefully, allocate time for quarterly dependency updates
+
+confidence: 85
+confidence_breakdown:
+  environment_detection: 95
+  requirements_clarity: 70
+  tool_maturity: 90
+  team_expertise: 75
+  compatibility: 95
+
+next_steps:
+  - step: 1
+    action: Review and approve WU report
+    owner: user
+    estimated_time: 15 minutes
+  - step: 2
+    action: Run scaffolding command
+    command: npm create vite@latest my-app -- --template react-ts
+    owner: greenfield-wu
+    estimated_time: 5 minutes
+  - step: 3
+    action: Install additional dependencies
+    commands:
+      - cd my-app && npm install
+      - npm install -D prettier eslint
+    estimated_time: 3 minutes
+  - step: 4
+    action: Initialize git repository
+    commands:
+      - git init
+      - git add .
+      - git commit -m "chore: initial scaffold"
+    estimated_time: 2 minutes
+  - step: 5
+    action: Transition to brief agent for requirements gathering
+    owner: orchestrator
+    handoff: brief
+
+recommendations:
+  immediate:
+    - Create .env.example for environment variable documentation
+    - Set up .gitignore for Node.js (node_modules, .env, dist)
+    - Add README.md with setup instructions
+  short_term:
+    - Configure GitHub Actions for CI (lint, test, build)
+    - Set up Prettier and ESLint with pre-commit hooks
+    - Add Vitest and React Testing Library
+    - Create basic component structure (components/, pages/, utils/)
+  medium_term:
+    - Set up Sentry or similar error tracking
+    - Add Storybook for component documentation
+    - Create API integration layer with TanStack Query
+    - Set up database with Prisma schema
+  long_term:
+    - Consider monorepo structure if multiple apps needed
+    - Implement monitoring and alerting
+    - Add end-to-end testing with Playwright
+    - Evaluate micro-frontend architecture for scale
+
+artifacts_generated:
+  - wu-analysis.yaml
+  - scaffold-report.yaml
+  - tech-stack.yaml
+  - wu-report.yaml
+
+handoff_to: brief
+handoff_context: |
+  Greenfield project setup complete. Recommended stack defined. Next phase
+  is requirements gathering to define features and scope before development.
+```

package/framework/tasks/greenfield-wu-scaffold-detection.md

@@ -0,0 +1,203 @@
+---
+id: greenfield-wu-scaffold-detection
+agent: greenfield-wu
+trigger: greenfield-wu-analyze-empty
+phase: clarity
+requires_input: false
+parallelizable: false
+outputs: [scaffold-report.yaml]
+handoff_to: greenfield-wu-tech-stack-assess
+autonomous_gate: true
+criteria:
+  - All available scaffolding tools identified for detected runtime
+  - Tool compatibility assessed
+  - Recommendations ranked by suitability
+---
+# Detect Project Scaffolding Tools
+
+## Purpose
+Identify and evaluate available project scaffolding tools that match the detected runtime environment and project requirements.
+
+## Prerequisites
+- `wu-analysis.yaml` exists with runtime detection
+- Internet connectivity for checking tool availability (optional)
+- Knowledge of current project requirements
+
+## Steps
+
+### 1. Load Runtime Context
+- Read `wu-analysis.yaml` to get detected runtime(s)
+- Extract primary runtime and version
+- Note any existing frameworks or build tools
+
+### 2. Map Runtime to Scaffolding Tools
+- **Node.js/JavaScript/TypeScript**:
+  - `create-react-app` - React applications
+  - `vite` - Fast modern build tool (React, Vue, Svelte, Vanilla)
+  - `create-next-app` - Next.js applications
+  - `create-vue` - Vue.js applications
+  - `@angular/cli` - Angular applications
+  - `create-remix` - Remix applications
+  - `create-t3-app` - Full-stack TypeScript (Next.js + tRPC + Tailwind + Prisma)
+  - `create-expo-app` - React Native/Expo mobile apps
+  - `express-generator` - Express.js backend
+  - `nest-cli` - NestJS backend
+- **Python**:
+  - `django-admin startproject` - Django web framework
+  - `flask` - Flask microframework (manual setup)
+  - `fastapi` - FastAPI modern API framework
+  - `cookiecutter` - Template-based project generator
+  - `poetry new` - Poetry package manager with project scaffolding
+- **Ruby**:
+  - `rails new` - Ruby on Rails
+  - `hanami new` - Hanami framework
+  - `sinatra` - Sinatra microframework (manual setup)
+- **PHP**:
+  - `composer create-project laravel/laravel` - Laravel
+  - `symfony new` - Symfony
+- **Go**:
+  - `go mod init` - Go modules (manual structure)
+  - `gonew` - Go project templates
+- **Rust**:
+  - `cargo new` - Rust binary/library
+- **Java**:
+  - Spring Initializr - Spring Boot
+  - Maven archetypes
+  - Gradle init
+
+### 3. Filter by Project Type
+- Determine project type from requirements or ask user:
+  - Web application (frontend)
+  - Web application (fullstack)
+  - API/Backend service
+  - Mobile application
+  - CLI tool
+  - Library/Package
+- Remove incompatible scaffolding tools
+
+### 4. Assess Tool Compatibility
+For each remaining tool, evaluate:
+- **Version Compatibility**: Does it support the detected runtime version?
+- **Maintenance Status**: Is the tool actively maintained? (check last release date)
+- **Community Size**: NPM downloads, GitHub stars, community activity
+- **Flexibility**: How much control does it give vs. abstraction?
+- **Ejection Support**: Can you customize deeply or "eject"?
+- **TypeScript Support**: Native or via plugin?
+- **Testing Setup**: Does it include testing framework?
+- **Build Performance**: Known for fast/slow builds?
+
+### 5. Check for Existing Scaffolding
+- If `wu-analysis.yaml` shows existing framework:
+  - Identify the scaffolding tool that was likely used
+  - Check if re-scaffolding is needed or if incremental setup is better
+  - Flag if existing setup is non-standard
+
+### 6. Rank Recommendations
+- Assign score (0-100) to each tool based on:
+  - Match to project requirements (40 points)
+  - Community support (20 points)
+  - Maintenance status (15 points)
+  - TypeScript support if needed (10 points)
+  - Build performance (10 points)
+  - Developer experience (5 points)
+- Sort by score descending
+- Select top 3 recommendations
+
+### 7. Document Trade-offs
+For each recommended tool, document:
+- **Pros**: What it does well
+- **Cons**: Known limitations or issues
+- **Use Case**: When to choose this tool
+- **Learning Curve**: Beginner-friendly vs. advanced
+- **Vendor Lock-in**: How easy to migrate away
+
+### 8. Generate Scaffold Commands
+For each recommendation, provide:
+- Exact command to run
+- Required prerequisites (global installs, etc.)
+- Expected output
+- Post-scaffold next steps
+
+## Decision Points
+- **Multiple Runtimes**: If project uses multiple runtimes (e.g., Node + Python), ask user which runtime should be primary for scaffolding
+- **Existing Framework Conflict**: If analysis detected existing framework but user wants to scaffold fresh, confirm they want to overwrite
+- **Opinionated vs. Flexible**: If requirements are unclear, ask user preference for opinionated (batteries-included) vs. flexible (minimal) setup
+
+## Error Handling
+- **Unknown Runtime**: If runtime not recognized, skip scaffold detection and document manual setup requirement
+- **No Tools Available**: If no scaffolding tools exist for the runtime, provide manual project structure recommendations
+- **Version Mismatch**: If detected runtime version is too old for modern scaffolding tools, warn user and suggest upgrade path
+- **Conflicting Requirements**: If requirements suggest incompatible tools (e.g., React + Vue), flag conflict and request clarification
+
+## Output Format
+```yaml
+# scaffold-report.yaml
+runtime: node
+runtime_version: "22.22.0"
+project_type: web_application_frontend
+existing_scaffold: null
+available_tools:
+  - name: vite
+    score: 95
+    command: npm create vite@latest my-app -- --template react-ts
+    prerequisites: [npm >= 7.0.0]
+    pros:
+      - Extremely fast HMR and build times
+      - Modern ESM-based architecture
+      - First-class TypeScript support
+      - Framework-agnostic (React, Vue, Svelte, etc.)
+    cons:
+      - Less opinionated than CRA
+      - Smaller ecosystem of plugins vs. webpack
+    use_case: Modern React/Vue/Svelte apps prioritizing build speed
+    learning_curve: easy
+    vendor_lockin: low
+    compatibility:
+      node: ">= 18.0.0"
+      typescript: true
+      testing: vitest
+    maintenance:
+      last_release: 2026-01-15
+      status: active
+      community_size: high
+  - name: create-next-app
+    score: 88
+    command: npx create-next-app@latest my-app --typescript --tailwind --app
+    prerequisites: []
+    pros:
+      - Full-stack framework (SSR, API routes, file-based routing)
+      - Excellent developer experience
+      - Strong community and Vercel backing
+    cons:
+      - More complex than pure React
+      - Some vendor lock-in to Next.js patterns
+    use_case: Full-stack React apps with SSR/SSG needs
+    learning_curve: moderate
+    vendor_lockin: medium
+  - name: create-react-app
+    score: 72
+    command: npx create-react-app my-app --template typescript
+    prerequisites: []
+    pros:
+      - Zero config setup
+      - Battle-tested and stable
+      - Large ecosystem
+    cons:
+      - Slow build times
+      - Maintenance has slowed
+      - Difficult to customize without ejecting
+    use_case: Traditional React SPAs, learning projects
+    learning_curve: easy
+    vendor_lockin: low
+recommended: vite
+reasoning: |
+  Vite offers the best balance of performance, flexibility, and modern architecture
+  for a new React TypeScript project. Its HMR is significantly faster than alternatives,
+  and it provides a minimal but extensible starting point.
+next_steps:
+  - Run scaffold command
+  - Install additional dependencies if needed
+  - Configure linting and formatting
+  - Set up testing framework (Vitest recommended)
+timestamp: 2026-02-13T10:35:00Z
+```