@applica-software-guru/sdd-core 1.8.1 → 1.8.3

package/src/prompt/draft-prompt-generator.ts

@@ -8,67 +8,55 @@ export interface DraftElements {
 
 export function generateDraftEnrichmentPrompt(
   drafts: DraftElements,
-  projectContext: StoryFile[],
-  projectDescription: string,
 ): string | null {
   const totalDrafts = drafts.docs.length + drafts.crs.length + drafts.bugs.length;
   if (totalDrafts === 0) {
     return null;
   }
 
-  const sections: string[] = [];
+  const sections: string[] = [
+    '# Draft Tasks',
+    '',
+    'Enrich all draft elements listed below.',
+    'Read each file directly from disk, complete missing details, and save it keeping `status: draft`.',
+    'Do not mark statuses automatically in this step.',
+    '',
+  ];
 
-  // Project context header
-  sections.push(`# Draft Enrichment\n`);
-  sections.push(`## Project\n\n${projectDescription}\n`);
-
-  // Global context: all non-draft documents
-  if (projectContext.length > 0) {
-    const ctxLines = [`## Project context (${projectContext.length} documents)\n`];
-    ctxLines.push('Use the following existing documents as context to produce complete, coherent documentation.\n');
-    for (const f of projectContext) {
-      ctxLines.push(`### \`${f.relativePath}\` — ${f.frontmatter.title}\n`);
-      ctxLines.push(f.body.trim());
-      ctxLines.push('');
-    }
-    sections.push(ctxLines.join('\n'));
-  }
-
-  // Draft documents
   if (drafts.docs.length > 0) {
-    const lines = [`## Draft documents to enrich (${drafts.docs.length})\n`];
-    lines.push('Each draft below contains incomplete human-written content. Produce a complete version for each document, preserving the original intent while adding missing details based on project context.\n');
+    const lines = [`## Draft documents (${drafts.docs.length})`];
     for (const f of drafts.docs) {
-      lines.push(`### \`${f.relativePath}\` — ${f.frontmatter.title}\n`);
-      lines.push(f.body.trim());
-      lines.push('');
+      lines.push(`- \`${f.relativePath}\` — ${f.frontmatter.title}`);
     }
     sections.push(lines.join('\n'));
+    sections.push('');
   }
 
-  // Draft change requests
   if (drafts.crs.length > 0) {
-    const lines = [`## Draft change requests to enrich (${drafts.crs.length})\n`];
-    lines.push('Each draft CR contains a rough description of requested changes. Produce a complete, actionable change request for each, specifying which documents are affected and what changes should be made.\n');
+    const lines = [`## Draft change requests (${drafts.crs.length})`];
     for (const cr of drafts.crs) {
-      lines.push(`### \`${cr.relativePath}\` — ${cr.frontmatter.title}\n`);
-      lines.push(cr.body.trim());
-      lines.push('');
+      lines.push(`- \`${cr.relativePath}\` — ${cr.frontmatter.title}`);
     }
     sections.push(lines.join('\n'));
+    sections.push('');
   }
 
-  // Draft bugs
   if (drafts.bugs.length > 0) {
-    const lines = [`## Draft bugs to enrich (${drafts.bugs.length})\n`];
-    lines.push('Each draft bug contains a rough description of an issue. Produce a complete bug report for each, including affected components, expected vs actual behavior, and steps to reproduce when possible.\n');
+    const lines = [`## Draft bugs (${drafts.bugs.length})`];
     for (const bug of drafts.bugs) {
-      lines.push(`### \`${bug.relativePath}\` — ${bug.frontmatter.title}\n`);
-      lines.push(bug.body.trim());
-      lines.push('');
+      lines.push(`- \`${bug.relativePath}\` — ${bug.frontmatter.title}`);
     }
     sections.push(lines.join('\n'));
+    sections.push('');
   }
 
-  return sections.join('\n\n');
+  sections.push(
+    '## Report\n',
+    'At the end of the enrichment, provide a detailed report including:\n' +
+    '- List of enriched files (documents, CRs, bugs)\n' +
+    '- For each file: what was added or completed\n' +
+    '- Any ambiguities resolved or assumptions made'
+  );
+
+  return sections.join('\n');
 }

package/src/prompt/prompt-generator.ts

@@ -35,5 +35,13 @@ export function generatePrompt(files: StoryFile[], root?: string): string {
     sections.push(delLines.join('\n'));
   }
 
+  sections.push(
+    '## Report\n\n' +
+    'At the end of your work, provide a detailed report including:\n' +
+    '- List of files created, modified, or deleted\n' +
+    '- Description of actions taken for each file\n' +
+    '- Any issues encountered or decisions made'
+  );
+
   return sections.join('\n\n');
 }

package/src/remote/api-client.ts

@@ -180,7 +180,7 @@ export async function pushDocs(
 }
 
 /** GET /cli/pending-crs */
-export async function fetchPendingCRs(config: ApiClientConfig): Promise<RemoteCRResponse[]> {
+export async function pullPendingCRs(config: ApiClientConfig): Promise<RemoteCRResponse[]> {
   return request<RemoteCRResponse[]>(config, 'GET', '/cli/pending-crs');
 }
 
@@ -193,7 +193,7 @@ export async function pushCRs(
 }
 
 /** GET /cli/open-bugs */
-export async function fetchOpenBugs(config: ApiClientConfig): Promise<RemoteBugResponse[]> {
+export async function pullOpenBugs(config: ApiClientConfig): Promise<RemoteBugResponse[]> {
   return request<RemoteBugResponse[]>(config, 'GET', '/cli/open-bugs');
 }
 

package/src/remote/sync-engine.ts

@@ -8,7 +8,7 @@ import { readConfig } from '../config/config-manager.js';
 import { parseAllStoryFiles } from '../parser/story-parser.js';
 import { parseAllCRFiles } from '../parser/cr-parser.js';
 import { parseAllBugFiles } from '../parser/bug-parser.js';
-import { buildApiConfig, pullDocs, pushDocs, pushCRs, pushBugs, deleteDocs, deleteCRs, deleteBugs, fetchPendingCRs, fetchOpenBugs, resetProject } from './api-client.js';
+import { buildApiConfig, pullDocs, pushDocs, pushCRs, pushBugs, deleteDocs, deleteCRs, deleteBugs, pullPendingCRs, pullOpenBugs, resetProject } from './api-client.js';
 import { readRemoteState, writeRemoteState } from './state.js';
 import type {
   PushResult,
@@ -139,6 +139,7 @@ export async function pushToRemote(root: string, options?: PushOptions): Promise
       path: normalizePath(f.relativePath),
       title: f.frontmatter.title,
       content: f.body,
+      status: f.frontmatter.status,
     }));
 
     const result = await pushDocs(api, documents);
@@ -194,13 +195,13 @@ export async function pushToRemote(root: string, options?: PushOptions): Promise
     const crResult = await pushCRs(api, crPayload);
 
     for (const cr of crResult.change_requests) {
-      const localPath = crsToPush.find(
-        (f) => f.frontmatter.title === cr.title,
-      )?.relativePath;
+      const localPath = cr.path
+        ?? crsToPush.find((f) => f.frontmatter.title === cr.title)?.relativePath;
       if (localPath) {
-        const absPath = resolve(root, localPath);
+        const normalized = normalizePath(localPath);
+        const absPath = resolve(root, normalized);
         const rawContent = existsSync(absPath) ? await readFile(absPath, 'utf-8') : '';
-        state.changeRequests![normalizePath(localPath)] = {
+        state.changeRequests![normalized] = {
           remoteId: cr.id,
           localHash: sha256(rawContent),
           lastSynced: new Date().toISOString(),
@@ -247,13 +248,13 @@ export async function pushToRemote(root: string, options?: PushOptions): Promise
     const bugResult = await pushBugs(api, bugPayload);
 
     for (const bug of bugResult.bugs) {
-      const localPath = bugsToPush.find(
-        (b) => b.frontmatter.title === bug.title,
-      )?.relativePath;
+      const localPath = bug.path
+        ?? bugsToPush.find((b) => b.frontmatter.title === bug.title)?.relativePath;
       if (localPath) {
-        const absPath = resolve(root, localPath);
+        const normalized = normalizePath(localPath);
+        const absPath = resolve(root, normalized);
         const rawContent = existsSync(absPath) ? await readFile(absPath, 'utf-8') : '';
-        state.bugs![normalizePath(localPath)] = {
+        state.bugs![normalized] = {
           remoteId: bug.id,
           localHash: sha256(rawContent),
           lastSynced: new Date().toISOString(),
@@ -432,7 +433,7 @@ export async function pullCRsFromRemote(root: string, timeout?: number): Promise
   const config = await readConfig(root);
   const api = buildApiConfig(config, timeout);
 
-  const remoteCRs = await fetchPendingCRs(api);
+  const remoteCRs = await pullPendingCRs(api);
   const state = await readRemoteState(root);
   if (!state.changeRequests) state.changeRequests = {};
 
@@ -448,7 +449,7 @@ export async function pullCRsFromRemote(root: string, timeout?: number): Promise
 
   // Detect remote deletions: tracked locally but not in remote response
   const remoteCRIdSet = new Set(remoteCRs.map((cr) => cr.id));
-  for (const [localPath, tracked] of Object.entries(state.changeRequests!)) {
+  for (const [localPath, tracked] of Object.entries(state.changeRequests)) {
     if (!remoteCRIdSet.has(tracked.remoteId)) {
       const absPath = resolve(root, localPath);
       if (existsSync(absPath)) {
@@ -522,7 +523,7 @@ export async function pullBugsFromRemote(root: string, timeout?: number): Promis
   const config = await readConfig(root);
   const api = buildApiConfig(config, timeout);
 
-  const remoteBugs = await fetchOpenBugs(api);
+  const remoteBugs = await pullOpenBugs(api);
   const state = await readRemoteState(root);
   if (!state.bugs) state.bugs = {};
 
@@ -538,7 +539,7 @@ export async function pullBugsFromRemote(root: string, timeout?: number): Promis
 
   // Detect remote deletions: tracked locally but not in remote response
   const remoteBugIdSet = new Set(remoteBugs.map((b) => b.id));
-  for (const [localPath, tracked] of Object.entries(state.bugs!)) {
+  for (const [localPath, tracked] of Object.entries(state.bugs)) {
     if (!remoteBugIdSet.has(tracked.remoteId)) {
       const absPath = resolve(root, localPath);
       if (existsSync(absPath)) {

package/src/remote/worker-client.ts

@@ -0,0 +1,141 @@
+import type { ApiClientConfig } from './api-client.js';
+import type { WorkerRegistration, WorkerJobAssignment, WorkerJobAnswer } from './worker-types.js';
+
+/**
+ * Low-level fetch wrapper for worker endpoints.
+ * Unlike the main api-client, worker requests have different timeout needs
+ * (e.g. long-poll uses 35s timeout) and don't need full retry logic.
+ */
+async function workerRequest<T>(
+  config: ApiClientConfig,
+  method: string,
+  path: string,
+  body?: unknown,
+  timeoutMs?: number,
+): Promise<T> {
+  const url = `${config.baseUrl}${path}`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs ?? 10_000);
+
+  try {
+    const res = await fetch(url, {
+      method,
+      headers: {
+        Authorization: `Bearer ${config.apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: body != null ? JSON.stringify(body) : undefined,
+      signal: controller.signal,
+    });
+    clearTimeout(timer);
+
+    if (!res.ok) {
+      let detail: string;
+      try {
+        const err = (await res.json()) as { detail?: string };
+        detail = err.detail ?? res.statusText;
+      } catch {
+        detail = res.statusText;
+      }
+      throw new Error(`Worker API error ${res.status}: ${detail}`);
+    }
+
+    // 204 No Content (poll with no job)
+    if (res.status === 204) {
+      return null as T;
+    }
+
+    return (await res.json()) as T;
+  } catch (error) {
+    clearTimeout(timer);
+    throw error;
+  }
+}
+
+/** POST /cli/workers/register */
+export async function registerWorker(
+  config: ApiClientConfig,
+  name: string,
+  agent: string,
+  branch?: string,
+  metadata?: Record<string, unknown>,
+): Promise<WorkerRegistration> {
+  return workerRequest<WorkerRegistration>(
+    config, 'POST', '/cli/workers/register',
+    { name, agent, branch, metadata },
+  );
+}
+
+/** POST /cli/workers/:workerId/heartbeat */
+export async function workerHeartbeat(
+  config: ApiClientConfig,
+  workerId: string,
+  workerStatus: 'online' | 'busy' = 'online',
+): Promise<void> {
+  await workerRequest(
+    config, 'POST', `/cli/workers/${workerId}/heartbeat`,
+    { status: workerStatus },
+  );
+}
+
+/** GET /cli/workers/:workerId/poll — long-poll (up to 35s timeout) */
+export async function workerPoll(
+  config: ApiClientConfig,
+  workerId: string,
+): Promise<WorkerJobAssignment | null> {
+  return workerRequest<WorkerJobAssignment | null>(
+    config, 'GET', `/cli/workers/${workerId}/poll`,
+    undefined,
+    35_000, // 35s to exceed server's 30s hold time
+  );
+}
+
+/** POST /cli/workers/jobs/:jobId/started */
+export async function workerJobStarted(
+  config: ApiClientConfig,
+  jobId: string,
+): Promise<void> {
+  await workerRequest(config, 'POST', `/cli/workers/jobs/${jobId}/started`);
+}
+
+/** POST /cli/workers/jobs/:jobId/output */
+export async function workerJobOutput(
+  config: ApiClientConfig,
+  jobId: string,
+  lines: string[],
+): Promise<void> {
+  await workerRequest(config, 'POST', `/cli/workers/jobs/${jobId}/output`, { lines });
+}
+
+/** POST /cli/workers/jobs/:jobId/question */
+export async function workerJobQuestion(
+  config: ApiClientConfig,
+  jobId: string,
+  content: string,
+): Promise<void> {
+  await workerRequest(config, 'POST', `/cli/workers/jobs/${jobId}/question`, { content });
+}
+
+/** GET /cli/workers/jobs/:jobId/answers?after_sequence=N */
+export async function workerJobAnswers(
+  config: ApiClientConfig,
+  jobId: string,
+  afterSequence: number = 0,
+): Promise<WorkerJobAnswer[]> {
+  return workerRequest<WorkerJobAnswer[]>(
+    config, 'GET', `/cli/workers/jobs/${jobId}/answers?after_sequence=${afterSequence}`,
+  );
+}
+
+/** POST /cli/workers/jobs/:jobId/completed */
+export async function workerJobCompleted(
+  config: ApiClientConfig,
+  jobId: string,
+  exitCode: number,
+  changedFiles?: Array<{ path: string; status: 'new' | 'modified' | 'deleted' }>,
+): Promise<void> {
+  await workerRequest(config, 'POST', `/cli/workers/jobs/${jobId}/completed`, {
+    exit_code: exitCode,
+    changed_files: changedFiles ?? [],
+  });
+}

package/src/remote/worker-types.ts

@@ -0,0 +1,40 @@
+/** Worker registration response from the server */
+export interface WorkerRegistration {
+  id: string;
+  project_id: string;
+  name: string;
+  status: string;
+  agent: string;
+  branch?: string;
+  last_heartbeat_at: string | null;
+  registered_at: string;
+  is_online: boolean;
+}
+
+/** Job assignment returned by the poll endpoint */
+export interface WorkerJobAssignment {
+  job_id: string;
+  entity_type: string | null;
+  entity_id: string | null;
+  prompt: string;
+  agent: string;
+  model?: string;
+  branch?: string;
+}
+
+/** Answer message from the user */
+export interface WorkerJobAnswer {
+  id: string;
+  job_id: string;
+  kind: 'answer';
+  content: string;
+  sequence: number;
+  created_at: string;
+}
+
+/** Local worker state persisted in .sdd/worker.json */
+export interface WorkerState {
+  workerId: string;
+  name: string;
+  registeredAt: string;
+}

package/src/scaffold/skill-adapters.ts

@@ -6,6 +6,7 @@ import {
   CHANGE_REQUESTS_REFERENCE,
   FILE_FORMAT_REFERENCE,
   SKILL_MD_TEMPLATE,
+  SKILL_REMOTE_MD_TEMPLATE,
   SKILL_UI_MD_TEMPLATE,
 } from "./templates.js";
 
@@ -81,22 +82,20 @@ const CANONICAL_SKILLS: Array<{
       },
     ],
   },
+  {
+    id: "sdd-remote",
+    files: [
+      {
+        path: `${CANONICAL_BASE_DIR}/sdd-remote/SKILL.md`,
+        content: SKILL_REMOTE_MD_TEMPLATE,
+      },
+    ],
+  },
 ];
 
 const CANONICAL_FILES: Array<{ path: string; content: string }> =
   CANONICAL_SKILLS.flatMap((skill) => skill.files);
 
-export interface SkillPathsDefinition {
-  skillId: string;
-  paths: string[];
-}
-
-export interface SkillAdapterDefinition {
-  id: string;
-  mode: AdapterMode;
-  skills: SkillPathsDefinition[];
-}
-
 export const SKILL_ADAPTERS: SkillAdapterDefinition[] = [
   {
     id: "claude",
@@ -115,6 +114,10 @@ export const SKILL_ADAPTERS: SkillAdapterDefinition[] = [
         skillId: "sdd-ui",
         paths: [".claude/skills/sdd-ui/SKILL.md"],
       },
+      {
+        skillId: "sdd-remote",
+        paths: [".claude/skills/sdd-remote/SKILL.md"],
+      },
     ],
   },
   {
@@ -134,6 +137,10 @@ export const SKILL_ADAPTERS: SkillAdapterDefinition[] = [
         skillId: "sdd-ui",
         paths: [".agents/skills/sdd-ui/SKILL.md"],
       },
+      {
+        skillId: "sdd-remote",
+        paths: [".agents/skills/sdd-remote/SKILL.md"],
+      },
     ],
   },
 ];