@glxmart/boss-cli 1.0.0-beta.0

package/assets/claude-md/docs/github-operations.md

@@ -0,0 +1,238 @@
+# GitHub MCP Operations
+
+**CRITICAL:** 
+- **GitHub MCP is already authenticated and available** - use it directly for GitHub API operations (repositories, PRs, issues, branch protection)
+- Use git commands for local git operations (branches, pushes, merges)
+- **ALWAYS use HTTPS URLs for git remotes:** `https://github.com/<owner>/<repo>.git` (NEVER use SSH `git@github.com` format)
+- **Git authentication:** Git automatically uses `GITHUB_TOKEN` environment variable for HTTPS authentication (set to same value as `GITHUB_PERSONAL_ACCESS_TOKEN` for consistency)
+
+## Organization Selection
+
+**CRITICAL: Use MCP for ALL GitHub Operations**
+
+**When user requests to create repository in an organization:**
+
+1. **Ask user directly for organization name:**
+   - Simply ask: "What is the name of the GitHub organization you want to create the repository in?"
+   - Wait for user to provide the organization name as a string (e.g., "my-org", "company-name")
+   - Store the organization name for use in repository creation and transfer
+
+2. **DO NOT:**
+   - NOT OK List organizations using `search_users` MCP tool with `type:org` - this searches public organizations
+   - NOT OK Use curl to call GitHub API endpoints - use GitHub MCP tools instead
+   - NOT OK Try to enumerate user's organizations - just ask the user directly
+
+3. **Use GitHub MCP for all operations:**
+   - Use GitHub MCP `createRepository` tool to create the repository
+   - Use GitHub MCP transfer tool (if available) to transfer repository to organization
+   - Use GitHub MCP for all repository, branch, and PR operations
+
+## Repository Creation
+
+**CRITICAL: BOSS's Role in Repository Setup**
+
+**BOSS does NOT:**
+- NOT OK Push to main branch (husky pre-push hooks block this - enforced for everyone)
+- NOT OK Create Container-Use environments for repository setup operations
+- NOT OK Use Container-Use MCP for BOSS's own git operations
+
+**BOSS DOES:**
+- OK Use git commands for orchestration: create branches, push code, merge branches, add remotes
+- OK Use GitHub MCP for GitHub API operations: create repositories, create PRs, set branch protection
+
+**BOSS DOES (continued):**
+- OK Use GitHub MCP to check if repository exists (`search_repositories` or similar)
+- OK Use GitHub MCP to create repository if it doesn't exist (`createRepository`)
+- OK Use GitHub MCP to set branch protection (use GitHub MCP tools, or if not available, use `run_terminal_cmd` with curl as fallback)
+- OK Use git commands to add remotes: `git remote add origin https://github.com/<owner>/<repo>.git` (ALWAYS use HTTPS, NEVER SSH)
+- OK Use git commands to push branches: `git push origin <branch-name>` (except main - blocked by hooks)
+- OK **Git authentication:** Git automatically uses `GITHUB_TOKEN` environment variable for HTTPS authentication (set to same value as `GITHUB_PERSONAL_ACCESS_TOKEN` for consistency)
+- OK **GitHub MCP is authenticated:** GitHub MCP server is already up and authenticated - use it directly, no additional setup needed
+- OK Update `.boss/project-config.json` directly with repository information, then commit and push: `git add .boss/project-config.json && git commit -m "chore: update project-config.json" && git push`
+
+**IMPORTANT LIMITATION:** The GitHub MCP `createRepository` tool currently only creates repositories under the authenticated user's personal account, not under organizations. This is a limitation of the GitHub MCP tool itself, not the PAT permissions.
+
+**AUTOMATIC TRANSFER:** When an organization is requested, automatically ask the user if they want to transfer the repository. First try using GitHub MCP transfer tool if available, otherwise fall back to GitHub API.
+
+When creating a GitHub repository:
+
+1. **Ask User for Preferences:**
+   - Should repository be **private** or **public**? (default: private)
+   - Should it be created in an **organization**? (if yes, proceed to step 2)
+   - Repository name (if different from project name)
+
+2. **If Organization Was Requested - Get Organization Name:**
+   - **CRITICAL:** Ask user directly for the organization name as a string
+   - Simply ask: "What is the name of the GitHub organization you want to create the repository in?"
+   - Wait for user to provide the organization name (e.g., "my-org", "company-name")
+   - Store the organization name for use in repository transfer
+   - **DO NOT use `search_users` MCP tool** - this searches public organizations, not the user's organizations
+   - **DO NOT use curl** - use GitHub MCP tools for all operations
+
+3. **Create Repository:**
+   ```typescript
+   // Use GitHub MCP to create repository (GitHub MCP is already authenticated - use it directly)
+   // NOTE: This will create under personal account even if organization is specified
+   const repo = await mcp.github.createRepository({
+     name: "project-name",
+     description: "BOSS project",
+     private: true,  // Ask user, default to private
+     // organization parameter is not supported by GitHub MCP
+   });
+   ```
+   **After creating repository, use HTTPS URL for git remote:**
+   - Repository URL format: `https://github.com/<owner>/<repo>.git`
+   - Add remote: `git remote add origin https://github.com/<owner>/<repo>.git` (NEVER use SSH `git@github.com` format)
+   - Git will automatically use `GITHUB_TOKEN` environment variable for authentication (set to same value as `GITHUB_PERSONAL_ACCESS_TOKEN` for consistency)
+
+4. **If Organization Was Selected - Automatic Transfer:**
+   - Inform the user: "Repository created under your personal account. Would you like me to transfer it to [org-name] now?"
+   - If user confirms:
+     - Transfer the repository (see "Repository Transfer" section below for complete instructions)
+     - First try GitHub MCP transfer tool if available
+     - If MCP tool not available, use `run_terminal_cmd` to execute curl command
+     - Verify response status is `202 Accepted`
+     - Wait for transfer to complete (poll status if needed, or wait a few seconds)
+     - **Verify dependencies are installed** - `start-boss.sh` already runs `pnpm install` automatically, so just verify `node_modules` exists (do NOT run install again)
+     - Update git remote URL using HTTPS: `git remote set-url origin https://github.com/<new-owner>/<repo>.git` (NEVER use SSH format)
+     - Update `project-config.json` with transferred repository info
+
+5. **Update project-config.json:**
+   - Set `repository.remote = "origin"`
+   - Set `repository.url` (use org URL if transferred, personal URL if not)
+   - Set `repository.owner` (org name if transferred, personal account if not)
+   - Set `repository.name`, `private`
+   - Set `repository.organization` to the org name (even if not yet transferred)
+   - Set `initialization.remoteCreated = true`
+
+## Repository Transfer
+
+**OFFICIAL INSTRUCTIONS:** Transfer repositories using GitHub MCP if available, otherwise fall back to GitHub REST API.
+
+**Official Documentation:** https://docs.github.com/en/rest/repos/repos#transfer-a-repository
+
+**Method 1: Try GitHub MCP First (Preferred)**
+
+Check if GitHub MCP provides a `transfer_repository` or similar tool. If available, use it:
+
+```typescript
+// Try GitHub MCP transfer tool if available
+try {
+  const result = await mcp.github.transferRepository({
+    owner: currentOwner,
+    repo: repoName,
+    new_owner: targetOrgName,
+    // Optional: team_ids, new_name
+  });
+  // Transfer successful via MCP
+} catch (error) {
+  // MCP tool not available, fall back to API method
+}
+```
+
+**Method 2: Fallback to GitHub REST API (If MCP Not Available)**
+
+If GitHub MCP doesn't have a transfer tool, use direct HTTP requests via `run_terminal_cmd`.
+
+**Endpoint:** `POST /repos/{owner}/{repo}/transfer`
+
+**Request Headers:**
+- `Authorization: Bearer {GITHUB_PERSONAL_ACCESS_TOKEN}`
+- `Accept: application/vnd.github.v3+json`
+
+**Request Body:**
+```json
+{
+  "new_owner": "new_owner_username_or_org",
+  "team_ids": [1234567, 2345678],  // Optional: array of team IDs (for org transfers)
+  "new_name": "new_repository_name"  // Optional: rename during transfer
+}
+```
+
+**Response:** `202 Accepted` - Transfer initiated successfully
+
+**Using run_terminal_cmd with curl (Fallback if MCP not available):**
+```bash
+curl -X POST \
+  -H "Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN" \
+  -H "Accept: application/vnd.github.v3+json" \
+  -H "Content-Type: application/json" \
+  https://api.github.com/repos/{current-owner}/{repo-name}/transfer \
+  -d "{\"new_owner\": \"{target-org}\"}"
+```
+
+**Critical Requirements:**
+- OK **Administrative access required** - You must have admin access to the repository being transferred
+- OK **Organization permissions** - If transferring to an organization, you must have permission to create repositories in that organization
+- OK **Acceptance window** - The new owner has 24 hours to accept the transfer, otherwise it expires
+- OK **Update git remote** - After successful transfer, update the git remote URL using Container-Use MCP
+- OK **Update project-config.json** - Update repository owner, URL, and organization fields
+
+**Post-Transfer Steps:**
+1. Wait for transfer to complete (poll repository status or wait a few seconds)
+2. **CRITICAL: Verify dependencies are installed** - Before creating Container-Use environments, ensure `node_modules` exists:
+   - **NOTE:** `start-boss.sh` already runs `pnpm install` (or `npm install`) automatically before launching Claude
+   - **DO NOT run `pnpm install` again** - dependencies should already be installed
+   - Only verify `node_modules` directory exists (if missing, that's unexpected)
+   - This prevents pre-push hook failures due to missing dependencies
+3. Update git remote URL in Container-Use environment
+4. Verify remote was updated correctly
+5. Update `project-config.json` with new owner and URL
+
+## Branch Operations
+
+- **Create branches:** BOSS uses git commands: `git checkout -b <branch-name>` or Container-Use MCP for worker branches (creates environment = branch)
+- **Push branches:** BOSS uses git commands: `git push origin <branch-name>` (except main - blocked by husky hooks)
+  - **Git authentication:** Git automatically uses `GITHUB_TOKEN` environment variable for HTTPS authentication (set to same value as `GITHUB_PERSONAL_ACCESS_TOKEN` for consistency)
+  - **ALWAYS use HTTPS remotes:** Ensure remote URL is `https://github.com/<owner>/<repo>.git` (NEVER SSH format)
+- **List branches:** Use GitHub MCP for remote branch info, or git commands for local branches: `git branch` or `git branch -a`
+
+## Branch Protection
+
+**CRITICAL: MAIN BRANCH IS PROTECTED - PRs REQUIRED**
+
+- **Main branch is locked during initial setup** - direct pushes are blocked
+- **ALL changes to main must go through pull requests** - no exceptions
+- Branch protection is set up automatically during initial setup with:
+  - Required pull request reviews before merging
+  - Required status checks to pass
+  - Required branches to be up to date
+  - Force pushes disabled
+  - Branch deletions disabled
+
+**NEVER:**
+- NOT OK Push directly to main branch
+- NOT OK Bypass PR requirement
+- NOT OK Skip PR creation
+
+**ALWAYS:**
+- OK Push to feature branch (`feature/boss-initial-setup` or `feature/*`)
+- OK Create PR from feature branch to main
+- OK Use PRs for all changes to main
+
+## Pull Requests
+
+**CRITICAL: AUTOMATIC PR CREATION - NO USER PROMPTS - MANDATORY**
+
+- **ALWAYS** create PRs automatically - **NEVER ask user if they want a PR created**
+- **MANDATORY:** After merging worker changes and pushing to remote, **IMMEDIATELY** create PR using GitHub MCP
+- **Main branch protection requires PRs** - direct pushes will fail
+- Use GitHub MCP `mcp__github__create_pull_request` to create PR from feature branch to main
+- Include worker summaries, quality gate results, and related specs/issues in PR body
+- Link to container-use environments for review
+- PR title format: `feat: [feature-name] - [brief description]` or `chore: [description]`
+- **DO NOT wait for user confirmation** - create PR automatically as part of workflow completion
+- **DO NOT skip PR creation** - it's mandatory for all changes to main
+
+## GitHub Repository Requirements
+
+**CRITICAL: Repository Privacy Policy**
+
+- **Default to PRIVATE repositories** - Ask user for preference
+- When using GitHub MCP to create repositories, ask user:
+  - Should it be private or public? (default: private)
+  - Should it be in an organization? (if yes, which org?)
+- This applies to:
+  - Initial repository creation during setup
+  - Any new repositories created for projects, features, or sub-projects
+

package/assets/claude-md/docs/initialization.md

@@ -0,0 +1,186 @@
+# Initial Setup Workflow
+
+**CRITICAL: AUTOMATIC INITIALIZATION CHECK ON STARTUP**
+
+**When BOSS starts (via `./start-boss.sh`), you MUST automatically:**
+
+1. **Check Initialization Status (AUTOMATIC - DO THIS FIRST)**
+   - Read `.boss/project-config.json` immediately on startup
+   - Check `initialization.stage` to determine what needs to be done
+   - **If `initialization.stage !== "ready"`, automatically complete initial setup without asking user**
+   - **DO NOT wait for user to ask** - check and complete setup automatically
+
+2. **Verify Bootstrap State**
+   - **CRITICAL:** Main branch should be EMPTY (only empty commit) - bootstrap files are NOT on main
+   - **CRITICAL:** Feature branch `feature/boss-initial-setup` should already exist with ALL bootstrap files (created during bootstrap)
+   - **CRITICAL: Verify dependencies are installed** - Before creating Container-Use environments:
+     - **NOTE:** `start-boss.sh` already runs `pnpm install` (or `npm install`) automatically before launching Claude
+     - **DO NOT run `pnpm install` again** - dependencies should already be installed
+     - Only verify `node_modules` directory exists (if missing, that's unexpected - `start-boss.sh` should have installed them)
+     - This prevents pre-push/pre-commit hook failures due to missing dependencies (e.g., `tsc` not found)
+   - If feature branch doesn't exist, create it from main
+   - Switch to this branch using Container-Use MCP (create environment on this branch)
+   - Update `project-config.json` with `currentBranch: "feature/boss-initial-setup"`
+
+3. **Run Initial Setup Checklist**
+   - **CRITICAL:** BOSS handles initialization directly using GitHub MCP - do NOT spawn workers for this
+   - Checklist includes:
+     - [ ] Check if remote repository exists using GitHub MCP `search_repositories` tool
+     - [ ] If no remote, ask user:
+       - Should repository be private or public? (default: private)
+       - Should it be created in an organization? (if yes, proceed to list orgs)
+       - Repository name (if different from project name)
+     - [ ] If organization was requested:
+       - [ ] **CRITICAL:** Ask user directly for the organization name as a string
+       - [ ] Simply ask: "What is the name of the GitHub organization you want to create the repository in?"
+       - [ ] Wait for user to provide the organization name (e.g., "my-org", "company-name")
+       - [ ] Store the organization name for use in repository transfer
+       - [ ] **DO NOT use `search_users` MCP tool** - this searches public organizations
+       - [ ] **DO NOT use curl** - use GitHub MCP tools for all operations
+     - [ ] Create GitHub repository using GitHub MCP
+     - [ ] **CRITICAL: Lock main branch and require PRs** - Use GitHub MCP to set branch protection:
+       - First, try to use GitHub MCP tools for branch protection (if available)
+       - If GitHub MCP doesn't have a branch protection tool, use `run_terminal_cmd` with curl as fallback:
+         - Make HTTP PUT request to: `https://api.github.com/repos/{owner}/{repo}/branches/main/protection`
+         - Headers: `Authorization: Bearer {GITHUB_PERSONAL_ACCESS_TOKEN}`, `Accept: application/vnd.github.v3+json` (use GITHUB_PERSONAL_ACCESS_TOKEN, not GITHUB_TOKEN, for API calls)
+         - Body:
+           ```json
+           {
+             "required_pull_request_reviews": {
+               "required": true,
+               "dismiss_stale_reviews": true,
+               "require_code_owner_reviews": false,
+               "required_approving_review_count": 1
+             },
+             "enforce_admins": true,
+             "required_status_checks": {
+               "strict": true,
+               "contexts": []
+             },
+             "restrictions": null,
+             "allow_force_pushes": false,
+             "allow_deletions": false,
+             "required_linear_history": false,
+             "allow_squash_merge": true,
+             "allow_merge_commit": true,
+             "allow_rebase_merge": true
+           }
+           ```
+       - Verify protection was set: Check response status is 200
+     - [ ] **CRITICAL ORDER - Follow EXACTLY:**
+       1. **Add remote using HTTPS:** `git remote add origin https://github.com/<owner>/<repo>.git` (ALWAYS use HTTPS format, NEVER SSH `git@github.com` format)
+       2. **Check current branch:** `git branch --show-current` - verify you're on the correct branch
+       3. **Handle uncommitted changes:** If on `feature/boss-initial-setup` with uncommitted changes, commit them first: `git add . && git commit -m "chore: bootstrap files"` (these should be on feature branch)
+       4. **Switch to main branch:** `git checkout main` (if uncommitted changes prevent checkout, commit them to current branch first, then switch)
+       5. **FIRST push empty main branch:** `git push -u origin main` (main is EMPTY - only empty commit, no validation needed, git will use GITHUB_TOKEN automatically, which is set to same value as GITHUB_PERSONAL_ACCESS_TOKEN)
+          - **NOTE:** The pre-push hook allows empty main push without validation checks
+          - **Main branch must be pushed first (empty) before feature branch**
+       6. **Switch back to feature branch:** `git checkout feature/boss-initial-setup` (branch should already exist from bootstrap)
+       7. **Verify validation checks pass BEFORE pushing feature branch:**
+          - **BEFORE pushing feature branch, verify all checks pass:**
+            1. **Typecheck:** Run `pnpm typecheck` (or `npm run typecheck`) - must pass
+            2. **Lint:** Run `pnpm lint` (or `npm run lint`) - must pass
+            3. **Security:** Run `bash scripts/security-check.sh` - must pass
+            4. **Tests:** Run `pnpm test:unit` (or `npm run test:unit`) - must pass
+          - **If any check fails, fix the issues before pushing**
+       8. **THEN push feature branch:** `git push -u origin feature/boss-initial-setup` (contains all bootstrap files, git will use GITHUB_TOKEN automatically, which is set to same value as GITHUB_PERSONAL_ACCESS_TOKEN)
+       9. **Update `.boss/project-config.json`** with repository information:
+          - Set `repository.remote = "origin"`
+          - Set `repository.url = "https://github.com/{owner}/{repo}"`
+          - Set `repository.owner`, `repository.name`, `repository.private`
+          - Set `initialization.remoteCreated = true`
+       10. **Commit and push project-config.json:** `git add .boss/project-config.json && git commit -m "chore: update project-config.json" && git push`
+       11. **Mark `initialization.stage = "ready"`** in `project-config.json`
+       12. **Commit and push again:** `git add .boss/project-config.json && git commit -m "chore: mark initialization as ready" && git push`
+       13. **FINAL STEP - Create PR from feature/boss-initial-setup to main:** Use GitHub MCP `create_pull_request` with:
+          - **Title:** `"chore: BOSS initial setup - bootstrap files"`
+          - **Body:** `"This PR contains all BOSS bootstrap files and initial project structure. Ready for review and merge."`
+          - **Base branch:** `"main"`
+          - **Head branch:** `"feature/boss-initial-setup"`
+          - **DO NOT ask user** - create PR automatically
+     - [ ] **DO NOT create Container-Use environments for initialization** - BOSS handles this via git commands
+     - [ ] **NEVER push feature branch before main branch** - main must be pushed first
+     - [ ] **After initial setup, NEVER push directly to main** - always use PRs
+
+4. **After Initial Setup**
+   - All BOSS and worker work happens on `feature/boss-initial-setup` branch
+   - Workers spawn from this branch
+   - **AUTOMATICALLY** create PR from `feature/boss-initial-setup` to `main` when work is complete
+   - **DO NOT ask user** - always create PR automatically after pushing changes
+
+## Pre-Push Hook Behavior During Initialization
+
+**CRITICAL UNDERSTANDING:** The pre-push hook (`.husky/pre-push`) has special behavior for the first push to main:
+
+1. **First Push Detection:** The hook checks if remote main branch exists using `git ls-remote --heads origin main`
+2. **Empty Main Allowed:** If remote main doesn't exist AND main branch is empty (only empty commit or minimal files), the hook allows the push WITHOUT validation checks
+3. **Non-Empty Main:** If main branch contains files, validation checks will run even for first push
+4. **Feature Branch Validation:** All validation checks run normally for feature branch pushes:
+   - TypeScript typecheck (`pnpm typecheck`)
+   - Linting (`pnpm lint`)
+   - Security checks (`bash scripts/security-check.sh`)
+   - Unit tests (`pnpm test:unit`)
+   - Test file presence check (blocks non-interactive pushes if no test files exist)
+5. **After First Push:** Once main branch exists remotely, all future pushes to main are blocked (must use feature branches and PRs)
+
+**IMPORTANT:** Before pushing main branch during initialization:
+- **ALWAYS verify all validation checks pass first**
+- Run the checks manually: `pnpm typecheck && pnpm lint && bash scripts/security-check.sh && pnpm test:unit`
+- Fix any failures before attempting to push
+- The bootstrap process should have created passing code, but verify before pushing
+
+## Project Config Structure
+
+**CRITICAL:** Always check `.boss/project-config.json` for project status, initialization stages, and current state. This file is the single source of truth for:
+- Initialization status (bootstrap, remote setup, initial setup completion)
+- Current branch and workflow stage
+- Remote repository information
+- Worker activity summaries
+- Project metadata
+
+**DO NOT** use git commands to determine project status. Read `.boss/project-config.json` instead.
+
+**Project Config Structure:**
+```json
+{
+  "initialization": {
+    "stage": "bootstrap",  // Values: "bootstrap" | "remote-setup" | "initial-setup" | "ready"
+    "bootstrapComplete": true,
+    "remoteCreated": false,
+    "initialSetupComplete": false
+  },
+  "repository": {
+    "remote": "origin",  // Values: "origin" or null
+    "url": "https://github.com/owner/repo",  // string or null
+    "owner": "username",  // string or null
+    "name": "project-name",  // string or null
+    "private": true,  // boolean or null
+    "organization": "org-name"  // string or null
+  },
+  "currentBranch": "feature/boss-initial-setup",
+  "workflow": {
+    "stage": "initialization",  // current workflow stage
+    "activeWorkers": [],
+    "completedTasks": []
+  },
+  "workers": {
+    "summaries": []
+  }
+}
+```
+
+**When to Update project-config.json:**
+- After completing initialization steps
+- When spawning/merging workers
+- When creating/updating remote repository
+- When changing branches or workflow stages
+- After any significant project state change
+
+**CRITICAL: After ANY change to project-config.json, you MUST:**
+1. **Immediately commit the change:** `git add .boss/project-config.json && git commit -m "chore: update project-config.json"`
+2. **Immediately push the change:** `git push` (or `git push origin <branch-name>` if not tracking)
+3. **DO NOT wait** - do this automatically without asking for confirmation
+4. **DO NOT leave project-config.json changes uncommitted** - always commit and push immediately after modification
+
+This ensures project state is always persisted and synchronized with the remote repository.
+

package/assets/claude-md/docs/quality-standards.md

@@ -0,0 +1,15 @@
+# Quality Standards
+
+- **Test-First (NON-NEGOTIABLE)** - TDD cycle: red → green → refactor
+- **BDD (Mandatory)** - Behavior-Driven Development with Given/When/Then
+- **Feature Documentation (NON-NEGOTIABLE)** - Every feature must be documented
+- **Coverage:** Coverage thresholds are defined in `.boss/config.yaml` and enforced by quality gates
+- **Mutation Testing:** Mutation testing thresholds are defined in `.boss/config.yaml` and enforced by quality gates
+
+Quality gates are configured based on the quality preset selected during bootstrap:
+- **Startup:** Coverage ≥60%
+- **Production:** Coverage ≥80%, Mutation ≥80%
+- **Enterprise:** Coverage ≥90%, Mutation ≥80%
+
+See `.boss/config.yaml` for the exact thresholds configured for this project.
+

package/assets/claude-md/docs/spec-kit.md

@@ -0,0 +1,46 @@
+# Spec-Kit Commands
+
+**Spec-Kit is the foundation of our development methodology.** Workers use Spec-Kit commands throughout the development lifecycle. BOSS should understand these commands to coordinate workers effectively.
+
+## Available Spec-Kit Commands
+
+- **`/speckit.constitution`** - Create or update project constitution (used by `architect`)
+- **`/speckit.clarify`** - Identify underspecified areas and ask targeted clarification questions (used by `clarifier` and `product-owner`)
+- **`/speckit.specify`** - Create or update feature specifications (used by `spec-writer`)
+- **`/speckit.plan`** - Generate technical implementation plans (used by `planner`)
+- **`/speckit.tasks`** - Break down plans into actionable tasks with [P] parallel markers (used by `planner`)
+- **`/speckit.implement`** - Execute implementation following task breakdown (used by `developer-*` workers)
+- **`/speckit.checklist`** - Generate requirement quality checklists (used by `spec-writer`, `tester`, `security-engineer`, `technical-writer`)
+- **`/speckit.analyze`** - Run project consistency analysis (used by `reviewer`, `code-reviewer`, `consolidator`)
+
+## Spec-Kit Structure
+
+- **Templates**: `.specify/templates/` - Template files for specs, plans, tasks, checklists
+- **Scripts**: `.specify/scripts/` - Executable scripts for Spec-Kit commands
+- **Memory**: `.specify/memory/constitution.md` - Governing principles (NON-NEGOTIABLE)
+- **Specs**: `.specify/specs/[feature-name]/` - Feature specifications, plans, tasks, checklists
+
+## When Workers Use Spec-Kit Commands
+
+- **Phase 1 (Constitution)**: `architect` uses `/speckit.constitution` or follows constitution template
+- **Phase 2 (Clarification)**: `clarifier` uses `/speckit.clarify` to identify ambiguities
+- **Phase 3 (Specification)**: `spec-writer` uses `/speckit.specify` and `/speckit.checklist`
+- **Phase 4 (Planning)**: `planner` uses `/speckit.plan` to generate technical plans
+- **Phase 6 (Task Breakdown)**: `planner` uses `/speckit.tasks` to create task breakdown
+- **Phase 7 (Implementation)**: `developer-*` workers use `/speckit.implement` or follow TDD manually
+- **Phase 5 & 7 (Validation/Review)**: `reviewer` and `code-reviewer` use `/speckit.analyze`
+- **Cross-Phase**: `tester`, `security-engineer`, `technical-writer` use `/speckit.checklist` as needed
+
+## BOSS Methodology
+
+This project uses Spec-Kit for specification-driven development with the following phases:
+
+1. **Constitution** - Governing principles (NON-NEGOTIABLE)
+2. **Clarification** - Business requirements gathering
+3. **Specification** - User stories in Given/When/Then format
+4. **Planning** - Technical approach and architecture
+5. **Validation** - Constitution compliance check
+6. **Task Breakdown** - Granular tasks with [P] parallel markers
+7. **Implementation** - TDD + BDD with feature documentation
+8. **Consolidation** - Integration and delivery artifacts
+