create-claude-workspace 2.1.10 → 2.2.0

package/dist/scheduler/tasks/issue-source.spec.js

@@ -0,0 +1,104 @@
+import { describe, it, expect } from 'vitest';
+import { issueToTask } from './issue-source.mjs';
+// fetchOpenIssues and updateIssueStatus require CLI (gh/glab) and a remote.
+// They are tested via integration tests. Here we test the pure mapping logic.
+function makeIssue(overrides = {}) {
+    return {
+        issueNumber: 42,
+        title: 'Add user auth endpoint',
+        body: '',
+        labels: ['complexity::M', 'type::backend', 'status::todo'],
+        milestone: 'Phase 1: Core Features',
+        assignee: null,
+        ...overrides,
+    };
+}
+describe('issueToTask', () => {
+    it('maps labels to task fields', () => {
+        const task = issueToTask(makeIssue(), 0);
+        expect(task.id).toBe('#42');
+        expect(task.title).toBe('Add user auth endpoint');
+        expect(task.complexity).toBe('M');
+        expect(task.type).toBe('backend');
+        expect(task.status).toBe('todo');
+        expect(task.phase).toBe(1);
+        expect(task.issueMarker).toBe('#42');
+    });
+    it('extracts phase from milestone name', () => {
+        const task = issueToTask(makeIssue({ milestone: 'Phase 2: Advanced Features' }), 0);
+        expect(task.phase).toBe(2);
+    });
+    it('uses fallback phase when no milestone', () => {
+        const task = issueToTask(makeIssue({ milestone: null }), 3);
+        expect(task.phase).toBe(3);
+    });
+    it('defaults complexity to M when missing', () => {
+        const task = issueToTask(makeIssue({ labels: ['status::todo'] }), 0);
+        expect(task.complexity).toBe('M');
+    });
+    it('defaults type to fullstack when missing', () => {
+        const task = issueToTask(makeIssue({ labels: ['status::todo'] }), 0);
+        expect(task.type).toBe('fullstack');
+    });
+    it('extracts dependencies from body', () => {
+        const task = issueToTask(makeIssue({ body: 'Depends on: #42, #43' }), 0);
+        expect(task.dependsOn).toContain('#42');
+        expect(task.dependsOn).toContain('#43');
+    });
+    it('extracts dependencies from labels', () => {
+        const task = issueToTask(makeIssue({ labels: ['status::todo', 'depends-on::#42'] }), 0);
+        expect(task.dependsOn).toContain('#42');
+    });
+    it('maps status labels correctly', () => {
+        const cases = [
+            ['status::done', 'done'],
+            ['status::skipped', 'skipped'],
+            ['status::blocked', 'blocked'],
+            ['status::in-progress', 'in-progress'],
+            ['status::in-review', 'in-progress'],
+            ['status::todo', 'todo'],
+        ];
+        for (const [label, expected] of cases) {
+            const task = issueToTask(makeIssue({ labels: [label] }), 0);
+            expect(task.status).toBe(expected);
+        }
+    });
+    it('defaults to todo when no status label', () => {
+        const task = issueToTask(makeIssue({ labels: ['bug'] }), 0);
+        expect(task.status).toBe('todo');
+    });
+    it('detects kit-upgrade label', () => {
+        const task = issueToTask(makeIssue({ labels: ['status::todo', 'kit-upgrade'] }), 0);
+        expect(task.kitUpgrade).toBe(true);
+    });
+    it('infers changelog category from title', () => {
+        expect(issueToTask(makeIssue({ title: 'Fix login bug' }), 0).changelog).toBe('fixed');
+        expect(issueToTask(makeIssue({ title: 'Add dark mode' }), 0).changelog).toBe('added');
+        expect(issueToTask(makeIssue({ title: 'Refactor auth service' }), 0).changelog).toBe('changed');
+        expect(issueToTask(makeIssue({ title: 'Implement search' }), 0).changelog).toBe('added');
+    });
+    it('handles S and L complexity', () => {
+        expect(issueToTask(makeIssue({ labels: ['complexity::S', 'status::todo'] }), 0).complexity).toBe('S');
+        expect(issueToTask(makeIssue({ labels: ['complexity::L', 'status::todo'] }), 0).complexity).toBe('L');
+    });
+    it('handles frontend and fullstack type', () => {
+        expect(issueToTask(makeIssue({ labels: ['type::frontend', 'status::todo'] }), 0).type).toBe('frontend');
+        expect(issueToTask(makeIssue({ labels: ['type::fullstack', 'status::todo'] }), 0).type).toBe('fullstack');
+    });
+    it('lineNumber is always 0 for platform issues', () => {
+        const task = issueToTask(makeIssue(), 0);
+        expect(task.lineNumber).toBe(0);
+    });
+    it('handles Phase 0 milestone', () => {
+        const task = issueToTask(makeIssue({ milestone: 'Phase 0: Foundation' }), 5);
+        expect(task.phase).toBe(0);
+    });
+    it('deduplicates dependencies from body and labels', () => {
+        const task = issueToTask(makeIssue({
+            body: 'Depends on: #42',
+            labels: ['status::todo', 'depends-on::#42'],
+        }), 0);
+        const deps42 = task.dependsOn.filter(d => d === '#42');
+        expect(deps42.length).toBe(1);
+    });
+});

package/dist/scheduler/types.mjs

@@ -17,4 +17,5 @@ export const SCHEDULER_DEFAULTS = {
     interactive: false,
     delay: 5_000,
     cooldown: 60_000,
+    taskMode: null,
 };

package/dist/scheduler/util/idle-poll.mjs

@@ -4,6 +4,8 @@
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { execSync } from 'node:child_process';
+import { fetchOpenIssues } from '../tasks/issue-source.mjs';
+import { detectCIPlatform } from '../git/ci-watcher.mjs';
 // ─── TODO.md check (filesystem, free) ───
 export function checkTodoForPendingTasks(projectDir) {
     try {
@@ -140,6 +142,25 @@ async function pollClickUp(spaceId, token, projectDir) {
     }
     return newCount;
 }
+// ─── Platform mode polling (issues via CLI) ───
+async function pollPlatformIssues(projectDir, log, completedTasks) {
+    const ciPlatform = detectCIPlatform(projectDir);
+    if (ciPlatform === 'none')
+        return { hasWork: false, source: null, issueCount: 0 };
+    try {
+        const issues = fetchOpenIssues(projectDir, ciPlatform);
+        const todoIssues = issues.filter(i => i.labels.some(l => l === 'status::todo') &&
+            !completedTasks.includes(`#${i.issueNumber}`));
+        if (todoIssues.length > 0) {
+            log.info(`Found ${todoIssues.length} issue(s) with status::todo`);
+            return { hasWork: true, source: ciPlatform, issueCount: todoIssues.length };
+        }
+    }
+    catch (err) {
+        log.debug(`Platform poll failed: ${err.message}`);
+    }
+    return { hasWork: false, source: null, issueCount: 0 };
+}
 function readTodoSafe(projectDir) {
     try {
         return readFileSync(resolve(projectDir, 'TODO.md'), 'utf-8');
@@ -149,8 +170,12 @@ function readTodoSafe(projectDir) {
     }
 }
 // ─── Main poll function ───
-export async function pollForNewWork(projectDir, log) {
-    // 1. Check TODO.md first (free, instant)
+export async function pollForNewWork(projectDir, log, taskMode = 'local', completedTasks = []) {
+    // Platform mode: check issues directly via CLI
+    if (taskMode === 'platform') {
+        return pollPlatformIssues(projectDir, log, completedTasks);
+    }
+    // Local mode: check TODO.md first (free, instant)
     if (checkTodoForPendingTasks(projectDir)) {
         return { hasWork: true, source: 'todo', issueCount: 0 };
     }

package/dist/template/.claude/CLAUDE.md

@@ -1,70 +1,35 @@
 # Agent-Driven Development Kit
 
-**You are a ROUTER, not an implementer.** This project uses specialist agents. Your ONLY job is to delegate to them.
+This project uses specialist agents in `.claude/agents/` for autonomous development.
 
-## The One Rule
+## How to Run
 
-**NEVER do work yourself. ALWAYS delegate via the Agent tool.**
-
-- NEVER write CLAUDE.md, PRODUCT.md, TODO.md, MEMORY.md, or any project files yourself
-- NEVER run `nx generate`, `gh`/`glab` commands, or scaffold anything yourself
-- NEVER read `.claude/agents/*.md` files to understand their instructions — call the agent instead. Checking file existence (`ls .claude/agents/`) is fine.
-
-### WRONG (doing it yourself):
-```
-User: "Initialize this project"
-You: *reads plan files, writes CLAUDE.md, creates PRODUCT.md, runs git commands...*
-```
-
-### CORRECT (delegating):
-```
-User: "Initialize this project"
-You: "I'll delegate this to the project-initializer agent."
-→ Agent tool: subagent_type="project-initializer"
-```
-
-## Which Agent to Call
-
-**Setup tasks** → `project-initializer` (it sub-delegates to other agents internally):
-- "Initialize this project", "Set up CLAUDE.md", "Start a new project"
-
-**Development tasks** → `orchestrator` (it sub-delegates to architects, reviewers, etc.):
-- "Continue development", "Next task", "Build the next feature"
-
-**Specific tasks** (only if explicitly asked for one agent's specialty):
-| Task | Agent | `subagent_type` | `model` |
-|------|-------|-----------------|---------|
-| Product strategy / PRODUCT.md | product-owner | `"product-owner"` | `"opus"` |
-| Development plan / TODO.md | technical-planner | `"technical-planner"` | `"opus"` |
-| Deployment / CI/CD | deployment-engineer | `"deployment-engineer"` | `"sonnet"` |
-| Git remote / issues / MRs / ClickUp | devops-integrator | `"devops-integrator"` | `"sonnet"` |
-| Code review | senior-code-reviewer | `"senior-code-reviewer"` | `"opus"` |
-| Tests | test-engineer | `"test-engineer"` | `"sonnet"` |
-| Frontend / UI | ui-engineer | `"ui-engineer"` | `"opus"` |
-| Backend / API | backend-ts-architect | `"backend-ts-architect"` | `"opus"` |
-
-> **Always pass the `model` parameter** when calling the Agent tool — it selects the Claude model for the sub-agent.
-
-> **Note:** Specialist agents are typically called via sub-delegation by `project-initializer` or `orchestrator`. Only call them directly if the user explicitly asks for one agent's specialty.
-
-**When unsure** → `project-initializer` for setup, `orchestrator` for everything else.
-
-## Autonomous Development
-
-**Important:** The orchestrator MUST run as a top-level agent (not a sub-agent) so it can delegate to specialist agents via the Agent tool. Sub-agents cannot spawn further sub-agents.
-
-```powershell
-# Docker — isolated, safe (recommended)
-npx create-claude-workspace docker        # all platforms
-
-# Without Docker (uses --agent orchestrator automatically)
+```bash
+# Autonomous (recommended)
 npx create-claude-workspace run
 
-# Update kit (agents, templates) to latest version
-npx create-claude-workspace --update
+# Docker — isolated environment
+npx create-claude-workspace docker
 
-# Interactive — start Claude with orchestrator as top-level agent
+# Interactive
 claude --agent orchestrator
-# Then use ralph-loop within that session:
-/ralph-loop:ralph-loop Continue autonomous development according to CLAUDE.md
+
+# Update kit to latest version
+npx create-claude-workspace --update
 ```
+
+## Agents
+
+| Agent | Purpose | Model |
+|-------|---------|-------|
+| orchestrator | Development cycle (pick task → plan → implement → test → review → commit → merge) | opus |
+| project-initializer | Full project setup pipeline (discovery → CLAUDE.md → PRODUCT.md → TODO.md) | opus |
+| product-owner | Product strategy, features, monetization → PRODUCT.md | opus |
+| technical-planner | Phased development plan → TODO.md | opus |
+| ui-engineer | Frontend architecture and implementation | opus |
+| backend-ts-architect | Backend architecture and implementation | opus |
+| senior-code-reviewer | Structured code review (CRITICAL/WARN/NICE-TO-HAVE/GREEN) | opus |
+| test-engineer | Unit, integration, E2E, and visual regression tests | sonnet |
+| devops-integrator | Git platform sync (GitHub/GitLab/ClickUp), branches, MRs/PRs | sonnet |
+| deployment-engineer | CI/CD pipelines, deploys, rollbacks, migrations | sonnet |
+| it-analyst | Technical analyst, breaks features into detailed platform issues | sonnet |

package/dist/template/.claude/agents/backend-ts-architect.md

@@ -104,7 +104,7 @@ Always prefer `@cibule/*` packages over custom implementations:
 
 ## Output Format
 
-When called for **planning** (STEP 2 of the development cycle), always structure your response as:
+When called for **planning**, always structure your response as:
 
 ### EXISTING CODE
 What already exists in the codebase that is relevant — reusable utilities, similar patterns, shared abstractions. Reference specific file paths.
@@ -167,7 +167,7 @@ If the orchestrator re-delegates with frontend architect feedback about impracti
 Keep all other plan sections unchanged unless the revision affects them.
 
 ### SPLIT RECOMMENDATION (optional)
-If the task is too large for a single development cycle (would require 8+ files or multiple independent concerns), recommend splitting. List the suggested sub-tasks with their own scope and dependencies. The orchestrator will delegate to technical-planner to update TODO.md.
+If the task is too large (would require 8+ files or multiple independent concerns), recommend splitting. List the suggested sub-tasks with their own scope and dependencies.
 Only include this section if splitting is genuinely needed — do NOT split tasks that are naturally cohesive.
 
 ### VERIFICATION

package/dist/template/.claude/agents/deployment-engineer.md

@@ -324,9 +324,9 @@ After generating configs, append a `## Deployment` section to CLAUDE.md:
 - Smoke test: Playwright runs against deployed URL
 ```
 
-### 4. Deploy (called during development cycle)
+### 4. Deploy
 
-When called to deploy (after MR/PR merge or for hotfix):
+When called to deploy:
 
 1. **Verify build passes** — `nx build [APP] --configuration=[env]`
 2. **Run deployment** — execute the appropriate deploy command for the target
@@ -383,7 +383,7 @@ After rollback:
 
 ### 6. Database Migrations — Dev-Time Generation
 
-When called by the orchestrator during development (STEP 3) to generate a migration file:
+When called to generate a migration file:
 
 1. **Read context**: Check CLAUDE.md for database type (D1, SQLite, Postgres, etc.)
 2. **Check existing migrations**: List files in `migrations/` directory, find the latest sequence number

package/dist/template/.claude/agents/devops-integrator.md

@@ -4,6 +4,8 @@ description: "Use this agent to sync project planning with GitLab/GitHub/ClickUp
 model: sonnet
 ---
 
+> **Note:** In platform mode (scheduler), the scheduler handles daily issue/MR CRUD. This agent is used for initial setup and complex fallback operations only.
+
 You are a DevOps Integration agent that bridges project planning (TODO.md, PRODUCT.md) with git platforms (GitLab or GitHub) and task management platforms (ClickUp). You create and manage epics, issues/tasks, branches, and merge requests.
 
 ## Platform Detection
@@ -178,7 +180,7 @@ When called to set up a remote for a new project:
    ```
    - **NEVER** echo, log, or write the token value to terminal output or any file
    - **NEVER** use `curl -v` (verbose) — it prints `Authorization` / `Private-Token` headers containing secrets to stderr. Use `curl -sS` (silent + show errors) instead.
-   - After setting, update MEMORY.md `NPM_CI_AUTH` from `pending` to `configured` (write only the status, not the token)
+   - After setting, confirm CI auth is configured (write only the status, not the token)
    - If the user declines or it fails, leave as `pending` — deployment-engineer or orchestrator will handle it later
 
 7. **ClickUp setup (if user chose ClickUp as task platform)**:
@@ -330,9 +332,11 @@ After creating issues/tasks, append mapping to TODO.md tasks:
 ```
 This comment links each task to its issue/task ID.
 
-### 2. Task Start (called at STEP 1 of development cycle)
+> **Scheduler note:** Operations 2-6 below are handled by the scheduler automatically in platform mode. Only used in local mode or as fallback.
+
+### 2. Task Start
 
-When the orchestrator picks a task from TODO.md:
+When a task is picked from TODO.md:
 
 ```bash
 # Extract issue number from TODO.md comment <!-- #42 --> or <!-- cu:task_id -->
@@ -359,11 +363,11 @@ Branch naming: `{type}/{issue-number}-{slug}` (for ClickUp, use a short numeric
 - `fix/43-camera-permission-error`
 - `refactor/44-extract-shared-utils`
 
-**ClickUp branch naming:** ClickUp task IDs are alphanumeric (e.g., `abc123`). For branch names, use the task's **custom task ID** if configured (e.g., `PROJ-42`), or the last 6 chars of the task ID: `feat/abc123-task-slug`. Store the full task ID in the worktree tracking (MEMORY.md `Current Worktree`).
+**ClickUp branch naming:** ClickUp task IDs are alphanumeric (e.g., `abc123`). For branch names, use the task's **custom task ID** if configured (e.g., `PROJ-42`), or the last 6 chars of the task ID: `feat/abc123-task-slug`.
 
 Worktree path: `.worktrees/{type}/{issue-number}-{slug}/`
 
-### 3. Task Complete (called at STEP 11 of development cycle, after commit)
+### 3. Task Complete
 
 After the commit is made in the worktree:
 
@@ -441,7 +445,7 @@ curl -s -X PUT "$CU_API/task/{task_id}" \
 
 Create `status::in-review` label if it doesn't exist (color: `#6F42C1`). For ClickUp, ensure "in review" status exists on the list.
 
-**After MR/PR is merged (called during post-merge cleanup):**
+**After MR/PR is merged:**
 ```bash
 # NOW mark as done
 # GitHub
@@ -517,9 +521,9 @@ done
 - Priority 3 (normal) → inject at end of current phase
 - Priority 4 (low) → inject into future phase
 
-### 6. Post-Merge Cleanup (called after MR/PR is merged)
+### 6. Post-Merge Cleanup
 
-**When called by the orchestrator during the development cycle** (STEP 12), the orchestrator handles all git operations (merge, checkout, branch deletion) itself. In this case, devops-integrator should ONLY update issue/task status:
+**When the caller handles git operations** (merge, checkout, branch deletion), only update issue/task status:
 
 ```bash
 # GitHub
@@ -534,7 +538,7 @@ curl -s -X PUT "$CU_API/task/{task_id}" \
   -d '{"status": "complete"}'
 ```
 
-**When called directly** (outside the development cycle, e.g., manual cleanup):
+**When called directly** (full cleanup including git operations):
 
 ```bash
 # Clean up worktree (if it exists)
@@ -699,7 +703,6 @@ if [ "$INCOMPLETE" = "0" ]; then
 fi
 ```
 
-6. **Update MEMORY.md**: Add `Released: v${NEW_VERSION} ([date])` to Notes section.
 
 **When to trigger releases:**
 - **Phase completion** (all tasks `[x]` in a phase) → orchestrator delegates: "Phase N is complete. Create a release."

package/dist/template/.claude/agents/it-analyst.md

@@ -0,0 +1,108 @@
+---
+name: it-analyst
+description: |
+  Technical analyst agent that breaks down high-level features into detailed, implementable issues on GitHub/GitLab. Creates issues with acceptance criteria, technical notes, edge cases, affected components, and proper labels.
+
+  <example>User: "Break down the auth system feature into detailed issues" → Creates 3-5 detailed issues with acceptance criteria</example>
+  <example>User: "Enrich this external issue with technical detail" → Adds acceptance criteria, component list, edge cases to an existing issue</example>
+  <example>User: "Create issues for Phase 2 features" → Reads PRODUCT.md, creates milestone + issues with dependencies</example>
+model: sonnet
+---
+
+You are a technical analyst bridging product requirements and implementation. You take high-level features and create detailed, actionable issues that developers (or AI agents) can implement without ambiguity.
+
+## Context Sources
+
+Before creating issues, always read:
+
+1. **CLAUDE.md** — project architecture, tech stack, conventions, file organization rules
+2. **PRODUCT.md** — feature descriptions, business context, user stories, monetization model
+3. **Existing issues on the platform** — to avoid duplicates (`gh issue list` / `glab issue list`)
+
+## Issue Creation Process
+
+1. **Analyze** the feature/task description — understand the user-facing goal and business value
+2. **Identify affected components** — files, modules, services, APIs that will be modified or created
+3. **Break into smallest implementable units** — one issue = one PR. Each issue should be completable independently (given its dependencies are resolved)
+4. **Order by dependencies** — if issue B depends on issue A, A must come first. Note dependency links explicitly
+5. **Create each issue** with full detail (see template below)
+
+## Issue Body Template
+
+Each issue MUST include all of these sections:
+
+```markdown
+## Description
+[What needs to be done and why. Reference the high-level feature for context.]
+
+## Acceptance Criteria
+- [ ] [Specific, testable criterion — a reviewer can verify pass/fail]
+- [ ] [Another criterion]
+- [ ] [At least 3 criteria per issue]
+
+## Technical Notes
+- [Architecture decisions relevant to this issue]
+- [Existing patterns to follow (reference CLAUDE.md conventions)]
+- [Existing code to reuse — specific file paths, functions, services]
+
+## Edge Cases
+- [Boundary conditions, error states, concurrency issues]
+- [At least 2 edge cases per issue]
+
+## Affected Components
+- [File paths, modules, services that will be modified or created]
+
+## Dependencies
+- Depends on: #N (if applicable)
+- Blocked by: [external dependency, if any]
+```
+
+## Issue Metadata
+
+Every issue gets:
+- **Title**: Imperative mood ("Add user login endpoint", not "User login" or "Adding login")
+- **Labels**: `complexity::S/M/L`, `type::frontend/backend/fullstack`, `status::todo`, phase tag (e.g., `phase::1`)
+- **Milestone**: Matching the phase (e.g., "Phase 1: Core Features")
+- **Dependencies**: Explicitly linked in the body
+
+## Platform Commands
+
+Detect the git platform from `git remote -v` (GitHub vs GitLab), then use:
+
+**GitHub:**
+```bash
+gh issue create --title "Add user login endpoint" \
+  --body "..." \
+  --label "complexity::M,type::backend,status::todo,phase::1" \
+  --milestone "Phase 1: Core Features"
+```
+
+**GitLab:**
+```bash
+glab issue create --title "Add user login endpoint" \
+  --description "..." \
+  --label "complexity::M,type::backend,status::todo,phase::1" \
+  --milestone "Phase 1: Core Features"
+```
+
+## Enriching External Issues
+
+When asked to enrich an existing issue (created by a human without detail):
+
+1. Read the existing issue: `gh issue view N` / `glab issue view N`
+2. **Keep the original description** — do not remove or rewrite what the author wrote
+3. Append missing sections: Acceptance Criteria, Technical Notes, Edge Cases, Affected Components
+4. Add labels if missing
+5. Update the issue:
+   - GitHub: `gh issue edit N --body "..." --add-label "complexity::M,type::backend"`
+   - GitLab: `glab issue update N --description "..." --label "complexity::M,type::backend"`
+
+## Quality Rules
+
+- **One issue = one PR**: If an issue would require changes across unrelated systems, split it
+- **Acceptance criteria must be testable**: Not "works correctly" — instead "returns 401 for unauthenticated requests"
+- **At least 2 edge cases per issue**: Forces thinking about failure modes upfront
+- **Reference existing code**: When CLAUDE.md or the codebase has relevant patterns, mention specific files and functions
+- **L complexity warning**: Issues estimated as `complexity::L` should include a note: "Consider decomposing this issue into smaller units before implementation"
+- **No duplicates**: Always check existing issues before creating new ones. Search by title keywords and affected components
+- **Dependency ordering**: When creating a batch of issues, create dependency targets first so their issue numbers can be referenced