@glxmart/boss-cli 1.0.0-beta.0

package/dist/assets/claude-md/docs/workers.md

@@ -0,0 +1,174 @@
+# Available Workers
+
+BOSS has access to **15 specialized workers** that form a fully functional, high-performance engineering team. Each worker is aware of their role, uses Spec-Kit commands, and follows team collaboration patterns.
+
+## How to Discover and Load Workers
+
+**CRITICAL: Worker Discovery Instructions**
+
+When you need to find available workers or load a worker's configuration:
+
+1. **Discover Available Workers:**
+   - List directories in `.boss/workers/` to find available worker names
+   - Use: `ls -la .boss/workers/` or list the directory contents
+   - Each worker is a **directory** (not a file), named after the worker type (e.g., `architect`, `clarifier`, `spec-writer`)
+   - **DO NOT** search for `*.yaml` files - workers are directories, not YAML files
+
+2. **Load Worker Configuration:**
+   - **Worker prompt:** Read `.boss/workers/[worker-name]/prompt.md` (contains the worker's role and instructions)
+   - **Worker instructions:** Read `.boss/workers/[worker-name]/CLAUDE.md` (contains execution guidelines)
+   - **Container config:** Read `.boss/workers/[worker-name]/container-config.json` (contains container-use environment settings)
+   - **DO NOT** look for `README.md` files - use `prompt.md` and `CLAUDE.md` instead
+
+3. **Container-Use Configuration:**
+   - **Global config:** Read `.container-use/environment.json` (NOT `config.yaml`)
+   - This file contains base container settings and environment variables
+   - **DO NOT** look for `.container-use/config.yaml` - it doesn't exist
+
+**Example Worker Discovery:**
+```bash
+# List available workers
+ls .boss/workers/
+# Output: architect  clarifier  spec-writer  planner  ...
+
+# Load architect worker prompt
+cat .boss/workers/architect/prompt.md
+
+# Load architect container config
+cat .boss/workers/architect/container-config.json
+```
+
+**Common Mistakes to Avoid:**
+- NOT OK **DO NOT** search for `.boss/workers/*.yaml` - workers are directories, not YAML files
+- NOT OK **DO NOT** read `.boss/workers/[worker-name]/README.md` - use `prompt.md` instead
+- NOT OK **DO NOT** read `.container-use/config.yaml` - read `.container-use/environment.json` instead
+
+## Phase-Specific Workers
+
+**Phase 1: Constitution**
+- **`architect`** - Creates `.specify/memory/constitution.md` with governing principles. Establishes NON-NEGOTIABLE standards: Test-First, BDD, Documentation. Defines architectural principles and development methodology.
+
+**Phase 2: Clarification**
+- **`clarifier`** - Gathers business requirements through conversation. Uses `/speckit.clarify` to identify ambiguities. Asks business questions (not technical). Documents user personas and workflows.
+
+**Phase 3: Specification**
+- **`spec-writer`** - Creates `spec.md` with user stories in Given/When/Then format (BDD). Uses `/speckit.specify` and `/speckit.checklist`. Includes acceptance criteria and edge cases. Ensures specs are testable and actionable.
+
+**Phase 4: Planning**
+- **`planner`** - Creates `plan.md`, `data-model.md`, `contracts/`. Uses `/speckit.plan` to generate technical approach. Plans BDD test strategy and documentation structure.
+
+**Phase 5: Validation**
+- **`reviewer`** - Validates plan against constitution. Checks TDD/BDD/Documentation compliance. Uses `/speckit.analyze`. Verifies BDD layer and documentation requirements. Ensures constitution compliance.
+
+**Phase 6: Task Breakdown**
+- **`planner`** - Creates `tasks.md` with [P] parallel markers. Uses `/speckit.tasks` to break down plans. Orders tasks by dependencies. Enables parallel execution where possible.
+
+**Phase 7: Implementation**
+- **`developer-frontend`** - Implements frontend features following TDD + BDD. Uses `/speckit.implement`. Creates BDD tests and feature documentation. Ensures accessibility, performance, and responsive design.
+- **`developer-backend`** - Implements backend features following TDD + BDD. Uses `/speckit.implement`. Creates API documentation and feature documentation. Ensures security, performance, and scalability.
+- **`developer-fullstack`** - Implements fullstack features following TDD + BDD. Uses `/speckit.implement`. Creates comprehensive tests and documentation. Ensures seamless frontend-backend integration.
+- **`tester`** - Creates comprehensive test suites (BDD, unit, integration, E2E). Uses `/speckit.checklist` for test requirements. Ensures test coverage ≥80% and mutation score ≥80%. Validates implementations meet specifications.
+- **`code-reviewer`** - Reviews code for quality, maintainability, and adherence to coding standards. Uses `/speckit.analyze`. Provides constructive feedback. Validates code follows TDD/BDD practices and architecture principles.
+
+**Phase 8: Consolidation**
+- **`consolidator`** - Merges all worker branches. Creates `quickstart.md` and `checklist.md`. Uses `/speckit.analyze`. Validates documentation completeness. Runs integration tests. Prepares artifacts for PR creation.
+
+## Cross-Phase Workers
+
+These workers can be spawned at any phase as needed:
+
+- **`product-owner`** - Represents business and user needs throughout the lifecycle. Prioritizes user stories (P1, P2, P3) based on business value. Validates acceptance criteria are measurable and business-focused. Works with Clarifier, Spec Writer, and all team members.
+
+- **`security-engineer`** - Ensures applications are secure and compliant. Performs security reviews, threat modeling, and vulnerability scanning. Uses `/speckit.checklist` for security requirements. Integrates security into CI/CD pipeline. Follows OWASP Top 10 and security best practices.
+
+- **`devops-engineer`** - Sets up CI/CD pipelines, infrastructure, and deployment automation. Ensures applications are deployable, scalable, and maintainable. Configures monitoring, logging, and alerting. Creates deployment documentation in `quickstart.md`.
+
+- **`technical-writer`** - Creates comprehensive documentation (API docs, user guides, developer docs). Uses `/speckit.checklist` for documentation quality. Maintains documentation quality and completeness. Updates `quickstart.md` and other documentation artifacts.
+
+## Worker Spawning Guidelines
+
+**When to spawn workers:**
+
+1. **Sequential Phase Workers**: Spawn in order (architect → clarifier → spec-writer → planner → reviewer → planner → developers → consolidator)
+2. **Parallel Implementation**: Spawn multiple developers in parallel based on [P] markers in `tasks.md` (max 5 concurrent)
+3. **Cross-Phase Workers**: Spawn as needed:
+   - `product-owner` - During clarification, specification, and planning phases
+   - `security-engineer` - During planning and implementation phases
+   - `devops-engineer` - During planning and consolidation phases
+   - `technical-writer` - During implementation and consolidation phases
+4. **Quality Workers**: Spawn `tester` and `code-reviewer` during implementation phase
+
+**Worker Configuration:**
+- Each worker has configs in `.boss/workers/[worker-name]/`
+- Worker prompts are in `.boss/workers/[worker-name]/prompt.md`
+- Container configs are in `.boss/workers/[worker-name]/container-config.json`
+- Worker instructions are in `.boss/workers/[worker-name]/CLAUDE.md`
+
+**Worker Execution (MANDATORY - BOSS Must Spawn Workers):**
+
+**CRITICAL:** BOSS must ALWAYS spawn workers using `mcp_container-use_execute_in_environment`. BOSS must NEVER write deliverables directly.
+
+1. **Create environment** using `mcp_container-use_create_environment`
+   - Load worker config from `.boss/workers/[worker-name]/container-config.json`
+
+2. **Load worker configuration:**
+   - Read `.boss/workers/[worker-name]/prompt.md` to understand worker's role and instructions
+   - Read `.boss/workers/[worker-name]/CLAUDE.md` for execution guidelines
+   - Check for worker-specific `.claude` folder: `.boss/workers/[worker-name]/.claude/`
+
+3. **Configure container environment (MANDATORY - ONLY EXCEPTION):**
+   - **This is the ONLY time BOSS uses `environment_file_write`** - to configure the container for the worker
+   - **Overwrite `.claude/CLAUDE.md` in container:**
+     - Read `.boss/workers/[worker-name]/CLAUDE.md` from host
+     - Use `mcp_container-use_environment_file_write` to write to `/workdir/.claude/CLAUDE.md` in container
+     - **CRITICAL PATH:** Host `.boss/workers/architect/CLAUDE.md` → Container `/workdir/.claude/CLAUDE.md`
+     - Container needs worker's instructions, not BOSS's orchestration instructions
+   - **Copy worker-specific `.claude` files to container:**
+     - If `.boss/workers/[worker-name]/.claude/` exists, copy all files maintaining directory structure
+     - **CRITICAL PATH TRANSFORMATION:**
+       - Remove `.boss/workers/[worker-name]/` prefix
+       - Keep `.claude/` structure
+       - Example: `.boss/workers/architect/.claude/commands/file.md` → `/workdir/.claude/commands/file.md`
+     - Copy all subdirectories:
+       - `.claude/commands/` → `/workdir/.claude/commands/`
+       - `.claude/skills/` → `/workdir/.claude/skills/`
+       - `.claude/agents/` → `/workdir/.claude/agents/`
+       - `.claude/settings*.json` → `/workdir/.claude/settings*.json`
+     - Use `mcp_container-use_environment_file_write` for each file
+   - **Why:** Container's Claude Code reads from `/workdir/.claude/` by convention - we must copy files there
+   - **Why NOT environment variables:** Claude Code reads from `.claude/` folder by convention, cannot be changed with env vars
+
+4. **Assemble task prompt:**
+   - Combine worker prompt with specific task instructions
+   - Include context (constitution, specs, requirements)
+   - Include quality gates and deliverables
+
+5. **Execute worker using `mcp_container-use_execute_in_environment`** (MANDATORY)
+   - Worker runs in isolated container with its own branch
+   - Container has worker-specific `.claude/CLAUDE.md` and `.claude/` config files
+   - **WORKER writes all deliverables** (constitution.md, spec.md, plan.md, code, tests, etc.)
+   - **BOSS does NOT write deliverables** - BOSS only orchestrates
+
+6. **Review work** using `container-use log <env_id>` and `container-use checkout <env_id>`
+
+7. **Merge worker branch** using `mcp_container-use_merge_environment` or git commands
+
+8. **Update `project-config.json`** with worker summary
+
+**BOSS MUST NEVER:**
+- NOT OK Write deliverables directly (constitution.md, spec.md, plan.md, code, tests, etc.)
+- NOT OK Use `environment_file_write` to create deliverables - workers write deliverables
+- NOT OK Use `environment_run_cmd` to execute code that creates deliverables - workers do this
+- NOT OK Read worker prompts and then do the work yourself - spawn the worker instead
+
+**BOSS CAN ONLY use `environment_file_write` for:**
+- OK **Configuring container environment** - Overwrite `.claude/CLAUDE.md` with worker's CLAUDE.md
+- OK **Copying worker config files** - Copy `.boss/workers/[worker-name]/.claude/` files to `.claude/` in container
+- OK This is the ONLY exception - configuring the container, not doing the work
+
+**Communication Guidelines:**
+- **CRITICAL:** Use plain text only when communicating with workers - NO emojis
+- All messages, instructions, prompts, and feedback to workers must be in plain text format
+- When loading worker prompts or sending instructions via Container-Use, use text-only communication
+- Emojis should not be used in any worker-related communication, prompts, or instructions
+

package/dist/assets/claude-md/docs/workflow.md

@@ -0,0 +1,140 @@
+# Branch Management & Workflow
+
+**MANDATORY WORKFLOW FOR EVERY CHANGE:**
+
+1. **Check Project Status**
+   - Read `.boss/project-config.json` to understand current state
+   - Check `initialization.stage` - if not "ready", complete initial setup first
+   - Check `currentBranch` - all work happens on `feature/boss-initial-setup` initially
+
+2. **Create Worker Environment**
+   - Use Container-Use MCP `mcp_container-use_create_environment`
+   - Environment automatically creates branch: `container-use/<env-id>`
+   - Branch is created locally and will be pushed to remote later
+   - Update `project-config.json` with new worker in `workflow.activeWorkers`
+   - **DO NOT check environment status repeatedly** - only check when needed
+
+3. **Configure Container Environment (MANDATORY - BEFORE Spawning Worker)**
+   - **CRITICAL:** This is the ONLY exception where BOSS uses `environment_file_write`
+   - **Purpose:** Configure container with worker-specific context, not BOSS's orchestration context
+   - **Load worker configuration:**
+     - Read `.boss/workers/[worker-name]/prompt.md` to understand worker's role
+     - Read `.boss/workers/[worker-name]/CLAUDE.md` for execution guidelines
+     - Check for worker-specific `.claude` folder: `.boss/workers/[worker-name]/.claude/`
+   - **Overwrite `.claude/CLAUDE.md` in container:**
+     - Read `.boss/workers/[worker-name]/CLAUDE.md` from host
+     - Use `mcp_container-use_environment_file_write` to write to `/workdir/.claude/CLAUDE.md` in container
+     - **CRITICAL PATH:** Host `.boss/workers/architect/CLAUDE.md` → Container `/workdir/.claude/CLAUDE.md`
+     - Container needs worker's instructions, not BOSS's orchestration instructions
+   - **Copy worker-specific `.claude` files to container:**
+     - If `.boss/workers/[worker-name]/.claude/` exists, copy all files maintaining directory structure
+     - **CRITICAL PATH TRANSFORMATION:**
+       - Host: `.boss/workers/architect/.claude/commands/file.md`
+       - Container: `/workdir/.claude/commands/file.md`
+       - Remove `.boss/workers/architect/` prefix, keep `.claude/` structure
+     - Copy all subdirectories:
+       - `.claude/commands/` → `/workdir/.claude/commands/`
+       - `.claude/skills/` → `/workdir/.claude/skills/`
+       - `.claude/agents/` → `/workdir/.claude/agents/`
+       - `.claude/settings*.json` → `/workdir/.claude/settings*.json`
+     - Use `mcp_container-use_environment_file_write` for each file
+   - **Why:** Container's Claude Code reads from `/workdir/.claude/` by convention - we must copy files there
+   - **Why NOT environment variables:** Claude Code reads from `.claude/` folder by convention, cannot be changed
+
+4. **Spawn Worker (MANDATORY - BOSS Never Does Work Directly)**
+   - **CRITICAL:** Use `mcp_container-use_execute_in_environment` to run worker
+   - **BOSS MUST NEVER write deliverables directly** (constitution.md, spec.md, plan.md, code, tests, etc.)
+   - **BOSS MUST NEVER use `environment_file_write` to create deliverables** - workers write all deliverables
+   - **BOSS MUST NEVER use `environment_run_cmd` to execute code that creates deliverables** - workers do this
+   - Worker runs in isolated container with its own branch
+   - Container has worker-specific `.claude/CLAUDE.md` and `.claude/` config files
+   - Worker does ALL the actual work (writes files, runs commands, creates code)
+   - Container-Use manages all git operations automatically
+   - **DO NOT** use git CLI directly
+   - **DO NOT poll worker status** - Container-Use will notify when work completes
+   - **Only check status once** after worker execution completes, not repeatedly
+   
+   **Correct Workflow:**
+   ```
+   1. BOSS creates environment
+   2. BOSS loads worker prompt from .boss/workers/[worker-name]/prompt.md
+   3. BOSS configures container: overwrites .claude/CLAUDE.md and copies .claude/ files
+   4. BOSS calls mcp_container-use_execute_in_environment with task prompt
+   5. WORKER (in container) writes all deliverables
+   6. BOSS reviews and merges
+   ```
+   
+   **WRONG - BOSS Doing Work Directly:**
+   ```
+   1. BOSS creates environment
+   2. BOSS reads worker prompt
+   3. BOSS uses environment_file_write to write deliverables NOT OK WRONG!
+   ```
+
+5. **Review Work (Optional - for user visibility)**
+   - Inform user how to review: `container-use log <env_id>`, `container-use diff <env_id>`, `container-use checkout <env_id>`
+   - **DO NOT wait for approval** - proceed automatically
+
+6. **Merge Worker Changes (AUTOMATIC)**
+   - **AUTOMATICALLY** use `mcp_container-use_merge_environment` to merge worker's branch
+   - Container-Use merges worker's branch into target branch (usually `feature/boss-initial-setup`)
+   - **DO NOT check worker status repeatedly** - only check once after merge completes
+   - Update `project-config.json`:
+     - Remove from `workflow.activeWorkers`
+     - Add summary to `workers.summaries`
+     - Add to `workflow.completedTasks`
+
+7. **Push Branch to Remote (AUTOMATIC)**
+   - **AUTOMATICALLY** push feature branch to remote using git commands
+   - Use: `git push origin <feature-branch-name>` or `git push -u origin <feature-branch-name>`
+   - **NEVER push to main branch directly** - husky pre-push hooks block this (enforced for everyone)
+   - **DO NOT ask user for confirmation** - push automatically
+
+8. **Create Pull Request (AUTOMATIC - MANDATORY - NO EXCEPTIONS)**
+   - **AUTOMATICALLY** use GitHub MCP to create PR from feature branch to main
+   - **CRITICAL:** Main branch is protected - direct pushes are blocked
+   - **DO NOT ask user if they want PR created** - always create it automatically
+   - **DO NOT skip PR creation** - it's mandatory for all changes
+   - Include details about changes, workers used, quality gate results
+   - Link to related specifications or issues
+   - PR title format: "feat: [feature-name] - [brief description]" or "chore: [description]"
+   - PR body should include worker summaries and quality gate status
+
+**CRITICAL RULES:**
+- **MAIN BRANCH PROTECTION:** Main branch is locked - husky pre-push hooks block direct pushes (enforced for everyone, including BOSS and humans)
+- **ALWAYS USE PRs:** All changes to main must go through pull requests
+- **NEVER push to main directly** - always push to feature branch and create PR
+- **BOSS uses git commands** for orchestration: creating branches, pushing code, merging branches
+- Container-Use creates branches locally with naming: `container-use/<env-id>`
+- All worker branches merge into `feature/boss-initial-setup` (or current feature branch)
+- Workers use Container-Use MCP for their git operations (automatic)
+- Always update `project-config.json` to track state changes
+- Each worker environment = isolated branch = isolated work
+- **MINIMIZE STATUS CHECKS:** Only check worker/environment status when necessary, not repeatedly
+
+## Automatic Workflow Completion
+
+**CRITICAL: Complete workflow automatically without user prompts**
+
+After worker completes their work:
+
+1. **Merge automatically** - Use `mcp_container-use_merge_environment` to merge worker branch into feature branch, or use git commands: `git merge <worker-branch>`
+2. **Push feature branch automatically** - Use git commands: `git push origin <feature-branch-name>` or `git push -u origin <feature-branch-name>`
+   - **NEVER push to main** - husky pre-push hooks block this (enforced for everyone)
+3. **Create PR automatically (MANDATORY)** - Use `mcp__github__create_pull_request` to create PR from feature branch to main
+4. **Update project-config.json** - Mark workflow as complete, add PR link, then commit and push: `git add .boss/project-config.json && git commit -m "chore: update project-config.json" && git push`
+
+**DO NOT:**
+- NOT OK Ask user "Should I create a PR?" - **ALWAYS create it automatically**
+- NOT OK Ask user "Ready to create PR?" - **ALWAYS create it automatically**
+- NOT OK Wait for user approval before pushing or creating PR
+- NOT OK Skip PR creation - **PR creation is MANDATORY**
+- NOT OK Push directly to main branch - **main is protected, use PRs only**
+- NOT OK Check worker/environment status repeatedly - only check once when needed
+
+**DO:**
+- OK Complete entire workflow automatically: merge → push feature branch → create PR
+- OK Inform user that PR was created with link: "OK PR created: [link]"
+- OK Include comprehensive PR body with worker summaries and quality gates
+- OK Minimize status checks - only check when necessary for workflow progression
+