@relipa/ai-flow-kit 0.2.0-beta.0 → 0.2.0-beta.2

package/scripts/link-resolver.js

@@ -3,9 +3,13 @@ const https = require('https');
 const chalk = require('chalk');
 
 const BACKLOG_RE = /https?:\/\/([\w.-]+\.backlog(?:tool)?\.com)\/view\/([A-Z][A-Z0-9_]+-\d+)(?:#comment-(\d+))?/i;
-// Backlog Document permalink — "Copy link" on a Document page gives /alias/document/{id}.
-// NOTE: Nulab's Document REST API is new (2026) — path unverified against a live space, adjust if it 404s.
-const BACKLOG_DOCUMENT_RE = /https?:\/\/([\w.-]+\.backlog(?:tool)?\.com)\/(?:alias\/)?document\/(\d+)(?:#comment-(\d+))?/i;
+// Backlog Document permalink — "Copy link" on a Document page gives /alias/document/{id},
+// where {id} is Nulab's hex document ID (e.g. 0193b335c62173de9547bab5dd0b5324), not numeric.
+// Newer "Share link" format adds a project-key + /e/ prefix: /document/{PROJECT_KEY}/e/{id}.
+// Confirmed live against a real space (2026-08-06): GET /api/v2/documents/{id} returns the
+// body as `plain` (not `plainText`/`content`) — see fetchBacklogDocument below.
+// Comment fetch (fetchBacklogDocumentComment) is still unverified — adjust its field names if it 404s or returns empty content.
+const BACKLOG_DOCUMENT_RE = /https?:\/\/([\w.-]+\.backlog(?:tool)?\.com)\/(?:alias\/)?document\/(?:[A-Z][A-Z0-9_]*\/e\/)?([0-9a-f]+)(?:#comment-(\d+))?/i;
 // Backlog Wiki permalink — "Copy link" on a Wiki page gives /alias/wiki/{id}.
 const BACKLOG_WIKI_RE = /https?:\/\/([\w.-]+\.backlog(?:tool)?\.com)\/alias\/wiki\/(\d+)/i;
 const JIRA_RE = /https?:\/\/([\w.-]+\.atlassian\.net)\/browse\/([A-Z][A-Z0-9_]+-\d+)/i;
@@ -78,6 +82,41 @@ function httpsGet(url, headers) {
   });
 }
 
+// Generic POST — `bodyType` picks the wire format:
+//   'form' → application/x-www-form-urlencoded (Backlog's write API)
+//   'json' → application/json (Jira's write API)
+function httpsPost(url, payload, { headers = {}, bodyType = 'json' } = {}) {
+  return new Promise((resolve, reject) => {
+    const body = bodyType === 'form'
+      ? new URLSearchParams(payload).toString()
+      : JSON.stringify(payload);
+    const reqHeaders = {
+      ...headers,
+      'Content-Type': bodyType === 'form' ? 'application/x-www-form-urlencoded' : 'application/json',
+      'Content-Length': Buffer.byteLength(body),
+    };
+    const { hostname, pathname, search } = new URL(url);
+    const req = https.request(
+      { hostname, path: pathname + search, method: 'POST', headers: reqHeaders },
+      (res) => {
+        let data = '';
+        res.on('data', chunk => (data += chunk));
+        res.on('end', () => {
+          if (res.statusCode < 200 || res.statusCode >= 300) {
+            reject(new Error(`HTTP ${res.statusCode}: ${data.substring(0, 500)}`));
+            return;
+          }
+          try { resolve(data ? JSON.parse(data) : {}); }
+          catch (e) { reject(new Error('Invalid JSON from API')); }
+        });
+      }
+    );
+    req.on('error', reject);
+    req.write(body);
+    req.end();
+  });
+}
+
 async function fetchBacklogTicket(domain, apiKey, ticketId) {
   const issue = await httpsGet(`https://${domain}/api/v2/issues/${ticketId}?apiKey=${apiKey}`);
   return {
@@ -115,7 +154,7 @@ async function fetchBacklogDocument(domain, apiKey, documentId) {
     documentId: String(documentId),
     title: doc.title || doc.name || '',
     tag: (doc.tags || []).map(t => t.name).join(', '),
-    content: (doc.plainText || doc.content || '').substring(0, 4000),
+    content: (doc.plain || doc.plainText || doc.content || '').substring(0, 4000),
   };
 }
 
@@ -148,6 +187,36 @@ async function fetchBacklogWiki(domain, apiKey, wikiId) {
   };
 }
 
+// ── Backlog WRITE — issue creation (PM Workflow_v1.0.md "Vấn đề 5") ──────────
+
+async function fetchBacklogIssueTypes(domain, apiKey, projectIdOrKey) {
+  return httpsGet(`https://${domain}/api/v2/projects/${projectIdOrKey}/issueTypes?apiKey=${apiKey}`);
+}
+
+async function fetchBacklogPriorities(domain, apiKey) {
+  return httpsGet(`https://${domain}/api/v2/priorities?apiKey=${apiKey}`);
+}
+
+/**
+ * Creates a Backlog issue. Requires an apiKey with WRITE permission — distinct from the
+ * read-only key used elsewhere in this file for `ak fetch-links`/`ak use`.
+ * `projectId`, `summary`, `issueTypeId`, `priorityId` are mandatory per Backlog's API.
+ */
+async function createBacklogIssue(domain, apiKeyWrite, { projectId, summary, description, issueTypeId, priorityId }) {
+  const issue = await httpsPost(
+    `https://${domain}/api/v2/issues?apiKey=${apiKeyWrite}`,
+    {
+      projectId: String(projectId),
+      summary,
+      issueTypeId: String(issueTypeId),
+      priorityId: String(priorityId),
+      description: description || '',
+    },
+    { bodyType: 'form' }
+  );
+  return { ticketId: issue.issueKey, url: `https://${domain}/view/${issue.issueKey}`, raw: issue };
+}
+
 function jiraAuth(email, token) {
   return `Basic ${Buffer.from(`${email}:${token}`).toString('base64')}`;
 }
@@ -191,6 +260,32 @@ async function fetchJiraComment(domain, email, token, ticketId, commentId) {
   };
 }
 
+// ── Jira WRITE — issue creation (PM Workflow_v1.0.md "Vấn đề 5") ────────────
+
+/**
+ * Creates a Jira issue. `apiTokenWrite`/`emailWrite` are distinct from the read-only
+ * credentials used elsewhere in this file — same "separate WRITE key" policy as Backlog.
+ */
+async function createJiraIssue(domain, emailWrite, apiTokenWrite, { projectKey, summary, description, issueTypeName }) {
+  const issue = await httpsPost(
+    `https://${domain}/rest/api/3/issue`,
+    {
+      fields: {
+        project: { key: projectKey },
+        summary,
+        issuetype: { name: issueTypeName || 'Task' },
+        description: {
+          type: 'doc',
+          version: 1,
+          content: [{ type: 'paragraph', content: [{ type: 'text', text: description || '' }] }],
+        },
+      },
+    },
+    { headers: { Authorization: jiraAuth(emailWrite, apiTokenWrite), Accept: 'application/json' }, bodyType: 'json' }
+  );
+  return { ticketId: issue.key, url: `https://${domain}/browse/${issue.key}`, raw: issue };
+}
+
 function linkDedupeKey(classified) {
   if (classified.kind === 'document') return 'doc:' + classified.documentId + (classified.commentId ? '#' + classified.commentId : '');
   if (classified.kind === 'wiki') return 'wiki:' + classified.wikiId;
@@ -270,4 +365,6 @@ module.exports = {
   fetchBacklogTicket, fetchBacklogComment,
   fetchBacklogDocument, fetchBacklogDocumentComment, fetchBacklogWiki,
   fetchJiraTicket, fetchJiraComment,
+  fetchBacklogIssueTypes, fetchBacklogPriorities, createBacklogIssue,
+  createJiraIssue,
 };

package/scripts/task.js

@@ -345,8 +345,9 @@ async function nextGate(taskId) {
     const isGenDoc = taskType === 'gen-doc';
     const isSystemRequirement = taskType === 'create-system-requirement';
     const isIngestData = taskType === 'ingest-data';
-    const isTwoGateDoc = isGenDoc || isSystemRequirement || isIngestData;
-    const maxGate = isTwoGateDoc ? 2 : 5;
+    const isTwoGateDoc = isGenDoc || isSystemRequirement;
+    const isDocFlow = isTwoGateDoc || isIngestData;
+    const maxGate = isTwoGateDoc ? 2 : isIngestData ? 3 : 5;
 
     const taskState = {
         ...existing,
@@ -371,7 +372,7 @@ async function nextGate(taskId) {
     console.log(chalk.green(`✓ Gate ${currentGate} approved for ${resolvedId}.`));
     console.log(chalk.gray(`  Summary saved to: .aiflow/tasks/${resolvedId}/task-summary.md`));
 
-    if (isTwoGateDoc && currentGate >= maxGate) {
+    if (isDocFlow && currentGate >= maxGate) {
         console.log(chalk.green('\n  ✅ Document workflow complete. Task is done.'));
     } else {
         const nextLabel = gateLabel(nextGateNum, taskType);
@@ -380,7 +381,7 @@ async function nextGate(taskId) {
         console.log(chalk.gray(`    1. Open a NEW chatbox or terminal session.`));
         console.log(chalk.gray(`    2. Run: aiflow task resume ${resolvedId} (to load context).`));
         console.log(chalk.gray(`    3. Type "start" or "continue from the current plan".`));
-        if (!isTwoGateDoc) {
+        if (!isDocFlow) {
             console.log(chalk.yellow(`       (Note: Gate 3 progress is saved via [x] checkboxes in the Gate 2 plan doc (AK-Docs/04.Coding/02.Plans/).`));
             console.log(chalk.yellow(`        The AI will automatically resume the exact task you left off.)`));
         }
@@ -485,7 +486,10 @@ async function detectCurrentGate(taskId) {
 
 async function generateMarkdownSummary(taskState, taskType = null) {
     taskType = taskType || taskState.taskType || 'feature';
-    const maxGate = taskType === 'testing' ? 4 : ((taskType === 'gen-doc' || taskType === 'create-system-requirement' || taskType === 'ingest-data') ? 2 : 5);
+    const maxGate = taskType === 'testing' ? 4
+        : taskType === 'ingest-data' ? 3
+        : (taskType === 'gen-doc' || taskType === 'create-system-requirement') ? 2
+        : 5;
     const lines = [];
     lines.push(`# Task Summary: ${taskState.taskId}`);
     lines.push(`**Title:** ${taskState.title}`);
@@ -531,7 +535,8 @@ function gateLabel(n, taskType = null) {
     if (taskType === 'ingest-data') {
         if (n === 1) return 'Fetch, Classify, Draft';
         if (n === 2) return 'Branch + Merge Request';
-        if (n >= 3) return 'Done';
+        if (n === 3) return 'Sinh Task & Tạo Ticket';
+        if (n >= 4) return 'Done';
     }
     const labels = {
         1: 'AI Analyze Requirement',
@@ -599,15 +604,19 @@ module.exports.createOrActivateTaskState = async function createOrActivateTaskSt
 };
 
 /**
- * Called by `aiflow gate <N> <start|approved>` to keep task-state.json in sync
+ * Called by `aiflow gate <N> <start|approved|skip>` to keep task-state.json in sync
  * with the actual gate progress — without requiring the user to run `task next`.
  *
  * - 'start'   : advances currentGate to N (if N is higher than stored value)
  * - 'approved': records approval timestamp + advances currentGate to N+1
+ * - 'skip'    : records a skip (gate legitimately produced no deliverable, e.g.
+ *               ingest-data Gate 3 deciding no task is needed) + advances currentGate
+ *               to N+1, same as 'approved' — every "is this task done" check only ever
+ *               inspects `currentGate`, so a skipped gate still lets the task complete.
  *
  * Silently no-ops when task-state.json does not exist yet (task not saved).
  */
-module.exports.updateTaskGateState = async function updateTaskGateState(ticketId, gateNum, action) {
+module.exports.updateTaskGateState = async function updateTaskGateState(ticketId, gateNum, action, options = {}) {
     if (!ticketId) return;
     const taskDir   = path.join(TASKS_DIR, ticketId);
     const statePath = path.join(taskDir, 'task-state.json');
@@ -633,6 +642,14 @@ module.exports.updateTaskGateState = async function updateTaskGateState(ticketId
         if (gateNum >= (existing.currentGate || 1)) {
             updated.currentGate = gateNum + 1;
         }
+    } else if (action === 'skip') {
+        const skippedGates = { ...(existing.skippedGates || {}) };
+        skippedGates[String(gateNum)] = { at: now, reason: options.reason || '' };
+        updated.skippedGates = skippedGates;
+        // Advance currentGate to next gate (only if not already ahead) — same as 'approved'
+        if (gateNum >= (existing.currentGate || 1)) {
+            updated.currentGate = gateNum + 1;
+        }
     }
 
     await fs.writeJson(statePath, updated, { spaces: 2 });

package/scripts/ticket-writer.js

@@ -0,0 +1,247 @@
+'use strict';
+// Vấn đề 5 (docs/internal/PM Workflow_v1.0.md) — turns an AI-proposed, PM-approved task list
+// (born out of `ingest-data` Gate 3) into real tickets on Backlog/Jira.
+//
+// Read access (fetch-links, listing projects/issueTypes/priorities) reuses the existing
+// read-only credentials already configured for `ak use`/`ak fetch-links`. Creating a ticket is a
+// WRITE action and requires a SEPARATE credential (`BACKLOG_API_KEY_WRITE` / `JIRA_API_TOKEN_WRITE`)
+// — same "distinct WRITE key" policy the PM Workflow doc calls for, kept apart from the read key so
+// a compromised/misconfigured read key can never create tickets.
+
+const fs = require('fs-extra');
+const chalk = require('chalk');
+const useCommand = require('./use');
+const linkResolver = require('./link-resolver');
+
+const {
+  loadCredentials,
+  resolveBacklogCredentials,
+  resolveJiraCredentials,
+  saveMcpCredentials,
+} = useCommand;
+
+const {
+  fetchBacklogIssueTypes,
+  fetchBacklogPriorities,
+  createBacklogIssue,
+  createJiraIssue,
+} = linkResolver;
+
+// Only these keys can be written via `ak credentials set` — dedicated adapter credentials
+// (BACKLOG_API_KEY, JIRA_API_TOKEN, ...) still go through `ak init --adapter` on purpose.
+const SETTABLE_CREDENTIAL_KEYS = [
+  'BACKLOG_API_KEY_WRITE',
+  'JIRA_API_TOKEN_WRITE',
+  'JIRA_EMAIL_WRITE',
+  'BACKLOG_DEFAULT_PROJECT_ID',
+  'BACKLOG_DEFAULT_PROJECT_KEY',
+  'JIRA_DEFAULT_PROJECT_KEY',
+];
+
+function jiraFullDomain(domain) {
+  return domain.includes('.') ? domain : `${domain}.atlassian.net`;
+}
+
+function missingCredResult(target, field, message) {
+  return { ok: false, error: 'missing-write-credentials', target, field, message };
+}
+
+async function resolveBacklogWrite(creds) {
+  const read = resolveBacklogCredentials(creds);
+  if (!read) {
+    return missingCredResult(
+      'backlog', 'BACKLOG_API_KEY / BACKLOG_SPACE_KEY',
+      'Chưa cấu hình credentials đọc Backlog. Chạy `ak init --adapter backlog` trước.'
+    );
+  }
+  const apiKeyWrite = process.env.BACKLOG_API_KEY_WRITE || creds.BACKLOG_API_KEY_WRITE;
+  if (!apiKeyWrite) {
+    return missingCredResult(
+      'backlog', 'BACKLOG_API_KEY_WRITE',
+      'Cần API key Backlog có quyền tạo issue (khác key đọc hiện tại). Cung cấp API key này, mình sẽ lưu lại và tạo ticket ngay.'
+    );
+  }
+  return { ok: true, domain: read.domain, apiKeyRead: read.apiKey, apiKeyWrite };
+}
+
+async function resolveJiraWrite(creds) {
+  const read = resolveJiraCredentials(creds);
+  if (!read) {
+    return missingCredResult(
+      'jira', 'JIRA_API_TOKEN / JIRA_EMAIL / JIRA_DOMAIN',
+      'Chưa cấu hình credentials đọc Jira. Chạy `ak init --adapter jira` trước.'
+    );
+  }
+  const apiTokenWrite = process.env.JIRA_API_TOKEN_WRITE || creds.JIRA_API_TOKEN_WRITE;
+  if (!apiTokenWrite) {
+    return missingCredResult(
+      'jira', 'JIRA_API_TOKEN_WRITE',
+      'Cần Jira API token có quyền tạo issue (khác token đọc hiện tại). Cung cấp token này, mình sẽ lưu lại và tạo ticket ngay.'
+    );
+  }
+  const emailWrite = process.env.JIRA_EMAIL_WRITE || creds.JIRA_EMAIL_WRITE || read.email;
+  return { ok: true, domain: jiraFullDomain(read.domain), emailWrite, apiTokenWrite };
+}
+
+async function pickBacklogDefaults(domain, apiKeyRead, projectId) {
+  const [issueTypes, priorities] = await Promise.all([
+    fetchBacklogIssueTypes(domain, apiKeyRead, projectId),
+    fetchBacklogPriorities(domain, apiKeyRead),
+  ]);
+  if (!issueTypes || !issueTypes.length) throw new Error(`Project ${projectId} không có issueType nào — không thể tạo issue.`);
+  const defaultIssueTypeId = issueTypes[0].id;
+  const normal = (priorities || []).find((p) => /normal|trung bình/i.test(p.name));
+  const defaultPriorityId = (normal || (priorities || [])[0] || {}).id;
+  if (!defaultPriorityId) throw new Error('Không lấy được danh sách priority từ Backlog.');
+  return { defaultIssueTypeId, defaultPriorityId };
+}
+
+/**
+ * `ak tasks create-tickets <file.json> [--json]`
+ *
+ * Input file shape:
+ * {
+ *   "target": "backlog" | "jira",
+ *   "projectId": "12345",     // optional — Backlog only, overrides BACKLOG_DEFAULT_PROJECT_ID
+ *   "projectKey": "PROJ",     // optional — Jira only, overrides JIRA_DEFAULT_PROJECT_KEY
+ *   "tasks": [
+ *     { "type": "spec|coding|test|other", "title": "...", "description": "..." }
+ *   ]
+ * }
+ *
+ * `description` is expected to already be fully composed by the AI per the ticket template in
+ * PM Workflow_v1.0.md §6.1 (Nội dung task + Nguồn tham chiếu) — this command posts it as-is.
+ */
+async function createTicketsCommand(inputFile, options = {}) {
+  const emit = (obj) => {
+    if (options.json) { process.stdout.write(JSON.stringify(obj)); return; }
+    if (obj.ok === false) {
+      console.log(chalk.red(`✗ ${obj.message || obj.error}`));
+    } else {
+      console.log(chalk.green(`✓ ${obj.results.filter(r => r.ok).length}/${obj.results.length} ticket(s) created on ${obj.target}.`));
+      for (const r of obj.results) {
+        console.log(r.ok ? `  ${chalk.green('✓')} ${r.ticketId}  ${chalk.gray(r.title)}` : `  ${chalk.red('✗')} ${chalk.gray(r.title)} — ${r.error}`);
+      }
+    }
+    console.log(JSON.stringify(obj));
+  };
+
+  let input;
+  try {
+    input = await fs.readJson(inputFile);
+  } catch (err) {
+    emit({ ok: false, error: 'invalid-input-file', message: `Không đọc được ${inputFile}: ${err.message}` });
+    process.exitCode = 1;
+    return;
+  }
+
+  const target = input.target;
+  const tasks = input.tasks || [];
+  if (!['backlog', 'jira'].includes(target)) {
+    emit({ ok: false, error: 'invalid-target', message: `target phải là "backlog" hoặc "jira", nhận được: ${target}` });
+    process.exitCode = 1;
+    return;
+  }
+  if (!tasks.length) {
+    emit({ ok: false, error: 'empty-tasks', message: 'File input không có task nào trong "tasks".' });
+    process.exitCode = 1;
+    return;
+  }
+
+  const creds = await loadCredentials();
+
+  if (target === 'backlog') {
+    const write = await resolveBacklogWrite(creds);
+    if (!write.ok) { emit(write); process.exitCode = 2; return; }
+
+    const projectId = input.projectId || creds.BACKLOG_DEFAULT_PROJECT_ID;
+    if (!projectId) {
+      emit({
+        ok: false, error: 'missing-project',
+        message: 'Chưa xác định projectId đích trên Backlog. Chạy `ak backlog-projects` để xem danh sách, rồi `ak backlog-set-default-project <id> <key>`.',
+      });
+      process.exitCode = 2;
+      return;
+    }
+
+    let defaults;
+    try {
+      defaults = await pickBacklogDefaults(write.domain, write.apiKeyRead, projectId);
+    } catch (err) {
+      emit({ ok: false, error: 'project-lookup-failed', message: err.message });
+      process.exitCode = 1;
+      return;
+    }
+
+    const results = [];
+    for (const task of tasks) {
+      try {
+        const created = await createBacklogIssue(write.domain, write.apiKeyWrite, {
+          projectId,
+          summary: task.title,
+          description: task.description,
+          issueTypeId: task.issueTypeId || defaults.defaultIssueTypeId,
+          priorityId: task.priorityId || defaults.defaultPriorityId,
+        });
+        results.push({ type: task.type, title: task.title, ok: true, ticketId: created.ticketId, url: created.url });
+      } catch (err) {
+        results.push({ type: task.type, title: task.title, ok: false, error: err.message });
+      }
+    }
+    emit({ ok: true, target, projectId, results });
+    return;
+  }
+
+  // target === 'jira'
+  const write = await resolveJiraWrite(creds);
+  if (!write.ok) { emit(write); process.exitCode = 2; return; }
+
+  const projectKey = input.projectKey || creds.JIRA_DEFAULT_PROJECT_KEY;
+  if (!projectKey) {
+    emit({
+      ok: false, error: 'missing-project',
+      message: 'Chưa xác định project đích trên Jira. Chạy `ak jira-projects` để xem danh sách, rồi `ak jira-set-default-project <key>`.',
+    });
+    process.exitCode = 2;
+    return;
+  }
+
+  const results = [];
+  for (const task of tasks) {
+    try {
+      const created = await createJiraIssue(write.domain, write.emailWrite, write.apiTokenWrite, {
+        projectKey,
+        summary: task.title,
+        description: task.description,
+        issueTypeName: task.issueType || 'Task',
+      });
+      results.push({ type: task.type, title: task.title, ok: true, ticketId: created.ticketId, url: created.url });
+    } catch (err) {
+      results.push({ type: task.type, title: task.title, ok: false, error: err.message });
+    }
+  }
+  emit({ ok: true, target, projectKey, results });
+}
+
+/**
+ * `ak credentials set <KEY> <VALUE>` — lets the AI persist a WRITE key the user pasted in chat
+ * (after being asked, per the missing-write-credentials error above) without a bespoke command
+ * per key. Restricted to an allowlist — dedicated adapter read-credentials still go through
+ * `ak init --adapter`, this is only for the pieces that flow introduced.
+ */
+async function setCredentialCommand(key, value) {
+  if (!SETTABLE_CREDENTIAL_KEYS.includes(key)) {
+    console.log(chalk.red(`✗ Unknown credential key: ${key}.`));
+    console.log(chalk.gray(`  Allowed: ${SETTABLE_CREDENTIAL_KEYS.join(', ')}`));
+    process.exitCode = 1;
+    return;
+  }
+  await saveMcpCredentials({ [key]: value });
+  console.log(chalk.green(`✓ Saved ${key} to ~/.aiflow/credentials.json`));
+}
+
+module.exports = {
+  createTicketsCommand,
+  setCredentialCommand,
+  SETTABLE_CREDENTIAL_KEYS,
+};

package/scripts/use.js

@@ -360,6 +360,14 @@ function backlogGet(url) {
   });
 }
 
+/**
+ * Fetch the list of projects in the Backlog space — used to let the user pick a default
+ * project for tasks created manually (no ticket to derive a project from).
+ */
+function fetchBacklogProjects(domain, apiKey) {
+  return backlogGet(`https://${domain}/api/v2/projects?apiKey=${apiKey}`);
+}
+
 /**
  * Fetch issue detail from Backlog REST API
  */
@@ -584,6 +592,64 @@ function fetchJiraIssue(domain, email, apiToken, issueKey) {
   });
 }
 
+/**
+ * `ak jira-projects [--json]` — lists the projects visible to the configured Jira account, so the
+ * user can pick a default project for tasks created from Meeting Minutes/QnA (see Vấn đề 5.1 in
+ * PM Workflow_v1.0.md). Mirrors `listBacklogProjectsCommand` above.
+ */
+function fetchJiraProjects(domain, email, apiToken) {
+  return new Promise((resolve, reject) => {
+    const auth = Buffer.from(`${email}:${apiToken}`).toString("base64");
+    const url = `https://${domain}.atlassian.net/rest/api/3/project`;
+    https
+      .get(url, { headers: { Authorization: `Basic ${auth}`, Accept: "application/json" } }, (res) => {
+        let data = "";
+        res.on("data", (chunk) => (data += chunk));
+        res.on("end", () => {
+          if (res.statusCode !== 200) {
+            reject(new Error(`HTTP ${res.statusCode}: ${data}`));
+            return;
+          }
+          try { resolve(JSON.parse(data)); }
+          catch (e) { reject(new Error("Invalid JSON response from Jira")); }
+        });
+      })
+      .on("error", reject);
+  });
+}
+
+async function listJiraProjectsCommand(options = {}) {
+  const creds = await loadCredentials();
+  const resolved = resolveJiraCredentials(creds);
+  if (!resolved) {
+    const msg = "Jira credentials not set. Run `aiflow init --adapter jira` first.";
+    if (options.json) { process.stdout.write(JSON.stringify({ ok: false, error: msg })); return; }
+    console.log(chalk.yellow(`⚠ ${msg}`));
+    return;
+  }
+  try {
+    const projects = await fetchJiraProjects(resolved.domain, resolved.email, resolved.apiToken);
+    const list = projects.map((p) => ({ id: p.id, key: p.key, name: p.name }));
+    if (options.json) {
+      process.stdout.write(JSON.stringify({ ok: true, projects: list, defaultProjectKey: creds.JIRA_DEFAULT_PROJECT_KEY ?? null }));
+      return;
+    }
+    console.log(chalk.cyan(`\nJira projects (${list.length}):`));
+    for (const p of list) {
+      const isDefault = p.key === creds.JIRA_DEFAULT_PROJECT_KEY;
+      console.log(`  ${isDefault ? chalk.green("●") : " "} ${p.key}  ${chalk.gray(p.name)}  ${chalk.gray(`(id: ${p.id})`)}`);
+    }
+  } catch (err) {
+    if (options.json) { process.stdout.write(JSON.stringify({ ok: false, error: err.message })); return; }
+    console.log(chalk.red(`✗ Could not fetch Jira projects: ${err.message}`));
+  }
+}
+
+async function setDefaultJiraProjectCommand(key) {
+  await saveMcpCredentials({ JIRA_DEFAULT_PROJECT_KEY: key });
+  console.log(chalk.green(`✓ Default Jira project set to ${key}.`));
+}
+
 /**
  * Fetch ALL comments of an issue from Jira REST API.
  */
@@ -787,11 +853,20 @@ async function manualContext(prefillId = "", options = {}) {
   // Task type — pre-select existing value if available
   const taskType = await promptForTaskType(existing.taskType, options.taskType);
 
+  // Stamp the default Backlog project (`ak backlog-set-default-project`), if one was ever set —
+  // manual tasks have no ticket to derive a project from otherwise. Kept for later use: syncing a
+  // locally-created task up to Backlog as a new issue needs to know which project it belongs to.
+  const creds = await loadCredentials();
+  const projectId = existing.projectId ?? creds.BACKLOG_DEFAULT_PROJECT_ID ?? null;
+  const projectKey = existing.projectKey ?? creds.BACKLOG_DEFAULT_PROJECT_KEY ?? null;
+
   const context = {
     taskId,
     taskType,
     title,
     description,
+    projectId,
+    projectKey,
     status: existing.status || "In Progress",
     mode: existing.mode || "auto",
     acceptanceCriteria: existing.acceptanceCriteria || [],
@@ -967,6 +1042,63 @@ async function loadCredentials() {
   return {};
 }
 
+/** Always the global file (`~/.aiflow/credentials.json`) — same path `loadCredentials` reads
+ *  first — so a value written here is picked up by every later `loadCredentials()` call. */
+function globalCredentialsPath() {
+  return path.join(os.homedir(), ".aiflow", "credentials.json");
+}
+
+/** Merges `patch` into the saved `.mcp` credentials block, creating the file if needed. */
+async function saveMcpCredentials(patch) {
+  const file = globalCredentialsPath();
+  await fs.ensureDir(path.dirname(file));
+  const data = (await fs.pathExists(file)) ? await fs.readJson(file).catch(() => ({})) : {};
+  data.mcp = { ...(data.mcp || {}), ...patch };
+  await fs.writeJson(file, data, { spaces: 2 });
+}
+
+/**
+ * `ak backlog-projects [--json]` — lists the projects in the configured Backlog space, so the
+ * user (or a headless caller like the VS Code extension) can pick one as the default project for
+ * manually-created tasks (see `manualContext` below, which stamps that default onto new tasks).
+ */
+async function listBacklogProjectsCommand(options = {}) {
+  const creds = await loadCredentials();
+  const resolved = resolveBacklogCredentials(creds);
+  if (!resolved) {
+    const msg = "Backlog credentials not set. Run `aiflow init --adapter backlog` first.";
+    if (options.json) { process.stdout.write(JSON.stringify({ ok: false, error: msg })); return; }
+    console.log(chalk.yellow(`⚠ ${msg}`));
+    return;
+  }
+  try {
+    const projects = await fetchBacklogProjects(resolved.domain, resolved.apiKey);
+    const list = projects.map((p) => ({ id: p.id, projectKey: p.projectKey, name: p.name }));
+    if (options.json) {
+      process.stdout.write(JSON.stringify({ ok: true, projects: list, defaultProjectId: creds.BACKLOG_DEFAULT_PROJECT_ID ?? null }));
+      return;
+    }
+    console.log(chalk.cyan(`\nBacklog projects (${list.length}):`));
+    for (const p of list) {
+      const isDefault = String(p.id) === String(creds.BACKLOG_DEFAULT_PROJECT_ID);
+      console.log(`  ${isDefault ? chalk.green("●") : " "} ${p.projectKey}  ${chalk.gray(p.name)}  ${chalk.gray(`(id: ${p.id})`)}`);
+    }
+  } catch (err) {
+    if (options.json) { process.stdout.write(JSON.stringify({ ok: false, error: err.message })); return; }
+    console.log(chalk.red(`✗ Could not fetch Backlog projects: ${err.message}`));
+  }
+}
+
+/**
+ * `ak backlog-set-default-project <id> <key>` — saves the chosen default project, so future
+ * manually-created tasks (`ak use --manual`) get stamped with it automatically. Non-interactive —
+ * safe to spawn without a TTY (see New-ex-architecture_v1.0.md §1.1 for why that distinction matters).
+ */
+async function setDefaultBacklogProjectCommand(id, key) {
+  await saveMcpCredentials({ BACKLOG_DEFAULT_PROJECT_ID: id, BACKLOG_DEFAULT_PROJECT_KEY: key });
+  console.log(chalk.green(`✓ Default Backlog project set to ${key} (id: ${id}).`));
+}
+
 // ──────────────────────────────────────────────────────────────
 // Context persistence
 // ──────────────────────────────────────────────────────────────
@@ -1353,3 +1485,12 @@ module.exports.detectTaskTypeFromString = detectTaskTypeFromString;
 module.exports.manualContext = manualContext;
 module.exports.promptForTaskType = promptForTaskType;
 module.exports.previewTarget = previewTarget;
+module.exports.resolveBacklogCredentials = resolveBacklogCredentials;
+module.exports.fetchBacklogProjects = fetchBacklogProjects;
+module.exports.listBacklogProjectsCommand = listBacklogProjectsCommand;
+module.exports.setDefaultBacklogProjectCommand = setDefaultBacklogProjectCommand;
+module.exports.resolveJiraCredentials = resolveJiraCredentials;
+module.exports.fetchJiraProjects = fetchJiraProjects;
+module.exports.listJiraProjectsCommand = listJiraProjectsCommand;
+module.exports.setDefaultJiraProjectCommand = setDefaultJiraProjectCommand;
+module.exports.saveMcpCredentials = saveMcpCredentials;