create-claude-workspace 1.1.101 → 1.1.103

package/dist/scripts/autonomous.mjs

@@ -10,6 +10,7 @@ import { emptyCheckpoint, readCheckpoint, writeCheckpoint } from './lib/state.mj
 import { runClaude, currentChild } from './lib/claude-runner.mjs';
 import { sleep, formatDuration, acquireLock, releaseLock, readMemory, isProjectComplete, getCurrentTask, getCurrentPhase, checkClaudeInstalled, checkAuth, checkGitIdentity, checkFilesystemWritable, gitFetchAndPull, gitCheckState, notify, printSummary, promptUser, parseUsageLimitResetMs, } from './lib/utils.mjs';
 import { isTokenExpiringSoon, refreshOAuthToken } from './lib/oauth-refresh.mjs';
+import { pollForNewWork } from './lib/idle-poll.mjs';
 // ─── Args ───
 function parseArgs(argv) {
     const opts = { ...DEFAULTS };
@@ -119,6 +120,16 @@ function parseArgs(argv) {
             i++;
             continue;
         }
+        if (arg === '--idle-poll') {
+            opts.idlePollInterval = numFlag(arg, i);
+            i++;
+            continue;
+        }
+        if (arg === '--max-idle') {
+            opts.maxIdleTime = numFlag(arg, i);
+            i++;
+            continue;
+        }
         if (arg.startsWith('--')) {
             console.error(`Unknown option: ${arg}`);
             process.exit(1);
@@ -148,6 +159,8 @@ Options:
   --log-file <path>            Log file (default: .claude/autonomous.log)
   --no-lock                    Disable lock file
   --no-pull                    Skip auto git pull
+  --idle-poll <ms>             Poll interval when idle (default: 300000 = 5min)
+  --max-idle <ms>              Max idle time before exit, 0=unlimited (default: 0)
   --dry-run                    Validate prerequisites only
   --help                       Show this message
 `);
@@ -330,9 +343,41 @@ async function main() {
         }
         // Read project state
         const memory = readMemory(opts.projectDir);
-        if (isProjectComplete(memory)) {
-            log.info('Project complete!');
-            break;
+        if (isProjectComplete(memory, opts.projectDir)) {
+            if (!checkpoint.completionVerified) {
+                // First time seeing "complete" — let orchestrator check for external issues once
+                log.info('Project marked complete. Running orchestrator to verify (checking for external issues)...');
+                checkpoint.completionVerified = true;
+                writeCheckpoint(opts.projectDir, checkpoint, log);
+                // Fall through to run Claude (orchestrator step 1b will check external issues)
+            }
+            else {
+                // Orchestrator confirmed complete — enter idle polling mode
+                log.info('Project complete. Entering idle polling mode...');
+                const idleStart = Date.now();
+                let foundWork = false;
+                while (!stopping) {
+                    const poll = await pollForNewWork(opts.projectDir, log);
+                    if (poll.hasWork) {
+                        log.info(`New work detected (source: ${poll.source}${poll.issueCount ? `, ${poll.issueCount} issue(s)` : ''}). Resuming development...`);
+                        notify(opts.notifyCommand, 'info', `New work detected from ${poll.source}`, i);
+                        checkpoint.completionVerified = false;
+                        writeCheckpoint(opts.projectDir, checkpoint, log);
+                        foundWork = true;
+                        break;
+                    }
+                    if (opts.maxIdleTime > 0 && Date.now() - idleStart >= opts.maxIdleTime) {
+                        log.info(`Max idle time (${formatDuration(opts.maxIdleTime)}) reached. Exiting.`);
+                        break;
+                    }
+                    log.debug(`No new work. Polling again in ${formatDuration(opts.idlePollInterval)}...`);
+                    await sleep(opts.idlePollInterval, stoppingRef);
+                }
+                if (!foundWork)
+                    break;
+                // Re-read state after idle — memory may have changed
+                continue;
+            }
         }
         const phase = getCurrentPhase(memory);
         const task = getCurrentTask(memory);
@@ -484,6 +529,7 @@ async function main() {
         if (result.task_completed) {
             stats.tasksCompleted.push(result.task_completed);
             log.info(`Completed: ${result.task_completed}`);
+            checkpoint.completionVerified = false; // Reset so completion is re-verified if all tasks finish
         }
         if (result.next_task)
             log.info(`Next: ${result.next_task}`);

package/dist/scripts/autonomous.spec.js

@@ -33,4 +33,14 @@ describe('parseArgs', () => {
         expect(parseArgs(['--help']).help).toBe(true);
         expect(parseArgs(['-h']).help).toBe(true);
     });
+    it('parses idle poll flags', () => {
+        const opts = parseArgs(['--idle-poll', '60000', '--max-idle', '3600000']);
+        expect(opts.idlePollInterval).toBe(60000);
+        expect(opts.maxIdleTime).toBe(3600000);
+    });
+    it('uses defaults for idle poll flags when not provided', () => {
+        const opts = parseArgs([]);
+        expect(opts.idlePollInterval).toBe(5 * 60_000);
+        expect(opts.maxIdleTime).toBe(0);
+    });
 });

package/dist/scripts/lib/idle-poll.mjs

@@ -0,0 +1,196 @@
+// ─── Idle polling: check for new work without AI ───
+// Checks TODO.md (filesystem) and GitHub/GitLab/ClickUp API for new issues.
+// Zero AI tokens consumed — pure Node.js HTTP + filesystem checks.
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { execSync } from 'node:child_process';
+// ─── TODO.md check (filesystem, free) ───
+export function checkTodoForPendingTasks(projectDir) {
+    try {
+        const todo = readFileSync(resolve(projectDir, 'TODO.md'), 'utf-8');
+        return /^- \[ \] /m.test(todo);
+    }
+    catch {
+        return false;
+    }
+}
+// ─── Platform detection ───
+export function detectPlatform(projectDir) {
+    const config = {
+        git: null,
+        gitOwner: null,
+        gitToken: null,
+        taskPlatform: null,
+        clickupListIds: [],
+        clickupToken: null,
+    };
+    // 1. Detect git platform from remote URL
+    try {
+        const remoteUrl = execSync('git remote get-url origin', {
+            cwd: projectDir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        if (remoteUrl.includes('github.com')) {
+            config.git = 'github';
+            config.gitOwner = extractGitHubOwnerRepo(remoteUrl);
+            config.gitToken = process.env.GH_TOKEN || process.env.GITHUB_TOKEN || null;
+            config.taskPlatform = 'github'; // default, may be overridden by ClickUp
+        }
+        else if (remoteUrl.includes('gitlab')) {
+            config.git = 'gitlab';
+            config.gitOwner = extractGitLabProject(remoteUrl);
+            config.gitToken = process.env.GITLAB_TOKEN || null;
+            config.taskPlatform = 'gitlab'; // default, may be overridden by ClickUp
+        }
+    }
+    catch { /* no remote */ }
+    // 2. Check for ClickUp override in CLAUDE.md
+    try {
+        const claudeMd = readFileSync(resolve(projectDir, 'CLAUDE.md'), 'utf-8');
+        if (/TaskPlatform:\s*clickup/i.test(claudeMd)) {
+            config.taskPlatform = 'clickup';
+            config.clickupToken = process.env.CLICKUP_API_TOKEN || null;
+            // Extract ClickUp Space ID for list discovery
+            const spaceMatch = claudeMd.match(/ClickUp Space ID:\s*(\S+)/i);
+            if (spaceMatch) {
+                config.clickupListIds.push(spaceMatch[1]);
+            }
+        }
+    }
+    catch { /* no CLAUDE.md */ }
+    return config;
+}
+/** Extract "owner/repo" from GitHub URL (HTTPS or SSH) */
+export function extractGitHubOwnerRepo(url) {
+    // https://github.com/owner/repo.git or git@github.com:owner/repo.git
+    const match = url.match(/github\.com[/:]([\w.-]+\/[\w.-]+?)(?:\.git)?$/);
+    return match ? match[1] : null;
+}
+/** Extract project path from GitLab URL */
+export function extractGitLabProject(url) {
+    // https://gitlab.com/group/project.git or git@gitlab.com:group/project.git
+    const cleaned = url.replace(/\.git$/, '');
+    // Match after the host portion: "gitlab.com/" or "gitlab.com:"
+    const match = cleaned.match(/gitlab[^/:]*[/:]([\w./-]+)$/);
+    return match ? match[1] : null;
+}
+// ─── API polling (no AI, just HTTP) ───
+async function fetchJson(url, headers) {
+    const response = await fetch(url, { headers, signal: AbortSignal.timeout(10_000) });
+    if (!response.ok)
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    return response.json();
+}
+/** Check GitHub for open issues not yet in TODO.md */
+async function pollGitHub(ownerRepo, token, projectDir) {
+    const headers = {
+        'Accept': 'application/vnd.github+json',
+        'Authorization': `Bearer ${token}`,
+        'X-GitHub-Api-Version': '2022-11-28',
+    };
+    const url = `https://api.github.com/repos/${ownerRepo}/issues?state=open&per_page=100&sort=created&direction=desc`;
+    const issues = await fetchJson(url, headers);
+    // Filter out PRs (GitHub API returns PRs as issues)
+    const realIssues = issues.filter(i => !i.pull_request);
+    // Check which issues are already tracked in TODO.md
+    const todoContent = readTodoSafe(projectDir);
+    let newCount = 0;
+    for (const issue of realIssues) {
+        if (!todoContent.includes(`<!-- #${issue.number} -->`)) {
+            newCount++;
+        }
+    }
+    return newCount;
+}
+/** Check GitLab for open issues not yet in TODO.md */
+async function pollGitLab(projectPath, token, projectDir) {
+    const headers = {
+        'PRIVATE-TOKEN': token,
+    };
+    // URL-encode the project path for the API
+    const encodedPath = encodeURIComponent(projectPath);
+    const url = `https://gitlab.com/api/v4/projects/${encodedPath}/issues?state=opened&per_page=100&order_by=created_at&sort=desc`;
+    const issues = await fetchJson(url, headers);
+    const todoContent = readTodoSafe(projectDir);
+    let newCount = 0;
+    for (const issue of issues) {
+        if (!todoContent.includes(`<!-- #${issue.iid} -->`)) {
+            newCount++;
+        }
+    }
+    return newCount;
+}
+/** Check ClickUp for tasks with "to do" status */
+async function pollClickUp(spaceId, token, projectDir) {
+    const headers = {
+        'Authorization': token,
+    };
+    // First get lists in the space (ClickUp: Space → Lists → Tasks)
+    const listsUrl = `https://api.clickup.com/api/v2/space/${spaceId}/list`;
+    const listsData = await fetchJson(listsUrl, headers);
+    const todoContent = readTodoSafe(projectDir);
+    let newCount = 0;
+    for (const list of listsData.lists) {
+        const tasksUrl = `https://api.clickup.com/api/v2/list/${list.id}/task?statuses[]=to%20do`;
+        const tasksData = await fetchJson(tasksUrl, headers);
+        for (const task of tasksData.tasks) {
+            if (!todoContent.includes(`<!-- cu:${task.id} -->`)) {
+                newCount++;
+            }
+        }
+    }
+    return newCount;
+}
+function readTodoSafe(projectDir) {
+    try {
+        return readFileSync(resolve(projectDir, 'TODO.md'), 'utf-8');
+    }
+    catch {
+        return '';
+    }
+}
+// ─── Main poll function ───
+export async function pollForNewWork(projectDir, log) {
+    // 1. Check TODO.md first (free, instant)
+    if (checkTodoForPendingTasks(projectDir)) {
+        return { hasWork: true, source: 'todo', issueCount: 0 };
+    }
+    // 2. Detect platform and check for external issues
+    const platform = detectPlatform(projectDir);
+    if (platform.taskPlatform === 'clickup' && platform.clickupToken && platform.clickupListIds.length > 0) {
+        try {
+            const count = await pollClickUp(platform.clickupListIds[0], platform.clickupToken, projectDir);
+            if (count > 0) {
+                log.info(`Found ${count} new ClickUp task(s).`);
+                return { hasWork: true, source: 'clickup', issueCount: count };
+            }
+        }
+        catch (err) {
+            log.debug(`ClickUp poll failed: ${err.message}`);
+        }
+    }
+    if (platform.git === 'github' && platform.gitToken && platform.gitOwner) {
+        try {
+            const count = await pollGitHub(platform.gitOwner, platform.gitToken, projectDir);
+            if (count > 0) {
+                log.info(`Found ${count} new GitHub issue(s).`);
+                return { hasWork: true, source: 'github', issueCount: count };
+            }
+        }
+        catch (err) {
+            log.debug(`GitHub poll failed: ${err.message}`);
+        }
+    }
+    if (platform.git === 'gitlab' && platform.gitToken && platform.gitOwner) {
+        try {
+            const count = await pollGitLab(platform.gitOwner, platform.gitToken, projectDir);
+            if (count > 0) {
+                log.info(`Found ${count} new GitLab issue(s).`);
+                return { hasWork: true, source: 'gitlab', issueCount: count };
+            }
+        }
+        catch (err) {
+            log.debug(`GitLab poll failed: ${err.message}`);
+        }
+    }
+    return { hasWork: false, source: null, issueCount: 0 };
+}

package/dist/scripts/lib/idle-poll.spec.js

@@ -0,0 +1,92 @@
+import { describe, it, expect, vi } from 'vitest';
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { checkTodoForPendingTasks, extractGitHubOwnerRepo, extractGitLabProject, detectPlatform, pollForNewWork, } from './idle-poll.mjs';
+function makeTmpDir() {
+    return mkdtempSync(join(tmpdir(), 'idle-poll-test-'));
+}
+function makeLogger() {
+    return { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() };
+}
+describe('checkTodoForPendingTasks', () => {
+    it('returns true when TODO.md has unchecked tasks', () => {
+        const dir = makeTmpDir();
+        writeFileSync(join(dir, 'TODO.md'), '## Phase 9\n- [ ] New task\n- [x] Done\n');
+        expect(checkTodoForPendingTasks(dir)).toBe(true);
+    });
+    it('returns false when all tasks are done', () => {
+        const dir = makeTmpDir();
+        writeFileSync(join(dir, 'TODO.md'), '- [x] Done\n- [~] Skipped\n');
+        expect(checkTodoForPendingTasks(dir)).toBe(false);
+    });
+    it('returns false when no TODO.md exists', () => {
+        const dir = makeTmpDir();
+        expect(checkTodoForPendingTasks(dir)).toBe(false);
+    });
+});
+describe('extractGitHubOwnerRepo', () => {
+    it('extracts from HTTPS URL', () => {
+        expect(extractGitHubOwnerRepo('https://github.com/owner/repo.git')).toBe('owner/repo');
+    });
+    it('extracts from HTTPS URL without .git', () => {
+        expect(extractGitHubOwnerRepo('https://github.com/owner/repo')).toBe('owner/repo');
+    });
+    it('extracts from SSH URL', () => {
+        expect(extractGitHubOwnerRepo('git@github.com:owner/repo.git')).toBe('owner/repo');
+    });
+    it('returns null for non-GitHub URL', () => {
+        expect(extractGitHubOwnerRepo('https://gitlab.com/group/project.git')).toBeNull();
+    });
+});
+describe('extractGitLabProject', () => {
+    it('extracts from HTTPS URL', () => {
+        expect(extractGitLabProject('https://gitlab.com/group/project.git')).toBe('group/project');
+    });
+    it('extracts nested group', () => {
+        expect(extractGitLabProject('https://gitlab.com/group/sub/project.git')).toBe('group/sub/project');
+    });
+    it('extracts from SSH URL', () => {
+        expect(extractGitLabProject('git@gitlab.com:group/project.git')).toBe('group/project');
+    });
+    it('extracts from self-hosted GitLab', () => {
+        expect(extractGitLabProject('https://gitlab.example.com/team/repo.git')).toBe('team/repo');
+    });
+    it('returns null for non-GitLab URL', () => {
+        expect(extractGitLabProject('https://github.com/owner/repo.git')).toBeNull();
+    });
+});
+describe('detectPlatform', () => {
+    it('detects ClickUp override from CLAUDE.md', () => {
+        const dir = makeTmpDir();
+        // No git repo, but CLAUDE.md has ClickUp config
+        writeFileSync(join(dir, 'CLAUDE.md'), '## Tech Stack\n- TaskPlatform: clickup\n- ClickUp Space ID: 12345\n');
+        const config = detectPlatform(dir);
+        expect(config.taskPlatform).toBe('clickup');
+        expect(config.clickupListIds).toContain('12345');
+    });
+    it('defaults to null when no remote and no CLAUDE.md', () => {
+        const dir = makeTmpDir();
+        const config = detectPlatform(dir);
+        expect(config.git).toBeNull();
+        expect(config.taskPlatform).toBeNull();
+    });
+});
+describe('pollForNewWork', () => {
+    it('returns hasWork=true from TODO.md without hitting API', async () => {
+        const dir = makeTmpDir();
+        writeFileSync(join(dir, 'TODO.md'), '- [ ] New task\n');
+        const log = makeLogger();
+        const result = await pollForNewWork(dir, log);
+        expect(result.hasWork).toBe(true);
+        expect(result.source).toBe('todo');
+    });
+    it('returns hasWork=false when no work anywhere', async () => {
+        const dir = makeTmpDir();
+        writeFileSync(join(dir, 'TODO.md'), '- [x] All done\n');
+        const log = makeLogger();
+        const result = await pollForNewWork(dir, log);
+        expect(result.hasWork).toBe(false);
+        expect(result.source).toBeNull();
+    });
+});

package/dist/scripts/lib/state.mjs

@@ -26,6 +26,7 @@ export function emptyCheckpoint() {
         authRetries: 0,
         rateLimitBackoff: 0,
         lastAuthCheckTime: Date.now(),
+        completionVerified: false,
         stats: emptyStats(),
     };
 }

package/dist/scripts/lib/types.mjs

@@ -17,4 +17,6 @@ export const DEFAULTS = {
     notifyCommand: null,
     resume: false,
     help: false,
+    idlePollInterval: 5 * 60_000,
+    maxIdleTime: 0,
 };

package/dist/scripts/lib/utils.mjs

@@ -166,11 +166,26 @@ export function readMemory(projectDir) {
         return null;
     }
 }
-export function isProjectComplete(memory) {
+export function hasPendingTasks(projectDir) {
+    try {
+        const todo = readFileSync(resolve(projectDir, 'TODO.md'), 'utf-8');
+        return /^- \[ \] /m.test(todo);
+    }
+    catch {
+        return false;
+    }
+}
+export function isProjectComplete(memory, projectDir) {
     if (!memory)
         return false;
     const lower = memory.toLowerCase();
-    return lower.includes('project complete') || lower.includes('status: complete');
+    const markedComplete = lower.includes('project complete') || lower.includes('status: complete');
+    if (!markedComplete)
+        return false;
+    // If TODO.md has unchecked tasks, project is NOT complete — user added new work
+    if (projectDir && hasPendingTasks(projectDir))
+        return false;
+    return true;
 }
 export function getMemoryField(memory, field) {
     if (!memory)

package/dist/scripts/lib/utils.spec.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { formatDuration, sleep, getMemoryField, getCurrentTask, getCurrentPhase, isProjectComplete, printSummary, parseUsageLimitResetMs } from './utils.mjs';
+import { formatDuration, sleep, getMemoryField, getCurrentTask, getCurrentPhase, isProjectComplete, hasPendingTasks, printSummary, parseUsageLimitResetMs } from './utils.mjs';
 describe('formatDuration', () => {
     it('formats seconds', () => {
         expect(formatDuration(5000)).toBe('5s');
@@ -82,7 +82,7 @@ describe('getCurrentPhase', () => {
     });
 });
 describe('isProjectComplete', () => {
-    it('detects project complete', () => {
+    it('detects project complete (no projectDir)', () => {
         expect(isProjectComplete('## Status\nProject Complete')).toBe(true);
         expect(isProjectComplete('status: complete')).toBe(true);
     });
@@ -92,6 +92,54 @@ describe('isProjectComplete', () => {
     it('returns false for active project', () => {
         expect(isProjectComplete('## Status\nIn progress')).toBe(false);
     });
+    it('returns false when marked complete but TODO.md has pending tasks', () => {
+        const { mkdtempSync, writeFileSync } = require('node:fs');
+        const { join } = require('node:path');
+        const { tmpdir } = require('node:os');
+        const dir = mkdtempSync(join(tmpdir(), 'claude-test-'));
+        writeFileSync(join(dir, 'TODO.md'), '## Phase 9\n- [ ] New task\n- [x] Done task\n');
+        expect(isProjectComplete('## Status\nProject Complete', dir)).toBe(false);
+    });
+    it('returns true when marked complete and TODO.md has no pending tasks', () => {
+        const { mkdtempSync, writeFileSync } = require('node:fs');
+        const { join } = require('node:path');
+        const { tmpdir } = require('node:os');
+        const dir = mkdtempSync(join(tmpdir(), 'claude-test-'));
+        writeFileSync(join(dir, 'TODO.md'), '## Phase 8\n- [x] Done task\n- [~] Skipped task\n');
+        expect(isProjectComplete('## Status\nProject Complete', dir)).toBe(true);
+    });
+    it('returns true when marked complete and TODO.md does not exist', () => {
+        const { mkdtempSync } = require('node:fs');
+        const { join } = require('node:path');
+        const { tmpdir } = require('node:os');
+        const dir = mkdtempSync(join(tmpdir(), 'claude-test-'));
+        expect(isProjectComplete('## Status\nProject Complete', dir)).toBe(true);
+    });
+});
+describe('hasPendingTasks', () => {
+    it('detects unchecked tasks', () => {
+        const { mkdtempSync, writeFileSync } = require('node:fs');
+        const { join } = require('node:path');
+        const { tmpdir } = require('node:os');
+        const dir = mkdtempSync(join(tmpdir(), 'claude-test-'));
+        writeFileSync(join(dir, 'TODO.md'), '- [ ] Pending\n- [x] Done\n');
+        expect(hasPendingTasks(dir)).toBe(true);
+    });
+    it('returns false when all tasks done', () => {
+        const { mkdtempSync, writeFileSync } = require('node:fs');
+        const { join } = require('node:path');
+        const { tmpdir } = require('node:os');
+        const dir = mkdtempSync(join(tmpdir(), 'claude-test-'));
+        writeFileSync(join(dir, 'TODO.md'), '- [x] Done\n- [~] Skipped\n');
+        expect(hasPendingTasks(dir)).toBe(false);
+    });
+    it('returns false when no TODO.md', () => {
+        const { mkdtempSync } = require('node:fs');
+        const { join } = require('node:path');
+        const { tmpdir } = require('node:os');
+        const dir = mkdtempSync(join(tmpdir(), 'claude-test-'));
+        expect(hasPendingTasks(dir)).toBe(false);
+    });
 });
 describe('parseUsageLimitResetMs', () => {
     it('parses "resets 6pm (UTC)"', () => {

package/dist/template/.claude/agents/orchestrator.md

@@ -79,6 +79,27 @@ At the beginning of EVERY session (including every Ralph Loop iteration):
 - Read MEMORY.md — find where you left off, what is done, what is next, what phase you're in
 - **Load `.env`**: If `.env` exists in the project root, source it to load tokens (`GITLAB_TOKEN`, `GH_TOKEN`, `CLICKUP_API_TOKEN`, etc.): `set -a && [ -f .env ] && . ./.env && set +a`
 
+### 1b. Detect resumed development on completed project
+If MEMORY.md indicates "Project complete" (Current Phase contains "PROJECT COMPLETE" or Next says "project complete"):
+
+**Check for new work from two sources:**
+
+1. **TODO.md** — check for unchecked tasks (`- [ ]`). User may have added new phases/tasks directly.
+2. **External issues** (if git integration active) — delegate to `devops-integrator`: "Run external issue intake — check for new issues on GitHub/GitLab/ClickUp that are not yet in TODO.md. Ingest bugs and feature requests." This catches issues created by the user or team members on the platform while the project was "complete".
+
+**If new tasks are found** (from either source):
+- Reset MEMORY.md for the new phase:
+  1. Find the first unchecked task's phase heading in TODO.md (e.g., `## Phase 9 — ...`)
+  2. Update MEMORY.md `Current Phase` to that phase name
+  3. Update `Next` to the first unchecked task
+  4. Clear `Current Task`, `Current Step`, `Current Worktree` (set to `(none)`)
+  5. Reset `Iterations This Session` to `0` and `Complexity This Session` to `0`
+  6. Add a note: "Resumed development — new tasks detected after previous completion (v1.x.x)"
+  7. **Do NOT delete** the `Done` section or `Release History` — previous work is preserved
+- Then continue with the normal health check (step 2+). The new tasks will be picked up in STEP 1.
+
+**If no new tasks found** (TODO.md has no `[ ]` and no external issues ingested) → project is truly complete, end session.
+
 ### 2. Resolve app names and package manager
 - Read CLAUDE.md — find app name(s) and package manager from the Architecture/Tech Stack section
 - Store app names for use in build/test/lint commands:
@@ -423,7 +444,7 @@ To determine if a task is frontend, backend, or fullstack, use this heuristic:
   - The FULL architect plan from STEP 2 (copy it verbatim into the prompt)
   - Any additional context: design system (UX.md), Figma references, existing code patterns
   - Explicit instruction: "Implement EXACTLY per this plan. Production code, not prototypes. Stay within SCOPE — do not gold-plate."
-  - For UI: if Figma MCP is available and design exists, include: "Use `/figma:implement-design` for components with Figma designs. Otherwise use UX.md spec or `/frontend-design` skill."
+  - For UI: if Figma MCP is available and CLAUDE.md contains a `<!-- FIGMA_URL: ... -->`, include: "Figma designs are available at [URL]. Use `/figma:implement-design` for components with Figma designs — find the relevant frames in the Figma file. Otherwise use UX.md spec or `/frontend-design` skill."
 - **Include these rules in the implementation prompt:**
   - **CLI commands and Nx Generators FIRST**: Always prioritize using CLI commands and `nx generate` over manual file creation. NEVER manually create `project.json`, `tsconfig.*`, or configure build/test/lint targets — generators and CLI tools handle this correctly. NEVER manually install or configure build tools (tsup, esbuild, rollup, webpack) — Nx generators handle build configuration. Internal libs don't need a build step; publishable libs get `--bundler` from the generator. This includes:
     - **Workspace scaffolding** (Phase 0): `create-nx-workspace` via the detected package manager runner (`bunx` / `npx` / `pnpm dlx` / `yarn dlx`) — architect decides preset and flags. If PKG is bun, use `bunx create-nx-workspace` and pass `--packageManager=bun`. After workspace creation, run `nx g @cibule/devkit:preset {orgName}` to initialize onion architecture layers.

package/dist/template/.claude/agents/project-initializer.md

@@ -26,7 +26,8 @@ Have a natural conversation with the user about their project. The user does NOT
    If yes, follow up immediately:
    - **Which registry?** (npmjs.com / GitHub Packages / GitLab Packages / private)
    - **Public or private?** (`--access public` vs `--access restricted`)
-7. **Anything else important?** Special constraints, integrations, existing work, design files, etc.
+7. **Do you have designs in Figma?** (If yes: "Paste the Figma file URL — I'll set it up so agents can implement directly from the designs.")
+8. **Anything else important?** Special constraints, integrations, existing work, design files, etc.
 
 Do NOT ask technical questions (runtime, database, package manager, deployment target, architecture). Those decisions belong to architect agents during development planning.
 
@@ -47,9 +48,35 @@ After the conversation, scan what already exists. Do NOT create or scaffold anyt
 - List `apps/` and `libs/` structure if they exist
 - Check for existing plan/design/UX files (TODO.md, PLAN.md, PRODUCT.md, UX.md)
 - Check for existing `.claude/profiles/frontend.md` (may already exist if user set it up manually)
-- Check if Figma MCP server is available
+- Check if Figma MCP server is available (try listing MCP tools — if figma tools exist, it's configured)
 - `git log --oneline -10` — recent history
 
+### Step 2a: Figma Setup (if question 7 = yes)
+
+If the user provided a Figma URL:
+
+1. **Check if Figma MCP is already configured** — try using a Figma MCP tool. If it works, skip to step 3.
+2. **If not configured**, guide the user:
+   - "To connect Figma, I need a Figma API token. Create one at: https://www.figma.com/developers/api#access-tokens (Settings → Security → Personal access tokens → Generate new token)."
+   - Ask the user to paste the token directly as a plain text reply.
+   - Configure the MCP server by writing to `.claude/settings.json` in the project:
+     ```json
+     {
+       "mcpServers": {
+         "figma": {
+           "command": "npx",
+           "args": ["-y", "figma-developer-mcp", "--stdio"],
+           "env": { "FIGMA_API_KEY": "<pasted-token>" }
+         }
+       }
+     }
+     ```
+   - **IMPORTANT**: Add `.claude/settings.json` to `.gitignore` — it contains the API token and MUST NOT be committed.
+   - Verify the MCP server works by attempting to use a Figma tool.
+3. **Store the Figma URL** — save it for Step 4 (CLAUDE.md generation). The URL will be written into CLAUDE.md so agents know where to find designs.
+
+**For Docker / autonomous mode**: The Figma API token should be passed as `FIGMA_API_KEY` environment variable. Add to `docker-compose.yml` or `.env` (Docker reads `.env` automatically). The MCP server config in `.claude/settings.json` can reference `${FIGMA_API_KEY}` env var instead of hardcoding the token.
+
 **Validate agent availability:**
 - Verify `.claude/agents/` directory exists and contains all required agents:
   `orchestrator.md`, `ui-engineer.md`, `backend-ts-architect.md`, `senior-code-reviewer.md`,
@@ -145,6 +172,7 @@ Read the template from `.claude/templates/claude-md.md`.
 Create a **minimal** CLAUDE.md in the project root by filling what is KNOWN from the conversation and codebase:
 - The template content starts after the `---` separator line — copy everything below it
 - Fill in: project name, description, workflow (solo/team)
+- If the user provided a Figma URL (question 7), fill in the `<!-- FIGMA_URL: -->` placeholder in the Figma MCP section: `<!-- FIGMA_URL: https://www.figma.com/design/... -->`
 - If user answered "yes" to npm publishing (question 6), add `- **Distribution**: npm ([registry], [public/restricted])` to Tech Stack section (details collected in Step 2b)
 - Fill in Tech Stack ONLY for what is already detected in the codebase (existing package.json, nx.json, etc.)
 - **Detect package manager** from lockfile: `bun.lock` or `bun.lockb` → bun, `pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `package-lock.json` → npm. If no lockfile, check `package.json` `packageManager` field. Fill `[PKG]` in the template with the detected value. This is critical — all agents use this value for install/run/add commands.

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

@@ -91,7 +91,7 @@ Write clean, elegant code that is easy to test and reason about:
 
 ## Design Implementation
 
-- If Figma MCP is available and design exists: implement from Figma with 1:1 fidelity
+- If Figma MCP is available and design exists: implement from Figma with 1:1 fidelity. Find the Figma project URL in CLAUDE.md (`<!-- FIGMA_URL: ... -->`) and use `/figma:implement-design` with the specific frame/component URL.
 - If UX.md exists: follow its design tokens, typography, colors, breakpoints
 - If neither: use `/frontend-design` skill for high-quality UI generation
 - Always use @themecraft generated SCSS variables (`colors.$token`, `sizes.$token`, `@include typography.level-name`) — no hardcoded color/size values, no direct `color-var()`/`size-var()` calls

package/dist/template/.claude/templates/claude-md.md

@@ -391,8 +391,10 @@ Install these before starting autonomous development:
 
 - **Figma MCP** (optional) — for implementing designs from Figma files
   - Enables: `/figma:implement-design`, `/figma:code-connect-components`
-  - Install: configure in Claude Code MCP settings with Figma API token
+  - Install: `claude mcp add figma -- npx -y figma-developer-mcp --stdio`, then set `FIGMA_API_KEY` in MCP server env (see setup below)
   - If not available, use `/frontend-design` skill or UX.md spec for UI implementation
+  - **Figma Project URL**: <!-- FIGMA_URL: --> (set during project initialization or manually)
+  - When implementing UI tasks, agents use this URL to find the relevant design frames
 
 - **Playwright MCP** (`@anthropic/plugin-playwright`) — browser automation for visual verification
   - Enables: navigating to dev server, taking screenshots, clicking, filling forms

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-claude-workspace",
-  "version": "1.1.101",
+  "version": "1.1.103",
   "description": "Scaffold a project with Claude Code agents for autonomous AI-driven development",
   "type": "module",
   "bin": {